Skip to content

Commit c76ea57

Browse files
dcharkesdcharkes
authored
[hooks] [code_assets] README.md (#2685)
This revamps the READMEs to include 1. code snippets with links to the examples, and 2. links to https://dart.dev/tools/hooks. Side note, I'm thinking we might want to completely remove the examples from `package:hooks` and simply link to the examples in `package:code_assets`. The examples in `package:hooks` are rather artificial and more of a feature showcase, which makes them less understandable. Bug: * #2324
1 parent 33a33b2 commit c76ea57

File tree

3 files changed

+138
-19
lines changed

3 files changed

+138
-19
lines changed

‎pkgs/code_assets/README.md‎

Lines changed: 76 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,17 @@
33
[![pub package](https://img.shields.io/pub/v/code_assets.svg)](https://pub.dev/packages/code_assets)
44
[![package publisher](https://img.shields.io/pub/publisher/code_assets.svg)](https://pub.dev/packages/code_assets/publisher)
55

6-
A library to use in build hooks (`hook/build.dart`) for building and bundling
7-
code assets.
6+
This package provides the API for code assets to be used with
7+
[`package:hooks`](https://pub.dev/packages/hooks).
88

99
A code asset is an asset containing executable code which respects the native
10-
application binary interface (ABI).
10+
application binary interface (ABI). These assets are bundled with a Dart or
11+
Flutter application. They can be produced by compiling C, C++, Objective-C,
12+
Rust, or Go code for example.
13+
14+
This package is used in a build hook (`hook/build.dart`) to inform the Dart
15+
and Flutter SDKs about the code assets that need to be bundled with an
16+
application.
1117

1218
Code assets can be added in a build hook as follows:
1319

@@ -33,11 +39,74 @@ void main(List<String> args) async {
3339
}
3440
```
3541

36-
For more documentation of hooks, refer to the API docs of
37-
[`package:hooks`](https://pub.dev/packages/hooks).
38-
3942
When compiling C, C++ or Objective-C code from source, consider using
40-
[`package:native_toolchain_c`](https://pub.dev/packages/native_toolchain_c).
43+
[`package:native_toolchain_c`](https://pub.dev/packages/native_toolchain_c):
44+
45+
<!-- file://./example/sqlite/hook/build.dart -->
46+
```dart
47+
import 'package:code_assets/code_assets.dart';
48+
import 'package:hooks/hooks.dart';
49+
import 'package:native_toolchain_c/native_toolchain_c.dart';
50+
51+
void main(List<String> args) async {
52+
await build(args, (input, output) async {
53+
if (input.config.buildCodeAssets) {
54+
final builder = CBuilder.library(
55+
name: 'sqlite3',
56+
assetName: 'src/third_party/sqlite3.g.dart',
57+
sources: ['third_party/sqlite/sqlite3.c'],
58+
defines: {
59+
if (input.config.code.targetOS == OS.windows)
60+
// Ensure symbols are exported in dll.
61+
'SQLITE_API': '__declspec(dllexport)',
62+
},
63+
);
64+
await builder.run(input: input, output: output);
65+
}
66+
});
67+
}
68+
```
69+
70+
See the full example in [example/sqlite/](example/sqlite/).
71+
72+
When interfacing with system libraryies, the API in this package is enough:
73+
74+
<!-- file://./example/host_name/hook/build.dart -->
75+
```dart
76+
import 'package:code_assets/code_assets.dart';
77+
import 'package:hooks/hooks.dart';
78+
79+
void main(List<String> args) async {
80+
await build(args, (input, output) async {
81+
if (input.config.buildCodeAssets) {
82+
switch (input.config.code.targetOS) {
83+
case OS.android || OS.iOS || OS.linux || OS.macOS:
84+
output.assets.code.add(
85+
CodeAsset(
86+
package: 'host_name',
87+
name: 'src/third_party/unix.dart',
88+
linkMode: LookupInProcess(),
89+
),
90+
);
91+
case OS.windows:
92+
output.assets.code.add(
93+
CodeAsset(
94+
package: 'host_name',
95+
name: 'src/third_party/windows.dart',
96+
linkMode: DynamicLoadingSystem(Uri.file('ws2_32.dll')),
97+
),
98+
);
99+
case final os:
100+
throw UnsupportedError('Unsupported OS: ${os.name}.');
101+
}
102+
}
103+
});
104+
}
105+
```
106+
107+
See the full example in [example/host_name/](example/host_name/).
108+
109+
For more information see [dart.dev/tools/hooks](https://dart.dev/tools/hooks).
41110

42111
## Status: In Preview
43112

‎pkgs/hooks/README.md‎

Lines changed: 50 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -3,28 +3,66 @@
33
[![pub package](https://img.shields.io/pub/v/hooks.svg)](https://pub.dev/packages/hooks)
44
[![package publisher](https://img.shields.io/pub/publisher/hooks.svg)](https://pub.dev/packages/hooks/publisher)
55

6-
A library to use in build hooks (`hook/build.dart`).
6+
This package provides the API for hooks in Dart. Hooks are Dart
7+
scripts placed in the `hook/` directory of a Dart package, designed to automate
8+
tasks for a Dart package.
79

8-
For more documentation on adding native code to your package, refer to the API
9-
docs of [`package:code_assets`](https://pub.dev/packages/code_assets).
10+
Currently, the main supported hook is the build hook (`hook/build.dart`). The
11+
build hook is executed during a Dart build and enables you to bundle assets with
12+
a Dart package.
13+
14+
The main supported asset type is a code asset, code written in other languages
15+
that are compiled into machine code. You can use a build hook to do things such
16+
as compile or download code assets, and then call these assets from the Dart
17+
code of a package. The
18+
[`CodeAsset`](https://pub.dev/documentation/code_assets/latest/code_assets/CodeAsset-class.html)
19+
API is an extension to this package and is available in
20+
[`package:code_assets`](https://pub.dev/packages/code_assets).
21+
22+
When compiling C, C++ or Objective-C code from source, consider using
23+
[`package:native_toolchain_c`](https://pub.dev/packages/native_toolchain_c):
24+
25+
<!-- file://./../code_assets/example/sqlite/hook/build.dart -->
26+
```dart
27+
import 'package:code_assets/code_assets.dart';
28+
import 'package:hooks/hooks.dart';
29+
import 'package:native_toolchain_c/native_toolchain_c.dart';
30+
31+
void main(List<String> args) async {
32+
await build(args, (input, output) async {
33+
if (input.config.buildCodeAssets) {
34+
final builder = CBuilder.library(
35+
name: 'sqlite3',
36+
assetName: 'src/third_party/sqlite3.g.dart',
37+
sources: ['third_party/sqlite/sqlite3.c'],
38+
defines: {
39+
if (input.config.code.targetOS == OS.windows)
40+
// Ensure symbols are exported in dll.
41+
'SQLITE_API': '__declspec(dllexport)',
42+
},
43+
);
44+
await builder.run(input: input, output: output);
45+
}
46+
});
47+
}
48+
```
49+
50+
See the full example in [package:code_assets
51+
example/sqlite/](../code_assets/example/sqlite/).
52+
53+
For more information see [dart.dev/tools/hooks](https://dart.dev/tools/hooks).
1054

1155
## Status: In Preview
1256

1357
**NOTE**: This package is currently in preview and published under the
1458
[labs.dart.dev](https://dart.dev/dart-team-packages) pub publisher in order to
15-
solicit feedback.
59+
solicit feedback.
1660

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

22-
Your feedback is valuable and will help us evolve this package.
23-
For bugs, please file an issue in the
66+
Your feedback is valuable and will help us evolve this package.
67+
For bugs, please file an issue in the
2468
[bug tracker](https://github.com/dart-lang/native/issues).
25-
26-
27-
## Example
28-
29-
An example can be found in [../hooks/example/build/](
30-
../hooks/example/build/).

‎pkgs/hooks/tool/update_snippets.dart‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -187,6 +187,18 @@ String updateSnippets(String oldContent, Uri fileUri, List<String> errors) {
187187
if (extractedMatch != null) {
188188
newSnippetText = extractedMatch.group(1)!;
189189
}
190+
final copyrightRegex = RegExp(r'''
191+
// Copyright \(c\) [0-9]*, the Dart project authors. Please see the AUTHORS file
192+
// for details. All rights reserved. Use of this source code is governed by a
193+
// BSD-style license that can be found in the LICENSE file.
194+
''');
195+
final copyrightHeader = copyrightRegex.firstMatch(newSnippetText);
196+
if (copyrightHeader != null) {
197+
newSnippetText = newSnippetText.replaceFirst(
198+
copyrightHeader.group(0)!,
199+
'',
200+
);
201+
}
190202
newSnippetText = newSnippetText.trim();
191203

192204
final newContentForBlock = newSnippetText

0 commit comments

Comments
 (0)