README: Add some info for getting started with wasi-http

Signed-off-by: Andrew Clayton <a.clayton@nginx.com>

1 files changed, 115 insertions, 0 deletions

diff --git a/README b/README
index 3fc254d..0c208f9 100644
--- a/README
+++ b/README
@@ -12,6 +12,121 @@ or under wasmtime (v24 works), e.g.
     $ wasmtime serve -Scli -Sinherit-env ./component.wasm
 
 
+Getting Started
+===============
+
+First you'll need some tools.
+
+Firstly clang/llvm
+
+Fedora
+------
+
+# dnf install make clang llvm compiler-rt lld wasi-libc-devel wasi-libc-static
+
+Debian
+------
+
+# apt install make clang llvm lld
+
+You will also need to grab the wasi-sysroot, this is essentially a C library
+targeting WebAssembly (it is based partly on cloudlibc and musl libc) and
+is required for building server side WebAssembly modules.
+
+It's up to you where you put this.
+
+$ wget -O- https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-24/wasi-sysroot-24.0.tar.gz | tar -xzf -
+
+Note: Debian does provide a wasi-libc package, but the way it's packaged
+makes it unusable in this instance as --sysroot expects the include and lib
+directories to both be there (whereas in the Debian package they are in
+different locations).
+
+libclang_rt.builtins-wasm32.a
+-----------------------------
+
+For either of the above you will also need the libclang wasm32-wasi runtime
+library, this can be done with
+
+# wget -O- https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-24/libclang_rt.builtins-wasm32-wasi-24.0.tar.gz | tar --strip-components=1 -xvzf -
+ -C $(dirname $(clang -print-runtime-dir))
+
+That will install the following, path may vary slightly
+
+/usr/lib/clang/18/lib/wasi/libclang_rt.builtins-wasm32.a
+
+**NOTE:** If you get a major clang version update, you may need to repeat
+that last task.
+
+wit-bindgen & wasm-tools
+------------------------
+
+Finally you need a couple of rust based tools.
+
+You can grab the latest versions for your platform here
+
+https://github.com/bytecodealliance/wit-bindgen/releases
+https://github.com/bytecodealliance/wasm-tools/releases
+
+Again, where you put these is up to you.
+
+You will need to tell make where to find these tools, you can either set the
+WIT_BINDGEN & WASM_TOOLS environment variables in your shell or pass these
+directly to make, e.g.
+
+$ make WIT_BINDGEN=/path/to/wit-bindgen WASM_TOOLS=/path/to/wasm-tools
+
+
+Now you are ready to try building some components!
+
+(from the project_blackbird repository root)
+
+$ cd c/wasi-http/0.2.0/echo-request
+$ make # or the above make command depending on how you set the above vars
+
+or for Debian you will need to specify the WASI_SYSROOT
+
+$ make WASI_SYSROOT=/path/to/wasi-sysroot
+
+If it works you should be left with (amongst others) a component.wasm file,
+you can test that out by using the wasmtime-serve command
+
+You can grab wasmtime from
+
+https://github.com/bytecodealliance/wasmtime/releases/download/v24.0.0/wasmtime-v24.0.0-x86_64-linux.tar.xz
+
+or pick a different version for your platform, don't take the c-api package by
+mistake.
+
+Untar that someplace then you can do
+
+$ /path/to/wasmtime serve ./component.wasm
+
+Then try
+
+$ curl localhost:8080
+*** Welcome to WebAssembly with wasi-http / C ***
+
+[Request Info]
+REQUEST_PATH = /
+METHOD       = GET
+QUERY        =
+
+[Request Headers]
+accept = */*
+user-agent = curl/8.6.0
+
+For the other components using the reactor adaptor you will want to use
+
+$ /path/to/wasmtime serve -Scli ./component.wasm
+
+For env-var you will want
+
+$ /path/to/wasmtime serve -Scli -Sinherit-env ./component.wasm
+
+You can of course use that last command for them all.
+
+
 ================================================================================
 
 Make Fermyon Spin WebAssembly Modules run on NGINX Unit.