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* [ ] Implement support for the proposal in the [`wasm-tools` repository].
10  [(example)](https://github.com/bytecodealliance/wasm-tools/pull/1853)
11  * [ ] [`wast`] - text parsing
12  * [ ] [`wasmparser`] - binary decoding and validation
13  * [ ] [`wasmprinter`] - binary-to-text
14  * [ ] [`wasm-encoder`] - binary encoding
15  * [ ] [`wasm-smith`] - fuzz test case generation
16* [ ] Update Wasmtime to use these `wasm-tools` crates, but leave the new
17  proposal unimplemented for now (implementation comes in subsequent PRs).
18  [(example)](https://github.com/bytecodealliance/wasmtime/pull/9399)
19* [ ] Add `Config::wasm_your_proposal` to the `wasmtime` crate.
20* [ ] Implement the proposal in `wasmtime`, gated behind this flag.
21* [ ] Add `-Wyour-proposal` to the `wasmtime-cli-flags` crate.
22* [ ] Update `tests/wast.rs` to spec tests should pass for this proposal.
23* [ ] Write custom tests in `tests/misc_testsuite/*.wast` for this proposal.
24* [ ] Enable the proposal in [the fuzz targets](./contributing-fuzzing.md).
25  * [ ] Write a custom fuzz target, oracle, and/or test
26    case generator for fuzzing this proposal in particular.
27
28    > For example, we wrote a [custom
29    > generator](https://github.com/bytecodealliance/wasmtime/blob/c7cd70fcec3eee66c9d7b5aa6fb4580d5a802218/crates/fuzzing/src/generators/table_ops.rs),
30    > [oracle](https://github.com/bytecodealliance/wasmtime/blob/c7cd70fcec3eee66c9d7b5aa6fb4580d5a802218/crates/fuzzing/src/oracles.rs#L417-L467),
31    > and [fuzz
32    > target](https://github.com/bytecodealliance/wasmtime/blob/c7cd70fcec3eee66c9d7b5aa6fb4580d5a802218/fuzz/fuzz_targets/table_ops.rs)
33    > for exercising `table.{get,set}` instructions and their interaction with
34    > GC while implementing the reference types proposal.
35* [ ] Expose the proposal's new functionality in the `wasmtime` crate's API.
36
37  > For example, the bulk memory operations proposal introduced a `table.copy`
38  > instruction, and we exposed its functionality as the `wasmtime::Table::copy`
39  > method.
40* [ ] Expose the proposal's new functionality in the C API.
41
42  > This may require extensions to the standard C API, and if so, should be
43  > defined in
44  > [`wasmtime.h`](https://github.com/bytecodealliance/wasmtime/blob/c7cd70fcec3eee66c9d7b5aa6fb4580d5a802218/crates/c-api/include/wasmtime.h)
45  > and prefixed with `wasmtime_`.
46* [ ] Update `docs/stability-tiers.md` with an implementation status of the
47  proposal.
48
49
50[`wasm-tools` repository]: https://github.com/bytecodealliance/wasm-tools
51[`wasmparser`]: https://github.com/bytecodealliance/wasm-tools/tree/main/crates/wasmparser
52[`wast`]: https://github.com/bytecodealliance/wasm-tools/tree/main/crates/wast
53[`wasmprinter`]: https://github.com/bytecodealliance/wasm-tools/tree/main/crates/wasmprinter
54[`wasm-encoder`]: https://github.com/bytecodealliance/wasm-tools/tree/main/crates/wasm-encoder
55[`wasm-smith`]: https://github.com/bytecodealliance/wasm-tools/tree/main/crates/wasm-smith
56
57For information about the status of implementation of various proposals in
58Wasmtime see the [associated documentation](./stability-wasm-proposals.md).
59
60## Adding component functionality to WASI
61The [cap-std](https://github.com/bytecodealliance/cap-std) repository contains
62crates which implement the capability-based version of the Rust standard library
63and extensions to that functionality. Once the functionality has been added to
64the relevant crates of that repository, they can be added into wasmtime by
65including them in the preview2 directory of the [wasi crate](https://github.com/bytecodealliance/wasmtime/tree/main/crates/wasi).
66
67Currently, WebAssembly modules which rely on preview2 ABI cannot be directly
68executed by the wasmtime command. The following steps allow for testing such
69changes.
70
711. Build wasmtime with the changes `cargo build --release`
72
732. Create a simple Webassembly module to test the new component functionality by
74compiling your test code to the `wasm32-wasip1` build target.
75
763. Build the [wasi-preview1-component-adapter](https://github.com/bytecodealliance/wasmtime/tree/main/crates/wasi-preview1-component-adapter)
77as a command adapter. `cargo build -p wasi-preview1-component-adapter --target
78wasm32-wasip1 --release --features command --no-default-features`
79
804. Use [wasm-tools](https://github.com/bytecodealliance/wasm-tools) to convert
81the test module to a component. `wasm-tools component new --adapt
82wasi_snapshot_preview1=wasi_snapshot_preview1.command.wasm -o component.wasm
83path/to/test/module`
84
855. Run the test component created in the previous step with the locally built
86wasmtime. `wasmtime -W component-model=y -S preview2=y component.wasm`
87