Initial support for experiments

Author: sigurdm

lib/src/command/global_activate.dart

@@ -52,6 +52,8 @@ class GlobalActivateCommand extends PubCommand {
       hide: true,
     );
 
+    argParser.addMultiOption('experiments', help: 'Experiments(s) to enable.');
+
     argParser.addFlag(
       'no-executables',
       negatable: false,
@@ -131,6 +133,7 @@ class GlobalActivateCommand extends PubCommand {
           overwriteBinStubs: overwrite,
           path: argResults.option('git-path'),
           ref: argResults.option('git-ref'),
+          allowedExperiments: argResults.multiOption('experiments'),
         );
 
       case 'hosted':
@@ -171,6 +174,7 @@ class GlobalActivateCommand extends PubCommand {
           ref.withConstraint(constraint),
           executables,
           overwriteBinStubs: overwrite,
+          allowedExperiments: argResults.multiOption('experiments'),
         );
 
       case 'path':

lib/src/entrypoint.dart

@@ -404,7 +404,9 @@ See $workspacesDocUrl for more information.''',
   /// package dir.
   ///
   /// Also marks the package active in `PUB_CACHE/active_roots/`.
-  Future<void> writePackageConfigFiles() async {
+  Future<void> writePackageConfigFiles({
+    required List<String> experiments,
+  }) async {
     ensureDir(p.dirname(packageConfigPath));
 
     writeTextFileIfDifferent(
@@ -416,6 +418,7 @@ See $workspacesDocUrl for more information.''',
                 .pubspec
                 .sdkConstraints[sdk.identifier]
                 ?.effectiveConstraint,
+        experiments: experiments,
       ),
     );
     writeTextFileIfDifferent(packageGraphPath, await _packageGraphFile(cache));
@@ -471,6 +474,7 @@ See $workspacesDocUrl for more information.''',
   Future<String> _packageConfigFile(
     SystemCache cache, {
     VersionConstraint? entrypointSdkConstraint,
+    required List<String> experiments,
   }) async {
     final entries = <PackageConfigEntry>[];
     if (lockFile.packages.isNotEmpty) {
@@ -515,6 +519,7 @@ See $workspacesDocUrl for more information.''',
       packages: entries,
       generator: 'pub',
       generatorVersion: sdk.version,
+      experiments: experiments,
       additionalProperties: {
         if (FlutterSdk().isAvailable) ...{
           'flutterRoot':
@@ -616,6 +621,7 @@ Try running `$topLevelProgram pub get` to create `$lockFilePath`.''');
       lockFile,
       newLockFile,
       result.availableVersions,
+      result.experiments,
       cache,
       dryRun: dryRun,
       enforceLockfile: enforceLockfile,
@@ -644,7 +650,7 @@ To update `$lockFilePath` run `$topLevelProgram pub get`$suffix without
       /// have to reload and reparse all the pubspecs.
       _packageGraph = Future.value(PackageGraph.fromSolveResult(this, result));
 
-      await writePackageConfigFiles();
+      await writePackageConfigFiles(experiments: result.experiments);
 
       try {
         if (precompile) {

lib/src/experiment.dart

@@ -0,0 +1,16 @@
+// Copyright (c) 2025, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+/// An experiment as described by an sdk_experiments file
+class Experiment {
+  final String name;
+
+  /// A description of the experiment
+  final String description;
+
+  /// Where you can read more about the experiment
+  final String docUrl;
+
+  Experiment(this.name, this.description, this.docUrl);
+}

lib/src/global_packages.dart

@@ -90,6 +90,7 @@ class GlobalPackages {
   Future<void> activateGit(
     String repo,
     List<String>? executables, {
+    required List<String> allowedExperiments,
     required bool overwriteBinStubs,
     String? path,
     String? ref,
@@ -127,10 +128,15 @@ class GlobalPackages {
       packageRef.withConstraint(VersionConstraint.any),
       executables,
       overwriteBinStubs: overwriteBinStubs,
+      allowedExperiments: allowedExperiments,
     );
   }
 
-  Package packageForConstraint(PackageRange dep, String dir) {
+  Package packageForConstraint(
+    PackageRange dep,
+    String dir,
+    List<String> allowedExperiments,
+  ) {
     return Package(
       Pubspec(
         'pub global activate',
@@ -142,6 +148,7 @@ class GlobalPackages {
             defaultUpperBoundConstraint: null,
           ),
         },
+        experiments: allowedExperiments,
       ),
       dir,
       [],
@@ -164,12 +171,14 @@ class GlobalPackages {
   Future<void> activateHosted(
     PackageRange range,
     List<String>? executables, {
+    required List<String> allowedExperiments,
     required bool overwriteBinStubs,
     String? url,
   }) async {
     await _installInCache(
       range,
       executables,
+      allowedExperiments: allowedExperiments,
       overwriteBinStubs: overwriteBinStubs,
     );
   }
@@ -231,6 +240,7 @@ class GlobalPackages {
   Future<void> _installInCache(
     PackageRange dep,
     List<String>? executables, {
+    required List<String> allowedExperiments,
     required bool overwriteBinStubs,
     bool silent = false,
   }) async {
@@ -239,7 +249,7 @@ class GlobalPackages {
 
     final tempDir = cache.createTempDir();
     // Create a dummy package with just [dep] so we can do resolution on it.
-    final root = packageForConstraint(dep, tempDir);
+    final root = packageForConstraint(dep, tempDir, allowedExperiments);
 
     // Resolve it and download its dependencies.
     SolveResult result;
@@ -284,6 +294,7 @@ To recompile executables, first run `$topLevelProgram pub global deactivate $nam
           originalLockFile ?? LockFile.empty(),
           lockFile,
           result.availableVersions,
+          result.experiments,
           cache,
           dryRun: false,
           quiet: false,
@@ -300,19 +311,19 @@ To recompile executables, first run `$topLevelProgram pub global deactivate $nam
       // Load the package graph from [result] so we don't need to re-parse all
       // the pubspecs.
       final entrypoint = Entrypoint.global(
-        packageForConstraint(dep, packageDir),
+        packageForConstraint(dep, packageDir, result.experiments),
         lockFile,
         cache,
         solveResult: result,
       );
 
-      await entrypoint.writePackageConfigFiles();
+      await entrypoint.writePackageConfigFiles(experiments: result.experiments);
 
       await entrypoint.precompileExecutables();
     }
 
     final entrypoint = Entrypoint.global(
-      packageForConstraint(dep, _packageDir(dep.name)),
+      packageForConstraint(dep, _packageDir(dep.name), allowedExperiments),
       lockFile,
       cache,
       solveResult: result,
@@ -427,7 +438,11 @@ Consider `$topLevelProgram pub global deactivate $name`''');
       // For cached sources, the package itself is in the cache and the
       // lockfile is the one we just loaded.
       entrypoint = Entrypoint.global(
-        packageForConstraint(id.toRange(), _packageDir(id.name)),
+        packageForConstraint(
+          id.toRange(),
+          _packageDir(id.name),
+          [], // XXX load experiments here
+        ),
         lockFile,
         cache,
       );
@@ -536,6 +551,7 @@ Try reactivating the package.
           entrypoint.lockFile,
           newLockFile,
           result.availableVersions,
+          result.experiments,
           cache,
           dryRun: true,
           enforceLockfile: true,
@@ -678,6 +694,7 @@ Try reactivating the package.
               id.toRange(),
               packageExecutables,
               overwriteBinStubs: true,
+              allowedExperiments: [], // XXX
               silent: true,
             );
           } else {

lib/src/package.dart

@@ -87,6 +87,11 @@ class Package {
       ...package.pubspec.dependencyOverrides,
   };
 
+  /// A collection of the union of all experiments used in the workspace.
+  late final Set<String> allExperimentsInWorkspace = {
+    for (final package in transitiveWorkspace) ...package.pubspec.experiments,
+  };
+
   /// The immediate dependencies this package specifies in its pubspec.
   Map<String, PackageRange> get dependencies => pubspec.dependencies;
 

lib/src/package_config.dart

@@ -38,11 +38,14 @@ class PackageConfig {
   /// `.dart_tool/package_config.json` file.
   Map<String, dynamic> additionalProperties;
 
+  List<String> experiments;
+
   PackageConfig({
     required this.configVersion,
     required this.packages,
     this.generator,
     this.generatorVersion,
+    required this.experiments,
     Map<String, dynamic>? additionalProperties,
   }) : additionalProperties = additionalProperties ?? {} {
     final names = <String>{};
@@ -100,6 +103,21 @@ class PackageConfig {
       );
     }
 
+    // Read the 'experiments' property
+    final experiments = root['experiments'] ?? <String>[];
+    if (experiments is! List) {
+      throw const FormatException(
+        '"experiments" in package_config.json must be a list, if given',
+      );
+    }
+    for (final experiment in experiments) {
+      if (experiment is! String) {
+        throw const FormatException(
+          '"experiments" in package_config.json must all be strings',
+        );
+      }
+    }
+
     // Read the 'generatorVersion' property
     Version? generatorVersion;
     final generatorVersionRaw = root['generatorVersion'];
@@ -122,6 +140,7 @@ class PackageConfig {
       packages: packages,
       generator: generator,
       generatorVersion: generatorVersion,
+      experiments: experiments.cast<String>(),
       additionalProperties: Map.fromEntries(
         root.entries.where(
           (e) =>
@@ -131,6 +150,7 @@ class PackageConfig {
                 'generated',
                 'generator',
                 'generatorVersion',
+                'experiments',
               }.contains(e.key),
         ),
       ),
@@ -141,6 +161,7 @@ class PackageConfig {
   Map<String, Object?> toJson() => {
     'configVersion': configVersion,
     'packages': packages.map((p) => p.toJson()).toList(),
+    'experiments': experiments,
     'generator': generator,
     'generatorVersion': generatorVersion?.toString(),
   }..addAll(additionalProperties);

lib/src/pubspec.dart

@@ -143,6 +143,51 @@ environment:
         _containingDescription,
       );
 
+  List<String>? _experiments;
+  List<String> get experiments => _experiments ??= parseExperiments();
+
+  List<String> parseExperiments() {
+    final experimentsNode = fields.nodes['experiments'];
+    if (experimentsNode == null || experimentsNode.value == null) {
+      return [];
+    }
+    if (experimentsNode is! YamlList) {
+      _error('`experiments` must be a list of strings', experimentsNode.span);
+    }
+    final result = <String>[];
+    for (final e in experimentsNode.nodes) {
+      final value = e.value;
+      if (value is! String) {
+        _error('`experiments` must be a list of strings', e.span);
+      }
+
+      /// For root packages, validate that all experiments are known by at least
+      /// one of the current sdks.
+      ///
+      /// Dependencies will only be chosen by the solver if their experiments
+      /// are a subset of those of the root packages, so we don't filter here.
+      if (_containingDescription is ResolvedRootDescription &&
+          !availableExperiments.containsKey(value)) {
+        final availableExperimentsDescription =
+            availableExperiments.isEmpty
+                ? '''There are no available experiments.'''
+                : '''
+Available experiments are:
+${availableExperiments.values.map((experiment) => '* ${experiment.name}: ${experiment.description}, ${experiment.docUrl}').join('\n')}''';
+        _error('''
+$value is not a known experiment.
+
+$availableExperimentsDescription
+
+Read more about experiments at https://dart.dev/go/experiments.
+''', e.span);
+      } else {
+        result.add(value);
+      }
+    }
+    return result;
+  }
+
   Map<String, PackageRange>? _dependencies;
 
   /// The packages this package depends on when it is the root package.
@@ -341,6 +386,7 @@ environment:
     this.workspace = const <String>[],
     this.dependencyOverridesFromOverridesFile = false,
     this.resolution = Resolution.none,
+    List<String> experiments = const <String>[],
   }) : _dependencies =
            dependencies == null
                ? null
@@ -364,6 +410,7 @@ environment:
        // This is a dummy value. Dependencies should already be resolved, so we
        // never need to do relative resolutions.
        _containingDescription = ResolvedRootDescription.fromDir('.'),
+       _experiments = experiments,
        super(
          fields == null ? YamlMap() : YamlMap.wrap(fields),
          name: name,