mirror of
https://github.com/dart-lang/sdk
synced 2024-10-14 21:49:13 +00:00
[dart2wasm] Remove pkg/dart2wasm/README.md and move remaining things into pkg/dart2wasm/docs/*.md files
* removes duplicate list of options in readme file (that is available via `--help` already) * add more information about checkout, namely the custom vars for `.gclient` * moves remaining 2 sections into their own pkg/dart2wasm/docs/*.md file Change-Id: I9a505b7a37cdfe6e3745933410dd1ba309e50c3b Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/368305 Reviewed-by: Ömer Ağacan <omersa@google.com>
This commit is contained in:
Martin Kustermann
parent
004d6a3fad
commit
8aa5e2dbca
|
|
@ -1,89 +0,0 @@
|
|||
# Compiling Dart to WebAssembly (internal SDK developer notes)
|
||||
|
||||
**This page contains notes for how to compile to WebAssembly for SDK contributors.
|
||||
If you are a Dart developer, using a prebuilt Dart SDK, please refer to the
|
||||
[regular documentation](https://dart.dev/web/wasm).**
|
||||
|
||||
**Note:** This feature is under active development,
|
||||
and is currently considered experimental.
|
||||
The tracking issue is [#32894](https://github.com/dart-lang/sdk/issues/32894).
|
||||
|
||||
## Running dart2wasm as an SDK contributor
|
||||
|
||||
You don't need to build the Dart SDK to run dart2wasm, as long as you have a Dart SDK installed and have the [Dart SDK repository checked out](https://github.com/dart-lang/sdk/wiki/Building#getting-the-source). NB: the SDK must be checked out using depot tools and not just cloned from this repo.
|
||||
|
||||
To compile a Dart file to Wasm, in a checkout of the Dart SDK repository, run:
|
||||
|
||||
```
|
||||
dart --enable-asserts pkg/dart2wasm/bin/dart2wasm.dart <options> <input file>.dart <output file>.wasm
|
||||
```
|
||||
|
||||
### Compiler options
|
||||
|
||||
| Option | Default | Description |
|
||||
| --------------------------------------- | ------- | ----------- |
|
||||
| `--dart-sdk=`*path* | relative to script | The location of the `sdk` directory inside the Dart SDK, containing the core library sources.
|
||||
| `--platform=`*path* | none | The location of the platform `dill` file containing the compiled core libraries.
|
||||
| `--depfile=`*path* | none | Write a Ninja depfile listing the input sources for the compilation.
|
||||
| `--`[`no-`]`enable-asserts` | no | Enable assertions at runtime.
|
||||
| `--`[`no-`]`export-all` | no | Export all functions; otherwise, just export `main`.
|
||||
| `--`[`no-`]`import-shared-memory` | no | Import a shared memory buffer. If this is on, `--shared-memory-max-pages` must also be specified.
|
||||
| `--`[`no-`]`inlining` | yes | Enable function inlining.
|
||||
| `--inlining-limit` *size* | 0 | Always inline functions no larger than this number of AST nodes, if inlining is enabled.
|
||||
| `--`[`no-`]`js-compatibility` | no | Enable JS compatibility mode.
|
||||
| `--`[`no-`]`name-section` | yes | Emit Name Section with function names.
|
||||
| `--`[`no-`]`omit-type-checks` | no | Omit runtime type checks, such as covariance checks and downcasts.
|
||||
| `--`[`no-`]`polymorphic-specialization` | no | Do virtual calls by switching on the class ID instead of using `call_indirect`.
|
||||
| `--`[`no-`]`print-kernel` | no | Print IR for each function before compiling it.
|
||||
| `--`[`no-`]`print-wasm` | no | Print Wasm instructions of each compiled function.
|
||||
| `--`[`no-`]`verify-type-checks` | no | Instrument code to verify that type check optimizations produce the correct result.
|
||||
| `--shared-memory-max-pages` *pagecount* | | Max size of the imported memory buffer. If `--shared-import-memory` is specified, this must also be specified.
|
||||
| `--watch` *offset* | | Print stack trace leading to the byte at offset *offset* in the `.wasm` output file. Can be specified multiple times.
|
||||
|
||||
Dart2Wasm will output a `wasm` file, containing Dart compiled to Wasm, as well as an `mjs` file containing the runtime. The result can be run with:
|
||||
|
||||
```
|
||||
d8 pkg/dart2wasm/bin/run_wasm.js -- /abs/path/to/<output file>.mjs <output file>.wasm
|
||||
```
|
||||
|
||||
Where `d8` is the [V8 developer shell](https://v8.dev/docs/d8).
|
||||
|
||||
## Imports and exports
|
||||
|
||||
To import a function, declare it as a global, external function and mark it with a `wasm:import` pragma indicating the imported name (which must be two identifiers separated by a dot):
|
||||
```dart
|
||||
@pragma("wasm:import", "foo.bar")
|
||||
external void fooBar(Object object);
|
||||
```
|
||||
which will call `foo.bar` on the host side:
|
||||
```javascript
|
||||
var foo = {
|
||||
bar: function(object) { /* implementation here */ }
|
||||
};
|
||||
```
|
||||
To export a function, mark it with a `wasm:export` pragma:
|
||||
```dart
|
||||
@pragma("wasm:export")
|
||||
void foo(double x) { /* implementation here */ }
|
||||
|
||||
@pragma("wasm:export", "baz")
|
||||
void bar(double x) { /* implementation here */ }
|
||||
```
|
||||
With the Wasm module instance in `inst`, these can be called as:
|
||||
```javascript
|
||||
inst.exports.foo(1);
|
||||
inst.exports.baz(2);
|
||||
```
|
||||
|
||||
### Types to use for interop
|
||||
|
||||
In the signatures of imported and exported functions, use the following types:
|
||||
|
||||
- For numbers, use `double`.
|
||||
- For JS objects, use a JS interop type, e.g. `JSAny`, which translates to the Wasm `externref` type. These can be passed around and stored as opaque values on the Dart side.
|
||||
- For Dart objects, use the corresponding Dart type. This will be emitted as `anyref` and automatically converted to and from the Dart type at the boundary.
|
||||
|
||||
## Detecting whether code is running as WebAssembly
|
||||
|
||||
`dart2wasm` defines `dart.tool.dart2wasm` as `true`, meaning that `bool.fromEnvironment('dart.tool.dart2wasm')` can be used in a constant context to determine whether it was
|
||||
compiled to WebAssembly.
|
||||
|
|
@ -1,3 +1,30 @@
|
|||
# Checkout
|
||||
|
||||
Ensure you have a valid checkout by following the
|
||||
[Getting the source](https://github.com/dart-lang/sdk/blob/main/docs/Building.md#getting-the-source)
|
||||
instructions.
|
||||
|
||||
In order to be able to run on all tests modify the `../.gclient` file by adding
|
||||
custom variables:
|
||||
|
||||
```
|
||||
solutions = [
|
||||
{
|
||||
"name" : "sdk",
|
||||
...
|
||||
"custom_vars" : {
|
||||
"download_emscripten": True,
|
||||
"download_firefox": True,
|
||||
"download_chrome": True,
|
||||
"checkout_flute": True,
|
||||
"checkout_javascript_engines": True,
|
||||
},
|
||||
},
|
||||
]
|
||||
```
|
||||
This configures the `DEPS` to download various tools on the next `gclient sync`
|
||||
invocation.
|
||||
|
||||
# Building Dart2Wasm
|
||||
|
||||
To build dart2wasm for local running & testing we use
|
||||
|
|
@ -49,6 +76,10 @@ from source:
|
|||
* Use `pkg/dart2wasm/tool/compile_benchmark --src ...`
|
||||
* Use `pkg/dart2wasm/tool/compile_benchmark --src --compiler-asserts ...`
|
||||
|
||||
One can pass through any option to the dart2wasm compiler by adding
|
||||
`--extra-compiler-option=--<option>=<value>`.
|
||||
|
||||
See available options via `dart pkg/dart2wasm/bin/dart2wasm.dart --help`.
|
||||
|
||||
# Testing Dart2Wasm
|
||||
|
||||
|
|
@ -66,4 +97,3 @@ The test framwork will use the same two scripts to compile & run (
|
|||
|
||||
(The test framework can be asked to use `dart compile wasm` from the SDK
|
||||
instead using `--use-sdk` (or update in `tools/bots/test_matrix.json`))
|
||||
|
||||
|
|
|
|||
37
pkg/dart2wasm/docs/imports_and_exports.md
Normal file
37
pkg/dart2wasm/docs/imports_and_exports.md
Normal file
|
|
@ -0,0 +1,37 @@
|
|||
## Imports and exports
|
||||
|
||||
**NOTE**: This is for internal usage only and not intended for end-users (yet).
|
||||
See tracking issue for eventually exposing this at [github.com/dart-lang/sdk/issues/55856](https://github.com/dart-lang/sdk/issues/55856)
|
||||
|
||||
To import a function, declare it as a global, external function and mark it with a `wasm:import` pragma indicating the imported name (which must be two identifiers separated by a dot):
|
||||
```dart
|
||||
@pragma("wasm:import", "foo.bar")
|
||||
external void fooBar(Object object);
|
||||
```
|
||||
which will call `foo.bar` on the host side:
|
||||
```javascript
|
||||
var foo = {
|
||||
bar: function(object) { /* implementation here */ }
|
||||
};
|
||||
```
|
||||
To export a function, mark it with a `wasm:export` pragma:
|
||||
```dart
|
||||
@pragma("wasm:export")
|
||||
void foo(double x) { /* implementation here */ }
|
||||
|
||||
@pragma("wasm:export", "baz")
|
||||
void bar(double x) { /* implementation here */ }
|
||||
```
|
||||
With the Wasm module instance in `inst`, these can be called as:
|
||||
```javascript
|
||||
inst.exports.foo(1);
|
||||
inst.exports.baz(2);
|
||||
```
|
||||
|
||||
### Types to use for interop
|
||||
|
||||
In the signatures of imported and exported functions, use the following types:
|
||||
|
||||
- For numbers, use `double`.
|
||||
- For JS objects, use a JS interop type, e.g. `JSAny`, which translates to the Wasm `externref` type. These can be passed around and stored as opaque values on the Dart side.
|
||||
- For Dart objects, use the corresponding Dart type. This will be emitted as `anyref` and automatically converted to and from `externref` at the boundary
|
||||
4
pkg/dart2wasm/docs/wasm_detection.md
Normal file
4
pkg/dart2wasm/docs/wasm_detection.md
Normal file
|
|
@ -0,0 +1,4 @@
|
|||
## Detecting whether code is running as WebAssembly
|
||||
|
||||
`dart2wasm` defines `dart.tool.dart2wasm` as `true`, meaning that `bool.fromEnvironment('dart.tool.dart2wasm')` can be used in a constant context to determine whether it was
|
||||
compiled to WebAssembly.
|
||||
Loading…
Reference in a new issue