[breaking change] discontinue .packages file

[mit-mit]

Intended change in behaviour

When the commands dart pub get or flutter pub get are executed, pub resolves all dependencies, and downloads those dependencies to the local pub cache. It furthermore creates a mapping from each used package to their location on the local file system. Today this mapping is stored in two files:

• .dart_tool/package_config.json
• .packages (legacy, as of Dart 2.8.0)

The former of these is the file that the current SDKs rely on. The latter has until now been generated for backwards compatibility with older Dart SDKs. After the present breaking change is made, we'll change pub get to only generate the former (.dart_tool/package_config.json), and the Dart SDK will no longer be able to read the .packages file.

Rationale for making the change

The .packages file is left-over from older Dart SDKs and is not fully compatible with Dart 2.x SDKs (it, for example, doesn’t support language versioning). We're removing the generation of .packages to prevent having extraneous files in the file system, and to prevent corner-case bugs that may occur if both files are around, but in an inconsistent state.

Expected impact of this change.

Regular apps and packages that are written using Dart 2.x will not be impacted, as they rely on .dart_tool/package_config.json.

If you already have a .packages file, you can delete it. After upgrading your Dart SDK it will no longer be generated, and pub will delete it when pub get runs.

Developer tools that need to look up the packages used by a project, and their locations on the file system, will no longer be able to rely on the .packages file. Such tools should be upgraded to rely on the content of the package_config.json file. Rather than reading this file directly, we strongly recommend using the API for consuming it available in package:package_config.

If you are passing a .packages file to the dart command (dart --packages=.packages) you'll need to pass the package config instead (dart --packages=.dart_tool/package_config.json).

Steps for mitigating the change

If you for some reason depend on this legacy file, you will for one stable release be able to generate it by passing the flag --legacy-packages-file to dart pub get / flutter pub get. After one stable release, this flag will be removed, and all support for generating the legacy file be removed. Note however this this is only being offered for external tools that may depend on the .packages file; all tools offered by the Dart team will no longer support this .packages file.

Timeline

The change to no longer generate .packages, and to remove support for reading that file in tools offered by the Dart team / the Dart SDK, will be made in a dev-channel release of Dart 2.18.

The --legacy-packages-file flag -- which offers a temporary solution for retaining the generation of .packages for other legacy tools -- will be removed one release later in a dev-channel release of Dart 2.19.

Related issues

In the Dart 2.18 stable release:

• Stop generating .packages file: Stop producing .packages #47431, Stop generating .packages pub#2756
• Update Dart.dev documentation: documentation for deprecated .packages file site-www#3909
• Remove support in any Dart-owned tool which reads .packages
  • Remove VM/CFE/compiler/analyzer support for .packages: Remove CFE/analyzer/compiler/VM support for .packages file #48939
  • Remove use of .package in main sdk repo: Remove .packages from the Dart SDK repo #48275
  • Update DartCode: Don't rely on .packages to detect if dependencies needs to be fetched Dart-Code/Dart-Code#3813
  • Update IntelliJ: https://youtrack.jetbrains.com/issue/WEB-54703
  • Update DartPad: Use package_config dart-archive/dart-services#834
  • Update web tooling: Migrate to package_config.json webdev#1526
  • Update package:coverage: Migrate to package_config tools#483, Deprecate --packages flag tools#484
• Update Flutter: Eliminate CoverageCollector dependency on .package files flutter/flutter#103775
• Update changelog: https://dart-review.googlesource.com/c/sdk/+/251765

In the following Dart 2.19 stable release:

• Remove --legacy-packages-file flag entirely: Discontinue --legacy-packages-file flag pub#3496

[devoncarew]

From a dart scrum discussion on this breaking change:

This change talks about not generating the .packages file anymore. There's another part of this however - parts of our runtime fall back on reading the .packages file if we can't find a package_config.json file. There may be parts of the ecosystem that rely on generating .packages files themselves, and then having the CFE and the analyzer consume these file.

Is removing support for reading from .packages file from our tools unspecified here? Not part of this breaking change? Something we might follow up on in a separate, future breaking change?

[mit-mit]

This breaking change notification tracks removing the existence of .packages. After this breaking change lands, I'd consider any code path in our tools that falls back to .packages essentially dead code, and we could remove that at any time.

[devoncarew]

This breaking change notification tracks removing the existence of .packages. After this breaking change lands, I'd consider any code path in our tools that falls back to .packages essentially dead code, and we could remove that at any time.

We should probably make that explicit in any communications to users, and, plan out when we'd remove reading the file (Dart 2.18? Dart 2.19?)

[mit-mit]

Breaking change was announced:
https://groups.google.com/a/dartlang.org/g/announce/c/jNR4yY3mcW4

[itsjustkevin]

Could you take a look at this breaking change request @grouma and @Hixie?

[grouma]

I believe this will impact a number of packages. cc @natebosch

Off the top of my head, we rely on this file in package:dwds (cc @annagrin) and package:coverage (cc @liamappelbe).

[Hixie]

I have no objection in principle but I would not be surprised if this broke things unexpectedly (e.g. we probably have tests that depend on .packages in some way). Hard to determine exactly what will break without trying it though.