From ed7075719f9b3733dff97d120176a284e86ef846 Mon Sep 17 00:00:00 2001 From: Ankit Ram Date: Tue, 16 Jun 2026 00:56:41 +0530 Subject: [PATCH 1/2] docs: add Wasm GC proposal tutorial and update proposals link --- docs/start/wasmedge/extensions/gc.md | 138 ++++++++++++++++++++ docs/start/wasmedge/extensions/proposals.md | 2 +- 2 files changed, 139 insertions(+), 1 deletion(-) create mode 100644 docs/start/wasmedge/extensions/gc.md diff --git a/docs/start/wasmedge/extensions/gc.md b/docs/start/wasmedge/extensions/gc.md new file mode 100644 index 00000000..ce84226b --- /dev/null +++ b/docs/start/wasmedge/extensions/gc.md @@ -0,0 +1,138 @@ +--- +sidebar_position: 2 +--- + +# Garbage Collection + +WasmEdge supports the [WebAssembly Garbage Collection (GC) proposal](https://github.com/WebAssembly/gc) starting from version `0.14.0`. This allows high-level languages like Kotlin, Dart, and OCaml to compile to WebAssembly without bundling their own garbage collector, resulting in smaller binaries and better runtime performance. + +## What is Wasm GC? + +Normally, WebAssembly manages memory manually — programs allocate and free memory themselves using linear memory. The GC proposal adds first-class garbage-collected types: **structs** (fixed heterogeneous fields) and **arrays** (homogeneous elements), both allocated on the heap and automatically reclaimed when no longer reachable. + +This is enabled by default in WasmEdge since `0.16.0`. You can disable it with the `--disable-gc` CLI flag if needed. + +## Prerequisites + +- WasmEdge `0.14.0` or later. See the [installation guide](../../../start/install.md). +- [`wat2wasm`](https://github.com/WebAssembly/wabt) from the WABT toolkit, to compile `.wat` source files to `.wasm`. + +Install WABT on Linux: + +```bash +apt install wabt +``` + +Or on macOS: + +```bash +brew install wabt +``` + +## Example: Working with Structs + +The following WAT (WebAssembly Text Format) example defines a `$point` struct with two `i32` fields, allocates one, sets a field, and returns a value from it. + +Create a file called `point.wat`: + +```wasm +(module + (type $point (struct (field $x (mut i32)) (field $y (mut i32)))) + + (func (export "make_point") (result i32) + (local $p (ref $point)) + ;; Allocate a new $point struct with x=10, y=20 + (local.set $p + (struct.new $point (i32.const 10) (i32.const 20)) + ) + ;; Update x to 99 + (struct.set $point $x (local.get $p) (i32.const 99)) + ;; Return the value of x + (struct.get $point $x (local.get $p)) + ) +) +``` + +Compile it to a `.wasm` binary: + +```bash +wat2wasm point.wat -o point.wasm +``` + +Run it with WasmEdge: + +```bash +wasmedge --invoke make_point point.wasm +``` + +Expected output: + +``` +99 +``` + +## Example: Working with Arrays + +The following example creates a GC-managed array of `i32` values, fills it with a value, and reads back an element. + +Create a file called `array.wat`: + +```wasm +(module + (type $int_array (array (mut i32))) + + (func (export "array_example") (result i32) + (local $a (ref $int_array)) + ;; Allocate an array of length 5, initialized to 0 + (local.set $a + (array.new_default $int_array (i32.const 5)) + ) + ;; Set element at index 2 to 42 + (array.set $int_array (local.get $a) (i32.const 2) (i32.const 42)) + ;; Return element at index 2 + (array.get $int_array (local.get $a) (i32.const 2)) + ) +) +``` + +Compile and run: + +```bash +wat2wasm array.wat -o array.wasm +wasmedge --invoke array_example array.wasm +``` + +Expected output: + +``` +42 +``` + +## Disabling GC + +If you need to run a Wasm module without GC support (for example, to test compatibility), pass the `--disable-gc` flag: + +```bash +wasmedge --disable-gc your_module.wasm +``` + +## C API + +To configure GC support programmatically via the WasmEdge C API, use the `WasmEdge_Proposal_GC` enumeration value: + +```c +WasmEdge_ConfigureContext *ConfCxt = WasmEdge_ConfigureCreate(); +// GC is enabled by default since 0.16.0. +// To disable it: +WasmEdge_ConfigureRemoveProposal(ConfCxt, WasmEdge_Proposal_GC); +``` + +## Language Support + +Languages that compile to Wasm GC and can run on WasmEdge include: + +- **Kotlin/Wasm** — via the Kotlin compiler's `wasmGc` target +- **Dart** — via `dart compile wasm` +- **OCaml** — via the `wasm_of_ocaml` compiler + +For language-specific guides, refer to the respective language's documentation on compiling to the `wasm32-unknown-unknown` GC target. \ No newline at end of file diff --git a/docs/start/wasmedge/extensions/proposals.md b/docs/start/wasmedge/extensions/proposals.md index faeacc3b..3e1f3618 100644 --- a/docs/start/wasmedge/extensions/proposals.md +++ b/docs/start/wasmedge/extensions/proposals.md @@ -47,7 +47,7 @@ The following proposals are under development and may be supported in the future [Component Model]: https://github.com/WebAssembly/component-model [Exception handling]: https://github.com/WebAssembly/exception-handling [Typed Function References]: https://github.com/WebAssembly/function-references -[Garbage collection]: https://github.com/WebAssembly/gc +[Garbage collection]: ./gc [Relaxed SIMD]: https://github.com/WebAssembly/relaxed-simd [Memory64]: https://github.com/WebAssembly/memory64 [WebAssembly C and C++ API]: https://github.com/WebAssembly/wasm-c-api From cb2fbeed6d02fec7ff62e82f89f2d6ad9187a6c8 Mon Sep 17 00:00:00 2001 From: Ankit Ram Date: Tue, 16 Jun 2026 16:19:17 +0530 Subject: [PATCH 2/2] docs: address Copilot review comments --- docs/start/wasmedge/extensions/gc.md | 9 +++++---- docs/start/wasmedge/extensions/proposals.md | 2 +- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/start/wasmedge/extensions/gc.md b/docs/start/wasmedge/extensions/gc.md index ce84226b..c755fa73 100644 --- a/docs/start/wasmedge/extensions/gc.md +++ b/docs/start/wasmedge/extensions/gc.md @@ -1,5 +1,5 @@ --- -sidebar_position: 2 +sidebar_position: 3 --- # Garbage Collection @@ -10,7 +10,7 @@ WasmEdge supports the [WebAssembly Garbage Collection (GC) proposal](https://git Normally, WebAssembly manages memory manually — programs allocate and free memory themselves using linear memory. The GC proposal adds first-class garbage-collected types: **structs** (fixed heterogeneous fields) and **arrays** (homogeneous elements), both allocated on the heap and automatically reclaimed when no longer reachable. -This is enabled by default in WasmEdge since `0.16.0`. You can disable it with the `--disable-gc` CLI flag if needed. +This is enabled by default in WasmEdge since `0.16.0`. For WasmEdge `0.14.x`–`0.15.x`, enable it explicitly with the (deprecated) `--enable-gc` flag; you can disable GC with `--disable-gc` when needed. ## Prerequisites @@ -122,9 +122,10 @@ To configure GC support programmatically via the WasmEdge C API, use the `WasmEd ```c WasmEdge_ConfigureContext *ConfCxt = WasmEdge_ConfigureCreate(); -// GC is enabled by default since 0.16.0. -// To disable it: +// WasmEdge 0.16.0+ enables GC by default; to disable it: WasmEdge_ConfigureRemoveProposal(ConfCxt, WasmEdge_Proposal_GC); +// WasmEdge 0.14.x–0.15.x has GC off by default; to enable it instead: +// WasmEdge_ConfigureAddProposal(ConfCxt, WasmEdge_Proposal_GC); ``` ## Language Support diff --git a/docs/start/wasmedge/extensions/proposals.md b/docs/start/wasmedge/extensions/proposals.md index 3e1f3618..e8879c54 100644 --- a/docs/start/wasmedge/extensions/proposals.md +++ b/docs/start/wasmedge/extensions/proposals.md @@ -47,7 +47,7 @@ The following proposals are under development and may be supported in the future [Component Model]: https://github.com/WebAssembly/component-model [Exception handling]: https://github.com/WebAssembly/exception-handling [Typed Function References]: https://github.com/WebAssembly/function-references -[Garbage collection]: ./gc +[Garbage collection]: ./gc.md [Relaxed SIMD]: https://github.com/WebAssembly/relaxed-simd [Memory64]: https://github.com/WebAssembly/memory64 [WebAssembly C and C++ API]: https://github.com/WebAssembly/wasm-c-api