From 0ee6641151e59e8303182dc704782441abad1105 Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Mon, 11 Sep 2023 09:56:12 -0700 Subject: [PATCH] Bring some of Wasmtime's documentation more up-to-date (#6994) * Remove tutorial/wasm-writing documentation This commit removes the tutorial and "Writing WebAssembly" documentation sections from Wasmtime's documentation. These sections are quite dated at this point (they still recommend `cargo wasi`!) and haven't been updated much since their inception, especially in the arena of components. Today it seems best to leave this sort of documentation to [other resources] which are more tailored towards documentation of writing wasm. [other resources]: https://component-model.bytecodealliance.org/ * Remove markdown example from docs Like the previous commit this is quite dated and recommends effectively-deprecated tooling and doesn't take into account components. * Update our intro docs a bit * Link security blog post from docs * Fold docs of wasm proposals into tier docs This was already a bit duplicated so consolidate into one location. Additionally add some proposals that weren't previously documented and move some around based on their implementation status. * Document unsupported features In an effort to head off questions about platform support I figure it might be a good idea to start documenting what's not supported at this time. This is intended to mirror the current state, not future, of Wasmtime. In other words this should answer the question of "Does Wasmtime support X?" as opposed to "Does Wasmtime want to support X?" since we want to eventually support all of these features in the limit. * Fold WASI docs into tier docs Similar to the previous commit but for WASI proposals. --- docs/SUMMARY.md | 11 -- docs/examples-markdown.md | 65 --------- docs/introduction.md | 17 +-- docs/security.md | 4 +- docs/stability-tiers.md | 97 +++++++++++- docs/stability-wasi-proposals-support.md | 60 -------- docs/stability-wasm-proposals-support.md | 43 ------ docs/tutorial-create-hello-world.md | 63 -------- docs/tutorial-run-hello-world.md | 28 ---- docs/tutorial.md | 7 - docs/wasm-assemblyscript.md | 77 ---------- docs/wasm-c.md | 28 ---- docs/wasm-rust.md | 178 ----------------------- docs/wasm-wat.md | 56 ------- docs/wasm.md | 13 -- 15 files changed, 100 insertions(+), 647 deletions(-) delete mode 100644 docs/examples-markdown.md delete mode 100644 docs/stability-wasi-proposals-support.md delete mode 100644 docs/stability-wasm-proposals-support.md delete mode 100644 docs/tutorial-create-hello-world.md delete mode 100644 docs/tutorial-run-hello-world.md delete mode 100644 docs/tutorial.md delete mode 100644 docs/wasm-assemblyscript.md delete mode 100644 docs/wasm-c.md delete mode 100644 docs/wasm-rust.md delete mode 100644 docs/wasm-wat.md delete mode 100644 docs/wasm.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 1d247417773c..21c1061f2031 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -1,11 +1,7 @@ # Summary - [Introduction](./introduction.md) -- [Tutorial](./tutorial.md) - - [Creating `hello-world.wasm`](./tutorial-create-hello-world.md) - - [Running `hello-world.wasm`](./tutorial-run-hello-world.md) - [Examples](./examples.md) - - [Markdown Parser](./examples-markdown.md) - [Debugging WebAssembly](./examples-debugging.md) - [Profiling WebAssembly](./examples-profiling.md) - [Profiling with Perf](./examples-profiling-perf.md) @@ -42,17 +38,10 @@ - [CLI Options](./cli-options.md) - [CLI Logging](./cli-logging.md) - [Cache Configuration](./cli-cache.md) -- [Writing WebAssembly](./wasm.md) - - [Rust](./wasm-rust.md) - - [C/C++](./wasm-c.md) - - [AssemblyScript](./wasm-assemblyscript.md) - - [WebAssembly Text Format (`*.wat`)](./wasm-wat.md) - [Stability](stability.md) - [Release Process](./stability-release.md) - [Tiers of support](./stability-tiers.md) - [Platform Support](./stability-platform-support.md) - - [Wasm Proposals Support](./stability-wasm-proposals-support.md) - - [WASI Proposals Support](./stability-wasi-proposals-support.md) - [Security](security.md) - [Disclosure Policy](./security-disclosure.md) - [Contributing](contributing.md) diff --git a/docs/examples-markdown.md b/docs/examples-markdown.md deleted file mode 100644 index 36b0d63d546e..000000000000 --- a/docs/examples-markdown.md +++ /dev/null @@ -1,65 +0,0 @@ -# Markdown Parser - -The following steps describe an implementation of a WASI markdown parser, in Rust, using [pulldown-cmark](https://github.com/raphlinus/pulldown-cmark). - -First, we will generate a new executable with cargo: - -```bash -cargo new --bin rust_wasi_markdown_parser -cd rust_wasi_markdown_parser -``` - -Also, we need to add the `structopt` and `pulldown_cmark` crates to our project: - -```bash -cargo add structopt pulldown_cmark -``` - -Then, we will open the `src/main.rs` and enter the following contents. Please see the comments to understand what our program will be doing. - -## `src/main.rs` - -```rust,ignore -{{#include ./rust_wasi_markdown_parser/src/main.rs}} -``` - -Next, we will want to add WASI as a target that we can compile to. We will ask the rustup tool to install support for WASI. Then, we will compile our program to WASI. To do this we will run: - -```bash -rustup target add wasm32-wasi -cargo build --target wasm32-wasi -``` - -Our wasm file should be compiled to `target/wasm32-wasi/debug/rust_wasi_markdown_parser.wasm`. It is worth noting that even though the WASI APIs are not being used directly, when we compile our program to target WASI, the rust APIs and standard library will be using these WASI APIs under the hood for us! Now that we have our program compiled to target WASI, let's run our program! - -To do this, we can use the Wasmtime CLI. However, there is one thing to note about Wasmtime, WASI, and the capability based security model. We need to give our program explicit access to read files on our device. Wasm modules that implement WASI will not have this capability unless we give them the capability. - -To grant the capability to read in a directory using the Wasmtime CLI, we need to use the --dir flag. --dir will instruct wasmtime to make the passed directory available to access files from. (You can also `--mapdir GUEST_DIRECTORY::HOST_DIRECTORY` to make it available under a different path inside the content.) For example: - -```bash -wasmtime --dir . my-wasi-program.wasm -``` - -For this example, we will be passing a markdown file to our program called: `example_markdown.md`, that will exist in whatever our current directory (`./`) is. Our markdown file, `example_markdown.md`, will contain: - -```md -# Hello! - -I am example markdown for this demo! -``` - -So, **to run our compiled WASI program, we will run**: - -```bash -wasmtime --dir . target/wasm32-wasi/debug/rust_wasi_markdown_parser.wasm -- ./example_markdown.md -``` - -Which should look like the following: - -```html -

Hello!

-

I am example markdown for this demo!

-``` - -Hooray! We were able to write a Wasm Module, that uses WASI to read a markdown file, parse the markdown, and write the output to stdout! Continue reading to see more examples of using Wasmtime to execute Wasm Modules, from the CLI or even embedded in your application! - diff --git a/docs/introduction.md b/docs/introduction.md index 904d8638c858..207285c71866 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -1,21 +1,19 @@ # Introduction [Wasmtime][github] is a [Bytecode Alliance][BA] project that is a standalone -wasm-only optimizing runtime for [WebAssembly] and [WASI]. It runs WebAssembly -code [outside of the Web], and can be used both as a command-line utility or as -a library embedded in a larger application. +optimizing runtime for [WebAssembly], [the Component Model], and [WASI]. It runs +WebAssembly code [outside of the Web], and can be used both as a command-line +utility or as a library embedded in a larger application. Wasmtime strives to be +a highly configurable and embeddable runtime to run on any scale of application. -Wasmtime strives to be a highly configurable and embeddable runtime to run on -any scale of application. Many features are still under development so if you -have a question don't hesitate to [file an issue][issue]. +This documentation is intended to serve a number of purposes and within you'll +find: -This guide is intended to serve a number of purposes and within you'll find: - -* [How to create simple wasm modules](tutorial-create-hello-world.md) * [How to use Wasmtime from a number of languages](lang.md) * [How to install and use the `wasmtime` CLI](cli.md) * Information about [stability](stability.md) and [security](security.md) in Wasmtime. +* Documentation about [contributing](contributing.md) to Wasmtime. ... and more! The source for this guide [lives on GitHub](https://github.com/bytecodealliance/wasmtime/tree/main/docs) and @@ -27,3 +25,4 @@ contributions are welcome! [WASI]: https://wasi.dev [outside of the Web]: https://webassembly.org/docs/non-web/ [issue]: https://github.com/bytecodealliance/wasmtime/issues/new +[the Component Model]: https://github.com/WebAssembly/component-model diff --git a/docs/security.md b/docs/security.md index b36284a4ad6b..8eeea3a9beb8 100644 --- a/docs/security.md +++ b/docs/security.md @@ -4,7 +4,9 @@ One of WebAssembly (and Wasmtime's) main goals is to execute untrusted code in a safe manner inside of a sandbox. WebAssembly is inherently sandboxed by design (must import all functionality, etc). This document is intended to cover the various sandboxing implementation strategies that Wasmtime has as they are -developed. +developed. This has also been documented in a [historical blog post] too. + +[historical blog post]: https://bytecodealliance.org/articles/security-and-correctness-in-wasmtime At this time Wasmtime implements what's necessary for the WebAssembly specification, for example memory isolation between instances. Additionally the diff --git a/docs/stability-tiers.md b/docs/stability-tiers.md index d67c946cd277..19c052919241 100644 --- a/docs/stability-tiers.md +++ b/docs/stability-tiers.md @@ -27,9 +27,21 @@ For explanations of what each tier means see below. | Target | `x86_64-unknown-linux-gnu` | | WASI Proposal | `wasi_snapshot_preview1` | | WASI Proposal | `wasi_unstable` | -| WebAssembly Proposal | `bulk-memory` | -| WebAssembly Proposal | `reference-types` | -| WebAssembly Proposal | `simd` | +| WebAssembly Proposal | [`mutable-globals`] | +| WebAssembly Proposal | [`sign-extension-ops`] | +| WebAssembly Proposal | [`nontrapping-float-to-int-conversion`] | +| WebAssembly Proposal | [`multi-value`] | +| WebAssembly Proposal | [`bulk-memory`] | +| WebAssembly Proposal | [`reference-types`] | +| WebAssembly Proposal | [`simd`] | + +[`mutable-globals`]: https://github.com/WebAssembly/mutable-global/blob/master/proposals/mutable-global/Overview.md +[`sign-extension-ops`]: https://github.com/WebAssembly/spec/blob/master/proposals/sign-extension-ops/Overview.md +[`nontrapping-float-to-int-conversion`]: https://github.com/WebAssembly/spec/blob/master/proposals/nontrapping-float-to-int-conversion/Overview.md +[`multi-value`]: https://github.com/WebAssembly/spec/blob/master/proposals/multi-value/Overview.md +[`bulk-memory`]: https://github.com/WebAssembly/bulk-memory-operations/blob/master/proposals/bulk-memory-operations/Overview.md +[`reference-types`]: https://github.com/WebAssembly/reference-types/blob/master/proposals/reference-types/Overview.md +[`simd`]: https://github.com/WebAssembly/simd/blob/master/proposals/simd/SIMD.md #### Tier 2 @@ -38,8 +50,31 @@ For explanations of what each tier means see below. | Target | `aarch64-unknown-linux-gnu`| Continuous fuzzing | | Target | `s390x-unknown-linux-gnu` | Continuous fuzzing | | Target | `x86_64-pc-windows-gnu` | Clear owner of the target | -| WebAssembly Proposal | `memory64` | Unstable wasm proposal | -| WebAssembly Proposal | `multi-memory` | Unstable wasm proposal | +| WebAssembly Proposal | [`memory64`]] | Unstable wasm proposal | +| WebAssembly Proposal | [`multi-memory`] | Unstable wasm proposal | +| WebAssembly Proposal | [`threads`] | Unstable wasm proposal | +| WebAssembly Proposal | [`component-model`] | Unstable wasm proposal | +| WebAssembly Proposal | [`tail-call`] | Unstable wasm proposal, performance work | +| WebAssembly Proposal | [`relaxed-simd`] | Unstable wasm proposal | +| WebAssembly Proposal | [`function-references`] | Unstable wasm proposal | +| WASI Proposal | [`wasi-io`] | Unstable WASI proposal | +| WASI Proposal | [`wasi-clocks`] | Unstable WASI proposal | +| WASI Proposal | [`wasi-filesystem`] | Unstable WASI proposal | +| WASI Proposal | [`wasi-random`] | Unstable WASI proposal | +| WASI Proposal | [`wasi-poll`] | Unstable WASI proposal | + +[`memory64`]: https://github.com/WebAssembly/memory64/blob/master/proposals/memory64/Overview.md +[`multi-memory`]: https://github.com/WebAssembly/multi-memory/blob/master/proposals/multi-memory/Overview.md +[`threads`]: https://github.com/WebAssembly/threads/blob/master/proposals/threads/Overview.md +[`component-model`]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/Explainer.md +[`tail-call`]: https://github.com/WebAssembly/tail-call/blob/main/proposals/tail-call/Overview.md +[`relaxed-simd`]: https://github.com/WebAssembly/relaxed-simd/blob/main/proposals/relaxed-simd/Overview.md +[`function-references`]: https://github.com/WebAssembly/function-references/blob/main/proposals/function-references/Overview.md +[`wasi-clocks`]: https://github.com/WebAssembly/wasi-clocks +[`wasi-filesystem`]: https://github.com/WebAssembly/wasi-filesystem +[`wasi-io`]: https://github.com/WebAssembly/wasi-io +[`wasi-random`]: https://github.com/WebAssembly/wasi-random +[`wasi-poll`]: https://github.com/WebAssembly/wasi-poll #### Tier 3 @@ -48,12 +83,18 @@ For explanations of what each tier means see below. | Target | `aarch64-apple-darwin` | CI testing | | Target | `aarch64-pc-windows-msvc` | CI testing, unwinding, full-time maintainer | | Target | `riscv64gc-unknown-linux-gnu` | full-time maintainer | -| WASI Proposal | `wasi-nn` | More expansive CI testing | -| WebAssembly Proposal | `threads` | Complete implementation | -| WebAssembly Proposal | `component-model` | Complete implementation | +| WASI Proposal | [`wasi-nn`] | More expansive CI testing | +| WASI Proposal | [`wasi-threads`] | More CI, unstable proposal | +| WASI Proposal | [`wasi-sockets`] | Complete implementation | +| WASI Proposal | [`wasi-http`] | Complete implementation | | *misc* | Non-Wasmtime Cranelift usage [^1] | CI testing, full-time maintainer | | *misc* | DWARF debugging [^2] | CI testing, full-time maintainer, improved quality | +[`wasi-sockets`]: https://github.com/WebAssembly/wasi-sockets +[`wasi-nn`]: https://github.com/WebAssembly/wasi-nn +[`wasi-threads`]: https://github.com/WebAssembly/wasi-threads +[`wasi-http`]: https://github.com/WebAssembly/wasi-http + [^1]: This is intended to encompass features that Cranelift supports as a general-purpose code generator such as integer value types other than `i32` and `i64`, non-Wasmtime calling conventions, code model settings, relocation @@ -67,6 +108,46 @@ support is currently best-effort. Additionally there are known shortcomings and bugs. At this time there's no developer time to improve the situation here as well. +#### Unsupported features and platforms + +While this is not an exhaustive list, Wasmtime does not currently have support +for the following features. Note that this is intended to document Wasmtime's +current state and does not mean Wasmtime does not want to ever support these +features; rather design discussion and PRs are welcome for many of the below +features to figure out how best to implement them and at least move them to Tier +3 above. + +* Target: ARM 32-bit +* Target: WebAssembly (compiling Wasmtime to WebAssembly itself) +* Target: [FreeBSD](https://github.com/bytecodealliance/wasmtime/issues/5499) +* Target: [NetBSD/OpenBSD](https://github.com/bytecodealliance/wasmtime/issues/6962) +* Target: [i686 (32-bit Intel targets)](https://github.com/bytecodealliance/wasmtime/issues/1980) +* Target: Android +* Target: MIPS +* Target: SPARC +* Target: PowerPC +* Target: RISC-V 32-bit +* [WebAssembly proposal: `branch-hinting`](https://github.com/WebAssembly/branch-hinting) +* [WebAssembly proposal: `exception-handling`](https://github.com/WebAssembly/exception-handling) +* [WebAssembly proposal: `extended-const`](https://github.com/WebAssembly/extended-const) +* [WebAssembly proposal: `flexible-vectors`](https://github.com/WebAssembly/flexible-vectors) +* [WebAssembly proposal: `gc`](https://github.com/WebAssembly/gc) +* [WebAssembly proposal: `memory-control`](https://github.com/WebAssembly/memory-control) +* [WebAssembly proposal: `stack-switching`](https://github.com/WebAssembly/stack-switching) +* [WASI proposal: `proxy-wasm`](https://github.com/proxy-wasm/spec) +* [WASI proposal: `wasi-blob-store`](https://github.com/WebAssembly/wasi-blob-store) +* [WASI proposal: `wasi-crypto`](https://github.com/WebAssembly/wasi-crypto) +* [WASI proposal: `wasi-data`](https://github.com/WebAssembly/wasi-data) +* [WASI proposal: `wasi-distributed-lock-service`](https://github.com/WebAssembly/wasi-distributed-lock-service) +* [WASI proposal: `wasi-grpc`](https://github.com/WebAssembly/wasi-grpc) +* [WASI proposal: `wasi-kv-store`](https://github.com/WebAssembly/wasi-kv-store) +* [WASI proposal: `wasi-message-queue`](https://github.com/WebAssembly/wasi-message-queue) +* [WASI proposal: `wasi-parallel`](https://github.com/WebAssembly/wasi-parallel) +* [WASI proposal: `wasi-pubsub`](https://github.com/WebAssembly/wasi-pubsub) +* [WASI proposal: `wasi-runtime-config`](https://github.com/WebAssembly/wasi-runtime-config) +* [WASI proposal: `wasi-sql`](https://github.com/WebAssembly/wasi-sql) +* [WASI proposal: `wasi-url`](https://github.com/WebAssembly/wasi-url) + ## Tier Details Wasmtime's precise definitions of tiers are not guaranteed to be constant over diff --git a/docs/stability-wasi-proposals-support.md b/docs/stability-wasi-proposals-support.md deleted file mode 100644 index a3964bf5ebc5..000000000000 --- a/docs/stability-wasi-proposals-support.md +++ /dev/null @@ -1,60 +0,0 @@ -# WASI Proposals Support - -The following table summarizes Wasmtime's support for WASI [proposals]. If a -proposal is not listed, then it is not supported by Wasmtime. - -[proposals]: https://github.com/WebAssembly/WASI/blob/main/Proposals.md - -| WASI Proposal | Supported in Wasmtime? | Enabled by default? | CLI Flag Name [^cli] | -|----------------------------------------|-------------------------|----------------------|-----------------------------| -| [I/O][wasi-io] | **Yes** | **Yes** | `wasi-common` | -| [Filesystem][wasi-filesystem] | **Yes** | **Yes** | `wasi-common` | -| [Clocks][wasi-clocks] | **Yes** | **Yes** | `wasi-common` | -| [Random][wasi-random] | **Yes** | **Yes** | `wasi-common` | -| [Poll][wasi-poll] | **Yes** | **Yes** | `wasi-common` | -| [Machine Learning (wasi-nn)][wasi-nn] | **Yes** | No | `experimental-wasi-nn` | -| [Blob Store][wasi-blob-store] | No | No | N/A | -| [Crypto][wasi-crypto] | No | No | N/A | -| [Distributed Lock Service][wasi-distributed-lock-service] | No | No | N/A | -| [gRPC][wasi-grpc] | No | No | N/A | -| [HTTP][wasi-http] | No | No | N/A | -| [Key-value Store][wasi-kv-store] | No | No | N/A | -| [Message Queue][wasi-message-queue] | No | No | N/A | -| [Parallel][wasi-parallel] | No (see [#4949]) | No | N/A | -| [Pub/sub][wasi-pubsub] | No | No | N/A | -| [Runtime Config][wasi-runtime-config] | No | No | N/A | -| [Sockets][wasi-sockets] | No | No | N/A | -| [SQL][wasi-sql] | No | No | N/A | -| [Threads][wasi-threads] | **Yes** | No | `experimental-wasi-threads` | - -[^cli]: The CLI flag name refers to to the `--wasi-modules` argument of the - `wasmtime` executable; e.g., `--wasi-modules=wasi-crypto`. See `wasmtime run - --help` for more information on the flag's default value and configuration. -[^crypto]: Build Wasmtime with `--features=wasi-crypto` to enable this. - -[#4949]: https://github.com/bytecodealliance/wasmtime/pull/4949 -[wasi-blob-store]: https://github.com/WebAssembly/wasi-blob-store -[wasi-clocks]: https://github.com/WebAssembly/wasi-clocks -[wasi-classic-command]: https://github.com/WebAssembly/wasi-classic-command -[wasi-crypto]: https://github.com/WebAssembly/wasi-crypto -[wasi-data]: https://github.com/singlestore-labs/wasi-data -[wasi-distributed-lock-service]: https://github.com/WebAssembly/wasi-distributed-lock-service -[wasi-filesystem]: https://github.com/WebAssembly/wasi-filesystem -[wasi-grpc]: https://github.com/WebAssembly/wasi-grpc -[wasi-handle-index]: https://github.com/WebAssembly/wasi-handle-index -[wasi-http]: https://github.com/WebAssembly/wasi-http -[wasi-io]: https://github.com/WebAssembly/wasi-io -[wasi-kv-store]: https://github.com/WebAssembly/wasi-kv-store -[wasi-message-queue]: https://github.com/WebAssembly/wasi-message-queue -[wasi-misc]: https://github.com/WebAssembly/wasi-misc -[wasi-threads]: https://github.com/WebAssembly/wasi-native-threads -[wasi-nn]: https://github.com/WebAssembly/wasi-nn -[wasi-random]: https://github.com/WebAssembly/wasi-random -[wasi-parallel]: https://github.com/WebAssembly/wasi-parallel -[wasi-poll]: https://github.com/WebAssembly/wasi-poll -[wasi-proxy-wasm]: https://github.com/proxy-wasm/spec -[wasi-pubsub]: https://github.com/WebAssembly/wasi-pubsub -[wasi-runtime-config]: https://github.com/WebAssembly/wasi-runtime-config -[wasi-sockets]: https://github.com/WebAssembly/wasi-sockets -[wasi-sql]: https://github.com/WebAssembly/wasi-sql -[wasi-url]: https://github.com/WebAssembly/wasi-url diff --git a/docs/stability-wasm-proposals-support.md b/docs/stability-wasm-proposals-support.md deleted file mode 100644 index 9d56a72fa32b..000000000000 --- a/docs/stability-wasm-proposals-support.md +++ /dev/null @@ -1,43 +0,0 @@ -# WebAssembly Proposals Support - -The following table summarizes Wasmtime's support for WebAssembly proposals as -well as the command line flag and [`wasmtime::Config`][config] method you can -use to enable or disable support for a proposal. - -If a proposal is not listed, then it is not supported by Wasmtime. - -Wasmtime will never enable a proposal by default unless it has reached phase 4 -of [the WebAssembly standardizations process][phases] and its implementation in -Wasmtime has been [thoroughly -vetted](./contributing-implementing-wasm-proposals.html). - -| WebAssembly Proposal | Supported in Wasmtime? | Command Line Name | [`Config`][config] Method | -|---------------------------------------------|----------------------------------|--------------------|---------------------------| -| **[Import and Export Mutable Globals]** | **Yes.**
Always enabled. | (none) | (none) | -| **[Sign-Extension Operations]** | **Yes.**
Always enabled. | (none) | (none) | -| **[Non-Trapping Float-to-Int Conversions]** | **Yes.**
Always enabled. | (none) | (none) | -| **[Multi-Value]** | **Yes.**
Enabled by default. | `multi-value` | [`wasm_multi_value`](https://docs.rs/wasmtime/*/wasmtime/struct.Config.html#method.wasm_multi_value) | -| **[Bulk Memory Operations]** | **Yes.**
Enabled by default. | `bulk-memory` | [`wasm_bulk_memory`](https://docs.rs/wasmtime/*/wasmtime/struct.Config.html#method.wasm_bulk_memory) | -| **[Reference Types]** | **Yes.**
Enabled by default. | `reference-types` | [`wasm_reference_types`](https://docs.rs/wasmtime/*/wasmtime/struct.Config.html#method.wasm_reference_types) | -| **[Fixed-Width SIMD]** | **Yes.**
Enabled by default. | `simd` | [`wasm_simd`](https://docs.rs/wasmtime/*/wasmtime/struct.Config.html#method.wasm_simd) | -| **[Threads and Atomics]** | **Yes.** | `threads` | [`wasm_threads`](https://docs.rs/wasmtime/*/wasmtime/struct.Config.html#method.wasm_threads) | -| **[Multi-Memory]** | **Yes.** | `multi-memory` | [`wasm_multi_memory`](https://docs.rs/wasmtime/*/wasmtime/struct.Config.html#method.wasm_multi_memory) | -| **[Component Model]** | **In progress.** | `component-model` | [`wasm_component_model`](https://docs.rs/wasmtime/*/wasmtime/struct.Config.html#method.wasm_component_model) | -| **[Memory64]** | **Yes.** | `memory64` | [`wasm_memory64`](https://docs.rs/wasmtime/*/wasmtime/struct.Config.html#method.wasm_memory64) | - -The "Command Line Name" refers to the `--wasm-features` CLI argument of the -`wasmtime` executable and the name which must be passed to enable it. - -[config]: https://docs.rs/wasmtime/*/wasmtime/struct.Config.html -[Multi-Value]: https://github.com/WebAssembly/spec/blob/master/proposals/multi-value/Overview.md -[Bulk Memory Operations]: https://github.com/WebAssembly/bulk-memory-operations/blob/master/proposals/bulk-memory-operations/Overview.md -[Import and Export Mutable Globals]: https://github.com/WebAssembly/mutable-global/blob/master/proposals/mutable-global/Overview.md -[Reference Types]: https://github.com/WebAssembly/reference-types/blob/master/proposals/reference-types/Overview.md -[Non-Trapping Float-to-Int Conversions]: https://github.com/WebAssembly/spec/blob/master/proposals/nontrapping-float-to-int-conversion/Overview.md -[Sign-Extension Operations]: https://github.com/WebAssembly/spec/blob/master/proposals/sign-extension-ops/Overview.md -[Fixed-Width SIMD]: https://github.com/WebAssembly/simd/blob/master/proposals/simd/SIMD.md -[phases]: https://github.com/WebAssembly/meetings/blob/master/process/phases.md -[Threads and Atomics]: https://github.com/WebAssembly/threads/blob/master/proposals/threads/Overview.md -[Multi-Memory]: https://github.com/WebAssembly/multi-memory/blob/master/proposals/multi-memory/Overview.md -[Component Model]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/Explainer.md -[Memory64]: https://github.com/WebAssembly/memory64/blob/master/proposals/memory64/Overview.md diff --git a/docs/tutorial-create-hello-world.md b/docs/tutorial-create-hello-world.md deleted file mode 100644 index 6f2d9cb6da66..000000000000 --- a/docs/tutorial-create-hello-world.md +++ /dev/null @@ -1,63 +0,0 @@ -# Creating `hello-world.wasm` - -There are a number of ways to create `.wasm` files but for the purposes of this -tutorial, we'll be using the Rust toolchain. You can find more information on -creating `.wasm` files from other languages in the -[Writing WebAssembly section](./wasm.md). - -To build WebAssembly binaries with Rust, you'll need the standard Rust toolchain. - -[Follow these instructions to install `rustc`, `rustup` and `cargo`](https://www.rust-lang.org/tools/install) - -Next, you should add WebAssembly as a build target for cargo like so: - -```sh -$ rustup target add wasm32-wasi -``` - -Finally, create a new Rust project called 'hello-world'. You can do this by running: - -```sh -$ cargo new hello-world -``` - -After that, the hello-world folder should look like this. - -```text -hello-world/ -├── Cargo.lock -├── Cargo.toml -└── src - └── main.rs -``` - -And the `main.rs` file inside the `src` folder should contain the following rust code. - -```rust -fn main() { - println!("Hello, world!"); -} - -``` - -Now, we can tell `cargo` to build a WebAssembly file: - -```sh -$ cargo build --target wasm32-wasi -``` - -Now, in the `target` folder, there's a `hello-world.wasm` file. You can find it here: - -```text -hello-world/ -├── Cargo.lock -├── Cargo.toml -├── src -└── target - └── ... - └── wasm32-wasi - └── debug - └── ... - └── hello-world.wasm - -``` diff --git a/docs/tutorial-run-hello-world.md b/docs/tutorial-run-hello-world.md deleted file mode 100644 index 770f14fce7e6..000000000000 --- a/docs/tutorial-run-hello-world.md +++ /dev/null @@ -1,28 +0,0 @@ -# Running `hello-world.wasm` with Wasmtime - -## Installing Wasmtime - -The Wasmtime CLI can be installed on Linux and macOS with a small install -script: - -```sh -$ curl https://wasmtime.dev/install.sh -sSf | bash -``` - -You can find more information about installing the Wasmtime CLI in the -[CLI Installation section](./cli-install.md) - -## Running `hello-world.wasm` - -There are a number of ways to run a `.wasm` file with Wasmtime. In this -tutorial, we'll be using the CLI, Wasmtime can also be embedded in your -applications. More information on this can be found in the -[Embedding Wasmtime section](./lang.md). - -If you've built the `hello-world.wasm` file (the instructions for doing so are in the -[previous section](./tutorial-create-hello-world.md)), -you can run it with Wasmtime from the command line like so: - -```sh -$ wasmtime target/wasm32-wasi/debug/hello-world.wasm -``` diff --git a/docs/tutorial.md b/docs/tutorial.md deleted file mode 100644 index dc19ed194691..000000000000 --- a/docs/tutorial.md +++ /dev/null @@ -1,7 +0,0 @@ -# Tutorial - -This tutorial walks through creating a simple Hello World WebAssembly program -and then running it. - -* [Creating `hello-world.wasm`](tutorial-create-hello-world.md) -* [Running `hello-world.wasm`](tutorial-run-hello-world.md) diff --git a/docs/wasm-assemblyscript.md b/docs/wasm-assemblyscript.md deleted file mode 100644 index 527b7828f238..000000000000 --- a/docs/wasm-assemblyscript.md +++ /dev/null @@ -1,77 +0,0 @@ -# AssemblyScript - -[AssemblyScript] has included support for targeting WASI since version 0.10.0. If you're not familiar with AssemblyScript, check out the [docs](https://www.assemblyscript.org/introduction.html) or the [discord server](https://discord.gg/assemblyscript). -To setup this demo, you need a valid installation of [NodeJS](https://nodejs.org/), [Deno](https://deno.com/runtime), or [Bun](https://bun.sh/) along with a installation of [wasmtime](https://github.com/bytecodealliance/wasmtime). - -For the rest of this documentation, we'll default to NPM as our package manager. Feel free to use the manager of your choice. - -Let's walk through a simple hello world example using the latest AssemblyScript runtime (at the time of this writing, it is AssemblyScript runtime included in version 0.27.x): - -## Hello World! - -Enabling WASI support in AssemblyScript requires some configuration and dependencies in order to compile with WASI support. - -First, we'll install [assemblyscript](https://github.com/AssemblyScript/AssemblyScript) along with [wasi-shim](https://github.com/AssemblyScript/wasi-shim) which is a plugin that adds support for WASI. - -```sh -$ npm install --save-dev assemblyscript @assemblyscript/wasi-shim -``` - -Next, we'll use the built in `asinit` command to create our project files. When prompted, type `y` and return. - -```sh -$ npx asinit . -``` - -Next, we need to configure our project to use WASI as a build target. Navigate to `asconfig.json` and add the following line. - -`asconfig.json` -```json -{ - // "targets": { ... }, - "extends": "./node_modules/@assemblyscript/wasi-shim/asconfig.json" -} -``` - -With AssemblyScript now configured to use WASI, we can enter `./assembly/index.ts` and change it to the following. This will tell WASI to print the string to the terminal. - -`assembly/index.ts` -```js -console.log("Hello World!"); -``` - -Now, compile our WASI module using the `asc` command and run it using `wasmtime`. - -```sh -$ npx asc assembly/index.ts --target release -$ wasmtime ./build/release.wasm -``` - -Now that we know how to use WASI, we'll test the capabilities of WASI using a demo. - -## WASI Demo - -First, clone the [wasmtime](https://github.com/bytecodealliance/wasmtime) repository and navigate to the `docs/assemblyscript_demo` directory. - -```sh -$ git clone https://github.com/bytecodealliance/wasmtime -$ cd wasmtime/docs/assemblyscript_demo -``` - -Install our dependencies with NPM or your preferred package manager. - -```sh -$ npm install -``` - -Take a look at the code in `docs/assemblyscript_demo/wasi-demo.ts` and then build the WASM/WASI binary by running - -```sh -$ npx asc wasi-demo.ts --target wasi-demo -``` - -Lastly, run the demo using - -```sh -$ wasmtime ./build/wasi-demo.wasm -``` diff --git a/docs/wasm-c.md b/docs/wasm-c.md deleted file mode 100644 index d4c05d6a94b9..000000000000 --- a/docs/wasm-c.md +++ /dev/null @@ -1,28 +0,0 @@ -# C/C++ - -All the parts needed to support wasm are included in upstream clang, lld, and -compiler-rt, as of the LLVM 8.0 release. However, to use it, you'll need -to build WebAssembly-targeted versions of the library parts, and it can -be tricky to get all the CMake invocations lined up properly. - -To make things easier, we provide -[prebuilt packages](https://github.com/WebAssembly/wasi-sdk/releases) -that provide builds of Clang and sysroot libraries. - -WASI doesn't yet support `setjmp`/`longjmp` or C++ exceptions, as it is -waiting for [unwinding support in WebAssembly]. - -By default, the C/C++ toolchain orders linear memory to put the globals first, -the stack second, and start the heap after that. This reduces code size, -because references to globals can use small offsets. However, it also means -that stack overflow will often lead to corrupted globals. The -`-Wl,--stack-first` flag to clang instructs it to put the stack first, followed -by the globals and the heap, which may produce slightly larger code, but will -more reliably trap on stack overflow. - -See the [wasm-ld documentation] for more information and additional flags. Note -flags related to dynamic linking, such `-shared` and `--export-dynamic` are -not yet stable and are expected to change behavior in the future. - -[unwinding support in WebAssembly]: https://github.com/WebAssembly/exception-handling/ -[wasm-ld documentation]: https://lld.llvm.org/WebAssembly.html diff --git a/docs/wasm-rust.md b/docs/wasm-rust.md deleted file mode 100644 index 1e8fddd86ced..000000000000 --- a/docs/wasm-rust.md +++ /dev/null @@ -1,178 +0,0 @@ -# Rust - -The [Rust Programming Language](https://www.rust-lang.org) supports WebAssembly -as a compilation target. If you're not familiar with Rust it's recommended to -start [with its introductory documentation](https://www.rust-lang.org/learn). -Compiling to WebAssembly will involve specifying the desired target via the -`--target` flag, and to do this there are a number of "target triples" for -WebAssembly compilation in Rust: - -* `wasm32-wasi` - when using `wasmtime` this is likely what you'll be using. The - WASI target is integrated into the standard library and is intended on - producing standalone binaries. -* `wasm32-unknown-unknown` - this target, like the WASI one, is focused on - producing single `*.wasm` binaries. The standard library, however, is largely - stubbed out since the "unknown" part of the target means libstd can't assume - anything. This means that while binaries will likely work in `wasmtime`, - common conveniences like `println!` or `panic!` won't work. -* `wasm32-unknown-emscripten` - this target is intended to work in a web browser - and produces a `*.wasm` file coupled with a `*.js` file, and it is not - compatible with `wasmtime`. - -For the rest of this documentation we'll assume that you're using the -`wasm32-wasi` target for compiling Rust code and executing inside of `wasmtime`. - -## Hello, World! - -Cross-compiling to WebAssembly involves a number of knobs that need -configuration, but you can often gloss over these internal details by using -build tooling intended for the WASI target. For example we can start out writing -a WebAssembly binary with [`cargo -wasi`](https://github.com/bytecodealliance/cargo-wasi). - -First up we'll [install `cargo -wasi`](https://bytecodealliance.github.io/cargo-wasi/install.html): - -```sh -$ cargo install cargo-wasi -``` - -Next we'll make a new Cargo project: - -```sh -$ cargo new hello-world -$ cd hello-world -``` - -Inside of `src/main.rs` you'll see the canonical Rust "Hello, World!" using -`println!`. We'll be executing this for the `wasm32-wasi` target, so you'll want -to make sure you're previously [built `wasmtime` and inserted it into -`PATH`](./cli-install.md); - -```sh -$ cargo wasi run -info: downloading component 'rust-std' for 'wasm32-wasi' -info: installing component 'rust-std' for 'wasm32-wasi' - Compiling hello-world v0.1.0 (/hello-world) - Finished dev [unoptimized + debuginfo] target(s) in 0.16s - Running `/.cargo/bin/cargo-wasi target/wasm32-wasi/debug/hello-world.wasm` - Running `target/wasm32-wasi/debug/hello-world.wasm` -Hello, world! -``` - -And we're already running our first WebAssembly code inside of `wasmtime`! - -While it's automatically happening for you as part of `cargo wasi`, you can also -run `wasmtime` yourself: - -```sh -$ wasmtime target/wasm32-wasi/debug/hello-world.wasm -Hello, world! -``` - -You can check out the [introductory documentation of -`cargo-wasi`](https://bytecodealliance.github.io/cargo-wasi/hello-world.html) as -well for some more information. - -## Writing Libraries - -Previously for "Hello, World!" we created a *binary* project which used -`src/main.rs`. Not all `*.wasm` binaries are intended to be executed like -commands, though. Some are intended to be loaded into applications and called -through various APIs, acting more like libraries. For this use case you'll want -to add this to `Cargo.toml`: - -```toml -# in Cargo.toml ... - -[lib] -crate-type = ['cdylib'] -``` - -and afterwards you'll want to write your code in `src/lib.rs` like so: - -```rust -#[no_mangle] -pub extern "C" fn print_hello() { - println!("Hello, world!"); -} -``` - -When you execute `cargo wasi build` that'll generate a `*.wasm` file which has -one exported function, `print_hello`. We can then run it via the CLI like so: - -```sh -$ cargo wasi build - Compiling hello-world v0.1.0 (/home/alex/code/hello-world) - Finished dev [unoptimized + debuginfo] target(s) in 0.08s -$ wasmtime --invoke print_hello target/wasm32-wasi/debug/hello_world.wasm -Hello, world! -``` - -As a library crate one of your primary consumers may be other languages as well. -You'll want to consult the [section of this book for using `wasmtime` from -Python](./lang-python.md) and after running through the basics there you can -execute our file in Python: - -```sh -$ cp target/wasm32-wasi/debug/hello_world.wasm . -$ python3 ->>> import wasmtime ->>> import hello_world ->>> hello_world.print_hello() -Hello, world! -() ->>> -``` - -Note that this form of using `#[no_mangle]` Rust functions is pretty primitive. -You're only able to work with primitive datatypes like integers and floats. -While this works for some applications if you need to work with richer types -like strings or structs, then you'll want to use the support in `wasmtime` for -interface types. - -## Exporting Rust functionality - -Currently only Rust functions can be exported from a wasm module. Rust functions -must be `#[no_mangle]` to show up in the final binary. - -Memory is by default exported from Rust modules under the name `memory`. This -can be tweaked with the `-Clink-arg` flag to rustc to pass flags to LLD, the -WebAssembly code linker. - -Tables cannot be imported at this time. When using `rustc` directly there is no -support for `anyref` and only one function table is supported. When using -`wasm-bindgen` it may inject an `anyref` table if necessary, but this table is -an internal detail and is not exported. The function table can be exported by -passing the `--export-table` argument to LLD (via `-C link-arg`) or can be -imported with the `--import-table`. - -Rust currently does not have support for exporting or importing custom `global` -values. - -## Importing host functionality - -Only functions can be imported in Rust at this time, and they can be imported -via raw interfaces like: - -```rust -# struct MyStruct; -#[link(wasm_import_module = "the-wasm-import-module")] -extern "C" { - // imports the name `foo` from `the-wasm-import-module` - fn foo(); - - // functions can have integer/float arguments/return values - fn translate(a: i32) -> f32; - - // Note that the ABI of Rust and wasm is somewhat in flux, so while this - // works, it's recommended to rely on raw integer/float values where - // possible. - fn translate_fancy(my_struct: MyStruct) -> u32; - - // you can also explicitly specify the name to import, this imports `bar` - // instead of `baz` from `the-wasm-import-module`. - #[link_name = "bar"] - fn baz(); -} -``` diff --git a/docs/wasm-wat.md b/docs/wasm-wat.md deleted file mode 100644 index 634d3573090b..000000000000 --- a/docs/wasm-wat.md +++ /dev/null @@ -1,56 +0,0 @@ -# WebAssembly Text Format (`*.wat`) - -While not necessarily a full-blown language you might be curious how Wasmtime -interacts with [the `*.wat` text format][spec]! The `wasmtime` CLI and Rust -embedding API both support the `*.wat` text format by default. - -"Hello, World!" is pretty nontrivial in the `*.wat` format since it's -assembly-like and not really intended to be a primary programming language. That -being said we can create a simple add function to call it! - -For example if you have a file `add.wat` like so: - -```wat -(module - (func (export "add") (param i32 i32) (result i32) - local.get 0 - local.get 1 - i32.add)) -``` - -Then you can execute this on the CLI with: - -```sh -$ wasmtime add.wat --invoke add 1 2 -warning: ... -warning: ... -3 -``` - -And we can see that we're already adding numbers! - -You can also see how this works in the Rust API like so: - -```rust -# extern crate wasmtime; -# extern crate anyhow; -use wasmtime::*; - -# fn main() -> anyhow::Result<()> { -let mut store = Store::<()>::default(); -let wat = r#" - (module - (func (export "add") (param i32 i32) (result i32) - local.get 0 - local.get 1 - i32.add)) -"#; -let module = Module::new(store.engine(), wat)?; -let instance = Instance::new(&mut store, &module, &[])?; -let add = instance.get_typed_func::<(i32, i32), i32>(&mut store, "add")?; -println!("1 + 2 = {}", add.call(&mut store, (1, 2))?); -# Ok(()) -# } -``` - -[spec]: https://webassembly.github.io/spec/core/text/index.html diff --git a/docs/wasm.md b/docs/wasm.md deleted file mode 100644 index fb442f6006e0..000000000000 --- a/docs/wasm.md +++ /dev/null @@ -1,13 +0,0 @@ -# Writing WebAssembly - -Wasmtime is a runtime for *executing* WebAssembly but you also at some point -need to actually produce the WebAssembly module to feed into Wasmtime! This -section of the guide is intended to provide some introductory documentation for -compiling source code to WebAssembly to later run in Wasmtime. There's plenty of -other documentation on the web for doing this, so you'll want to be sure to -check out your language's documentation for WebAssembly as well. - -* [Rust](wasm-rust.md) -* [C/C++](wasm-c.md) -* [AssemblyScript](wasm-assemblyscript.md) -* [WebAssembly Text Format (`*.wat`)](wasm-wat.md)