From 5610021ea5dfb24d24c9652ca4d95a853b7aff4a Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Wed, 16 Jul 2025 20:54:48 -0700 Subject: [PATCH 01/32] Revise and expand on C/C++ language support section I tried to define some undefined terms, and verified the commands and their output. --- .../examples/tutorial/c/adder/component.c | 6 + .../tutorial/c/adder/component_with_printf.c | 9 + component-model/src/language-support/c.md | 280 +++++++++++++----- 3 files changed, 218 insertions(+), 77 deletions(-) create mode 100644 component-model/examples/tutorial/c/adder/component.c create mode 100644 component-model/examples/tutorial/c/adder/component_with_printf.c diff --git a/component-model/examples/tutorial/c/adder/component.c b/component-model/examples/tutorial/c/adder/component.c new file mode 100644 index 00000000..d1006fb3 --- /dev/null +++ b/component-model/examples/tutorial/c/adder/component.c @@ -0,0 +1,6 @@ +#include "adder.h" + +uint32_t exports_docs_adder_add_add(uint32_t x, uint32_t y) +{ + return x + y; +} diff --git a/component-model/examples/tutorial/c/adder/component_with_printf.c b/component-model/examples/tutorial/c/adder/component_with_printf.c new file mode 100644 index 00000000..b1c4bced --- /dev/null +++ b/component-model/examples/tutorial/c/adder/component_with_printf.c @@ -0,0 +1,9 @@ +#include "adder.h" +#include + +uint32_t exports_docs_adder_add_add(uint32_t x, uint32_t y) +{ + uint32_t result = x + y; + printf("%d", result); + return result; +} diff --git a/component-model/src/language-support/c.md b/component-model/src/language-support/c.md index a5db740a..8ba7370b 100644 --- a/component-model/src/language-support/c.md +++ b/component-model/src/language-support/c.md @@ -1,31 +1,64 @@ # C/C++ Tooling -WebAssembly components can be built from C and C++ using [`clang`][clang], the C language family frontend for [LLVM][llvm]. - -[`wit-bindgen`](https://github.com/bytecodealliance/wit-bindgen) is a tool to generate guest language bindings from a -given `.wit` file. - -Although `wit-bindgen` is a standalone tool (whereas some languages have more integrated toolchains like Rust's [`cargo-component`][cargo-component]), -`wit-bindgen` can generate source-level bindings for `Rust`, `C`, `Java (TeaVM)`, and `TinyGo`, with the ability for more -language generators to be added in the future. - -`wit-bindgen` can be used to build C applications that can be compiled directly to Wasm modules using [`clang`][clang] with a [`wasm32-wasi`][clang-tgt-wasm32-wasi] target. +WebAssembly components can be built from C and C++ using [`clang`][clang], +the C language family frontend for [LLVM][llvm]. + +[`wit-bindgen`](https://github.com/bytecodealliance/wit-bindgen) is a tool +to generate guest language bindings from a given `.wit` file. +When compiling C or C++ code to WebAssembly components, +we say that C or C++ is the "guest" language, +and WebAssembly is the "host" language. +In this case, "bindings" are C or C++ declarations: type signatures that +correspond to WIT functions, and type definitions that correspond to WIT types. +The bindings generator only generates declarations; you have to write +the code that actually implements these declarations, +if you're developing your own `.wit` files. +For WIT interfaces that are built in to WASI, the code is part of the +WebAssembly runtime that you will be using. + +C/C++ currently lacks an integrated toolchain like Rust's [`cargo-component`][cargo-component]). +However, the standaline `wit-bindgen` tool can generate source-level bindings for +Rust, C, Java ([TeaVM](https://teavm.org/)), and [TinyGo](https://tinygo.org/), +with the ability to add more language generators in the future. + +`wit-bindgen` can be used to build C applications that can be compiled directly to WebAssembly modules using [`clang`][clang] with a [`wasm32-wasi`][clang-tgt-wasm32-wasi] target. [clang]: https://clang.llvm.org/ [clang-tgt-wasm32-wasi]: https://clang.llvm.org/docs/ClangCommandLineReference.html#webassembly [llvm]: https://llvm.org/ [wasi]: https://wasi.dev/ [cargo-component]: https://crates.io/crates/cargo-component +[rust]: https://www.rust-lang.org/learn/get-started +[sample-wit]: https://github.com/bytecodealliance/component-docs/blob/main/component-model/examples/tutorial/wit/adder/world.wit ## 1. Download dependencies -First, install the CLI for [`wit-bindgen`](https://github.com/bytecodealliance/wit-bindgen#cli-installation), [`wasm-tools`](https://github.com/bytecodealliance/wasm-tools), and the [`WASI SDK`](https://github.com/webassembly/wasi-sdk). - -The WASI SDK will install a local version of `clang` configured with a wasi-sysroot. Follow [these instructions](https://github.com/WebAssembly/wasi-sdk#use) to configure it for use. Note that you can also use your installed system or emscripten `clang` by building with `--target=wasm32-wasi` but you will need some artifacts from WASI SDK to enable and link that build target (more information is available in WASI SDK's docs). +First, install the following dependencies: +1. The CLI for [`wit-bindgen`](https://github.com/bytecodealliance/wit-bindgen#cli-installation) +2. [`wasm-tools`](https://github.com/bytecodealliance/wasm-tools) + * `wasm-tools` is a program that inspects compiled WebAssembly modules and components, + as well as converting between preview1 modules and preview2 components in + the optional manual workflow. +3. The [`WASI SDK`](https://github.com/webassembly/wasi-sdk) + * The WASI SDK includes a version of the C standard library (`libc`) based on WASI, + among other artifacts necessary to compile C/C++ to WebAssembly. + * On a Linux system, you can skip to the ["Install"](https://github.com/webassembly/wasi-sdk?tab=readme-ov-file#install) section. + To build from source, start from the beginning of the README. + +The WASI SDK will install a local version of `clang` configured with a WASI sysroot. +(A sysroot is a directory containing header files and libraries +for a particular target platform.) +Follow [these instructions](https://github.com/WebAssembly/wasi-sdk#use) to configure it for use. +Note that you can also use your installed system or [Emscripten](https://emscripten.org/) `clang` +by building with `--target=wasm32-wasi`, but you will need some artifacts from WASI SDK +to enable and link that build target (see the text about `libclang_rt.*.a` objects in +[the WASI SDK README](https://github.com/webassembly/wasi-sdk?tab=readme-ov-file#about-this-repository)). ## 2. Generate program skeleton from WIT -Start by generating a C skeleton from `wit-bindgen` using the [sample `adder/world.wit` file](https://github.com/bytecodealliance/component-docs/blob/main/component-model/examples/tutorial/wit/adder/world.wit): +Start by pasting the contents of the [sample `adder/world.wit` file][sample-wit] +into a local file. +Then generate a C skeleton from `wit-bindgen` using this file: ``` > wit-bindgen c path/to/adder/world.wit @@ -34,28 +67,47 @@ Generating "adder.h" Generating "adder_component_type.o" ``` -This has generated several files: +This command generates several files: + +1. `adder.h` (based on the `adder` world). This header file contains, amidst some boilerplate, +the prototype of the `add` function, which should look like this. +(The name of the function has been prefixed with "`exports`".) + +```c + uint32_t exports_docs_adder_add_add(uint32_t x, uint32_t y); + ``` + +2. `adder.c`, which interfaces with the component model ABI to call your function. + This file contains an `extern` declaration that looks like: -1.`adder.h` (based on the `adder` world) with the prototype of the `add` function (prefixed by `exports_`) - `uint32_t exports_docs_adder_add_add(uint32_t x, uint32_t y);`. -2. `adder.c` that interfaces with the component model ABI to call your function. -3. `adder_component_type.o` which contains object code referenced in `adder.c` from an `extern` that must be linked via `clang`. + ```c + extern void __component_type_object_force_link_adder(void); + ``` + +3. `adder_component_type.o`, which contains object code, including + the definition of the `__component_type_object_force_link_adder` function, + which must be linked via `clang`. ## 3. Write program code -Next, create an `component.c` that implements the `adder` world (i.e. the interface defined in `adder.h`): +Next, create an `component.c` that implements the `adder` world: +that is, which provides definitions for the interface function declared in `adder.h`. ```c -#include "adder.h" - -uint32_t exports_docs_adder_add_add(uint32_t x, uint32_t y) -{ - return x + y; -} +{{#include ../../examples/tutorial/c/adder/component.c}} ``` -## 4. Compile a WebAssembly P2 component with `wasi-sdk`'s `wasm32-wasip2-clang` +## 4. Compile a WebAssembly Preview 2 component with `wasi-sdk`'s `wasm32-wasip2-clang` + +"P1" refers to [WASI Preview 1](https://github.com/WebAssembly/WASI/blob/main/legacy/README.md), +the initial version of the WASI APIs. +"P2" refers to [WASI Preview 2](https://github.com/WebAssembly/WASI/blob/main/wasip2/README.md), +which introduced the component model. -Given that `wasi-sdk` has ben installed, we can build a Preview 2 component quickly by using the provided `wasm32-wasip2-clang` binary: +We can build a P2 component quickly by using the `wasm32-wasip2-clang` binary +that was installed by the WASI SDK. +If necessary, change `/opt/wasi-sdk` to the path where you installed +the WASI SDK. ```console /opt/wasi-sdk/bin/wasm32-wasip2-clang \ @@ -66,92 +118,142 @@ Given that `wasi-sdk` has ben installed, we can build a Preview 2 component quic adder_component_type.o ``` -After this command completes, you will have a new file named `adder.wasm` available in the source folder. +Breaking down each part of this command: + +* `adder.wasm` is the output file that will contain binary WebAssembly code. +* The `-mexec-model` flag controls the desired execution model of the + generated code. The argument can be either `reactor` or `command`. + In this case, we pass in `-mexec-model=reactor` to build a _reactor_ component. + A reactor component is more like a library, while a command component + is more like an executable. +* `component.c` contains the code you wrote to implement the `adder` world. +* `adder.c` and `adder_component_type.o` were generated by `wit-bindgen`. + +After this command completes, you will have a new file named `adder.wasm` +available in the source folder. +You can see that `adder.wasm` contains a component with the following command: + +```console +> wasm-tools print adder.wasm | head -1 +(component +``` -For use cases that require building a P1 module and/or adapting an existing P1 module into a P2 module, -such as buliding for a platform that does not support P2, details on a more manual approach can be found below: +For use cases that require building a P1 module and/or +adapting an existing P1 module into a P2 module, +such as building for a platform that does not support P2, +details on a more manual approach using `wasi-sdk`'s `clang` and `wasm-tools` +can be found below:
-Manual P1 & P2 build using `wasi-sdk`'s `clang` and `wasm-tools` +Manual P1 and P2 build + +### Compile the component code into a WebAssembly P1 module via `clang`: + +Assuming you defined `WASI_SDK_PATH` according to +the ["Use" section](https://github.com/webassembly/wasi-sdk?tab=readme-ov-file#use) +in the WASI SDK README, execute: -## Build a WebAssembly module (P1) with `clang` +```console +$WASI_SDK_PATH/bin/clang component.c adder.c adder_component_type.o \ + -o adder.wasm -mexec-model=reactor +``` -Compile the component code into a WebAssembly P1 module via clang: +You can see that this command created a module with the following command: ```console -clang component.c adder.c adder_component_type.o -o adder.wasm -mexec-model=reactor +> wasm-tools print adder.wasm | head -1 +(module $adder.wasm ``` -> Use the `clang` included in the WASI SDK installation, for example at `/bin/clang`. > > Alternatively, you can also use the published [`ghcr.io/webassembly/wasi-sdk` container images][wasi-sdk-images] > for performing builds. > > For example, to enter a container with `wasi-sdk` installed: > +> ```console +> docker run --rm -it --mount type=bind,src=path/to/app/src,dst=/app \ +> ghcr.io/webassembly/wasi-sdk:wasi-sdk-25 > ``` -> docker run --rm -it --mount type=bind,src=path/to/app/src,dst=/app ghcr.io/webassembly/wasi-sdk:wasi-sdk-25 +> +> where `path/to/app/src` is replaced with the absolute path of the directory +> containing the code for your sample app. +> +> Then inside the container, after changing to the directory containing +> the code for your sample app, you can run: +> +> ```console +> /opt/wasi-sdk/bin/clang component.c adder.c adder_component_type.o \ +> -o adder.wasm -mexec-model=reactor > ``` > +> Using the Dockerfile avoids the need to install the WASI SDK on your system. +> > See also: [`Dockerfile` in `wasi-sdk`][wasi-sdk-dockerfile] [wasi-sdk-images]: https://github.com/WebAssembly/wasi-sdk/pkgs/container/wasi-sdk [wasi-sdk-dockerfile]: https://github.com/WebAssembly/wasi-sdk/blob/main/docker/Dockerfile -### Convert the P1 component to a P2 component with `wasm-tools` +### Transform the P1 component to a P2 component with `wasm-tools` -Next, we need to transform the P1 component to a P2 component. To do this, we can use `wasm-tools component new`: +Next, we need to transform the P1 component to a P2 component. +To do this, we can use `wasm-tools component new`: ```console -wasm-tools component new ./adder.wasm -o adder.component.wasm +wasm-tools component new adder.wasm -o adder.component.wasm ``` > [!NOTE] -> The `.component.` extension has no special meaning -- `.wasm` files can be either modules or components. +> The `.component.` extension has no special meaning—`.wasm` files can be either modules or components. ### (optional) Build a WASI-enabled WebAssembly (P2) component with `wasm-tools` -Do note `wasm-tools component new` may fail if your code references any [WASI][wasi] APIs that must be imported, for -example via standard library imports like `stdio.h`. +Note that `wasm-tools component new` may fail if your code references any +[WASI][wasi] APIs that must be imported, for example via standard library imports like `stdio.h`. -Using WASI interfaces requires an additional step as the WASI SDK still references `wasi_snapshot_preview1` APIs that are not compatible directly with components. +Using WASI interfaces requires an additional step, +as the WASI SDK still references WASI Preview 1 APIs (those with `wasi_snapshot_preview1` in their names) +that are not compatible directly with components. -For example, modifying the above to reference `printf()` would compile: +For example, if we modify the above code to reference `printf()`, +it would compile to a P1 component: ```c -#include "adder.h" -#include - -uint32_t exports_docs_adder_add_add(uint32_t x, uint32_t y) -{ - uint32_t result = x + y; - printf("%d", result); - return result; -} +{{#include ../../examples/tutorial/c/adder/component_with_printf.c}} ``` -However, the module would fail to transform to a component: +However, the module would fail to transform to a P2 component: ``` ->wasm-tools component new ./adder.wasm -o adder.component.wasm +> wasm-tools component new adder.wasm -o adder.component.wasm error: failed to encode a component from module Caused by: 0: failed to decode world from module 1: module was not valid - 2: module requires an import interface named `wasi_snapshot_preview1` + 2: failed to resolve import `wasi_snapshot_preview1::fd_close` + 3: module requires an import interface named `wasi_snapshot_preview1` ``` -To build a P2 component that uses [WASI][wasi] interfaces from a P1 component, we'll need to make use of adapter modules. +To build a P2 component that uses [WASI][wasi] interfaces from a P1 component, +we'll need to make use of adapter modules. +An adapter module provides definitions for WASI Preview 1 API functions +in terms of WASI Preview 2 API functions. -Install the appropriate reactor adapter module [as documented here](https://github.com/bytecodealliance/wit-bindgen#creating-components-wasi). +Download the appropriate reactor adapter module [as documented here](https://github.com/bytecodealliance/wit-bindgen#creating-components-wasi) +and save it to the same directory that contains the `.c` and `.wasm` files you have been working with. -You can either get [the linked release][wasmtime-releases] of `wasi_snapshot_preview1.reactor.wasm` and rename it to `wasi_snapshot_preview1.wasm`, or build it directly from source in `wasmtime` following the [instructions here](https://github.com/bytecodealliance/wasmtime/tree/main/crates/wasi-preview1-component-adapter) (make sure you `git submodule update --init` first). +You can either get [the linked release][wasmtime-releases] of `wasi_snapshot_preview1.reactor.wasm` +and rename it to `wasi_snapshot_preview1.wasm`, +or build it directly from source in `wasmtime` following +the [instructions here](https://github.com/bytecodealliance/wasmtime/tree/main/crates/wasi-preview1-component-adapter) +(make sure you `git submodule update --init` first). Now, you can adapt preview1 to preview2 to build a component: ```console -wasm-tools component new adder.wasm --adapt wasi_snapshot_preview1.wasm -o adder.component.wasm +wasm-tools component new adder.wasm --adapt wasi_snapshot_preview1.wasm \ + -o adder.component.wasm ``` [wasmtime-releases]: https://github.com/bytecodealliance/wasmtime/releases @@ -160,10 +262,11 @@ wasm-tools component new adder.wasm --adapt wasi_snapshot_preview1.wasm -o adder ## 5. Inspect the built component -Finally, you can inspect the embedded wit to see your component (including any WASI imports if necessary): +Finally, you can inspect the embedded WIT to see your component +(including any WASI imports if you used them): ``` ->wasm-tools component wit adder.component.wasm +> wasm-tools component wit adder.component.wasm package root:component; world root { @@ -186,34 +289,54 @@ world root { ... ``` -### 8. Running the component from the example host +### 6. Run the component from the example host + +The following section requires you to have [a Rust toolchain][rust] installed. > [!WARNING] > You must be careful to use a version of the adapter (`wasi_snapshot_preview1.wasm`) that is compatible with the version of > `wasmtime` that will be used, to ensure that WASI interface versions (and relevant implementation) match. -This repository contains an [example WebAssembly host][example-host] written in Rust that can run components that implement the `adder` world. +This repository contains an [example WebAssembly host][example-host] written in Rust +that can run components that implement the `adder` world. + +1. Check out the repository: + + `git clone https://github.com/bytecodealliance/component-docs.git` +2. `cd component-docs/component-model/examples/example-host` +3. `cargo run --release -- 1 2 /adder.wasm` +* The double dashes separate the flags passed to `cargo` from + the flags passed in to your code. +* The arguments 1 and 2 are the arguments to the adder. + +In place of ``, substitute the directory that contains your +generated `adder.wasm` file (or `adder.component.wasm` if you used +the manual instructions). > [!NOTE] -> When hosts run components that use WASI interfaces, they must *explicitly* [add WASI to the linker][add-to-linker] to run the built component. +> When hosts run components that use WASI interfaces, they must *explicitly* +> [add WASI to the linker][add-to-linker] to run the built component. -A successful run should show the following output: +A successful run should show the following output +(of course, the paths to your example host and adder component will vary, +and you should substitute `adder.wasm` with `adder.component.wasm` +if you followed the manual instructions above): ``` -cargo run --release -- 1 2 adder.component.wasm +cargo run --release -- 1 2 adder.wasm Compiling example-host v0.1.0 (/path/to/component-docs/component-model/examples/example-host) Finished `release` profile [optimized] target(s) in 7.85s - Running `target/debug/example-host 1 2 /tmp/docs/c/adder.component.wasm` + Running `target/debug/example-host 1 2 /path/to/adder.wasm` 1 + 2 = 3 ``` If *not* configured correctly, you may see errors like the following: ``` -cargo run --release -- 1 2 adder.component.wasm +cargo run --release -- 1 2 adder.wasm Compiling example-host v0.1.0 (/path/to/component-docs/component-model/examples/example-host) Finished `release` profile [optimized] target(s) in 7.85s - Running `target/release/example-host 1 2 adder.component.wasm` + Running `target/release/example-host 1 2 /path/to/adder.component.wasm` Error: Failed to instantiate the example world Caused by: @@ -222,23 +345,26 @@ Caused by: 2: resource implementation is missing ``` -This kind of error normally indicates that the host in question does not contain satisfy WASI imports. +This kind of error normally indicates that the host in question does not satisfy WASI imports. [host]: https://github.com/bytecodealliance/component-docs/tree/main/component-model/examples/example-host [add-to-linker]: https://docs.wasmtime.dev/api/wasmtime_wasi/fn.add_to_linker_sync.html [example-host]: https://github.com/bytecodealliance/component-docs/tree/main/component-model/examples/example-host -## 9. Running a Component from C/C++ Applications +## 7. Run the component from C/C++ Applications -It is not yet possible to run a WebAssembly Component using the C API of `wasmtime` `c-api`. See [`wasmtime` issue #6987](https://github.com/bytecodealliance/wasmtime/issues/6987) for more details. +It is not yet possible to run a WebAssembly Component using the C API of `wasmtime` `c-api`. +See [`wasmtime` issue #6987](https://github.com/bytecodealliance/wasmtime/issues/6987) for more details. The c-api is preferred over directly using the example host Rust crate in C++. -However, C/C++ language guest components can be composed with components written in any other language and -run by their toolchains, or even composed with a C language command component and run via the `wasmtime` CLI +However, C/C++ language guest components can be composed with components written in any other language +and run by their toolchains, +or even composed with a C language command component and run via the `wasmtime` CLI or any other host. -See the [Rust Tooling guide](../language-support/rust.md#running-a-component-from-rust-applications) for instructions on how to run this component from -the Rust `example-host` (replacing the path to `add.wasm` with your `add-component` above). +See the [Rust Tooling guide](../language-support/rust.md#running-a-component-from-rust-applications) +for instructions on how to run this component from the Rust `example-host` +(replacing the path to `add.wasm` with your `adder.wasm` or `adder.component.wasm` above). [!NOTE]: # [!WARNING]: # From 6d68e09a08cf215ffe9577557c7a7c63c199b2aa Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Wed, 6 Aug 2025 12:46:38 -0700 Subject: [PATCH 02/32] Update component-model/src/language-support/c.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> --- component-model/src/language-support/c.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/component-model/src/language-support/c.md b/component-model/src/language-support/c.md index 8ba7370b..52d15f39 100644 --- a/component-model/src/language-support/c.md +++ b/component-model/src/language-support/c.md @@ -17,7 +17,7 @@ For WIT interfaces that are built in to WASI, the code is part of the WebAssembly runtime that you will be using. C/C++ currently lacks an integrated toolchain like Rust's [`cargo-component`][cargo-component]). -However, the standaline `wit-bindgen` tool can generate source-level bindings for +However, `wit-bindgen` can generate source-level bindings for Rust, C, Java ([TeaVM](https://teavm.org/)), and [TinyGo](https://tinygo.org/), with the ability to add more language generators in the future. From df8a0454995f99b5af981144b849b474d320245e Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Wed, 6 Aug 2025 12:46:49 -0700 Subject: [PATCH 03/32] Update component-model/src/language-support/c.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> --- component-model/src/language-support/c.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/component-model/src/language-support/c.md b/component-model/src/language-support/c.md index 52d15f39..073d3655 100644 --- a/component-model/src/language-support/c.md +++ b/component-model/src/language-support/c.md @@ -36,7 +36,7 @@ with the ability to add more language generators in the future. First, install the following dependencies: 1. The CLI for [`wit-bindgen`](https://github.com/bytecodealliance/wit-bindgen#cli-installation) 2. [`wasm-tools`](https://github.com/bytecodealliance/wasm-tools) - * `wasm-tools` is a program that inspects compiled WebAssembly modules and components, + * `wasm-tools` can be used to inspect compiled WebAssembly modules and components, as well as converting between preview1 modules and preview2 components in the optional manual workflow. 3. The [`WASI SDK`](https://github.com/webassembly/wasi-sdk) From d47c6346d3ea75388e6e13c92c3a6882683f69d7 Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Wed, 6 Aug 2025 12:47:00 -0700 Subject: [PATCH 04/32] Update component-model/src/language-support/c.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> --- component-model/src/language-support/c.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/component-model/src/language-support/c.md b/component-model/src/language-support/c.md index 073d3655..9e4bc7a4 100644 --- a/component-model/src/language-support/c.md +++ b/component-model/src/language-support/c.md @@ -34,7 +34,7 @@ with the ability to add more language generators in the future. ## 1. Download dependencies First, install the following dependencies: -1. The CLI for [`wit-bindgen`](https://github.com/bytecodealliance/wit-bindgen#cli-installation) +1. [`wit-bindgen` CLI](https://github.com/bytecodealliance/wit-bindgen#cli-installation) 2. [`wasm-tools`](https://github.com/bytecodealliance/wasm-tools) * `wasm-tools` can be used to inspect compiled WebAssembly modules and components, as well as converting between preview1 modules and preview2 components in From 11409226262e833eac73fe3a26d7fb3174376475 Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Wed, 6 Aug 2025 12:47:52 -0700 Subject: [PATCH 05/32] Update component-model/src/language-support/c.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> --- component-model/src/language-support/c.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/component-model/src/language-support/c.md b/component-model/src/language-support/c.md index 9e4bc7a4..63ff0033 100644 --- a/component-model/src/language-support/c.md +++ b/component-model/src/language-support/c.md @@ -40,7 +40,8 @@ First, install the following dependencies: as well as converting between preview1 modules and preview2 components in the optional manual workflow. 3. The [`WASI SDK`](https://github.com/webassembly/wasi-sdk) - * The WASI SDK includes a version of the C standard library (`libc`) based on WASI, + * WASI SDK is a WASI enabled C/C++ toolchain which includes a version of the C standard + library (`libc`) implemented with WASI interfaces, among other artifacts necessary to compile C/C++ to WebAssembly. * On a Linux system, you can skip to the ["Install"](https://github.com/webassembly/wasi-sdk?tab=readme-ov-file#install) section. To build from source, start from the beginning of the README. From b28929af98656d4ebbbd18fa8ed9574dc8a272ef Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Wed, 6 Aug 2025 12:48:31 -0700 Subject: [PATCH 06/32] Update component-model/src/language-support/c.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> --- component-model/src/language-support/c.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/component-model/src/language-support/c.md b/component-model/src/language-support/c.md index 63ff0033..b54b219c 100644 --- a/component-model/src/language-support/c.md +++ b/component-model/src/language-support/c.md @@ -46,7 +46,7 @@ First, install the following dependencies: * On a Linux system, you can skip to the ["Install"](https://github.com/webassembly/wasi-sdk?tab=readme-ov-file#install) section. To build from source, start from the beginning of the README. -The WASI SDK will install a local version of `clang` configured with a WASI sysroot. +A WASI SDK installation will include a local version of `clang` configured with a WASI sysroot. (A sysroot is a directory containing header files and libraries for a particular target platform.) Follow [these instructions](https://github.com/WebAssembly/wasi-sdk#use) to configure it for use. From ac98c1ab5e7e720e240de3681c9c24619f15fa80 Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Wed, 6 Aug 2025 12:48:47 -0700 Subject: [PATCH 07/32] Update component-model/src/language-support/c.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> --- component-model/src/language-support/c.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/component-model/src/language-support/c.md b/component-model/src/language-support/c.md index b54b219c..a361bcee 100644 --- a/component-model/src/language-support/c.md +++ b/component-model/src/language-support/c.md @@ -49,7 +49,7 @@ First, install the following dependencies: A WASI SDK installation will include a local version of `clang` configured with a WASI sysroot. (A sysroot is a directory containing header files and libraries for a particular target platform.) -Follow [these instructions](https://github.com/WebAssembly/wasi-sdk#use) to configure it for use. +Follow [these instructions](https://github.com/WebAssembly/wasi-sdk#use) to configure WASI SDK for use. Note that you can also use your installed system or [Emscripten](https://emscripten.org/) `clang` by building with `--target=wasm32-wasi`, but you will need some artifacts from WASI SDK to enable and link that build target (see the text about `libclang_rt.*.a` objects in From 0cf108d3b284832acee4e26a482be96944248aaf Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Wed, 6 Aug 2025 12:49:25 -0700 Subject: [PATCH 08/32] Update component-model/src/language-support/c.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> --- component-model/src/language-support/c.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/component-model/src/language-support/c.md b/component-model/src/language-support/c.md index a361bcee..fb189a81 100644 --- a/component-model/src/language-support/c.md +++ b/component-model/src/language-support/c.md @@ -50,10 +50,10 @@ A WASI SDK installation will include a local version of `clang` configured with (A sysroot is a directory containing header files and libraries for a particular target platform.) Follow [these instructions](https://github.com/WebAssembly/wasi-sdk#use) to configure WASI SDK for use. -Note that you can also use your installed system or [Emscripten](https://emscripten.org/) `clang` -by building with `--target=wasm32-wasi`, but you will need some artifacts from WASI SDK -to enable and link that build target (see the text about `libclang_rt.*.a` objects in -[the WASI SDK README](https://github.com/webassembly/wasi-sdk?tab=readme-ov-file#about-this-repository)). +> [!NOTE]: Note that you can also use your installed system or [Emscripten](https://emscripten.org/) `clang` +> by building with `--target=wasm32-wasi`, but you will need some artifacts from WASI SDK +> to enable and link that build target (see the text about `libclang_rt.*.a` objects in +> [the WASI SDK README](https://github.com/webassembly/wasi-sdk?tab=readme-ov-file#about-this-repository)). ## 2. Generate program skeleton from WIT From 09e2c4f3346154feac6612ecc42d3c27d300c96f Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Wed, 6 Aug 2025 12:51:11 -0700 Subject: [PATCH 09/32] Fix markup in NOTE --- component-model/src/language-support/c.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/component-model/src/language-support/c.md b/component-model/src/language-support/c.md index fb189a81..212814fe 100644 --- a/component-model/src/language-support/c.md +++ b/component-model/src/language-support/c.md @@ -50,7 +50,9 @@ A WASI SDK installation will include a local version of `clang` configured with (A sysroot is a directory containing header files and libraries for a particular target platform.) Follow [these instructions](https://github.com/WebAssembly/wasi-sdk#use) to configure WASI SDK for use. -> [!NOTE]: Note that you can also use your installed system or [Emscripten](https://emscripten.org/) `clang` + +> [!NOTE] +> You can also use your installed system or [Emscripten](https://emscripten.org/) `clang` > by building with `--target=wasm32-wasi`, but you will need some artifacts from WASI SDK > to enable and link that build target (see the text about `libclang_rt.*.a` objects in > [the WASI SDK README](https://github.com/webassembly/wasi-sdk?tab=readme-ov-file#about-this-repository)). From 014a58c2bc8bc0d4ae9cc80c84e137c9c4028488 Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Wed, 6 Aug 2025 12:52:46 -0700 Subject: [PATCH 10/32] Fix backtick spacing --- component-model/src/language-support/c.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/component-model/src/language-support/c.md b/component-model/src/language-support/c.md index 212814fe..537e441b 100644 --- a/component-model/src/language-support/c.md +++ b/component-model/src/language-support/c.md @@ -78,14 +78,14 @@ the prototype of the `add` function, which should look like this. ```c uint32_t exports_docs_adder_add_add(uint32_t x, uint32_t y); - ``` +``` 2. `adder.c`, which interfaces with the component model ABI to call your function. This file contains an `extern` declaration that looks like: - ```c +```c extern void __component_type_object_force_link_adder(void); - ``` +``` 3. `adder_component_type.o`, which contains object code, including the definition of the `__component_type_object_force_link_adder` function, From dbbf191930adffb433cc9990e74bc3361a1d5923 Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Wed, 6 Aug 2025 12:54:03 -0700 Subject: [PATCH 11/32] Update component-model/src/language-support/c.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> --- component-model/src/language-support/c.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/component-model/src/language-support/c.md b/component-model/src/language-support/c.md index 537e441b..6c6e7ef4 100644 --- a/component-model/src/language-support/c.md +++ b/component-model/src/language-support/c.md @@ -93,7 +93,7 @@ the prototype of the `add` function, which should look like this. ## 3. Write program code -Next, create an `component.c` that implements the `adder` world: +Next, create a file named `component.c` with code that implements the `adder` world: that is, which provides definitions for the interface function declared in `adder.h`. ```c From 3be8a7e1e835c6f3472e167e802cd8c9c2625782 Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Wed, 6 Aug 2025 12:54:27 -0700 Subject: [PATCH 12/32] Update component-model/src/language-support/c.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> --- component-model/src/language-support/c.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/component-model/src/language-support/c.md b/component-model/src/language-support/c.md index 6c6e7ef4..2f73fed1 100644 --- a/component-model/src/language-support/c.md +++ b/component-model/src/language-support/c.md @@ -94,7 +94,7 @@ the prototype of the `add` function, which should look like this. ## 3. Write program code Next, create a file named `component.c` with code that implements the `adder` world: -that is, which provides definitions for the interface function declared in `adder.h`. +that is, code which fulfills the definition of the interface function declared in `adder.h`. ```c {{#include ../../examples/tutorial/c/adder/component.c}} From 42746b97823eedd4545ce613f36ce317c1c1162b Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Wed, 6 Aug 2025 12:54:57 -0700 Subject: [PATCH 13/32] Update component-model/src/language-support/c.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> --- component-model/src/language-support/c.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/component-model/src/language-support/c.md b/component-model/src/language-support/c.md index 2f73fed1..2c3a6c31 100644 --- a/component-model/src/language-support/c.md +++ b/component-model/src/language-support/c.md @@ -107,7 +107,8 @@ the initial version of the WASI APIs. "P2" refers to [WASI Preview 2](https://github.com/WebAssembly/WASI/blob/main/wasip2/README.md), which introduced the component model. -We can build a P2 component quickly by using the `wasm32-wasip2-clang` binary +While in the past building a P2 component required conversion from a P1 component, +we can build a P2 component directly by using the `wasm32-wasip2-clang` binary that was installed by the WASI SDK. If necessary, change `/opt/wasi-sdk` to the path where you installed the WASI SDK. From c02e274785b620542a8c503b6e81a496cd78e107 Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Wed, 6 Aug 2025 12:55:18 -0700 Subject: [PATCH 14/32] Update component-model/src/language-support/c.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> --- component-model/src/language-support/c.md | 1 + 1 file changed, 1 insertion(+) diff --git a/component-model/src/language-support/c.md b/component-model/src/language-support/c.md index 2c3a6c31..e4e61fc8 100644 --- a/component-model/src/language-support/c.md +++ b/component-model/src/language-support/c.md @@ -110,6 +110,7 @@ which introduced the component model. While in the past building a P2 component required conversion from a P1 component, we can build a P2 component directly by using the `wasm32-wasip2-clang` binary that was installed by the WASI SDK. + If necessary, change `/opt/wasi-sdk` to the path where you installed the WASI SDK. From 8bbe5bd360bc1bb304bf390eac78893094745850 Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Wed, 6 Aug 2025 12:55:43 -0700 Subject: [PATCH 15/32] Update component-model/src/language-support/c.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> --- component-model/src/language-support/c.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/component-model/src/language-support/c.md b/component-model/src/language-support/c.md index e4e61fc8..583c2d2d 100644 --- a/component-model/src/language-support/c.md +++ b/component-model/src/language-support/c.md @@ -125,7 +125,7 @@ the WASI SDK. Breaking down each part of this command: -* `adder.wasm` is the output file that will contain binary WebAssembly code. +* `-o adder.wasm` configures the output file that will contain binary WebAssembly code. * The `-mexec-model` flag controls the desired execution model of the generated code. The argument can be either `reactor` or `command`. In this case, we pass in `-mexec-model=reactor` to build a _reactor_ component. From 62ab88eb5ce62fa2f0c70da1218f41200aee6000 Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Wed, 6 Aug 2025 12:56:03 -0700 Subject: [PATCH 16/32] Update component-model/src/language-support/c.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> --- component-model/src/language-support/c.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/component-model/src/language-support/c.md b/component-model/src/language-support/c.md index 583c2d2d..c2cda259 100644 --- a/component-model/src/language-support/c.md +++ b/component-model/src/language-support/c.md @@ -126,7 +126,7 @@ the WASI SDK. Breaking down each part of this command: * `-o adder.wasm` configures the output file that will contain binary WebAssembly code. -* The `-mexec-model` flag controls the desired execution model of the +* `-mexec-model=reactor` controls the desired execution model of the generated code. The argument can be either `reactor` or `command`. In this case, we pass in `-mexec-model=reactor` to build a _reactor_ component. A reactor component is more like a library, while a command component From 7e553eed6f3474975906d1458a50359c4290d48e Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Wed, 6 Aug 2025 12:56:29 -0700 Subject: [PATCH 17/32] Update component-model/src/language-support/c.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> --- component-model/src/language-support/c.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/component-model/src/language-support/c.md b/component-model/src/language-support/c.md index c2cda259..07407333 100644 --- a/component-model/src/language-support/c.md +++ b/component-model/src/language-support/c.md @@ -132,7 +132,9 @@ Breaking down each part of this command: A reactor component is more like a library, while a command component is more like an executable. * `component.c` contains the code you wrote to implement the `adder` world. -* `adder.c` and `adder_component_type.o` were generated by `wit-bindgen`. +* `adder.c` and `adder_component_type.o` were generated by `wit-bindgen` and contain + necessary scaffolding (e.g. function exports) to enable building `component.c` into a WebAssembly + binary. After this command completes, you will have a new file named `adder.wasm` available in the source folder. From b6a4b0b50933a81ed727def6ebdff9633c82ded4 Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Wed, 6 Aug 2025 12:56:47 -0700 Subject: [PATCH 18/32] Update component-model/src/language-support/c.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> --- component-model/src/language-support/c.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/component-model/src/language-support/c.md b/component-model/src/language-support/c.md index 07407333..9a1640ef 100644 --- a/component-model/src/language-support/c.md +++ b/component-model/src/language-support/c.md @@ -138,7 +138,8 @@ Breaking down each part of this command: After this command completes, you will have a new file named `adder.wasm` available in the source folder. -You can see that `adder.wasm` contains a component with the following command: + +You can verify that `adder.wasm` is a valid WebAssembly component with the following command: ```console > wasm-tools print adder.wasm | head -1 From fc58b333cdc96ef037b9398fb2f07d284e69f187 Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Wed, 6 Aug 2025 12:57:04 -0700 Subject: [PATCH 19/32] Update component-model/src/language-support/c.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> --- component-model/src/language-support/c.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/component-model/src/language-support/c.md b/component-model/src/language-support/c.md index 9a1640ef..39c87cde 100644 --- a/component-model/src/language-support/c.md +++ b/component-model/src/language-support/c.md @@ -162,8 +162,12 @@ the ["Use" section](https://github.com/webassembly/wasi-sdk?tab=readme-ov-file#u in the WASI SDK README, execute: ```console -$WASI_SDK_PATH/bin/clang component.c adder.c adder_component_type.o \ - -o adder.wasm -mexec-model=reactor +$WASI_SDK_PATH/bin/clang \ + -o adder.wasm \ + -mexec-model=reactor \ + component.c \ + adder.c \ + adder_component_type.o ``` You can see that this command created a module with the following command: From c77a855b17bd71344ac30296f0c87647f4141c47 Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Wed, 6 Aug 2025 12:57:21 -0700 Subject: [PATCH 20/32] Update component-model/src/language-support/c.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> --- component-model/src/language-support/c.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/component-model/src/language-support/c.md b/component-model/src/language-support/c.md index 39c87cde..71638fb0 100644 --- a/component-model/src/language-support/c.md +++ b/component-model/src/language-support/c.md @@ -170,7 +170,7 @@ $WASI_SDK_PATH/bin/clang \ adder_component_type.o ``` -You can see that this command created a module with the following command: +You can verify that `adder.wasm` is a valid WebAssembly P1 component (i.e. a WebAssembly core module) with the following command: ```console > wasm-tools print adder.wasm | head -1 From 069313a49e8e4070b9141d717a2fb6e997c6d1a2 Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Wed, 6 Aug 2025 12:57:42 -0700 Subject: [PATCH 21/32] Update component-model/src/language-support/c.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> --- component-model/src/language-support/c.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/component-model/src/language-support/c.md b/component-model/src/language-support/c.md index 71638fb0..95b71473 100644 --- a/component-model/src/language-support/c.md +++ b/component-model/src/language-support/c.md @@ -184,8 +184,9 @@ You can verify that `adder.wasm` is a valid WebAssembly P1 component (i.e. a Web > For example, to enter a container with `wasi-sdk` installed: > > ```console -> docker run --rm -it --mount type=bind,src=path/to/app/src,dst=/app \ -> ghcr.io/webassembly/wasi-sdk:wasi-sdk-25 +> docker run --rm -it \ +> --mount type=bind,src=path/to/app/src,dst=/app \ +> ghcr.io/webassembly/wasi-sdk:wasi-sdk-27 > ``` > > where `path/to/app/src` is replaced with the absolute path of the directory From 58215c5e77d103151b6edf1df56a985791982e09 Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Wed, 6 Aug 2025 12:57:57 -0700 Subject: [PATCH 22/32] Update component-model/src/language-support/c.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> --- component-model/src/language-support/c.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/component-model/src/language-support/c.md b/component-model/src/language-support/c.md index 95b71473..d5c21808 100644 --- a/component-model/src/language-support/c.md +++ b/component-model/src/language-support/c.md @@ -189,7 +189,7 @@ You can verify that `adder.wasm` is a valid WebAssembly P1 component (i.e. a Web > ghcr.io/webassembly/wasi-sdk:wasi-sdk-27 > ``` > -> where `path/to/app/src` is replaced with the absolute path of the directory +> Replace `path/to/app/src` with the absolute path of the directory > containing the code for your sample app. > > Then inside the container, after changing to the directory containing From 1869fcfcf619d1b98e9e7db6696ac19b55c71809 Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Wed, 6 Aug 2025 12:58:28 -0700 Subject: [PATCH 23/32] Update component-model/src/language-support/c.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> --- component-model/src/language-support/c.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/component-model/src/language-support/c.md b/component-model/src/language-support/c.md index d5c21808..904736a2 100644 --- a/component-model/src/language-support/c.md +++ b/component-model/src/language-support/c.md @@ -192,8 +192,8 @@ You can verify that `adder.wasm` is a valid WebAssembly P1 component (i.e. a Web > Replace `path/to/app/src` with the absolute path of the directory > containing the code for your sample app. > -> Then inside the container, after changing to the directory containing -> the code for your sample app, you can run: +> Inside the container your source code will be available at `/app`. After changing +> to that directory, you can run: > > ```console > /opt/wasi-sdk/bin/clang component.c adder.c adder_component_type.o \ From ac9f43bf9286906eb92129f55db46ffe83dc2752 Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Wed, 6 Aug 2025 12:58:43 -0700 Subject: [PATCH 24/32] Update component-model/src/language-support/c.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> --- component-model/src/language-support/c.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/component-model/src/language-support/c.md b/component-model/src/language-support/c.md index 904736a2..eb516c02 100644 --- a/component-model/src/language-support/c.md +++ b/component-model/src/language-support/c.md @@ -196,8 +196,12 @@ You can verify that `adder.wasm` is a valid WebAssembly P1 component (i.e. a Web > to that directory, you can run: > > ```console -> /opt/wasi-sdk/bin/clang component.c adder.c adder_component_type.o \ -> -o adder.wasm -mexec-model=reactor +> /opt/wasi-sdk/bin/clang \ +> -o adder.wasm \ +> -mexec-model=reactor \ +> component.c \ +> adder.c \ +> adder_component_type.o > ``` > > Using the Dockerfile avoids the need to install the WASI SDK on your system. From 08f6720cdf21dd89dceac4eb79963b50e23f9e73 Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Wed, 6 Aug 2025 12:58:58 -0700 Subject: [PATCH 25/32] Update component-model/src/language-support/c.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> --- component-model/src/language-support/c.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/component-model/src/language-support/c.md b/component-model/src/language-support/c.md index eb516c02..f011aa4f 100644 --- a/component-model/src/language-support/c.md +++ b/component-model/src/language-support/c.md @@ -269,7 +269,9 @@ the [instructions here](https://github.com/bytecodealliance/wasmtime/tree/main/c Now, you can adapt preview1 to preview2 to build a component: ```console -wasm-tools component new adder.wasm --adapt wasi_snapshot_preview1.wasm \ +wasm-tools component new \ + adder.wasm \ + --adapt wasi_snapshot_preview1.wasm \ -o adder.component.wasm ``` From b93f7d4f7cbeb94ae110171da3eed62e1d92bb1b Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Wed, 6 Aug 2025 12:59:12 -0700 Subject: [PATCH 26/32] Update component-model/src/language-support/c.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> --- component-model/src/language-support/c.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/component-model/src/language-support/c.md b/component-model/src/language-support/c.md index f011aa4f..117262ca 100644 --- a/component-model/src/language-support/c.md +++ b/component-model/src/language-support/c.md @@ -285,7 +285,7 @@ Finally, you can inspect the embedded WIT to see your component (including any WASI imports if you used them): ``` -> wasm-tools component wit adder.component.wasm +$ wasm-tools component wit adder.component.wasm package root:component; world root { From d6737d5396d32cd608bfb0a5d2514c0b1482e143 Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Wed, 6 Aug 2025 12:59:22 -0700 Subject: [PATCH 27/32] Update component-model/src/language-support/c.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> --- component-model/src/language-support/c.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/component-model/src/language-support/c.md b/component-model/src/language-support/c.md index 117262ca..dbed0064 100644 --- a/component-model/src/language-support/c.md +++ b/component-model/src/language-support/c.md @@ -281,7 +281,7 @@ wasm-tools component new \ ## 5. Inspect the built component -Finally, you can inspect the embedded WIT to see your component +Finally, you can inspect the WIT embedded in your component (including any WASI imports if you used them): ``` From e25ffd7f19795d056b95f43e18aaa5af101636b4 Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Wed, 6 Aug 2025 13:00:05 -0700 Subject: [PATCH 28/32] Update component-model/src/language-support/c.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> --- component-model/src/language-support/c.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/component-model/src/language-support/c.md b/component-model/src/language-support/c.md index dbed0064..c24d8058 100644 --- a/component-model/src/language-support/c.md +++ b/component-model/src/language-support/c.md @@ -319,9 +319,7 @@ The following section requires you to have [a Rust toolchain][rust] installed. This repository contains an [example WebAssembly host][example-host] written in Rust that can run components that implement the `adder` world. -1. Check out the repository: - - `git clone https://github.com/bytecodealliance/component-docs.git` +1. `git clone https://github.com/bytecodealliance/component-docs.git` 2. `cd component-docs/component-model/examples/example-host` 3. `cargo run --release -- 1 2 /adder.wasm` * The double dashes separate the flags passed to `cargo` from From 363e7c9da94b8ddccf867b66e4a64b35d8d531be Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Wed, 6 Aug 2025 13:01:10 -0700 Subject: [PATCH 29/32] Update component-model/src/language-support/c.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> --- component-model/src/language-support/c.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/component-model/src/language-support/c.md b/component-model/src/language-support/c.md index c24d8058..73c0db8d 100644 --- a/component-model/src/language-support/c.md +++ b/component-model/src/language-support/c.md @@ -370,7 +370,7 @@ This kind of error normally indicates that the host in question does not satisfy ## 7. Run the component from C/C++ Applications -It is not yet possible to run a WebAssembly Component using the C API of `wasmtime` `c-api`. +It is not yet possible to run a WebAssembly Component using the `wasmtime` C API. See [`wasmtime` issue #6987](https://github.com/bytecodealliance/wasmtime/issues/6987) for more details. The c-api is preferred over directly using the example host Rust crate in C++. From 5bceb220b34a5eee7d219c780e27843617b9233a Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Wed, 6 Aug 2025 13:02:22 -0700 Subject: [PATCH 30/32] Indent note about PATH --- component-model/src/language-support/c.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/component-model/src/language-support/c.md b/component-model/src/language-support/c.md index 73c0db8d..1e32cb6e 100644 --- a/component-model/src/language-support/c.md +++ b/component-model/src/language-support/c.md @@ -325,10 +325,9 @@ that can run components that implement the `adder` world. * The double dashes separate the flags passed to `cargo` from the flags passed in to your code. * The arguments 1 and 2 are the arguments to the adder. - -In place of ``, substitute the directory that contains your -generated `adder.wasm` file (or `adder.component.wasm` if you used -the manual instructions). +* In place of ``, substitute the directory that contains your + generated `adder.wasm` file (or `adder.component.wasm` if you used + the manual instructions). > [!NOTE] > When hosts run components that use WASI interfaces, they must *explicitly* From dc7a7848d5359cb40f430c2c91a6862bcbca56d9 Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Wed, 6 Aug 2025 13:14:04 -0700 Subject: [PATCH 31/32] Minor fixes --- component-model/src/language-support/c.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/component-model/src/language-support/c.md b/component-model/src/language-support/c.md index 1e32cb6e..e1f62c77 100644 --- a/component-model/src/language-support/c.md +++ b/component-model/src/language-support/c.md @@ -16,7 +16,7 @@ if you're developing your own `.wit` files. For WIT interfaces that are built in to WASI, the code is part of the WebAssembly runtime that you will be using. -C/C++ currently lacks an integrated toolchain like Rust's [`cargo-component`][cargo-component]). +C/C++ currently lacks an integrated toolchain (like Rust's [`cargo-component`][cargo-component]). However, `wit-bindgen` can generate source-level bindings for Rust, C, Java ([TeaVM](https://teavm.org/)), and [TinyGo](https://tinygo.org/), with the ability to add more language generators in the future. @@ -30,6 +30,7 @@ with the ability to add more language generators in the future. [cargo-component]: https://crates.io/crates/cargo-component [rust]: https://www.rust-lang.org/learn/get-started [sample-wit]: https://github.com/bytecodealliance/component-docs/blob/main/component-model/examples/tutorial/wit/adder/world.wit +[cargo-config]: https://github.com/bytecodealliance/component-docs/blob/main/component-model/examples/example-host/Cargo.toml ## 1. Download dependencies @@ -64,7 +65,7 @@ into a local file. Then generate a C skeleton from `wit-bindgen` using this file: ``` -> wit-bindgen c path/to/adder/world.wit +$ wit-bindgen c path/to/adder/world.wit Generating "adder.c" Generating "adder.h" Generating "adder_component_type.o" @@ -108,7 +109,7 @@ the initial version of the WASI APIs. which introduced the component model. While in the past building a P2 component required conversion from a P1 component, -we can build a P2 component directly by using the `wasm32-wasip2-clang` binary +we can now build a P2 component directly by using the `wasm32-wasip2-clang` binary that was installed by the WASI SDK. If necessary, change `/opt/wasi-sdk` to the path where you installed @@ -226,7 +227,8 @@ wasm-tools component new adder.wasm -o adder.component.wasm ### (optional) Build a WASI-enabled WebAssembly (P2) component with `wasm-tools` Note that `wasm-tools component new` may fail if your code references any -[WASI][wasi] APIs that must be imported, for example via standard library imports like `stdio.h`. +[WASI][wasi] APIs that must be imported: +for example, via standard library imports like `stdio.h`. Using WASI interfaces requires an additional step, as the WASI SDK still references WASI Preview 1 APIs (those with `wasi_snapshot_preview1` in their names) @@ -313,8 +315,11 @@ world root { The following section requires you to have [a Rust toolchain][rust] installed. > [!WARNING] -> You must be careful to use a version of the adapter (`wasi_snapshot_preview1.wasm`) that is compatible with the version of -> `wasmtime` that will be used, to ensure that WASI interface versions (and relevant implementation) match. +> You must be careful to use a version of the adapter (`wasi_snapshot_preview1.wasm`) +> that is compatible with the version of `wasmtime` that will be used, +> to ensure that WASI interface versions (and relevant implementation) match. +> (The `wasmtime` version is specified in [the Cargo configuration file][cargo-config] +> for the example host.) This repository contains an [example WebAssembly host][example-host] written in Rust that can run components that implement the `adder` world. @@ -371,7 +376,7 @@ This kind of error normally indicates that the host in question does not satisfy It is not yet possible to run a WebAssembly Component using the `wasmtime` C API. See [`wasmtime` issue #6987](https://github.com/bytecodealliance/wasmtime/issues/6987) for more details. -The c-api is preferred over directly using the example host Rust crate in C++. +The C API is preferred over directly using the example host Rust crate in C++. However, C/C++ language guest components can be composed with components written in any other language and run by their toolchains, From b75535f6a5b16bcbd8bfc6dcc3041e6f4875003b Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Mon, 11 Aug 2025 10:47:13 -0700 Subject: [PATCH 32/32] Add comment in component_with_printf example --- .../examples/tutorial/c/adder/component_with_printf.c | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/component-model/examples/tutorial/c/adder/component_with_printf.c b/component-model/examples/tutorial/c/adder/component_with_printf.c index b1c4bced..7bc51586 100644 --- a/component-model/examples/tutorial/c/adder/component_with_printf.c +++ b/component-model/examples/tutorial/c/adder/component_with_printf.c @@ -4,6 +4,12 @@ uint32_t exports_docs_adder_add_add(uint32_t x, uint32_t y) { uint32_t result = x + y; + // On traditional platforms, printf() prints to stdout, but on Wasm platforms, + // stdout and the idea of printing to an output stream is + // introduced and managed by WASI. + // + // When building this code with wasi-libc (as a part of wasi-sdk), the printf call + // below is implemented with code that uses `wasi:cli/stdout` and `wasi:io/streams`. printf("%d", result); return result; }