Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Wasm landing page #5781

Merged
merged 10 commits into from
May 13, 2024
2 changes: 2 additions & 0 deletions src/_data/side-nav.yml
Original file line number Diff line number Diff line change
Expand Up @@ -237,6 +237,8 @@
permalink: /web/deployment
- title: Libraries & packages
permalink: /web/libraries
- title: Wasm compilation
permalink: /web/wasm
- title: Environment declarations
permalink: /guides/environment-declarations

Expand Down
21 changes: 13 additions & 8 deletions src/content/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -184,8 +184,8 @@ Dart's compiler technology lets you run code in different ways:
an ahead-of-time (AOT) compiler for producing machine code.

* **Web platform**: For apps targeting the web, Dart can compile for
development or production purposes. Its web compiler translates Dart
into JavaScript.
development or production purposes. Its web compilers translate Dart
into JavaScript or WebAssembly.

<img
src="/assets/img/Dart-platforms.svg"
Expand Down Expand Up @@ -221,26 +221,31 @@ More information:
* [Write command-line apps](/tutorials/server/cmdline)
* [Write HTTP servers](/tutorials/server/httpserver)

#### Dart Web (JavaScript dev & prod) {:#web-platform}
#### Dart Web (JavaScript dev & prod and WebAssembly) {:#web-platform}

Dart Web enables running Dart code on web platforms powered by
JavaScript. With Dart Web, you compile Dart code to JavaScript code, which in
turn runs in a browser—for example, [V8](https://v8.dev/) inside
[Chrome](https://www.google.com/chrome/).
Alternatively, Dart code can be compiled to WebAssembly.

Dart web contains two compilation modes:
Dart web contains three compilation modes:

* An incremental development compiler enabling a fast developer cycle
* An optimizing production compiler which compiles Dart code to fast,
compact, deployable JavaScript. These efficiencies come from
techniques such as dead-code elimination.
* An incremental JavaScript development compiler enabling a fast developer
cycle.
* An optimizing JavaScript production compiler which compiles Dart code to fast,
compact, deployable JavaScript. These efficiencies come from techniques such
as dead-code elimination.
* An optimizing WebAssembly (WasmGC) production compiler which compiles Dart
code to super-fast, deployable WebAssembly GC code.

More information:

* [Build a web app with Dart](/web/get-started)
* [`dart compile js`](/tools/dart-compile#js)
* [`webdev` tool](/tools/webdev)
* [Web deployment tips](/web/deployment)
* [WebAssembly compilation](/web/wasm)

#### The Dart runtime {:#runtime}

Expand Down
8 changes: 8 additions & 0 deletions src/content/tools/dart-compile.md
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,14 @@ The following table shows the subcommands of `dart compile`.
<br><em><a href="#js">Learn more.</a></em>
</td>
</tr>
<tr>
<td> <code>wasm</code> </td>
<td> WebAssembly </td>
<td> A portable, binary instruction format for a stack-based virtual machine.
Currently under development.
<br><em><a href="/web/wasm">Learn more.</a></em>
</td>
</tr>
</table>


Expand Down
74 changes: 74 additions & 0 deletions src/content/web/wasm.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
---
title: WebAssembly (Wasm) compilation
description: Learn how to compile your Dart web app to WebAssembly.
---

The Dart team is excited to add
[WebAssembly](https://webassembly.org/) as a compilation target when building
Dart and [Flutter]({{site.flutter}}/wasm) applications for the web.

Development of WebAssembly support remains ongoing,
which will potentially result in frequent changes.
Revisit this page for the latest updates.

:::note
**Support for Wasm is now in beta!**

WebAssembly support for Dart web is available on the Dart
*beta* and *main* [channels](/get-dart#release-channels).
:::

## WebAssembly support

The current version of Dart compilation to WebAssembly has a number of
restrictions:

1. It targets WebAssembly with Garbage Collection (aka *WasmGC*), so...

1. The compiled Wasm output currently targets JavaScript environments
(such as browsers), and thus currently doesn't support execution in standard
Wasm run-times like wasmtime and wasmer. For details, see
[issue #53884]({{site.repo.dart.sdk}}/issues/53884)

1. Only Dart's
[next-gen JS interop mechanism](/interop/js-interop/)
is supported when compiling to Wasm.

## Compiling your web app to Wasm {:#compiling-to-wasm}

We've landed support in the `dart` CLI for invoking the
`dart2wasm` compiler in the Dart and Flutter `main` channels:

```console
$ dart help compile wasm
Compile Dart to a WebAssembly/WasmGC module (EXPERIMENTAL).

Usage: dart compile wasm [arguments] <dart entry point>
-h, --help Print this usage information.
-o, --output Write the output to <file name>.
This can be an absolute or relative path.
-v, --verbose Print debug output during compilation
--enable-asserts Enable assert statements.
-D, --define=<key=value> Define an environment declaration. To specify multiple declarations, use multiple
options or use commas to separate key-value pairs.
For example: dart compile wasm -Da=1,b=2 main.dart
```

To try Wasm today from the `main` channel:

1. Start with a web app: `dart create -t web mywebapp`

The template creates a small web app using [`package:web`][],
which is necessary to run Wasm.
Make sure your web apps are [migrated][] from `dart:html` to `package:web`.

1. Compile with Wasm: `mywebapp$ dart compile wasm web/main.dart`

1. Serve the output: `dart pub global run ` [`dhttpd`]

You can also check out this small example [here](https://github.com/mit-mit/sandbox).

[`package:web`]: {{site.pub-pkg}}/web
[`dart:js_interop`]: {{site.dart.api}}/{{site.dart.sdk.channel}}/dart-js_interop
[migrated]: /interop/js-interop/package-web/
[`dhttpd`]: {{site.pub-pkg}}/dhttpd