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 -
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.**