# Wasm GC Implementation Plan

Milestone plan for implementing the [Wasm GC](https://github.com/WebAssembly/gc) specification.

(borrowed from https://docs.wasmtime.dev/contributing-implementing-wasm-proposals.html)

## Adding New Support for a Wasm Proposal

The following checkboxes enumerate the steps required to add support for a new WebAssembly proposal to Wasmtime. They can be completed over the course of multiple pull requests.

- Add support to the [`wat`](https://github.com/bytecodealliance/wasm-tools/tree/main/crates/wat) and [`wast`](https://github.com/bytecodealliance/wasm-tools/tree/main/crates/wast) crates: it's already there!
- [ ] (**in-progress**) Add support to the [`wasmparser`](https://github.com/bytecodealliance/wasm-tools/tree/main/crates/wasmparser) crate.
- [ ] (**in-progress**) Add support to the [`wasmprinter`](https://github.com/bytecodealliance/wasm-tools/tree/main/crates/wasmprinter) crate.
- [ ] (**in-progress**) Add support to the [`wasm-encoder`](https://github.com/bytecodealliance/wasm-tools/tree/main/crates/wasm-encoder) crate.
- [ ] Add support to the [`wasm-smith`](https://github.com/bytecodealliance/wasm-tools/tree/main/crates/wasm-smith) crate (this can be done in parallel with adding code to `wasmtime`).
- [ ] Add a `wasmtime::Config::enable_gc` method to the `wasmtime` crate.
- [ ] Add a `--enable-gc` command line flag to the `wasmtime` binary.
- [ ] Enable the spec tests in [`build.rs`](https://github.com/bytecodealliance/wasmtime/blob/c7cd70fcec3eee66c9d7b5aa6fb4580d5a802218/build.rs#L41-L52) but [mark them as ignored](https://github.com/bytecodealliance/wasmtime/blob/c7cd70fcec3eee66c9d7b5aa6fb4580d5a802218/build.rs#L196) for now.
- [ ] Stop ignoring individual spec tests and get them passing one by one.
- [ ] Enable the proposal in [the fuzz
targets](https://docs.wasmtime.dev/contributing-fuzzing.html).
- [ ] Add examples from the spec tests to [the relevant corpora](https://github.com/bytecodealliance/wasmtime-libfuzzer-corpus).
> The `wast2json` tool from [WABT] is useful for this.
- [ ] Write a custom fuzz target, oracle, and/or test
case generator for fuzzing this proposal in particular.
> For example, we wrote a [custom
> generator](https://github.com/bytecodealliance/wasmtime/blob/c7cd70fcec3eee66c9d7b5aa6fb4580d5a802218/crates/fuzzing/src/generators/table_ops.rs),
> [oracle](https://github.com/bytecodealliance/wasmtime/blob/c7cd70fcec3eee66c9d7b5aa6fb4580d5a802218/crates/fuzzing/src/oracles.rs#L417-L467),
> and [fuzz
> target](https://github.com/bytecodealliance/wasmtime/blob/c7cd70fcec3eee66c9d7b5aa6fb4580d5a802218/fuzz/fuzz_targets/table_ops.rs)
> for exercising `table.{get,set}` instructions and their interaction with
> GC while implementing the reference types proposal.
- [ ] Expose the proposal's new functionality in the
`wasmtime` crate's API.
> For example, the bulk memory operations proposal introduced a `table.copy`
> instruction, and we exposed its functionality as the `wasmtime::Table::copy`
> method.
- [ ] Expose the proposal's new functionality in the C API.
> This may require extensions to the standard C API, and if so, should be
> defined in
> [`wasmtime.h`](https://github.com/bytecodealliance/wasmtime/blob/c7cd70fcec3eee66c9d7b5aa6fb4580d5a802218/crates/c-api/include/wasmtime.h)
> and prefixed with `wasmtime_`.
- [ ] Use the C API to expose the proposal's new
functionality in the other language embedding APIs:
- [ ] [Python](https://github.com/bytecodealliance/wasmtime-py/)
- [ ] [Go](https://github.com/bytecodealliance/wasmtime-go/)
- [ ] [.NET](https://github.com/bytecodealliance/wasmtime-dotnet/)
- [ ] Document support for the proposal in
`wasmtime/docs/stability-wasm-proposals-support.md`.

## Enabling Support By Default

These are the standards that must be met to enable support for a proposal by
default in Wasmtime, and can be used as a review checklist.
- [ ] The proposal must be in phase 4, or greater, of [the
WebAssembly standardization process][phases].
- [ ] All spec tests must be passing in Wasmtime.
- [ ] No open questions, design concerns, or serious known
bugs.
- [ ] Has been fuzzed for at least a week minimum.
- [ ] We are confident that the fuzzers are fully
exercising the proposal's functionality.
> For example, it would *not* have been enough to simply enable reference
> types in the `compile` fuzz target to enable that proposal by
> default. Compiling a module that uses reference types but not instantiating
> it nor running any of its functions doesn't exercise any of the GC
> implementation and does not run the inline fast paths for `table` operations
> emitted by the JIT. Exercising these things was the motivation for writing
> the custom fuzz target for `table.{get,set}` instructions.
- [ ] The proposal's functionality is exposed in the
`wasmtime` crate's API.
- [ ] The proposal's functionality is exposed in the C API.
- [ ] The proposal's functionality is exposed in at least
one of the other languages' APIs.
[phases]: https://github.com/WebAssembly/meetings/blob/master/process/phases.md
[WABT]: https://github.com/WebAssembly/wabt/