Add recorded usages URI to API (#1502)

Add an API to retrieve the serialized recorded usages file. Keeping this as a URI decouples it from `package:record_use`, allowing us to evolve that package without needing to update `native_assets_cli`.

cc @mkustermann @dcharkes 

---

<details>
  <summary>Contribution guidelines:</summary><br>

- See our [contributor guide](https://github.com/dart-lang/.github/blob/main/CONTRIBUTING.md) for general expectations for PRs.
- Larger or significant changes should be discussed in an issue before creating a PR.
- Contributions to our repos should follow the [Dart style guide](https://dart.dev/guides/language/effective-dart) and use `dart format`.
- Most changes should add an entry to the changelog and may need to [rev the pubspec package version](https://github.com/dart-lang/sdk/blob/main/docs/External-Package-Maintenance.md#making-a-change).
- Changes to packages require [corresponding tests](https://github.com/dart-lang/.github/blob/main/CONTRIBUTING.md#Testing).

Note that many Dart repos have a weekly cadence for reviewing PRs - please allow for some latency before initial review feedback.
</details>

pkgs/native_assets_builder/lib/src/build_runner/build_runner.dart

@@ -279,7 +279,7 @@ class NativeAssetsBuildRunner {
         targetMacOSVersion: targetMacOSVersion,
         cCompiler: cCompilerConfig,
         targetAndroidNdkApi: targetAndroidNdkApi,
-        resourceIdentifierUri: resourcesFile?.uri,
+        recordedUsagesFile: resourcesFile?.uri,
         assets: buildResult!.assetsForLinking[package.name] ?? [],
         supportedAssetTypes: supportedAssetTypes,
         linkModePreference: linkModePreference,

pkgs/native_assets_cli/CHANGELOG.md

@@ -1,6 +1,6 @@
-## 0.7.4-wip
+## 0.8.0-wip
 
-- Nothing yet.
+- Add URI for the recorded usages file to the `LinkConfig`.
 
 ## 0.7.3
 

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

@@ -7,6 +7,7 @@ import 'dart:io';
 import 'package:args/args.dart';
 import 'package:cli_config/cli_config.dart';
 import 'package:collection/collection.dart';
+import 'package:meta/meta.dart';
 import 'package:pub_semver/pub_semver.dart';
 
 import '../model/hook.dart';
@@ -31,6 +32,12 @@ abstract class LinkConfig implements HookConfig {
   /// `build.dart` script destined for this packages `link.dart`.
   Iterable<Asset> get assets;
 
+  /// The path to the file containing recorded uses after kernel tree-shaking.
+  ///
+  /// The file contents can be parsed using `package:record_use`.
+  @experimental
+  Uri? get recordedUsagesFile;
+
   /// Generate the [LinkConfig] from the input arguments to the linking script.
   factory LinkConfig.fromArguments(List<String> arguments) =>
       LinkConfigImpl.fromArguments(arguments);

pkgs/native_assets_cli/lib/src/model/link_config.dart

@@ -18,11 +18,12 @@ class LinkConfigImpl extends HookConfigImpl implements LinkConfig {
 
   // TODO: Placeholder for the resources.json file URL. We don't want to change
   // native_assets_builder when implementing the parsing.
-  final Uri? resourceIdentifierUri;
+  @override
+  final Uri? recordedUsagesFile;
 
   LinkConfigImpl({
     required this.assets,
-    this.resourceIdentifierUri,
+    this.recordedUsagesFile,
     required super.outputDirectory,
     required super.packageName,
     required super.packageRoot,
@@ -46,7 +47,7 @@ class LinkConfigImpl extends HookConfigImpl implements LinkConfig {
 
   LinkConfigImpl.dryRun({
     required this.assets,
-    this.resourceIdentifierUri,
+    this.recordedUsagesFile,
     required super.outputDirectory,
     required super.packageName,
     required super.packageRoot,
@@ -72,8 +73,8 @@ class LinkConfigImpl extends HookConfigImpl implements LinkConfig {
   @override
   Map<String, Object> toJson() => {
         ...hookToJson(),
-        if (resourceIdentifierUri != null)
-          resourceIdentifierKey: resourceIdentifierUri!.toFilePath(),
+        if (recordedUsagesFile != null)
+          resourceIdentifierKey: recordedUsagesFile!.toFilePath(),
         assetsKey: AssetImpl.listToJson(assets, version),
       }.sortOnKey();
 
@@ -114,12 +115,12 @@ class LinkConfigImpl extends HookConfigImpl implements LinkConfig {
       targetMacOSVersion:
           HookConfigImpl.parseTargetMacOSVersion(config, dryRun, targetOS),
       assets: parseAssets(config),
-      resourceIdentifierUri: parseResourceIdentifier(config),
+      recordedUsagesFile: parseRecordedUsagesUri(config),
       dryRun: dryRun,
     );
   }
 
-  static Uri? parseResourceIdentifier(Config config) =>
+  static Uri? parseRecordedUsagesUri(Config config) =>
       config.optionalPath(resourceIdentifierKey);
 
   static List<AssetImpl> parseAssets(Config config) =>
@@ -133,7 +134,7 @@ class LinkConfigImpl extends HookConfigImpl implements LinkConfig {
     if (other is! LinkConfigImpl) {
       return false;
     }
-    if (other.resourceIdentifierUri != resourceIdentifierUri) {
+    if (other.recordedUsagesFile != recordedUsagesFile) {
       return false;
     }
     if (!const DeepCollectionEquality().equals(other.assets, assets)) {
@@ -145,7 +146,7 @@ class LinkConfigImpl extends HookConfigImpl implements LinkConfig {
   @override
   int get hashCode => Object.hashAll([
         super.hashCode,
-        resourceIdentifierUri,
+        recordedUsagesFile,
         const DeepCollectionEquality().hash(assets),
       ]);
 

pkgs/native_assets_cli/pubspec.yaml

@@ -4,7 +4,7 @@ description: >-
   native assets CLI.
 
 # Note: Bump BuildConfig.version and BuildOutput.version on breaking changes!
-version: 0.7.4-wip
+version: 0.8.0-wip
 repository: https://github.com/dart-lang/native/tree/main/pkgs/native_assets_cli
 
 topics:

pkgs/native_assets_cli/test/model/link_config_test.dart

@@ -20,7 +20,7 @@ void main() async {
   late Uri fakeAr;
   late Uri fakeCl;
   late Uri fakeVcVars;
-  late Uri resources;
+  late Uri recordedUsagesFile;
   final assets = [
     DataAsset(
       package: packageName,
@@ -55,8 +55,8 @@ void main() async {
     await File.fromUri(fakeCl).create();
     fakeVcVars = tempUri.resolve('vcvarsall.bat');
     await File.fromUri(fakeVcVars).create();
-    resources = tempUri.resolve('resources.json');
-    File.fromUri(resources).createSync();
+    recordedUsagesFile = tempUri.resolve('recorded_usages.json');
+    File.fromUri(recordedUsagesFile).createSync();
   });
 
   tearDown(() async {
@@ -78,7 +78,7 @@ void main() async {
       ),
       buildMode: BuildModeImpl.release,
       assets: assets,
-      resourceIdentifierUri: resources,
+      recordedUsagesFile: recordedUsagesFile,
       linkModePreference: LinkModePreferenceImpl.preferStatic,
     );
 
@@ -91,7 +91,7 @@ void main() async {
       targetAndroidNdkApi: 30,
       buildMode: BuildModeImpl.release,
       assets: [],
-      resourceIdentifierUri: null,
+      recordedUsagesFile: null,
       linkModePreference: LinkModePreferenceImpl.preferStatic,
     );
 
@@ -330,7 +330,7 @@ void main() async {
       targetAndroidNdkApi: 30,
       buildMode: BuildModeImpl.release,
       assets: assets,
-      resourceIdentifierUri: resources,
+      recordedUsagesFile: recordedUsagesFile,
       linkModePreference: LinkModePreferenceImpl.preferStatic,
     );
     final configFileContents = buildConfig.toJsonString();