Merge remote-tracking branch 'origin/master' into fix_command_suggestion

.github/workflows/test.yaml

@@ -24,7 +24,7 @@ jobs:
       matrix:
         sdk: [dev]
     steps:
-      - uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9
+      - uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744
       - uses: dart-lang/setup-dart@d6a63dab3335f427404425de0fbfed4686d93c4f
         with:
           sdk: ${{ matrix.sdk }}
@@ -52,7 +52,7 @@ jobs:
         sdk: [dev]
         shard: [0, 1, 2, 3, 4, 5, 6]
     steps:
-      - uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9
+      - uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744
       - uses: dart-lang/setup-dart@d6a63dab3335f427404425de0fbfed4686d93c4f
         with:
           sdk: ${{ matrix.sdk }}

doc/cache_layout.md

@@ -14,14 +14,14 @@ cache conventions.
 ## Location
 
 The global default pub-cache is located at:
- * `$HOME/.pub_cache` on Linux and Mac OS,
+ * `$HOME/.pub_cache` on Linux and macOS,
  * `%LOCALAPPDATA%/Pub/Cache` on Windows.
 
 Prior to Flutter 3.8.0, the Flutter SDK declared `PUB_CACHE=$FLUTTER_ROOT/.pub_cache` overriding the default global pub-cache.
 
 The default location of the pub-cache can be overridden using the environment variable `PUB_CACHE`.
 
-For the remainder of this document we refer to the location of the pub-cache as `$PUB_CACHE`.```
+For the remainder of this document we refer to the location of the pub-cache as `$PUB_CACHE`.
 
 ## Layout
 
@@ -48,7 +48,7 @@ stored in a platform specific config dir:
 
 * On Linux `$XDG_CONFIG_HOME/dart/pub-credentials.json` if `$XDG_CONFIG_HOME` is
   defined, otherwise `$HOME/.config/dart/pub-credentials.json`
-* On Mac OS: `$HOME/Library/Application Support/dart/pub-credentials.json`
+* On macOS: `$HOME/Library/Application Support/dart/pub-credentials.json`
 * On Windows: `%APPDATA%/dart/pub-credentials.json`
 
 ### Hosted
@@ -194,7 +194,6 @@ $PUB_CACHE/global_packages/
     │   └── mono_repo.dart-3.0.0-55.0.dev.snapshot
     ├── .dart_tool/
     │   └── package_config.json
-    ├── incremental
     └── pubspec.lock
 ```
 
@@ -213,9 +212,6 @@ activated package is used by several sdk-versions (TODO: This does have some
 limitations, and we should probably rethink this). A re-activation of the
 package will delete all the existing snapshots.
 
-The `incremental` is used while compiling them. (TODO: We should probably remove
-this after succesful compilation https://github.com/dart-lang/pub/issues/3896).
-
 For packages activated with `--source=path` the lockfile is special-cased to just point
 to the activated path, and `.dart_tool/package_config.json`, snapshots are
 stored in that folder.

doc/dart_tool_layout.md

@@ -0,0 +1,64 @@
+# Layout of the `.dart_tool/pub` folder
+
+The pub client creates `.dart_tool/package_config.json` as described by
+[https://github.com/dart-lang/language/blob/main/accepted/2.8/language-versioning/package-config-file-v2.md].
+
+But furthermore pub can use a folder called `.dart_tool/pub` for storing
+artifacts. The organization of that folder is what this document is trying to describe.
+
+The information in this document is informational, and can be used for
+understanding the cache, but we strongly encourage all manipulation of the
+`.dart_tool/pub` folder happens though the `dart pub`/`flutter pub` commands to
+avoid relying on accidental properties that might be broken in the future.
+
+## Precompilation cache
+
+```tree
+.dart_tool/
+├── package_config.json
+├── pub
+│   ├── bin
+│   │   ├── pub
+│   │   │   └── pub.dart-3.1.0.snapshot.incremental
+│   │   └── test
+│   │       └── test.dart-3.2.0-36.0.dev.snapshot
+
+```
+
+When `dart run <package>:<executable>` is called, pub will try to find `<executable>` in
+the package `<package>` and compile it as a "dill" file (using
+`package:frontend_server_client`).
+
+The output will be stored in The dill file will be stored in
+`.dart_tool/pub/bin/<package>/<executable>.dart-<sdk-version>.snapshot`.
+
+This can be used to run the executable by invoking (done implicitly by `dart run`):
+
+```
+dart .dart_tool/pub/bin/<package>/<executable>.dart-<sdk-version>.snapshot
+```
+
+But the dill-file is also fed to the compiler for incremental compilation. This
+can in many cases greatly speed up the compilation when no change has happened.
+
+If the compilation fails, pub avoids leaving a `.snapshot` file, but instead leaves a
+`.dart_tool/pub/bin/<package>/<executable>.dart-<sdk-version>.snapshot.incremental` file.
+
+This file cannot be executed. But it can still give the benefit of incremental
+compilation when changes have happened to the code.
+
+Earlier versions of the dart sdk would put this "incremental" file in:
+
+`.dart_tool/pub/incremental/<package>/<executable>.dart-incremental.dill`.
+
+As we don't expect many of those files to linger, we don't attempt to clean them up.
+
+We use the `<sdk-version>` to enable different sdk-versions to each have their
+own snapshot, so they don't step on each others toes when you switch from one
+sdk to another. The downside is that there is no mechanism for deleting
+snapshots of old sdks. We might want change that logic.
+
+One could argue that a "snapshot", is a different thing from a "dill" file in
+Dart VM terms. But both can be invoked by the VM, and run rather quickly without
+much more pre-compilation. In the future we might want to use true "snapshots"
+for executables from immutable packages, as they don't benefit from incremental compilation.

lib/src/command/deps.dart

@@ -71,7 +71,8 @@ class DepsCommand extends PubCommand {
 
   @override
   Future<void> runProtected() async {
-    // Explicitly Run this in the directorycase we don't access `entrypoint.packageGraph`.
+    // Explicitly run this in the directory in case
+    // we don't access `entrypoint.packageGraph`.
     await entrypoint.ensureUpToDate();
     final buffer = StringBuffer();
 

lib/src/command/outdated.dart

@@ -89,7 +89,7 @@ class OutdatedCommand extends PubCommand {
 
     argParser.addFlag(
       'show-all',
-      help: 'Include dependencies that are already fullfilling --mode.',
+      help: 'Include dependencies that are already fulfilling --mode.',
     );
 
     // Preserve for backwards compatibility.
@@ -876,7 +876,7 @@ class _MarkedVersionDetails {
   final String? _prefix;
   final String? _suffix;
 
-  /// This should be true if the mode creating this consideres the version as
+  /// This should be true if the mode creating this considers the version as
   /// "good".
   ///
   /// By default only packages with a current version that is not as desired