[code_assets] [data_assets] Document absolute paths (#2712)

Author: dcharkes

pkgs/code_assets/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.19.9
+
+- Document that asset file paths must be absolute.
+
 ## 0.19.8
 
 - Polished README.md, Dartdocs, and examples.

pkgs/code_assets/lib/src/code_assets/code_asset.dart

@@ -60,10 +60,11 @@ final class CodeAsset {
   /// Either dynamic loading or static linking.
   final LinkMode linkMode;
 
-  /// The file to be bundled with the Dart or Flutter application.
+  /// The native library to be bundled with the Dart or Flutter application.
   ///
   /// If the [linkMode] is [DynamicLoadingBundled], the file must be provided
-  /// and exist.
+  /// and exist. The path must be an absolute path. Prefer constructing the path
+  /// via [HookInput.outputDirectoryShared] or [HookInput.outputDirectory].
   ///
   /// If the [linkMode] is [DynamicLoadingSystem], the file must be provided,
   /// and not exist.

pkgs/code_assets/lib/src/code_assets/config.dart

@@ -165,10 +165,18 @@ final class BuildOutputCodeAssetBuilder {
   BuildOutputCodeAssetBuilder._(this._output);
 
   /// Adds the given [asset] to the hook output with [routing].
+  ///
+  /// The [CodeAsset.file], if provided, must be an absolute path. Prefer
+  /// constructing the path via [HookInput.outputDirectoryShared] or
+  /// [HookInput.outputDirectory].
   void add(CodeAsset asset, {AssetRouting routing = const ToAppBundle()}) =>
       _output.addEncodedAsset(asset.encode(), routing: routing);
 
   /// Adds the given [assets] to the hook output with [routing].
+  ///
+  /// The [CodeAsset.file]s, if provided, must be absolute paths. Prefer
+  /// constructing the paths via [HookInput.outputDirectoryShared] or
+  /// [HookInput.outputDirectory].
   void addAll(
     Iterable<CodeAsset> assets, {
     AssetRouting routing = const ToAppBundle(),

pkgs/code_assets/lib/src/code_assets/validation.dart

@@ -301,7 +301,10 @@ ValidationErrors _validateFile(
 }) {
   final errors = <String>[];
   if (mustBeAbsolute && !uri.isAbsolute) {
-    errors.add('$name (${uri.toFilePath()}) must be an absolute path.');
+    errors.add(
+      '$name (${uri.toFilePath()}) must be an absolute path. '
+      'Prefer constructing it via `input.outputDirectoryShared`.',
+    );
   }
   if (mustExist && !File.fromUri(uri).existsSync()) {
     errors.add('$name (${uri.toFilePath()}) does not exist as a file.');

pkgs/code_assets/pubspec.yaml

@@ -3,7 +3,7 @@ description: >-
   This library contains the hook protocol specification for bundling native code
   with Dart packages.
 
-version: 0.19.8
+version: 0.19.9
 
 repository: https://github.com/dart-lang/native/tree/main/pkgs/code_assets
 

pkgs/data_assets/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.19.4
+
+- Document that asset file paths must be absolute.
+
 ## 0.19.3
 
 - Added a library comment detailing how to use the package.

pkgs/data_assets/lib/src/data_assets/config.dart

@@ -119,10 +119,20 @@ final class BuildOutputDataAssetsBuilder {
   BuildOutputDataAssetsBuilder._(this._output);
 
   /// Adds the given [asset] to the hook output with [routing].
+  ///
+  /// The [DataAsset.file] must be an absolute path. Prefer constructing the
+  /// path via [HookInput.outputDirectoryShared] or [HookInput.outputDirectory]
+  /// for files emitted during a hook, and via [HookInput.packageRoot] for files
+  /// which are part of the package.
   void add(DataAsset asset, {AssetRouting routing = const ToAppBundle()}) =>
       _output.addEncodedAsset(asset.encode(), routing: routing);
 
   /// Adds the given [assets] to the hook output with [routing].
+  ///
+  /// The [DataAsset.file]s must be absolute paths. Prefer constructing the
+  /// path via [HookInput.outputDirectoryShared] or [HookInput.outputDirectory]
+  /// for files emitted during a hook, and via [HookInput.packageRoot] for files
+  /// which are part of the package.
   void addAll(
     Iterable<DataAsset> assets, {
     AssetRouting routing = const ToAppBundle(),

pkgs/data_assets/lib/src/data_assets/data_asset.dart

@@ -18,9 +18,10 @@ import 'syntax.g.dart';
 final class DataAsset {
   /// The file to be bundled with the Dart or Flutter application.
   ///
-  /// The file can also be omitted for asset types which refer to an asset
-  /// already present on the target system or an asset already present in Dart
-  /// or Flutter.
+  /// The path must be an absolute path. Prefer constructing the path via
+  /// [HookInput.outputDirectoryShared] or [HookInput.outputDirectory] for files
+  /// emitted during a hook, and via [HookInput.packageRoot] for files which are
+  /// part of the package.
   final Uri file;
 
   /// The name of this asset, which must be unique for the package.

pkgs/data_assets/lib/src/data_assets/validation.dart

@@ -129,7 +129,11 @@ ValidationErrors _validateFile(
 }) {
   final errors = <String>[];
   if (mustBeAbsolute && !uri.isAbsolute) {
-    errors.add('$name (${uri.toFilePath()}) must be an absolute path.');
+    errors.add(
+      '$name (${uri.toFilePath()}) must be an absolute path. '
+      'Prefer constructing it via `input.outputDirectoryShared` or '
+      '`input.packageRoot`.',
+    );
   }
   if (mustExist && !File.fromUri(uri).existsSync()) {
     errors.add('$name (${uri.toFilePath()}) does not exist as a file.');

pkgs/data_assets/pubspec.yaml

@@ -3,7 +3,7 @@ description: >-
   This library contains the hook protocol specification for bundling data assets
   with Dart packages.
 
-version: 0.19.3
+version: 0.19.4
 
 repository: https://github.com/dart-lang/native/tree/main/pkgs/data_assets