From b7b8e001f0c82bb7b98e3765e4eb6e97f4ec4919 Mon Sep 17 00:00:00 2001 From: Daco Harkes Date: Fri, 10 Jan 2025 12:29:21 +0100 Subject: [PATCH] [native_assets_cli] [doc] Add READMEs for examples (#1878) Add READMEs for the current set of supported use cases. I added a cross-link to the transformer test case so it doubles as example. Closes: https://github.com/dart-lang/native/issues/1375 --- .../test_data/transformer/README.md | 17 +++++++ .../native_assets_cli/example/build/README.md | 47 +++++++++++++++---- .../example/build/local_asset/README.md | 16 +++++-- 3 files changed, 67 insertions(+), 13 deletions(-) create mode 100644 pkgs/native_assets_builder/test_data/transformer/README.md diff --git a/pkgs/native_assets_builder/test_data/transformer/README.md b/pkgs/native_assets_builder/test_data/transformer/README.md new file mode 100644 index 0000000000..d754ec4742 --- /dev/null +++ b/pkgs/native_assets_builder/test_data/transformer/README.md @@ -0,0 +1,17 @@ +An example of a library that transforms some source files and bundles them as +data assets. + +## Usage + +Data assets are not yet consumable in Dart and Flutter. +This package is for illustration purposes only. + +## Code organization + +A typical layout of a package with data assets: + +* `data/` contains source files. +* `hook/build.dart` loops over all these files and transforms them. It reports + the transformed files as data assets. The file transformations are cached + within the hook to prevent retransforming the files if the sources didn't + change. diff --git a/pkgs/native_assets_cli/example/build/README.md b/pkgs/native_assets_cli/example/build/README.md index 1be681f6c0..fad771d891 100644 --- a/pkgs/native_assets_cli/example/build/README.md +++ b/pkgs/native_assets_cli/example/build/README.md @@ -1,9 +1,38 @@ -The examples in this folder illustrate how native code is built and bundled -in Dart and Flutter apps. - -* [native_add_app/](native_add_app/) has a dependency with C code. - This app should declare nothing special. Dart and Flutter should check - all dependencies for native code. -* [native_add_library/](native_add_library/) contains a library with C code. - When Dart code in this library or dependent on this library is invoked, the - C code must be built and bundled so that it can be used by the Dart code. +The examples in this folder illustrate how assets are built and bundled in Dart +and Flutter apps. + +Currently two main asset types are supported in `package:native_assets_cli`: + * Native libraries + * Data assets + +Note that Data assets are not yet consumable in Dart and Flutter. + +Examples: + +* Bundling C/C++/Objective-C source code in a package. This native code is built on the developers' machine when such package is a dependency. + * [native_add_library/](native_add_library/) contains a library with C code. + When Dart code in this library or dependent on this library is invoked, the + C code must be built and bundled so that it can be used by the Dart code. + * [native_add_app/](native_add_app/) has a dependency with C code. + This app should declare nothing special. Dart and Flutter should check + all dependencies for native code. +* Bundling prebuilt native libaries. + * [download_asset/](download_asset/) is very similar to + [native_add_library/](native_add_library/), but instead of building the + native code on the machine of developers pulling in the package, the native + libraries are prebuilt in GitHub actions and downloaded in the build hook. +* Bundling multiple dynamic libraries depending on each other. + * [native_dynamic_linking/](native_dynamic_linking/) contains source code for + 3 native libraries that depend on each other and load each other with the + native dynamic loader at runtime. +* Building dynamic libraries against `dart_api_dl.h`. + * [use_dart_api/](use_dart_api/) contains a library with C code that invokes + `dart_api_dl.h` to interact with the Dart runtime. +* Bundling all files in a directory as data assets. + * [local_asset/](local_asset/) contains a package that bundles all files in + the `assets/` directory as data assets. +* Transforming files and bundling them as data assets. + * [transformer/](../../../native_assets_builder/test_data/transformer/README.md) + contains a package that transforms files and bundles the result as data + assets. The hook uses caching internally to prevent retransforming files if + not needed. diff --git a/pkgs/native_assets_cli/example/build/local_asset/README.md b/pkgs/native_assets_cli/example/build/local_asset/README.md index 3ffe34cafd..aa68abbde7 100644 --- a/pkgs/native_assets_cli/example/build/local_asset/README.md +++ b/pkgs/native_assets_cli/example/build/local_asset/README.md @@ -1,5 +1,13 @@ -This example shows two use cases: +An example of a library bundling all files in a directory as data assets. -* Data assets that are part of the package source code. -* Code assets which are downloaded from the cloud. - (It doesn't show how to download, but shows how to implement the protocol correctly.) +## Usage + +Data assets are not yet consumable in Dart and Flutter. +This package is for illustration purposes only. + +## Code organization + +A typical layout of a package with data assets: + +* `assets/` contains data assets. +* `hook/build.dart` reports all these files as data assets.