[native_assets_cli] Add example using dart_api_dl.h (#858)

Example showing how to use `dart_api_dl.h` in native assets.

Does **not** address yet:

* #839

Author: dcharkes

.github/workflows/native.yaml

@@ -92,6 +92,9 @@ jobs:
       - run: dart pub get -C example/native_add_library/
         if: ${{ matrix.package == 'native_assets_cli' }}
 
+      - run: dart pub get -C example/use_dart_api/
+        if: ${{ matrix.package == 'native_assets_cli' }}
+
       - run: dart analyze --fatal-infos
         # Run on dev to ensure we're not depending on deprecated SDK things.
 
@@ -121,6 +124,10 @@ jobs:
         working-directory: pkgs/${{ matrix.package }}/example/native_add_app/bin/native_add_app/
         if: ${{ matrix.package == 'native_assets_cli' && matrix.sdk == 'dev' && !matrix.breaking-change }}
 
+      - run: dart --enable-experiment=native-assets test
+        working-directory: pkgs/${{ matrix.package }}/example/use_dart_api/
+        if: ${{ matrix.package == 'native_assets_cli' && matrix.sdk == 'dev' && !matrix.breaking-change }}
+
       - name: Install coverage
         run: dart pub global activate coverage
         if: ${{ matrix.sdk == 'stable' && matrix.dependencies == 'published' }}

pkgs/native_assets_cli/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 0.3.3-wip
+
+- Added [example/use_dart_api/](example/use_dart_api/) detailing how to use
+  `dart_api_dl.h` from the Dart SDK in native code.
+
 ## 0.3.2
 
 - Fixed an issue where `Depenendencies.dependencies` could not be

pkgs/native_assets_cli/example/use_dart_api/README.md

@@ -0,0 +1,18 @@
+An example that uses the [C API of the Dart VM].
+
+The example shows how to pass an object from the Dart heap to native code and
+hold on to it via a `PersistentHandle`. For more documentation about handles,
+and the other C API features refer to the documentation in the header files.
+
+## Usage
+
+Run tests with `dart --enable-experiment=native-assets test`.
+
+## Open TODOs
+
+It would be better to receive a path the include folder containing the C API
+rather than having to copy it into the `src/` directory.
+
+* https://github.com/dart-lang/native/issues/839
+
+[C API of the Dart VM]: https://github.com/dart-lang/sdk/tree/main/runtime/include

pkgs/native_assets_cli/example/use_dart_api/build.dart

@@ -0,0 +1,32 @@
+// Copyright (c) 2023, 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.
+
+import 'package:logging/logging.dart';
+import 'package:native_assets_cli/native_assets_cli.dart';
+import 'package:native_toolchain_c/native_toolchain_c.dart';
+
+const packageName = 'use_dart_api';
+
+void main(List<String> args) async {
+  final buildConfig = await BuildConfig.fromArgs(args);
+  final buildOutput = BuildOutput();
+  final cbuilder = CBuilder.library(
+    name: packageName,
+    assetId: 'package:$packageName/src/${packageName}_bindings_generated.dart',
+    sources: [
+      'src/$packageName.c',
+      'src/dart_api_dl.c',
+    ],
+  );
+  await cbuilder.run(
+    buildConfig: buildConfig,
+    buildOutput: buildOutput,
+    logger: Logger('')
+      ..level = Level.ALL
+      ..onRecord.listen((record) {
+        print('${record.level.name}: ${record.time}: ${record.message}');
+      }),
+  );
+  await buildOutput.writeToFile(outDir: buildConfig.outDir);
+}

pkgs/native_assets_cli/example/use_dart_api/ffigen.yaml

@@ -0,0 +1,20 @@
+# Run with `flutter pub run ffigen --config ffigen.yaml`.
+name: NativeAddBindings
+description: |
+  Bindings for `src/use_dart_api.h`.
+
+  Regenerate bindings with `flutter pub run ffigen --config ffigen.yaml`.
+output: "lib/src/use_dart_api_bindings_generated.dart"
+headers:
+  entry-points:
+    - "src/use_dart_api.h"
+  include-directives:
+    - "src/use_dart_api.h"
+preamble: |
+  // Copyright (c) 2023, 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.
+comments:
+  style: any
+  length: full
+ffi-native:

pkgs/native_assets_cli/example/use_dart_api/lib/src/use_dart_api_bindings_generated.dart

@@ -0,0 +1,32 @@
+// Copyright (c) 2023, 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.
+
+// AUTO GENERATED FILE, DO NOT EDIT.
+//
+// Generated by `package:ffigen`.
+// ignore_for_file: type=lint
+import 'dart:ffi' as ffi;
+
+@ffi.Native<ffi.Int32 Function(ffi.Int32, ffi.Int32)>(symbol: 'add')
+external int add(
+  int a,
+  int b,
+);
+
+@ffi.Native<ffi.IntPtr Function(ffi.Pointer<ffi.Void>)>(symbol: 'InitDartApiDL')
+external int InitDartApiDL(
+  ffi.Pointer<ffi.Void> data,
+);
+
+@ffi.Native<ffi.Pointer<ffi.Void> Function(ffi.Handle)>(
+    symbol: 'NewPersistentHandle')
+external ffi.Pointer<ffi.Void> NewPersistentHandle(
+  Object non_persistent_handle,
+);
+
+@ffi.Native<ffi.Handle Function(ffi.Pointer<ffi.Void>)>(
+    symbol: 'HandleFromPersistent')
+external Object HandleFromPersistent(
+  ffi.Pointer<ffi.Void> persistent_handle,
+);

pkgs/native_assets_cli/example/use_dart_api/lib/use_dart_api.dart

@@ -0,0 +1,5 @@
+// Copyright (c) 2023, 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.
+
+export 'src/use_dart_api_bindings_generated.dart';

pkgs/native_assets_cli/example/use_dart_api/manifest.yaml

@@ -0,0 +1,10 @@
+- build.dart
+- ffigen.yaml
+- lib/native_add.dart
+- lib/src/native_add_bindings_generated.dart
+- lib/src/native_add.dart
+- pubspec.yaml
+- pubspec_overrides.yaml
+- src/native_add.c
+- src/native_add.h
+- test/native_add_test.dart

pkgs/native_assets_cli/example/use_dart_api/pubspec.yaml

@@ -0,0 +1,19 @@
+name: use_dart_api
+description: Uses some functions from `dart_api_dl.h`.
+version: 0.1.0
+
+publish_to: none
+
+environment:
+  sdk: ">=3.0.0 <4.0.0"
+
+dependencies:
+  cli_config: ^0.1.1
+  logging: ^1.1.1
+  native_assets_cli: ^0.3.2
+  native_toolchain_c: ^0.3.2
+
+dev_dependencies:
+  ffigen: ^10.0.0
+  lints: ^3.0.0
+  test: ^1.23.1

pkgs/native_assets_cli/example/use_dart_api/pubspec_overrides.yaml

@@ -0,0 +1,5 @@
+dependency_overrides:
+  native_assets_cli:
+    path: ../../../native_assets_cli/
+  native_toolchain_c:
+    path: ../../../native_toolchain_c/