Suggested updates to proof of concept C host documentation

- Fills in documentation on how to use the C host
- Updates Dockerfile to be cross architecture
- Adds a new Dockerfile that is just the host

Signed-off-by: Kate Goldenring <kgoldenr@akamai.com>

Author: kate-goldenring

…model/examples/example-c-host/Dockerfile …example-c-host/Dockerfile.guest_and_hostcomponent-model/examples/example-c-host/Dockerfile renamed to component-model/examples/example-c-host/Dockerfile.guest_and_host component-model/examples/example-c-host/Dockerfile renamed to component-model/examples/example-c-host/Dockerfile.guest_and_host

@@ -2,27 +2,46 @@ FROM ubuntu:24.04 AS build
 
 ARG WASMTIME_VERSION=42.0.1
 ARG WASI_SDK_VERSION=27
+ARG TARGETARCH
 
 RUN apt-get update && apt-get install -y --no-install-recommends \
     gcc libc6-dev curl xz-utils ca-certificates \
     && rm -rf /var/lib/apt/lists/*
 
 # Install wasmtime C API
-RUN curl -sL https://github.com/bytecodealliance/wasmtime/releases/download/v${WASMTIME_VERSION}/wasmtime-v${WASMTIME_VERSION}-x86_64-linux-c-api.tar.xz \
-    | tar xJ --strip-components=1 -C /usr/local \
-    && ldconfig
+RUN set -eux; \
+    case "${TARGETARCH}" in \
+        amd64) WASMTIME_ARCH=x86_64 ;; \
+        arm64) WASMTIME_ARCH=aarch64 ;; \
+        *) echo "Unsupported TARGETARCH: ${TARGETARCH}" >&2; exit 1 ;; \
+    esac; \
+    curl -sL "https://github.com/bytecodealliance/wasmtime/releases/download/v${WASMTIME_VERSION}/wasmtime-v${WASMTIME_VERSION}-${WASMTIME_ARCH}-linux-c-api.tar.xz" \
+    | tar xJ --strip-components=1 -C /usr/local; \
+    ldconfig
 
 # Install wasi-sdk (for building the guest component)
-RUN curl -sLO https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-${WASI_SDK_VERSION}/wasi-sdk-${WASI_SDK_VERSION}.0-x86_64-linux.deb \
-    && dpkg -i wasi-sdk-${WASI_SDK_VERSION}.0-x86_64-linux.deb \
-    && rm wasi-sdk-${WASI_SDK_VERSION}.0-x86_64-linux.deb
+RUN set -eux; \
+    case "${TARGETARCH}" in \
+        amd64) WASI_SDK_ARCH=amd64 ;; \
+        arm64) WASI_SDK_ARCH=arm64 ;; \
+        *) echo "Unsupported TARGETARCH: ${TARGETARCH}" >&2; exit 1 ;; \
+    esac; \
+    curl -sLO "https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-${WASI_SDK_VERSION}/wasi-sdk-${WASI_SDK_VERSION}.0-${WASI_SDK_ARCH}-linux.deb"; \
+    dpkg -i "wasi-sdk-${WASI_SDK_VERSION}.0-${WASI_SDK_ARCH}-linux.deb"; \
+    rm "wasi-sdk-${WASI_SDK_VERSION}.0-${WASI_SDK_ARCH}-linux.deb"
 
 # Install wit-bindgen and wasm-tools (pin versions)
 ARG WIT_BINDGEN_VERSION=0.53.1
 ARG WASM_TOOLS_VERSION=1.245.1
-RUN curl -sL https://github.com/bytecodealliance/wit-bindgen/releases/download/v${WIT_BINDGEN_VERSION}/wit-bindgen-${WIT_BINDGEN_VERSION}-x86_64-linux.tar.gz \
-    | tar xz --strip-components=1 -C /usr/local/bin --wildcards '*/wit-bindgen' \
-    && curl -sL https://github.com/bytecodealliance/wasm-tools/releases/download/v${WASM_TOOLS_VERSION}/wasm-tools-${WASM_TOOLS_VERSION}-x86_64-linux.tar.gz \
+RUN set -eux; \
+    case "${TARGETARCH}" in \
+        amd64) TOOL_ARCH=x86_64 ;; \
+        arm64) TOOL_ARCH=aarch64 ;; \
+        *) echo "Unsupported TARGETARCH: ${TARGETARCH}" >&2; exit 1 ;; \
+    esac; \
+    curl -sL "https://github.com/bytecodealliance/wit-bindgen/releases/download/v${WIT_BINDGEN_VERSION}/wit-bindgen-${WIT_BINDGEN_VERSION}-${TOOL_ARCH}-linux.tar.gz" \
+    | tar xz --strip-components=1 -C /usr/local/bin --wildcards '*/wit-bindgen'; \
+    curl -sL "https://github.com/bytecodealliance/wasm-tools/releases/download/v${WASM_TOOLS_VERSION}/wasm-tools-${WASM_TOOLS_VERSION}-${TOOL_ARCH}-linux.tar.gz" \
     | tar xz --strip-components=1 -C /usr/local/bin --wildcards '*/wasm-tools'
 
 WORKDIR /src
@@ -55,4 +74,4 @@ COPY --from=build /usr/local/bin/adder-host /usr/local/bin/adder-host
 COPY --from=build /src/adder.wasm /opt/adder.wasm
 
 ENTRYPOINT ["adder-host"]
-CMD ["1", "2", "/opt/adder.wasm"]
+CMD ["1", "2", "/opt/adder.wasm"]

component-model/examples/example-c-host/Dockerfile.host

@@ -0,0 +1,35 @@
+FROM ubuntu:24.04 AS build
+
+ARG WASMTIME_VERSION=42.0.1
+ARG TARGETARCH
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    gcc libc6-dev curl xz-utils ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install wasmtime C API
+RUN set -eux; \
+    case "${TARGETARCH}" in \
+        amd64) WASMTIME_ARCH=x86_64 ;; \
+        arm64) WASMTIME_ARCH=aarch64 ;; \
+        *) echo "Unsupported TARGETARCH: ${TARGETARCH}" >&2; exit 1 ;; \
+    esac; \
+    curl -sL "https://github.com/bytecodealliance/wasmtime/releases/download/v${WASMTIME_VERSION}/wasmtime-v${WASMTIME_VERSION}-${WASMTIME_ARCH}-linux-c-api.tar.xz" \
+    | tar xJ --strip-components=1 -C /usr/local; \
+    ldconfig
+
+WORKDIR /src
+
+# Build the host
+COPY host.c .
+RUN gcc -o /usr/local/bin/adder-host host.c -lwasmtime
+
+# Runtime image
+FROM ubuntu:24.04
+
+COPY --from=build /usr/local/lib/libwasmtime.so /usr/local/lib/
+RUN ldconfig
+COPY --from=build /usr/local/bin/adder-host /usr/local/bin/adder-host
+
+ENTRYPOINT ["adder-host"]
+CMD ["1", "2", "/component/add.wasm"]

component-model/examples/example-c-host/justfile

@@ -29,7 +29,6 @@ with the ability to add more language generators in the future.
 [wasi]: https://wasi.dev/
 [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
 
@@ -303,39 +302,98 @@ world root {
 ...
 ```
 
-### 6. Run the component from the example host
+## 6. Run the component from the example C host
 
-The following section requires you to have [a Rust toolchain][rust] installed.
+This repository includes a C application that can execute components that implement the add interface. This application embeds Wasmtime using the Wasmtime C API:
+`component-model/examples/example-c-host/host.c`.
 
-> [!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.
-> (The `wasmtime` version is specified in [the Cargo configuration file][cargo-config]
-> for the example host.)
+The application expects three arguments: the two numbers to add and the Wasm component that executed the addition. For example:
 
-{{#include ../example-host-part1.md}}
+```sh
+./adder-host <x> <y> <path-to-component.wasm>
+```
+
+You can either use a Dockerfile to execute your add component with the C application or directly run the application.
+
+### Option A: Compile and run the host directly
+
+If the Wasmtime C API headers and library are installed on your system,
+you can compile and run the host directly:
 
-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):
+On Linux, the following commands install the C API artifacts in `/usr/local`
+using the same approach as `Dockerfile.host`:
 
-{{#include ../example-host-part2.md}}
+```console
+sudo apt-get update
+sudo apt-get install -y --no-install-recommends \
+  gcc libc6-dev curl xz-utils ca-certificates
 
-## 7. Run the component from the example C host
+WASMTIME_VERSION=42.0.1
+case "$(uname -m)" in
+  x86_64) WASMTIME_ARCH=x86_64 ;;
+  aarch64|arm64) WASMTIME_ARCH=aarch64 ;;
+  *) echo "unsupported architecture: $(uname -m)" >&2; exit 1 ;;
+esac
 
-After setting up the wasmtime toolchain 
-*TODO: somehow,* 
-the `example-c-host` project can be built, and run our `adder` much like the rust one.
+curl -sL "https://github.com/bytecodealliance/wasmtime/releases/download/v${WASMTIME_VERSION}/wasmtime-v${WASMTIME_VERSION}-${WASMTIME_ARCH}-linux-c-api.tar.xz" \
+  | sudo tar xJ --strip-components=1 -C /usr/local
 
-*TODO: the C++ API is nicer and may be more appropriate for example code*
+sudo ldconfig
+```
 
-C/C++ language guest components can also 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.
+```console
+cd component-model/examples/example-c-host
+gcc -o adder-host host.c -lwasmtime
+./adder-host 1 2 /absolute/path/to/adder.wasm
+```
+
+If `libwasmtime.so` is not in a default library path on Linux,
+set `LD_LIBRARY_PATH` before running:
+
+```console
+LD_LIBRARY_PATH=/path/to/wasmtime/lib ./adder-host 1 2 /absolute/path/to/adder.wasm
+```
+
+Expected output:
+
+```sh
+1 + 2 = 3
+```
+
+### Option B: Run with Docker (`Dockerfile.host`)
+
+Instead of installing the Wasmtime C API, you can use the provided Dockerfile which builds the C application. 
+
+From `component-model/examples/example-c-host`:
+
+```console
+cp ../../examples/example-host/add.wasm ./add.wasm
+
+docker build \
+  -f Dockerfile.host \
+  -t example-c-host:latest \
+  .
+```
+
+Then run the container, passing in the component as a volume.
+
+```console
+docker run --rm \
+  -v /absolute/path/to/component-docs/component-model/examples/example-c-host/adder.wasm:/component/add.wasm:ro \
+  example-c-host:latest 1 2 /component/add.wasm
+```
+
+Expected output:
+
+```sh
+1 + 2 = 3
+```
 
-*TODO: work in `wasmtime --invoke 'add(2,2)' adder.wasm`*
+`Dockerfile.guest_and_host` is also provided in the same directory if you want
+an all-in-one image that builds both the guest component and the C host.
 
-[!NOTE]: #
-[!WARNING]: #
+Its guest build path follows the same sequence described in steps 2-4:
+`wit-bindgen c ...`, then `/opt/wasi-sdk/bin/wasm32-wasip2-clang ...`.
+The Dockerfile additionally automates fetching `world.wit` and `component.c`
+from this repository and pins tool versions for reproducibility.
+At the time of writing, `Dockerfile.guest_and_host` is Linux `x86_64`-specific.