From 64e0f53f0934ecade81af972b25939366a2a2d4a Mon Sep 17 00:00:00 2001 From: Daco Harkes Date: Thu, 9 Oct 2025 16:21:48 +0200 Subject: [PATCH 1/2] [hooks] [code_assets] Library dartdoc comments --- .../example/api/code_config_snippet.dart | 23 ++++++++++ pkgs/code_assets/lib/code_assets.dart | 45 +++++++++++++++---- pkgs/hooks/lib/hooks.dart | 42 +++++++++++++++-- 3 files changed, 98 insertions(+), 12 deletions(-) create mode 100644 pkgs/code_assets/example/api/code_config_snippet.dart diff --git a/pkgs/code_assets/example/api/code_config_snippet.dart b/pkgs/code_assets/example/api/code_config_snippet.dart new file mode 100644 index 000000000..10cb7ae24 --- /dev/null +++ b/pkgs/code_assets/example/api/code_config_snippet.dart @@ -0,0 +1,23 @@ +// 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. + +// ignore_for_file: unused_local_variable + +// snippet-start +import 'package:code_assets/code_assets.dart'; +import 'package:hooks/hooks.dart'; + +void main(List args) async { + await build(args, (input, output) async { + if (input.config.buildCodeAssets) { + final codeConfig = input.config.code; + final targetOS = codeConfig.targetOS; + final targetArchitecture = codeConfig.targetArchitecture; + + // Add some code assets. + } + }); +} + +// snippet-end diff --git a/pkgs/code_assets/lib/code_assets.dart b/pkgs/code_assets/lib/code_assets.dart index 75903f51a..80942c652 100644 --- a/pkgs/code_assets/lib/code_assets.dart +++ b/pkgs/code_assets/lib/code_assets.dart @@ -2,15 +2,24 @@ // 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. +/// @docImport 'package:hooks/hooks.dart'; /// @docImport 'src/code_assets/code_asset.dart'; /// @docImport 'src/code_assets/config.dart'; -/// Code asset support for hook authors. +/// This package provides the API for code assets to be used with +/// [`package:hooks`](https://pub.dev/packages/hooks). +/// +/// A [CodeAsset] is an asset containing executable code which respects the +/// native application binary interface (ABI). These assets are bundled with a +/// Dart or Flutter application. They can be produced by compiling C, C++, +/// Objective-C, Rust, or Go code for example. /// -/// A code asset is an asset containing executable code which respects the -/// native application binary interface (ABI). +/// This package is used in a build hook (`hook/build.dart`) to inform the Dart +/// and Flutter SDKs about the code assets that need to be bundled with an +/// application. /// -/// Code assets can be added in a build hook as follows: +/// [CodeAsset] can be added to the [BuildOutputBuilder] a build hook as +/// follows: /// /// /// ```dart @@ -34,13 +43,31 @@ /// } /// ``` /// -/// See [CodeAsset] and [BuildOutputCodeAssetBuilder.add] for more details. +/// The [CodeConfig] nested in the [HookInput] gives access to configuration +/// specifically for compiling code assets. For example [CodeConfig.targetOS] +/// and [CodeConfig.targetArchitecture] give access to the target OS and +/// architecture that the code assets are compiled for: /// -/// For more documentation of hooks, refer to the API docs of -/// [`package:hooks`](https://pub.dev/packages/hooks). +/// +/// ```dart +/// import 'package:code_assets/code_assets.dart'; +/// import 'package:hooks/hooks.dart'; +/// +/// void main(List args) async { +/// await build(args, (input, output) async { +/// if (input.config.buildCodeAssets) { +/// final codeConfig = input.config.code; +/// final targetOS = codeConfig.targetOS; +/// final targetArchitecture = codeConfig.targetArchitecture; +/// +/// // Add some code assets. +/// } +/// }); +/// } +/// ``` /// -/// When compiling C, C++ or Objective-C code from source, consider using -/// [`package:native_toolchain_c`](https://pub.dev/packages/native_toolchain_c). +/// For more information about build hooks see +/// [dart.dev/tools/hooks](https://dart.dev/tools/hooks). library; export 'src/code_assets/architecture.dart' show Architecture; diff --git a/pkgs/hooks/lib/hooks.dart b/pkgs/hooks/lib/hooks.dart index 18dfac26a..332649944 100644 --- a/pkgs/hooks/lib/hooks.dart +++ b/pkgs/hooks/lib/hooks.dart @@ -4,10 +4,46 @@ /// @docImport 'src/api/build_and_link.dart'; -/// A library that contains the protocol for implementing hooks. +/// This package provides the API for hooks in Dart. Hooks are Dart scripts +/// placed in the `hook/` directory of a Dart package, designed to automate +/// tasks for a Dart package. /// -/// The main entrypoint for build hooks (`hook/build.dart`) is [build]. The main -/// entrypoint for link hooks (`hook/link.dart`) is [link]. +/// Currently, the main supported hook is the build hook (`hook/build.dart`). +/// The build hook is executed during a Dart build and enables you to bundle +/// assets with a Dart package. The main entrypoint for build hooks is [build]. +/// +/// The second hook available in this API is the link hook (`hook/link.dart`). +/// The main entrypoint for link hooks is [link]. +/// +/// Hooks can for example be used to bundle native code with a Dart package: +/// +/// +/// ```dart +/// import 'package:code_assets/code_assets.dart'; +/// import 'package:hooks/hooks.dart'; +/// import 'package:native_toolchain_c/native_toolchain_c.dart'; +/// +/// void main(List args) async { +/// await build(args, (input, output) async { +/// if (input.config.buildCodeAssets) { +/// final builder = CBuilder.library( +/// name: 'sqlite3', +/// assetName: 'src/third_party/sqlite3.g.dart', +/// sources: ['third_party/sqlite/sqlite3.c'], +/// defines: { +/// if (input.config.code.targetOS == OS.windows) +/// // Ensure symbols are exported in dll. +/// 'SQLITE_API': '__declspec(dllexport)', +/// }, +/// ); +/// await builder.run(input: input, output: output); +/// } +/// }); +/// } +/// ``` +/// +/// For more information see +/// [dart.dev/tools/hooks](https://dart.dev/tools/hooks). library; export 'src/api/build_and_link.dart' show build, link; From 15fe85fd023325aa5695eb0083b57e31f8e4248c Mon Sep 17 00:00:00 2001 From: Daco Harkes Date: Fri, 10 Oct 2025 17:26:14 +0200 Subject: [PATCH 2/2] address comment --- pkgs/code_assets/lib/code_assets.dart | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pkgs/code_assets/lib/code_assets.dart b/pkgs/code_assets/lib/code_assets.dart index 80942c652..21abce5b6 100644 --- a/pkgs/code_assets/lib/code_assets.dart +++ b/pkgs/code_assets/lib/code_assets.dart @@ -18,7 +18,7 @@ /// and Flutter SDKs about the code assets that need to be bundled with an /// application. /// -/// [CodeAsset] can be added to the [BuildOutputBuilder] a build hook as +/// A [CodeAsset] can be added to the [BuildOutputBuilder] in a build hook as /// follows: /// ///