Skip to content

Commit 22b4f5e

Browse files
dcharkesdcharkes
authored
[doc] Add READMEs, expand examples (#76)
1 parent efd6224 commit 22b4f5e

File tree

24 files changed

+222
-33
lines changed

24 files changed

+222
-33
lines changed

‎.github/workflows/dart.yaml‎

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,10 @@ jobs:
6767
- run: dart pub get -C test/data/package_with_metadata/
6868
if: ${{ matrix.package == 'native_assets_builder' }}
6969

70-
- run: dart pub get -C example/native_add/
70+
- run: dart pub get -C example/native_add_app/
71+
if: ${{ matrix.package == 'native_assets_cli' }}
72+
73+
- run: dart pub get -C example/native_add_library/
7174
if: ${{ matrix.package == 'native_assets_cli' }}
7275

7376
- run: dart analyze --fatal-infos
@@ -83,6 +86,31 @@ jobs:
8386
- run: dart test
8487
if: ${{ matrix.sdk == 'stable' }}
8588

89+
# This might temporarily break when doing breaking changes.
90+
- run: dart --enable-experiment=native-assets test
91+
working-directory: pkgs/${{ matrix.package }}/example/native_add_app/
92+
if: ${{ matrix.package == 'native_assets_cli' && matrix.sdk == 'dev' }}
93+
94+
# This might temporarily break when doing breaking changes.
95+
- run: dart --enable-experiment=native-assets test
96+
working-directory: pkgs/${{ matrix.package }}/example/native_add_app/
97+
if: ${{ matrix.package == 'native_assets_cli' && matrix.sdk == 'dev' }}
98+
99+
# This might temporarily break when doing breaking changes.
100+
- run: dart --enable-experiment=native-assets run
101+
working-directory: pkgs/${{ matrix.package }}/example/native_add_app/
102+
if: ${{ matrix.package == 'native_assets_cli' && matrix.sdk == 'dev' }}
103+
104+
# This might temporarily break when doing breaking changes.
105+
- run: dart --enable-experiment=native-assets build bin/native_add_app.dart
106+
working-directory: pkgs/${{ matrix.package }}/example/native_add_app/
107+
if: ${{ matrix.package == 'native_assets_cli' && matrix.sdk == 'dev' }}
108+
109+
# This might temporarily break when doing breaking changes.
110+
- run: ./native_add_app.exe
111+
working-directory: pkgs/${{ matrix.package }}/example/native_add_app/bin/native_add_app/
112+
if: ${{ matrix.package == 'native_assets_cli' && matrix.sdk == 'dev' }}
113+
86114
- name: Install coverage
87115
run: dart pub global activate coverage
88116
if: ${{ matrix.sdk == 'stable' }}

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,15 @@
44
## Overview
55

66
This repository is home to Dart packages related to FFI and native assets
7-
bundling.
7+
building and bundling.
88

99
## Packages
1010

1111
| Package | Description | Version |
1212
| -------------------------------------------- | ------------------------------------------------------------------------------------------- | ------- |
1313
| [c_compiler](pkgs/c_compiler/) | A library to invoke the native C compiler installed on the host machine. | |
14-
| [native_assets_cli](pkgs/native_assets_cli/) | A library that contains the argument and file formats for implementing a native assets CLI. | |
1514
| [native_assets_builder](pkgs/native_assets_builder/) | A library that contains the logic for building native assets. This should not be used by users, and is used as shared implementation between dartdev and flutter_tools. | |
15+
| [native_assets_cli](pkgs/native_assets_cli/) | A library that contains the argument and file formats for implementing a native assets CLI. | |
1616

1717
<!-- ## Publishing automation
1818

‎pkgs/c_compiler/README.md‎

Lines changed: 22 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,26 @@
11
[![dart](https://github.com/dart-lang/native/actions/workflows/dart.yaml/badge.svg)](https://github.com/dart-lang/native/actions/workflows/dart.yaml)
2-
[![pub package](https://img.shields.io/pub/v/c_compiler.svg)](https://pub.dev/packages/c_compiler)
32
[![Coverage Status](https://coveralls.io/repos/github/dart-lang/native/badge.svg?branch=main)](https://coveralls.io/github/dart-lang/native?branch=main)
4-
<!-- [![package publisher](https://img.shields.io/pub/publisher/c_compiler.svg)](https://pub.dev/packages/c_compiler/publisher) -->
3+
[![pub package](https://img.shields.io/pub/v/c_compiler.svg)](https://pub.dev/packages/c_compiler)
4+
[![package publisher](https://img.shields.io/pub/publisher/c_compiler.svg)](https://pub.dev/packages/c_compiler/publisher)
55

66
A library to invoke the native C compiler installed on the host machine.
7+
8+
## Status: Experimental
9+
10+
**NOTE**: This package is currently experimental and published under the
11+
[labs.dart.dev](https://dart.dev/dart-team-packages) pub publisher in order to
12+
solicit feedback.
13+
14+
For packages in the labs.dart.dev publisher we generally plan to either graduate
15+
the package into a supported publisher (dart.dev, tools.dart.dev) after a period
16+
of feedback and iteration, or discontinue the package. These packages have a
17+
much higher expected rate of API and breaking changes.
18+
19+
Your feedback is valuable and will help us evolve this package.
20+
For bugs, please file an issue in the
21+
[bug tracker](https://github.com/dart-lang/native/issues).
22+
23+
24+
## Example
25+
26+
An example can be found in [../native_assets_cli/example/](../native_assets_cli/example/).

‎pkgs/native_assets_builder/README.md‎

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,19 @@
1-
This package contains the logic for building native assets.
1+
[![dart](https://github.com/dart-lang/native/actions/workflows/dart.yaml/badge.svg)](https://github.com/dart-lang/native/actions/workflows/dart.yaml)
2+
[![Coverage Status](https://coveralls.io/repos/github/dart-lang/native/badge.svg?branch=main)](https://coveralls.io/github/dart-lang/native?branch=main)
3+
[![pub package](https://img.shields.io/pub/v/native_assets_builder.svg)](https://pub.dev/packages/native_assets_builder)
4+
[![package publisher](https://img.shields.io/pub/publisher/native_assets_builder.svg)](https://pub.dev/packages/native_assets_builder/publisher)
25

3-
This package is the backend that invokes toplevel `build.dart` scripts.
4-
For more info on these scripts see https://github.com/dart-lang/native.
6+
This package contains the shared logic for invoking [native assets CLI]s.
57

6-
This is a separate package so that dartdev and flutter_tools can reuse
7-
the same logic with flutter_tools having to import dartdev.
8+
## Audience
9+
10+
This package is not intended for users, rather it is shared logic for Dart
11+
launchers to invoke the native assets CLIs of packages.
12+
Known Dart launchers using this shared logic: [dartdev] and [flutter_tools].
13+
14+
For more information on how to use native assets as a user see
15+
package [native assets CLI].
16+
17+
[native assets CLI]: https://github.com/dart-lang/native/pkgs/native_assets_cli
18+
[dartdev]: https://github.com/dart-lang/sdk/tree/main/pkg/dartdev
19+
[flutter_tools]: https://github.com/flutter/flutter/tree/master/packages/flutter_tools

‎pkgs/native_assets_builder/test/data/native_add/lib/src/native_add.dart‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,4 @@
44

55
import 'native_add_bindings_generated.dart' as bindings;
66

7-
// TODO(dacoharkes): This will fail lookup until the Dart SDK consumes the
8-
// output of `build.dart`.
97
int add(int a, int b) => bindings.add(a, b);

‎pkgs/native_assets_builder/test/data/native_subtract/lib/src/native_subtract.dart‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,4 @@
44

55
import 'native_subtract_bindings_generated.dart' as bindings;
66

7-
// TODO(dacoharkes): This will fail lookup until the Dart SDK consumes the
8-
// output of `build.dart`.
97
int subtract(int a, int b) => bindings.subtract(a, b);

‎pkgs/native_assets_cli/README.md‎

Lines changed: 51 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,54 @@
11
[![package:native_assets_cli](https://github.com/dart-lang/native/actions/workflows/dart.yaml/badge.svg)](https://github.com/dart-lang/native/actions/workflows/dart.yaml)
2-
[![pub package](https://img.shields.io/pub/v/native_assets_cli.svg)](https://pub.dev/packages/native_assets_cli)
32
[![Coverage Status](https://coveralls.io/repos/github/dart-lang/native/badge.svg?branch=main)](https://coveralls.io/github/dart-lang/native?branch=main)
4-
<!-- [![package publisher](https://img.shields.io/pub/publisher/native_assets_cli.svg)](https://pub.dev/packages/native_assets_cli/publisher) -->
3+
[![pub package](https://img.shields.io/pub/v/native_assets_cli.svg)](https://pub.dev/packages/native_assets_cli)
4+
[![package publisher](https://img.shields.io/pub/publisher/native_assets_cli.svg)](https://pub.dev/packages/native_assets_cli/publisher)
5+
6+
This library contains the CLI specification and a default implementation
7+
for bundling native code with Dart packages.
8+
9+
## Status: Experimental
10+
11+
**NOTE**: This package is currently experimental and published under the
12+
[labs.dart.dev](https://dart.dev/dart-team-packages) pub publisher in order to
13+
solicit feedback.
14+
15+
For packages in the labs.dart.dev publisher we generally plan to either graduate
16+
the package into a supported publisher (dart.dev, tools.dart.dev) after a period
17+
of feedback and iteration, or discontinue the package. These packages have a
18+
much higher expected rate of API and breaking changes.
19+
20+
Your feedback is valuable and will help us evolve this package.
21+
For bugs, please file an issue in the
22+
[bug tracker](https://github.com/dart-lang/native/issues).
23+
For general feedback and suggestions for the native assets feature in Dart and
24+
Flutter, please comment in [dart-lang#50565] or [flutter#129757].
25+
26+
## Example
27+
28+
A typical layout of a package with native code is:
29+
30+
* `lib/` contains Dart code which uses [`dart:ffi`] and [`package:ffigen`]
31+
to call into native code.
32+
* `src/` contains C/C++/Rust code which is invoked through `dart:ffi`.
33+
* `build.dart` implements the CLI that communicates which native assets
34+
to build/bundle with the Dart/Flutter SDK. This file uses the
35+
protocol specified in this package.
36+
37+
An example can be found in [example/](example/).
38+
39+
## Usage
40+
41+
Using the native assets feature requires passing
42+
`--enable-experiment=native-assets` in Dart on a dev build.
43+
44+
The native assets feature is not yet available in Flutter.
45+
46+
## Development
47+
48+
The development of the feature can be tracked in [dart-lang#50565],
49+
[flutter#129757], and in the issue tracker on this repository.
550

6-
A library that contains the argument and file formats for implementing a native assets CLI.
51+
[`dart:ffi`]: https://api.dart.dev/stable/dart-ffi/dart-ffi-library.html
52+
[`package:ffigen`]: https://pub.dev/packages/ffigen
53+
[dart-lang#50565]: https://github.com/dart-lang/sdk/issues/50565
54+
[flutter#129757]: https://github.com/flutter/flutter/issues/129757

‎pkgs/native_assets_cli/example/README.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
The examples in this folder illustrate how native code is built and bundled
2+
in Dart and Flutter apps.
3+
4+
* [native_add_app/](native_add_app/) has a dependency with C code.
5+
This app should declare nothing special. Dart and Flutter should check
6+
all dependencies for native code.
7+
* [native_add_library/](native_add_library/) contains a library with C code.
8+
When Dart code in this library or dependent on this library is invoked, the
9+
C code must be built and bundled so that it can be used by the Dart code.

‎pkgs/native_assets_cli/example/native_add_app/README.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
An example application to show invocation of native code bundled with the native
2+
assets feature.
3+
4+
## Usage
5+
6+
Run application with `dart --enable-experiment=native-assets run`.
7+
8+
Run tests with `dart --enable-experiment=native-assets test`.
9+
10+
Release application with `dart --enable-experiment=native-assets build bin/native_add_app`. (Run with `./bin/native_add_app/native_add_app.exe`.)

‎pkgs/native_assets_cli/example/native_add_app/bin/native_add_app.dart‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
// Copyright (c) 2023, the Dart project authors. Please see the AUTHORS file
2+
// for details. All rights reserved. Use of this source code is governed by a
3+
// BSD-style license that can be found in the LICENSE file.
4+
5+
import 'package:native_add_library/native_add_library.dart';
6+
7+
void main() {
8+
print('Invoking a native function to calculate 1 + 2.');
9+
final result = add(1, 2);
10+
print('Invocation success: 1 + 2 = $result.');
11+
}

0 commit comments

Comments
 (0)