From c21d1562f0547a3e4e915b7cc8392e4150e77436 Mon Sep 17 00:00:00 2001 From: Daco Harkes Date: Sat, 18 Oct 2025 07:01:49 -0300 Subject: [PATCH 1/3] [code_assets] [data_assets] Document absolute paths --- pkgs/code_assets/lib/src/code_assets/code_asset.dart | 5 +++-- pkgs/code_assets/lib/src/code_assets/config.dart | 8 ++++++++ pkgs/data_assets/lib/src/data_assets/config.dart | 10 ++++++++++ pkgs/data_assets/lib/src/data_assets/data_asset.dart | 7 ++++--- 4 files changed, 25 insertions(+), 5 deletions(-) diff --git a/pkgs/code_assets/lib/src/code_assets/code_asset.dart b/pkgs/code_assets/lib/src/code_assets/code_asset.dart index 1aec76d8ce..04c893dcd4 100644 --- a/pkgs/code_assets/lib/src/code_assets/code_asset.dart +++ b/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. diff --git a/pkgs/code_assets/lib/src/code_assets/config.dart b/pkgs/code_assets/lib/src/code_assets/config.dart index 1d7a156242..78772cf83c 100644 --- a/pkgs/code_assets/lib/src/code_assets/config.dart +++ b/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 assets, { AssetRouting routing = const ToAppBundle(), diff --git a/pkgs/data_assets/lib/src/data_assets/config.dart b/pkgs/data_assets/lib/src/data_assets/config.dart index a4ac3d319d..8d691328d1 100644 --- a/pkgs/data_assets/lib/src/data_assets/config.dart +++ b/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 assets, { AssetRouting routing = const ToAppBundle(), diff --git a/pkgs/data_assets/lib/src/data_assets/data_asset.dart b/pkgs/data_assets/lib/src/data_assets/data_asset.dart index 90961df626..df811b82c8 100644 --- a/pkgs/data_assets/lib/src/data_assets/data_asset.dart +++ b/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. From 64ac46573248bf4564fe97ae8b058d53cd023ecd Mon Sep 17 00:00:00 2001 From: Daco Harkes Date: Sat, 18 Oct 2025 07:03:43 -0300 Subject: [PATCH 2/3] chore: [code_assets] [data_assets] update versions and changelogs --- pkgs/code_assets/CHANGELOG.md | 4 ++++ pkgs/code_assets/pubspec.yaml | 2 +- pkgs/data_assets/CHANGELOG.md | 4 ++++ pkgs/data_assets/pubspec.yaml | 2 +- 4 files changed, 10 insertions(+), 2 deletions(-) diff --git a/pkgs/code_assets/CHANGELOG.md b/pkgs/code_assets/CHANGELOG.md index e67e3b88ad..45b482537d 100644 --- a/pkgs/code_assets/CHANGELOG.md +++ b/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. diff --git a/pkgs/code_assets/pubspec.yaml b/pkgs/code_assets/pubspec.yaml index 4b04c8cada..ac7cab11e0 100644 --- a/pkgs/code_assets/pubspec.yaml +++ b/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 diff --git a/pkgs/data_assets/CHANGELOG.md b/pkgs/data_assets/CHANGELOG.md index 564be0099f..1b999e6b20 100644 --- a/pkgs/data_assets/CHANGELOG.md +++ b/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. diff --git a/pkgs/data_assets/pubspec.yaml b/pkgs/data_assets/pubspec.yaml index 3885fcc1e1..0dd43ccb3a 100644 --- a/pkgs/data_assets/pubspec.yaml +++ b/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 From ffc989db5053432c0d28403d2117084da168318b Mon Sep 17 00:00:00 2001 From: Daco Harkes Date: Sat, 18 Oct 2025 07:08:19 -0300 Subject: [PATCH 3/3] Elaborate error message --- pkgs/code_assets/lib/src/code_assets/validation.dart | 5 ++++- pkgs/data_assets/lib/src/data_assets/validation.dart | 6 +++++- 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/pkgs/code_assets/lib/src/code_assets/validation.dart b/pkgs/code_assets/lib/src/code_assets/validation.dart index 86b6d3d12c..432b2ae451 100644 --- a/pkgs/code_assets/lib/src/code_assets/validation.dart +++ b/pkgs/code_assets/lib/src/code_assets/validation.dart @@ -301,7 +301,10 @@ ValidationErrors _validateFile( }) { final errors = []; 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.'); diff --git a/pkgs/data_assets/lib/src/data_assets/validation.dart b/pkgs/data_assets/lib/src/data_assets/validation.dart index 40f6fb4b54..4f46e8bdc4 100644 --- a/pkgs/data_assets/lib/src/data_assets/validation.dart +++ b/pkgs/data_assets/lib/src/data_assets/validation.dart @@ -129,7 +129,11 @@ ValidationErrors _validateFile( }) { final errors = []; 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.');