[cli] Introduce `dart install` (replacing `dart pub global activate` to use)

[dcharkes]

2025-06-11: Updated to introduce dart install, see #60889 (comment) for a detailed design.

We should change dart pub global to use AOT instead of JIT.

Also, we should not let pub need to worry about how dart is compiled and run, dart should be responsible for that.

@jonasfj suggested that dart pub global activate should use dart build exe.

Subsequently, $PUB_CACHE/bin/ could contain symlinks to the executables in $PUB_CACHE/global_packages/<package_name>/outputdir/<package_name>.exe.

This would

1. remove logic from pub-global about how Dart is compiled,
2. speedup startup of pub-global activated packages, and
3. make native assets work ([native_assets] Support dart pub global run #56044).

Since the executables would include a dart precompiled runtime. The Dart version which is running would be the one that was used to run dart pub global activate. If we ever want to re-activate a package with a different Dart SDK version, we might need some way to detect what version of the Dart SDK was used to compile the executable.

@jonasfj and @sigurdm probably know much more constraints and considerations. I'm filing an issue so that we have something to point to.

[sigurdm]

One stumbling block is the lack of dart:mirrors support in AOT compilation

[gryznar]

+1. One step towards this could be to use existing binary (if it was compiled before manually). It is strange, that Dart uses .snapshot file from .dart-tool instead of executable from bin/, especially since manual edit of .bat script in cache and pointing there to .exe works well. @sigurdm is support for this feature dart:mirror going to be implemented in some subsequent release?

[jonasfj]

I don't think dart:mirrors will be supported in AOT-mode (See #44489).

I think that we should consider overhauling everything to do with global activation. Ideally, it shouldn't have to be a two-step process, but something more akin to npx. But that's just like my opinion (at this point in time; not fully conceived).

But I do think we should consider changing from JIT to AOT along with a minor overhaul of global activation in general. Both things will affect PUB_CACHE and cause pain for people switching between SDK versions.

[dcharkes]

@jonasfj suggested that dart pub global activate should use dart build exe.

We must do this, otherwise any package using build hooks with code assets will stop working.

I don't think dart:mirrors will be supported in AOT-mode (See dart-lang/sdk#44489).

I believe we should consider marking mirrors as no longer supported. @jonasfj Any chance we have data on which packages are pub global activated by users, is that instrumented? If so, we could check if any of the top ones uses mirrors.

@mkustermann suggested we should introduce dart install (which would be very similar to package manager CLI commands). If we introduce a new command, we also don't have to say not supporting mirrors is a breaking change. 🙃

@mit-mit Any thoughts on dart install as a command and not supporting mirrors?

[mkustermann]

@mkustermann suggested we should introduce dart install

I can also give some background thoughts on this.

The current state of dart pub global activate is

• It lazily compiles the entrypoint to a kernel file (for faster time-to-main in future runs)
• If the SDK changes it may need to rebuild the kernel file
  => This causes unpredictable time-to-main
• Therefore it needs to have the source code of the app
  => It's not self contained but requires pub cache
• The app can (not sure) probably not find it's own package or it's package dependencies
  => It's probably not able to find any resources in package dirs
• It doesn't work with the new dart hooks

Now IMHO we should have a way to build an entrypoint of a package and get a self-contained deployment bundle that can be run locally (or even distributed to others). The dart build command will produce such bundles.

For the use case where we want to get such bundles for packages from pub for local use, I think a dart install that puts it into an installation path would be great. It wouldn't depend on the ~/.pub-cache or .dart_tool folders. It could install to /usr/local/* or user-defined directories.

This would also potentially also allow package authors to pre-built not just hook artifacts (e.g. shared libraries) but also the apps themselves - bypassing the AOT compilation at dart install time.

The installed apps may have been built with older Dart SDK versions, so it may make sense to have some tooling to manage those installed packages:

• list all installed packages
• see if any of them are out-dated (i.e. package has newer version or newer Dart SDK to compile them with)
• remove packages

[mkustermann]

Maybe one addition: One could allow a dart install --mode=jit where the deployable bundle that is locally installed uses JIT and dart:mirrors - it could compile the app to kernel (as pub global activate does now) - run build hooks and bundle all assets with the kernel file - but compared to pub global activate, it could include the JIT runtime - making the bundle self contained (just like in AOT) and not suffer from the downsides mentioned above (unpredictable time-to-main, need pub cache, Dart SDK upgrade influences the installed app, ...)