p-hatan/ mirror

pub repository

mirror.p-hatan.ir

native_assets_cli

0.17.0

A library that contains the argument and file formats for implementing a native assets CLI.

This package is discontinued upstream.

Download archive

Readme

package:native_assets_cli Coverage Status pub package package publisher

This library contains the CLI specification and a default implementation for bundling native code with Dart packages.

Status: Experimental

NOTE: This package is currently experimental and published under the labs.dart.dev pub publisher in order to solicit feedback.

For packages in the labs.dart.dev publisher we generally plan to either graduate the package into a supported publisher (dart.dev, tools.dart.dev) after a period of feedback and iteration, or discontinue the package. These packages have a much higher expected rate of API and breaking changes.

Your feedback is valuable and will help us evolve this package. For bugs, please file an issue in the bug tracker. For general feedback and suggestions for the native assets feature in Dart and Flutter, please comment in dart-lang#50565 or flutter#129757.

Example

A typical layout of a package with native code is:

  • lib/ contains Dart code which uses dart:ffi and package:ffigen to call into native code.
  • src/ contains C/C++/Rust code which is invoked through dart:ffi.
  • hook/build.dart implements the CLI that communicates which native assets to build/bundle with the Dart/Flutter SDK. This file uses the protocol specified in this package.

Example can be found in example/build/.

Usage

To use native asset in Dart, pass --enable-experiment=native-assets. Native assets work on Dart stable, but prefer using the dev releases as we regularly break things.

To use native assets in Flutter, use flutter config --enable-experiment=native-assets and then flutter create --template=package_ffi <package_name>. In Flutter, the experiment is only available on the master channel.

We do breaking changes regularly! So frequently bump package:native_assets_cli and use dev/master SDK for CI.

Development

The development of the feature can be tracked in dart-lang#50565, flutter#129757, and in the issue tracker on this repository.

Changelog

0.17.0

  • Breaking change Removed support for old JSONs. Newer SDKs will not work with older hooks, and the lower bound of this package is bumped. #2199

0.16.0

  • Support relative paths in user-defines to be loaded as absolute paths.

0.15.0

  • Breaking change JSON encoding migration: change written asset type to the namespaced one. Still keep reading the old one. (Old build hooks will keep working with new SDKs.)
  • Bump SDK lower bound to version that understands namespaced asset types. (Version 3.8.0-260.0.dev)

0.14.0

  • Added support for sending assets between build hooks via the ToBuild Routing. This replaces the deprecated Metadata.
  • Added support for user-defines.

0.13.0

  • Breaking change Removed CodeAsset.type, use EncodedAsset.isCodeAsset instead.
  • Breaking change: Removed CodeAsset.os and CodeAsset.architecture. Use CodeConfig.targetOS and CodeConfig.targetArchitecture instead.
  • HookInput.outputDirectory is now based on HookInput.outputDirectoryShared. The outputDirectory now creates its own subdirectory inside outputDirectoryShared.
  • Another overhaul of the JSON encoding. (Old encoding still read and emitted for the time being).

0.12.0

  • Added validation that all URLs in the Input and Output of hooks are absolute.
  • Added addDataAssetDirectories extension method on BuildOutputBuilder.
  • Replaced JSON serialization/deserialization logic with code generated from the JSON schemas documenting the protocol.

0.11.0

  • Breaking change Complete overhaul of the API used in build and link hooks. The BuildConfig is now split in BuildInput and BuildConfig. The input is everything passed in to the hook. The config (a part of the input) is what shouldn't change on subsequent invocations of the same flutter or dart command for the same target. The outputDirectory is the same if the config is the same.
  • Breaking change The output.json is now part of BuildInput.

0.10.0

  • Breaking change The library import paths changed to be per asset type. (This enables extensibility with custom asset types.)
  • Breaking change: Rename supportedAssetTypes to buildAssetTypes. Hooks should no longer fail. Instead, the code should fail at runtime if an asset is missing. This enables (1) code to run if an asset is missing but that code is not invoked at runtime, and (2) doing fallback implementations in Dart if an asset is missing.
  • Breaking change Move BuildMode to package:native_toolchain_c. This way it can be controlled in the build hook together with the OptimizationLevel. Most likely, every package should ship with release. BuildMode.debug should only be used while developing the package locally.
  • Breaking change Move HookConfig.targetOS to CodeConfig. DataAssets and other asset types should not depend on OS for now.
  • Breaking change: Change the behavior of testBuildHook and testCodeBuildHook; instead of defining tests, these methods should now be called from within tests.
  • Move the package:test dependency from a regular dependency (exported to calling packages) to a dev_dependency.

0.9.0

  • Add BuildConfig and LinkConfig outputDirectoryShared.
  • Remove package:native_assets_cli/locking.dart with runUnderDirectoryLock. Hook writers should not use this, the native_assets_builder does this.
  • Fix example packages with RecordUse annotations #1586.
  • Remove v1.0 / v1.1 related serialization
  • Update SDK constraint to 3.5.0+
  • Remove (deprecated) support for accepting yaml as config
  • Remove usage of package:cli_config and package:args: it minimizes dependencies and it simplifies logic any hook has to do (as it no longer has to look into environment variables, arguments and json file, determine which has presence over other, etc)
  • Use DART_HOOK_TESTING prefix for environment variables used for testing on Dart CI
  • No longer try to resolve uris encoded in config.json against any base uri. The hook/{build,link}.dart invoker has to ensure the uris it encodes can be opened as-is (i.e. without resolving against any base uri)
  • Breaking change Moved some methods to be extension methods.
  • Some classes in the BuildConfig and BuildOutput now expose fromJson and toJson.
  • Breaking change Removed Asset class, removed {Build,Link}Output.assets*. Hook writers should now use e.g. output.dataAssets.add(DataAsset(...)) instead of output.addAsset(DataAsset(...)).
  • Breaking change Introduce builder classes that construct hook configs and hook outputs.

0.8.0

  • Add URI for the recorded usages file to the LinkConfig.
  • Added a validation step in the build and link methods.

0.7.3

  • Fix some more cases of: BuildConfig.dependencies and LinkConfig.dependencies no longer have to specify Dart sources.
  • DataAsset examples report all assets from assets/ dir and default the asset names to the path inside the package.
  • Add package:native_assets_cli/test.dart with testBuildHook helper method for testing build hooks.
  • Add package:native_assets_cli/locking.dart with runUnderDirectoryLock.

0.7.2

  • Deprecate metadata concept.

0.7.1

  • BuildConfig.dependencies and LinkConfig.dependencies no longer have to specify Dart sources.

0.7.0

  • BuildConfig constructors now have a required linkingEnabled parameter.

0.6.1

  • Introduce Builder and Linker interface.
  • Copy resources.json to the build directory.
  • Introduce HookConfig.targetIosSdk and HookConfig.targetMacosSdk optional values.

0.6.0

  • Add support for hook/link.dart.

0.5.4

  • Update documentation about providing NativeCodeAsset.file in dry runs.

0.5.3

0.5.2

  • Fix test.

0.5.1

0.5.0

0.4.2

  • Fix dartdoc generation. Hide the implementation details.

0.4.1

  • Breaking change Removed all code not used in build.dart scripts out of the public API.

0.4.0

  • Added example/use_dart_api/ detailing how to use dart_api_dl.h from the Dart SDK in native code.
  • Breaking change Moved code not used in build.dart to package:native_assets_builder.

0.3.2

  • Fixed an issue where Depenendencies.dependencies could not be modified when expected to.

0.3.1

  • Added Target.androidRiscv64.

0.3.0

  • Breaking change Add required BuildConfig.packageName (#142).

0.2.0

  • Breaking change Rename Asset.name to Asset.id (#100).
  • Added topics.
  • Fixed metadata example.
  • Throws FormatExceptions instead of TypeErrors when failing to parse Yaml (#109).

0.1.0

  • Initial version.

Installing

export PUB_HOSTED_URL=https://pub.mirror.p-hatan.ir
flutter pub add native_assets_cli
pubspec.yaml
name: native_assets_cli
description: >-
  A library that contains the argument and file formats for implementing a
  native assets CLI.

version: 0.17.0
repository: https://github.com/dart-lang/native/tree/main/pkgs/native_assets_cli

topics:
  - ffi
  - interop
  - native-assets

resolution: workspace

environment:
  sdk: '>=3.9.0-21.0.dev <4.0.0'

dependencies:
  collection: ^1.19.1
  crypto: ^3.0.6
  logging: ^1.3.0
  meta: ^1.16.0
  pub_semver: ^2.2.0
  yaml: ^3.1.3 # Used for reading pubspec.yaml to obtain the package name

dev_dependencies:
  dart_flutter_team_lints: ^3.5.1
  file_testing: ^3.0.2
  glob: any
  test: ^1.25.15

Version history

VersionPublishedArchiveSHA-256
0.1.02023-07-11T08:33:17.913341ZDownloade41cfa1116f8fc6ed958e85210964e98fbf6567ff87ff16299f8999a10f3868b
0.2.02023-08-07T13:41:45.609070ZDownload51d1af3ebc2437f5883ed749f1877cb82d6a569b0712dad02c8370e6e4f2b5e3
0.3.02023-10-03T12:10:05.263805ZDownloadbc46eb278008f2b5a736e5ebba88536107a698c685df03dcc92ed9a8a4606c1c
0.3.12023-10-27T09:18:31.896473ZDownload773fec4c7ba49a6dfd24176f58c1b3ee644b1ecac162855ec25a9d4fbb25c9b0
0.3.22023-10-27T19:54:56.891865ZDownload3119600043214157fb54f4ef05717a82a7858f35625fe767799c60f3039361c8
0.4.02024-01-11T19:15:33.615565ZDownload96ad94629485cd3a834ff086ea462ecce2822af3815667b39ca2d26accd02dcd
0.4.12024-01-15T10:27:55.518982ZDownload956a600ea41b0579ae90bd47ae4ce65a77f73935b11f4945c41d04a3edfb9fb9
0.4.22024-01-22T16:18:55.618781ZDownload4eb8a94601af0acd50f7e75e1ad15c0db0b046b89256ee994776b6a6d49139b7
0.5.02024-03-22T10:27:20.292859ZDownloadb53b7b057b107a0907a7238280e49cf16328eaefa56effd56eecfdf42353c375
0.5.12024-03-22T15:33:58.464844ZDownloadd9b1f2655703a24cca1fbc18be8d64a3638c3273a80b7db6fecc3dd9f433f660
0.5.22024-03-22T16:57:51.755564ZDownload1a5c26b452433eb6764964f7110ee67564d1f3ce9bd6fe5ac450fb6af7842dc5
0.5.32024-03-25T12:40:42.015519ZDownloadaa257d7c8d2e4bee8339a077d0ddef97f01b28fadb7a379074142782928ab1c3
0.5.42024-03-26T11:13:52.940514ZDownload9c1b67ccf85ec9282f34e5348ae78dcb7da2c7dc965c0265306477d977853a0d
0.6.02024-05-16T13:07:57.163945ZDownloadf54ddc4a3f8cff1d8d63723b4938902da7586a5a47fe3c1bfa226eb80223f32e
0.6.12024-07-05T06:14:54.485160ZDownloaddd11b0b4c7b7477e10c3e40cd9ed4006aec19069cee4cd5f15d81e8076d49ae4
0.7.02024-07-10T09:50:25.680432ZDownload6d6a20513787c3670fc1ed4e00b380dce01282a118cf7b88080dcfef76642e5e
0.7.12024-07-12T14:35:49.878258ZDownloadb94fd14839315dca7a0db87ba05759949746ca61583aa1a58b11cc532bce2c8d
0.7.22024-07-15T13:04:37.778399ZDownload3da9bdd4beb2ed059dae7fd93baa62c5f6c3cdf630bbb88334303dfa92d6da26
0.7.32024-09-02T09:34:28.661292ZDownload1ff032c0ca050391c4c5107485f1a26e0e95cee18d1fdb2b7bdbb990efd3c188
0.8.02024-09-13T11:50:12.574949ZDownloaddb902509468ec2a6c6d11fa9ce02805ede280e8dbfb5f0014ef3de8483cadfce
0.9.02024-11-04T14:53:25.643156ZDownload9573f442a27000af0597639bf8a3db24f23cf6cbab7469ce3b9c80f585075e6b
0.10.02024-12-20T13:02:43.341321ZDownload46b41ae12be818eb15515d1ff83fec0d5516e7e6afdc13e2738bf8da43d6dd52
0.11.02025-01-22T16:23:29.881117ZDownload537e258b4ee782d81344414c722822014c9e5429f2f98a84a0c2e796f71f4798
0.12.02025-03-20T14:28:03.944086ZDownloadbd4cac2c174be1ec0dd86c1bd2b55ffaad6870f7bcf31b2d5d85d0a5fbc40e82
0.13.02025-03-31T09:26:04.541418ZDownload0907c5b85a21ae08dcdd0d2b75061cc614939911c2cab5ac903f35a9fbb2a50b
0.14.02025-04-08T18:03:53.059232ZDownload298ba641e47b44f039601141ab26f6865186b5d05b7f313d45797513d7205b3d
0.15.0-02025-04-11T07:32:28.344733ZDownload06befcd32bc1a17166df5680aaeb4286d3e0b740871134a49060dd9866f1aea2
0.15.02025-04-15T14:14:28.794035ZDownload9e3bf0a7ef9e609836f1de93874e0570bc92b57464181fe9db2a08347873f220
0.16.02025-04-16T16:01:51.600309ZDownloadb5e4ff8d346c81e757403e17dec1d3c58adc561556ac8433d0becff69757b5cb
0.17.02025-04-23T16:02:51.847214ZDownloaddad5e15960ccf485da40aa010c47cab06e9a32fb6dbc336c1a89af325073f6fe
0.18.02025-04-29T09:56:05.792420ZDownload224d3d7eb3fd05ed631a2a19986a2189c009ccda7747f5192096998200d45bfe

Dependencies

collection "^1.19.1"

crypto "^3.0.6"

logging "^1.3.0"

meta "^1.16.0"

pub_semver "^2.2.0"

yaml "^3.1.3"