Document how to run code under WASI

[brettcannon]

https://github.com/python/cpython/tree/main/Tools/wasm doesn't cover how to take a WASI build and actually use it. We can probably just snag the instructions from https://github.com/tiran/cpython-wasm-test for wasmtime, maybe something for https://github.com/bytecodealliance/wasm-micro-runtime . Key thing is to probably show how to run something like pytest with a WASI build.

Linked PRs

• gh-100956: Update directions for how to run python + wasm #101003

[brendandburns]

fwiw, I have a devcontainer here: https://github.com/dev-wasm/dev-wasm-python that makes it easy to do this in GitHub codespaces or VS Code.

I would be happy to expand that documentation via PR if there is an interest.

[brettcannon]

I'm happy to take a PR! I'm honestly not looking at anything fancy, just something simple like, "To run code under wasmtime, you probably want to run the command wasmtime run --dir . --." Maybe something similar for iwasm, but that's just a bonus.

The only thing that may need checking is whether any specific directory mapping is necessary for e.g. /tmp in case some code somewhere in pytest or something is making some bad assumption about that directory always existing.

[brendandburns]

Ok, I will send a PR.

[brettcannon]

Mostly for me to not forget, wasmtime run --mapdir .::Python-3.11.0-wasm32-wasi-16 Python-3.11.0-wasm32-wasi-16/python.wasm gets the REPL up and running, as does wasmtime run --dir . python.wasm when in the same directory as lib/ (at least when grabbed from https://github.com/tiran/cpython-wasm-test/releases).

[brendandburns]

Here's the script I use (and which I put in the docs)

#!/bin/bash
if [ $# -eq 0 ]; then
    FILE=""
    HOST_DIR=$PWD
    GUEST_DIR=$PWD
elif [[ "$1" = /* ]]; then
    REAL_PATH=$(realpath $1)
    HOST_DIR=$(dirname $REAL_PATH)
    GUEST_DIR=$HOST_DIR
    FILE=${REAL_PATH}
else
    HOST_DIR=$PWD
    GUEST_DIR=$PWD
    FILE="/$PWD/${@#}"
fi
PYTHON_WASI_ROOT=/Python-3.11.0-wasm32-wasi-16
wasmtime run --dir  ${PYTHON_WASI_ROOT} \
             --mapdir /::${PYTHON_WASI_ROOT} \
             --dir ${HOST_DIR} \
             --mapdir ${GUEST_DIR}::${HOST_DIR} \
             -- ${PYTHON_WASI_ROOT}/python.wasm $FILE

Note that the one weirdness is that the working directory is the working directory of python.wasm not the directory of the script. That's a little unfortunate, but doesn't seem to be settable in wasmtime right now. I would wish for a flag that I could use in wasmtime to set the working directory, but I can't seem to find one.

[brettcannon]

Note that the one weirdness is that the working directory is the working directory of python.wasm not the directory of the script. That's a little unfortunate, but doesn't seem to be settable in wasmtime right now. I would wish for a flag that I could use in wasmtime to set the working directory, but I can't seem to find one.

Yeah, it's a bit annoying. We can actually compile in the bytecode for the .py files in the stdlib into the binary (it's called freezing), but it does make the tracebacks less useful since the actual source code won't be shown (the line numbers and file paths are still there, though). I think we have a mechanism right now that lets us manually specify the paths back to the source for frozen code; @ericsnowcurrently , is that right?

[ericsnowcurrently]

I think we have a mechanism right now that lets us manually specify the paths back to the source for frozen code; @ericsnowcurrently , is that right?

There is no manual step. Currently when freezing the stdlib, the tools record the relative path for each frozen stdlib module as part of the frozen data. During import we then make that path absolute (using sys._stdlib_dir) and use the result for __file__. I'm not sure how that works with WASM though.

[brettcannon]

70dc2fb