1# Implementing WebAssembly Proposals 2 3## Adding New Support for a Wasm Proposal 4 5The following checkboxes enumerate the steps required to add support for a new 6WebAssembly proposal to Wasmtime. They can be completed over the course of 7multiple pull requests. 8 9* <input type="checkbox"/> Add support to the 10 [`wasmparser`](https://github.com/bytecodealliance/wasm-tools/tree/main/crates/wasmparser) 11 crate. 12 13* <input type="checkbox"/> Add support to the 14 [`wat`](https://github.com/bytecodealliance/wasm-tools/tree/main/crates/wat) 15 and 16 [`wast`](https://github.com/bytecodealliance/wasm-tools/tree/main/crates/wast) 17 crates. 18 19* <input type="checkbox"/> Add support to the 20 [`wasmprinter`](https://github.com/bytecodealliance/wasm-tools/tree/main/crates/wasmprinter) 21 crate. 22 23* <input type="checkbox"/> Add support to the 24 [`wasm-encoder`](https://github.com/bytecodealliance/wasm-tools/tree/main/crates/wasm-encoder) 25 crate. 26 27* <input type="checkbox"/> Add support to the 28 [`wasm-smith`](https://github.com/bytecodealliance/wasm-tools/tree/main/crates/wasm-smith) 29 crate. 30 31* <input type="checkbox"/> Add a `wasmtime::Config::enable_foo_bar` method to 32 the `wasmtime` crate. 33 34* <input type="checkbox"/> Add a `--enable-foo-bar` command line flag to the 35 `wasmtime` binary. 36 37* <input type="checkbox"/> Enable the spec tests in 38 [`build.rs`](https://github.com/bytecodealliance/wasmtime/blob/c7cd70fcec3eee66c9d7b5aa6fb4580d5a802218/build.rs#L41-L52) 39 but [mark them as 40 ignored](https://github.com/bytecodealliance/wasmtime/blob/c7cd70fcec3eee66c9d7b5aa6fb4580d5a802218/build.rs#L196) 41 for now. 42 43* <input type="checkbox"/> Stop ignoring individual spec tests and get them 44 passing one by one. 45 46* <input type="checkbox"/> Enable the proposal in [the fuzz 47 targets](./contributing-fuzzing.html). 48 49 * <input type="checkbox"/> Add examples from the spec tests to [the relevant 50 corpora](https://github.com/bytecodealliance/wasmtime-libfuzzer-corpus). 51 52 > The `wast2json` tool from [WABT] is useful for this. 53 54 * <input type="checkbox"/> Write a custom fuzz target, oracle, and/or test 55 case generator for fuzzing this proposal in particular. 56 57 > For example, we wrote a [custom 58 > generator](https://github.com/bytecodealliance/wasmtime/blob/c7cd70fcec3eee66c9d7b5aa6fb4580d5a802218/crates/fuzzing/src/generators/table_ops.rs), 59 > [oracle](https://github.com/bytecodealliance/wasmtime/blob/c7cd70fcec3eee66c9d7b5aa6fb4580d5a802218/crates/fuzzing/src/oracles.rs#L417-L467), 60 > and [fuzz 61 > target](https://github.com/bytecodealliance/wasmtime/blob/c7cd70fcec3eee66c9d7b5aa6fb4580d5a802218/fuzz/fuzz_targets/table_ops.rs) 62 > for exercising `table.{get,set}` instructions and their interaction with 63 > GC while implementing the reference types proposal. 64 65* <input type="checkbox"/> Expose the proposal's new functionality in the 66 `wasmtime` crate's API. 67 68 > For example, the bulk memory operations proposal introduced a `table.copy` 69 > instruction, and we exposed its functionality as the `wasmtime::Table::copy` 70 > method. 71 72* <input type="checkbox"/> Expose the proposal's new functionality in the C API. 73 74 > This may require extensions to the standard C API, and if so, should be 75 > defined in 76 > [`wasmtime.h`](https://github.com/bytecodealliance/wasmtime/blob/c7cd70fcec3eee66c9d7b5aa6fb4580d5a802218/crates/c-api/include/wasmtime.h) 77 > and prefixed with `wasmtime_`. 78 79* <input type="checkbox"/> Use the C API to expose the proposal's new 80 functionality in the other language embedding APIs: 81 82 * <input type="checkbox"/> [Python](https://github.com/bytecodealliance/wasmtime-py/) 83 84 * <input type="checkbox"/> [Go](https://github.com/bytecodealliance/wasmtime-go/) 85 86 * <input type="checkbox"/> [.NET](https://github.com/bytecodealliance/wasmtime-dotnet/) 87 88* <input type="checkbox"/> Document support for the proposal in 89 `wasmtime/docs/stability-wasm-proposals-support.md`. 90 91## Enabling Support for a Proposal by Default 92 93These are the standards that must be met to enable support for a proposal by 94default in Wasmtime, and can be used as a review checklist. 95 96* <input type="checkbox"/> The proposal must be in phase 4, or greater, of [the 97 WebAssembly standardization process][phases]. 98 99* <input type="checkbox"/> All spec tests must be passing in Wasmtime. 100 101* <input type="checkbox"/> No open questions, design concerns, or serious known 102 bugs. 103 104* <input type="checkbox"/> Has been fuzzed for at least a week minimum. 105 106* <input type="checkbox"/> We are confident that the fuzzers are fully 107 exercising the proposal's functionality. 108 109 > For example, it would *not* have been enough to simply enable reference 110 > types in the `compile` fuzz target to enable that proposal by 111 > default. Compiling a module that uses reference types but not instantiating 112 > it nor running any of its functions doesn't exercise any of the GC 113 > implementation and does not run the inline fast paths for `table` operations 114 > emitted by the JIT. Exercising these things was the motivation for writing 115 > the custom fuzz target for `table.{get,set}` instructions. 116 117* <input type="checkbox"/> The proposal's functionality is exposed in the 118 `wasmtime` crate's API. 119 120* <input type="checkbox"/> The proposal's functionality is exposed in the C API. 121 122* <input type="checkbox"/> The proposal's functionality is exposed in at least 123 one of the other languages' APIs. 124 125[phases]: https://github.com/WebAssembly/meetings/blob/master/process/phases.md 126[WABT]: https://github.com/WebAssembly/wabt/ 127 128## Adding component functionality to WASI 129The [cap-std](https://github.com/bytecodealliance/cap-std) repository contains 130crates which implement the capability-based version of the Rust standard library 131and extensions to that functionality. Once the functionality has been added to 132the relevant crates of that repository, they can be added into wasmtime by 133including them in the preview2 directory of the [wasi crate](https://github.com/bytecodealliance/wasmtime/tree/main/crates/wasi). 134 135Currently, WebAssembly modules which rely on preview2 ABI cannot be directly 136executed by the wasmtime command. The following steps allow for testing such 137changes. 138 1391. Build wasmtime with the changes `cargo build --release` 140 1412. Create a simple Webassembly module to test the new component functionality by 142compiling your test code to the `wasm32-wasi` build target. 143 1443. Build the [wasi-preview1-component-adapter](https://github.com/bytecodealliance/wasmtime/tree/main/crates/wasi-preview1-component-adapter) 145as a command adapter. `cargo build -p wasi-preview1-component-adapter --target 146wasm32-wasi --release --features command --no-default-features` 147 1484. Use [wasm-tools](https://github.com/bytecodealliance/wasm-tools) to convert 149the test module to a component. `wasm-tools component new --adapt 150wasi_snapshot_preview1=wasi_snapshot_preview1.command.wasm -o component.wasm 151path/to/test/module` 152 1535. Run the test component created in the previous step with the locally built 154wasmtime. `wasmtime -W component-model=y -S preview2=y component.wasm` 155