[Python-checkins] gh-95205: Improve WASM README.md (GH-95267) (GH-95270)
ambv
webhook-mailer at python.org
Tue Jul 26 06:17:13 EDT 2022
https://github.com/python/cpython/commit/6284f232584d6e201f342b984bf45af85b8be25f
commit: 6284f232584d6e201f342b984bf45af85b8be25f
branch: 3.11
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: ambv <lukasz at langa.pl>
date: 2022-07-26T12:17:05+02:00
summary:
gh-95205: Improve WASM README.md (GH-95267) (GH-95270)
Co-authored-by: Erlend Egeberg Aasland <erlend.aasland at protonmail.com>
(cherry picked from commit e8f3e8f0ab8aa5d667229ce9694e6e1477e524fd)
Co-authored-by: Christian Heimes <christian at python.org>
files:
A Tools/wasm/wasi-env
M Tools/wasm/README.md
diff --git a/Tools/wasm/README.md b/Tools/wasm/README.md
index b9d773b226959..c1daddda463bb 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 0000000000000..600072b02fb8a
--- /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 "$@"
More information about the Python-checkins
mailing list