gh-95205: Improve WASM README.md (GH-95267)

Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@protonmail.com>

2 files changed, 112 insertions, 12 deletions

diff --git a/Tools/wasm/README.md b/Tools/wasm/README.md
index b9d773b..c1daddda 100644
--- a/Tools/wasm/README.md
+++ b/Tools/wasm/README.md
@@ -69,12 +69,9 @@ popd
 ```
 
 Serve `python.html` with a local webserver and open the file in a browser.
-
-```shell
-emrun builddir/emscripten-browser/python.html
-```
-
-or
+Python comes with a minimal web server script that sets necessary HTTP
+headers like COOP, COEP, and mimetypes. Run the script outside the container
+and from the root of the CPython checkout.
 
 ```shell
 ./Tools/wasm/wasm_webserver.py
@@ -84,6 +81,7 @@ and open http://localhost:8000/builddir/emscripten-browser/python.html . This
 directory structure enables the *C/C++ DevTools Support (DWARF)* to load C
 and header files with debug builds.
 
+
 ### Cross compile to wasm32-emscripten for node
 
 ```shell
@@ -232,6 +230,28 @@ WASI builds require [WASI SDK](https://github.com/WebAssembly/wasi-sdk) 15.0+
 and currently [wasix](https://github.com/singlestore-labs/wasix) for POSIX
 compatibility stubs.
 
+## Cross-compile to wasm32-wasi
+
+The script ``wasi-env`` sets necessary compiler and linker flags as well as
+``pkg-config`` overrides. The script assumes that WASI-SDK is installed in
+``/opt/wasi-sdk`` or ``$WASI_SDK_PATH``.
+
+```shell
+mkdir -p builddir/wasi
+pushd builddir/wasi
+
+CONFIG_SITE=../../Tools/wasm/config.site-wasm32-wasi \
+  CFLAGS="-isystem /opt/wasix/include" \
+  LDFLAGS="-L/opt/wasix/lib -lwasix" \
+  ../../Tools/wasm/wasi-env ../../configure -C \
+    --host=wasm32-unknown-wasi \
+    --build=$(../../config.guess) \
+    --with-build-python=$(pwd)/../build/python
+
+make -j$(nproc)
+popd
+```
+
 ## WASI limitations and issues (WASI SDK 15.0)
 
 A lot of Emscripten limitations also apply to WASI. Noticable restrictions
@@ -376,6 +396,16 @@ git clone https://github.com/emscripten-core/emsdk.git /opt/emsdk
 /opt/emsdk/emsdk activate latest
 ```
 
+### Optionally: enable ccache for EMSDK
+
+The ``EM_COMPILER_WRAPPER`` must be set after the EMSDK environment is
+sourced. Otherwise the source script removes the environment variable.
+
+```
+. /opt/emsdk/emsdk_env.sh
+EM_COMPILER_WRAPPER=ccache
+```
+
 ### Optionally: pre-build and cache static libraries
 
 Emscripten SDK provides static builds of core libraries without PIC
@@ -384,12 +414,8 @@ PIC. To populate the build cache, run:
 
 ```shell
 . /opt/emsdk/emsdk_env.sh
-embuilder build --force zlib bzip2
-embuilder build --force --pic \
-    zlib bzip2 libc-mt libdlmalloc-mt libsockets-mt \
-    libstubs libcompiler_rt libcompiler_rt-mt crtbegin libhtml5 \
-    libc++-mt-noexcept libc++abi-mt-noexcept \
-    libal libGL-mt libstubs-debug libc-mt-debug
+embuilder build zlib bzip2 MINIMAL_PIC
+embuilder build --pic zlib bzip2 MINIMAL_PIC
 ```
 
 ### Install [WASI-SDK](https://github.com/WebAssembly/wasi-sdk)
@@ -424,3 +450,9 @@ ln -srf -t /usr/local/bin/ ~/.wasmtime/bin/wasmtime
 git clone https://github.com/singlestore-labs/wasix.git ~/wasix
 make install -C ~/wasix
 ```
+
+### WASI debugging
+
+* ``wasmtime run -g`` generates debugging symbols for gdb and lldb.
+* The environment variable ``RUST_LOG=wasi_common`` enables debug and
+  trace logging.
diff --git a/Tools/wasm/wasi-env b/Tools/wasm/wasi-env
new file mode 100755
index 0000000..600072b
--- /dev/null
+++ b/Tools/wasm/wasi-env
@@ -0,0 +1,68 @@
+#!/bin/sh
+set -e
+
+# function
+usage() {
+    echo "wasi-env - Run command with WASI-SDK"
+    echo ""
+    echo "wasi-env is a helper to set various environment variables to"
+    echo "run configure and make with WASI-SDK. A WASI-SDK must be either"
+    echo "installed at /opt/wasi-sdk or the env var 'WASI_SDK_PATH' must"
+    echo "set to the root of a WASI-SDK."
+    echo ""
+    echo "Usage: wasi-env command [...]"
+    echo ""
+    echo "    -h --help     display this help and exit"
+    echo ""
+}
+
+case $1 in
+    -h|--help)
+        usage
+        exit
+        ;;
+esac
+
+if test -z "$1"; then
+    echo "ERROR: command required" >&2
+    usage
+    exit 1
+fi
+
+WASI_SDK_PATH="${WASI_SDK_PATH:-/opt/wasi-sdk}"
+
+if ! test -x "${WASI_SDK_PATH}/bin/clang"; then
+    echo "Error: ${WASI_SDK_PATH}/bin/clang does not exist." >&2
+    exit 2
+fi
+
+# --sysroot is required if WASI-SDK is not installed in /opt/wasi-sdk.
+WASI_SYSROOT="${WASI_SDK_PATH}/share/wasi-sysroot"
+CC="${WASI_SDK_PATH}/bin/clang --sysroot=${WASI_SYSROOT}"
+CPP="${WASI_SDK_PATH}/bin/clang-cpp --sysroot=${WASI_SYSROOT}"
+CXX="${WASI_SDK_PATH}/bin/clang++ --sysroot=${WASI_SYSROOT}"
+
+# use ccache if available
+if command -v ccache >/dev/null 2>&1; then
+    CC="ccache ${CC}"
+    CPP="ccache ${CPP}"
+    CXX="ccache ${CXX}"
+fi
+
+LDSHARED="${WASI_SDK_PATH}/bin/wasm-ld"
+AR="${WASI_SDK_PATH}/bin/llvm-ar"
+RANLIB="${WASI_SDK_PATH}/bin/ranlib"
+
+# instruct pkg-config to use sysroot
+PKG_CONFIG_PATH=""
+PKG_CONFIG_LIBDIR="${WASI_SYSROOT}/lib/pkgconfig:${WASI_SYSROOT}/share/pkgconfig"
+PKG_CONFIG_SYSROOT_DIR="${WASI_SYSROOT}"
+
+PATH="${WASI_SDK_PATH}/bin:$PATH"
+
+export WASI_SDK_PATH
+export CC CPP CXX LDSHARED AR RANLIB
+export PKG_CONFIG_PATH PKG_CONFIG_LIBDIR PKG_CONFIG_SYSROOT_DIR
+export PATH
+
+exec "$@"