[native_assets_cli] Redesign API step 1

pkgs/native_assets_builder/test_data/package_reading_metadata/build.dart

@@ -2,6 +2,10 @@
 // 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.
 
+// TODO(https://github.com/dart-lang/native/issues/882): A new version of
+// `package:native_assets_cli` needs to be published first.
+// ignore_for_file: deprecated_member_use
+
 import 'package:cli_config/cli_config.dart';
 import 'package:native_assets_cli/native_assets_cli.dart';
 

pkgs/native_assets_builder/test_data/package_with_metadata/build.dart

@@ -2,6 +2,10 @@
 // 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.
 
+// TODO(https://github.com/dart-lang/native/issues/882): A new version of
+// `package:native_assets_cli` needs to be published first.
+// ignore_for_file: deprecated_member_use
+
 import 'package:native_assets_cli/native_assets_cli.dart';
 
 void main(List<String> args) async {

pkgs/native_assets_cli/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.4.3-wip
+
+- New API.
+
 ## 0.4.2
 
 - Fix dartdoc generation. Hide the implementation details.

pkgs/native_assets_cli/lib/native_assets_cli.dart

@@ -7,6 +7,7 @@
 library native_assets_cli;
 
 export 'src/api/asset.dart';
+export 'src/api/build.dart';
 export 'src/api/build_config.dart';
 export 'src/api/build_mode.dart';
 export 'src/api/build_output.dart';

pkgs/native_assets_cli/lib/src/api/build.dart

@@ -0,0 +1,80 @@
+// Copyright (c) 2024, 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.
+
+import 'build_config.dart';
+import 'build_output.dart';
+
+/// Run a native assets build.
+///
+/// Example using `package:native_toolchain_c`:
+///
+/// ```dart
+/// void main(List<String> args) =>
+///     build(args, (buildConfig, buildOutput) async {
+///       final cbuilder = CBuilder.library(
+///         name: packageName,
+///         assetId: 'package:$packageName/$packageName.dart',
+///         sources: [
+///           'src/$packageName.c',
+///         ],
+///       );
+///       await cbuilder.run(
+///         buildConfig: buildConfig,
+///         buildOutput: buildOutput,
+///         logger: Logger('')
+///           ..level = Level.ALL
+///           ..onRecord.listen((record) => print(record.message)),
+///       );
+///     });
+/// ```
+///
+/// Example outputting assets manually:
+///
+/// ```dart
+/// void main(List<String> args) =>
+///     build(args, (config, output) async {
+///       if (config.linkModePreference == LinkModePreference.static) {
+///         // Simulate that this script only supports dynamic libraries.
+///         throw UnsupportedError(
+///           'LinkModePreference.static is not supported.',
+///         );
+///       }
+///
+///       final Iterable<Target> targets;
+///       final packageName = config.packageName;
+///       final assetPath = config.outDir.resolve(
+///         config.targetOs.dylibFileName(packageName),
+///       );
+///       if (config.dryRun) {
+///         // Dry run invocations report assets for all architectures for that OS.
+///         targets = Target.values.where(
+///           (element) => element.os == config.targetOs,
+///         );
+///       } else {
+///         targets = [config.target];
+///
+///         // Insert code that downloads or builds the asset to `assetPath`.
+///       }
+///
+///       for (final target in targets) {
+///         output.addAssets([
+///           Asset(
+///             id: 'library:${packageName}/src/some_file.dart',
+///             linkMode: LinkMode.dynamic,
+///             target: target,
+///             path: AssetAbsolutePath(assetPath),
+///           )
+///         ]);
+///       }
+///     });
+/// ```
+Future<void> build(
+  List<String> commandlineArguments,
+  Future<void> Function(BuildConfig, BuildOutput) builder,
+) async {
+  final config = await BuildConfig.fromArgs(commandlineArguments);
+  final output = BuildOutput();
+  await builder(config, output);
+  await output.writeToFile(outDir: config.outDir);
+}

pkgs/native_assets_cli/lib/src/api/build_config.dart

@@ -11,13 +11,20 @@ import '../model/build_config.dart' as model;
 import '../model/build_mode.dart' as model;
 import '../model/ios_sdk.dart' as model;
 import '../model/link_mode_preference.dart' as model;
+import '../model/metadata.dart' as model;
 import '../model/target.dart' as model;
 import 'build_mode.dart';
 import 'ios_sdk.dart';
 import 'link_mode_preference.dart';
 import 'metadata.dart';
 import 'target.dart';
 
+/// The configuration for a `build.dart` invocation.
+///
+/// A package can choose to have a toplevel `build.dart` script. If such a
+/// script exists, it will be automatically run, by the Flutter and Dart SDK
+/// tools. The script will then be run with specific commandline arguments,
+/// which [BuildConfig] can parse and provide more convenient access to.
 abstract class BuildConfig {
   /// The folder in which all output and intermediate artifacts should be
   /// placed.
@@ -34,12 +41,12 @@ abstract class BuildConfig {
 
   /// The target being compiled for.
   ///
-  /// Not available in [dryRun].
+  /// Not available during a [dryRun].
   Target get target;
 
   /// The architecture being compiled for.
   ///
-  /// Not available in [dryRun].
+  /// Not available during a [dryRun].
   Architecture get targetArchitecture;
 
   /// The operating system being compiled for.
@@ -49,15 +56,15 @@ abstract class BuildConfig {
   ///
   /// Required when [targetOs] equals [OS.iOS].
   ///
-  /// Not available in [dryRun].s
+  /// Not available during a [dryRun].
   IOSSdk? get targetIOSSdk;
 
   /// When compiling for Android, the minimum Android SDK API version to that
   /// the compiled code will be compatible with.
   ///
   /// Required when [targetOs] equals [OS.android].
   ///
-  /// Not available in [dryRun].
+  /// Not available during a [dryRun].
   ///
   /// For more information about the Android API version, refer to
   /// [`minSdkVersion`](https://developer.android.com/ndk/guides/sdk-versions#minsdkversion)
@@ -73,25 +80,36 @@ abstract class BuildConfig {
   ///
   /// The key in the nested map is the key for the metadata from the dependency.
   ///
-  /// Not available in [dryRun].
+  /// Not available during a [dryRun].
+  @Deprecated('Use getMetadata.')
   Map<String, Metadata>? get dependencyMetadata;
 
+  /// Get the metadata from a direct dependency.
+  ///
+  /// The [packageName] of is the package name of the direct dependency.
+  ///
+  /// Returns `null` if metadata was not provided.
+  ///
+  /// Not available during a [dryRun].
+  Object? metadata(String packageName, String key);
+
   /// The configuration for invoking the C compiler.
   ///
-  /// Not available in [dryRun].
+  /// Not available during a [dryRun].
   CCompilerConfig get cCompiler;
 
-  /// Don't run the build, only report the native assets produced.
+  /// Whether the current run is a "dry run".
+  ///
+  /// If so, the build won't actually be run, but will report the native assets
+  /// which would have been produced.
   bool get dryRun;
 
   /// The build mode that the code should be compiled in.
   ///
-  /// Not available in [dryRun].
+  /// Not available during a [dryRun].
   BuildMode get buildMode;
 
   /// The underlying config.
-  ///
-  /// Can be used for easier access to values on [dependencyMetadata].
   Config get config;
 
   /// The version of [BuildConfig].
@@ -115,7 +133,9 @@ abstract class BuildConfig {
     int? targetAndroidNdkApi,
     CCompilerConfig? cCompiler,
     required LinkModePreference linkModePreference,
+    @Deprecated('Use dependencyMetadata2.')
     Map<String, Metadata>? dependencyMetadata,
+    Map<String, Map<String, Object>>? dependencyMetadata2,
   }) =>
       model.BuildConfig(
         outDir: outDir,
@@ -128,7 +148,12 @@ abstract class BuildConfig {
         targetAndroidNdkApi: targetAndroidNdkApi,
         cCompiler: cCompiler as model.CCompilerConfig?,
         linkModePreference: linkModePreference as model.LinkModePreference,
-        dependencyMetadata: dependencyMetadata?.cast(),
+        dependencyMetadata: dependencyMetadata2 != null
+            ? {
+                for (final entry in dependencyMetadata2.entries)
+                  entry.key: model.Metadata(entry.value.cast())
+              }
+            : dependencyMetadata?.cast(),
       );
 
   factory BuildConfig.dryRun({

pkgs/native_assets_cli/lib/src/api/build_output.dart

@@ -13,30 +13,105 @@ import '../model/metadata.dart' as model;
 import 'asset.dart';
 import 'dependencies.dart';
 import 'metadata.dart';
+import 'target.dart';
 
+/// The output of a `build.dart` invocation.
+///
+/// A package can choose to have a toplevel `build.dart` script. If such a
+/// script exists, it will be automatically run, by the Flutter and Dart SDK
+/// tools. The script is expect to produce a specific output which [BuildOutput]
+/// can produce.
 abstract class BuildOutput {
-  /// Time the build this output belongs to started.
+  // Start time for the build of this output.
   ///
-  /// Rounded down to whole seconds, because [File.lastModified] is rounded
-  /// to whole seconds and caching logic compares these timestamps.
+  /// The [timestamp] is rounded down to whole seconds, because
+  /// [File.lastModified] is rounded to whole seconds and caching logic compares
+  /// these timestamps.
   DateTime get timestamp;
+
+  @Deprecated('Use assets2')
   List<Asset> get assets;
+
+  /// The assets produced by this build.
+  ///
+  /// In dry runs, the assets for all [Architecture]s for the [OS] specified in
+  /// the dry run must be provided.
+  // TODO: Rename to `assets` after removing old one.
+  Iterable<Asset> get assets2;
+
+  @Deprecated('Use dependencies2')
   Dependencies get dependencies;
+
+  /// The files used by this build.
+  ///
+  /// If any of the files in [dependencies2] are modified after [timestamp], the
+  /// build will be re-run.
+  // TODO: Rename to `dependencies` after removing old one.
+  Iterable<Uri> get dependencies2;
+
+  @Deprecated('Use getMetadata')
   Metadata get metadata;
 
+  /// Metadata can to be passed to `build.dart` invocations of dependent
+  /// packages.
+  // TODO(dacoharkes): Rename to metadata.
+  Object? metadata2(String key);
+
+  /// Create a build output.
+  ///
+  /// The [timestamp] must be before any any [dependencies2] are read by the
+  /// build this output belongs to. If the [BuildOutput] object is created at
+  /// the beginning of the `build.dart` script, it can be omitted and will
+  /// default to [DateTime.now]. The [timestamp] is rounded down to whole
+  /// seconds, because [File.lastModified] is rounded to whole seconds and
+  /// caching logic compares these timestamps.
+  ///
+  /// The [Asset]s produced by this build or dry-run can be provided to the
+  /// constructor as [assets], or can be added later using [addAssets]. In dry
+  /// runs, the assets for all [Architecture]s for the [OS] specified in the dry
+  /// run must be provided.
+  ///
+  /// The files used by this build must be passed in [dependencies2] or
+  /// [addDependencies]. If any of these files are modified after [timestamp],
+  /// the build will be re-run.
+  ///
+  /// Metadata can be passed to `build.dart` invocations of dependent packages
+  /// via [metadata2] or [addMetadata].
   factory BuildOutput({
     DateTime? timestamp,
-    List<Asset>? assets,
-    Dependencies? dependencies,
-    Metadata? metadata,
+    Iterable<Asset>? assets,
+    @Deprecated('Use addDependencies.') Dependencies? dependencies,
+    Iterable<Uri>? dependencies2,
+    @Deprecated('Use addMetadata.') Metadata? metadata,
+    Map<String, Object>? metadata2,
   }) =>
       model.BuildOutput(
         timestamp: timestamp,
-        assets: assets?.map((e) => e as model.Asset).toList(),
-        dependencies: dependencies as model.Dependencies?,
-        metadata: metadata as model.Metadata?,
+        assets: assets?.cast<model.Asset>().toList(),
+        dependencies: dependencies2 != null
+            ? model.Dependencies(dependencies2.toList())
+            : dependencies as model.Dependencies?,
+        metadata: metadata2 != null
+            ? model.Metadata(metadata2)
+            : metadata as model.Metadata?,
       );
 
+  /// Adds [Asset]s produced by this build or dry run.
+  ///
+  /// In dry runs, the assets for all [Architecture]s for the [OS] specified in
+  /// the dry run must be provided.
+  void addAssets(Iterable<Asset> assets);
+
+  /// Adds files used by this build.
+  ///
+  /// If any of the files are modified after [timestamp], the build will be
+  /// re-run.
+  void addDependencies(Iterable<Uri> dependencies);
+
+  /// Adds metadata to be passed to `build.dart` invocations of dependent
+  /// packages.
+  void addMetadata(String key, Object value);
+
   /// The version of [BuildOutput].
   ///
   /// This class is used in the protocol between the Dart and Flutter SDKs
@@ -47,5 +122,6 @@ abstract class BuildOutput {
   /// representation in the protocol.
   static Version get version => model.BuildOutput.version;
 
+  /// Write out this build output to a file inside [outDir].
   Future<void> writeToFile({required Uri outDir});
 }

pkgs/native_assets_cli/lib/src/api/dependencies.dart

@@ -4,6 +4,7 @@
 
 import '../model/dependencies.dart' as model;
 
+@Deprecated('Use the methods on BuildOutput.')
 abstract class Dependencies {
   /// The dependencies a build relied on.
   List<Uri> get dependencies;

pkgs/native_assets_cli/lib/src/api/metadata.dart

@@ -4,6 +4,7 @@
 
 import '../model/metadata.dart' as model;
 
+@Deprecated('Use the methods on BuildConfig and BuildOutput.')
 abstract class Metadata {
   Map<String, Object> get metadata;