|
1 | | -# WASM Runtime Adapters |
2 | | - |
3 | | -The test runner is designed to support different types of WebAssembly runtimes. Because the command line interface for WASM runtime is not standardized, every runtime can arbitrarily define how parameters should be passed to the runtime. |
4 | | - |
5 | | -WASI test runner is designed to support as many WASM runtimes as possible, therefore runtime peculiarities aren't hardcoded in the runner. |
6 | | - |
7 | | -In order to integrate WASM runtime with a test runner, the user has to provide a `runtime adapter`. It's a *Python script* that takes command-line arguments and translates them to a runtime call. The reason for using a Python script over a generic "she-bang" executable, is to ensure cross-platform compatibility, such an executable is expected to be a python a script. |
8 | | - |
9 | | -## Interface |
10 | | -The adapter executable must accept the following command line parameters and execute actions associated with those parameters: |
11 | | -* `--version` - prints to standard output name and version of the runtime in the following format: `<NAME> <VERSION>` |
12 | | -* `--env <NAME=VAL>` - passes environment variable to WASM module. The parameter can be used multiple times in one call. |
13 | | -* `--arg <ARG>` - passes argument `<ARG>` to WASM module. The parameter can be used multiple times in one call. |
14 | | -* `--dir <DIRECTORY>` - grants access to the `<DIRECTORY>` host directory. The parameter can be used multiple times in one call. |
15 | | -* `--test-file <PATH>` - runs WASM module located in `<PATH>` |
16 | | - |
17 | | -The adapter must return exit code to the environment that was passed as an argument to the `proc_exit` function in WASM code. This can be verified by running the following code: |
18 | | - |
19 | | -```wat |
20 | | -(module |
21 | | - (import "wasi_snapshot_preview1" "proc_exit" (func $fimport$0 (param i32))) |
22 | | - (memory $0 0) |
23 | | - (export "memory" (memory $0)) |
24 | | - (export "_start" (func $0)) |
25 | | - (func $0 |
26 | | - (call $fimport$0 |
27 | | - (i32.const 13) |
28 | | - ) |
29 | | - ) |
30 | | -) |
31 | | -``` |
32 | | -and check if the exit code is equal to `13`. There are also two test cases in Assembly Script test suite that verify the behavior: |
33 | | -* [proc_exit-failure](../tests/assemblyscript/wasm32-wasip1/src/proc_exit-failure.ts) |
34 | | -* [proc_exit-success](../tests/assemblyscript/wasm32-wasip1/src/proc_exit-success.ts) |
35 | | -### Examples: |
36 | | - |
37 | | -Print runtime version: |
38 | | - |
39 | | -```bash |
40 | | -$ ./adapter.py --version |
41 | | -wasmtime-cli 1.0.1 |
42 | | -``` |
43 | | - |
44 | | -Run WASM module: |
45 | | - |
46 | | -```bash |
47 | | -$ ./adapter.py --arg a1 --arg a2 --env E1=env1 --env E2=env2 --test-file test.wasm |
48 | | -# Expected to start test.wasm module with E1=env1 and E2=env2 |
49 | | -# environment variables defined and arguments a1, a2 passed to |
50 | | -# the module. |
51 | | - |
52 | | -$ echo $? |
53 | | -# should display value passed to proc_exit function in WASM code |
54 | | -``` |
55 | | - |
56 | | -## Examples |
57 | | - |
58 | | -See the [`adapters`](../adapters) directory for example adapters. |
59 | | - |
60 | | -## Contributions |
61 | | - |
62 | | -We prefer runtime maintainers to maintain adapters in their own repository We'll only maintain adapters for [Bytecode Alliance](https://bytecodealliance.org/) projects and we'll aim for compatibility with the most recent stable version. |
63 | | - |
64 | | -We'll accept pull requests for new adapters in this repository, but we can't guarantee we'll have the capacity to maintain them (so they might stop working with the new runtime release). |
| 1 | +# WASM Runtime Support |
| 2 | + |
| 3 | +The WASI test runner will try to run all tests against all WASI |
| 4 | +implementations that it knows about. Each test is run in a fresh |
| 5 | +sub-process. A *runtime adapter* is code to translate the test |
| 6 | +parameters (wasm file location, exposed directories, environment |
| 7 | +variables, and any command-line arguments) into a command line that can |
| 8 | +be run. The adapter also indicates to the test runner which WASI |
| 9 | +versions are supported by a WASI runtime and what the version of the |
| 10 | +runtime itself is. |
| 11 | + |
| 12 | +The WASI test runner includes adapters for |
| 13 | +[pywasm](https://github.com/mohanson/pywasm), |
| 14 | +[wamr](https://bytecodealliance.github.io/wamr.dev/), |
| 15 | +[wasmedge](https://wasmedge.org), [wasmtime](https://wasmtime.dev), |
| 16 | +[wazero](https://wazero.io), and |
| 17 | +[wizard](https://github.com/titzer/wizard-engine/). Contributions of |
| 18 | +adapters for other runtimes are welcome. |
| 19 | + |
| 20 | +## Writing your own adapter |
| 21 | + |
| 22 | +The adapter is a python file that the test runner will load as a module. |
| 23 | +To create a new adapter, we recommend you take a look at |
| 24 | +[`adapters/wasmtime.py`](../adapters/wasmtime.py). As you can see, |
| 25 | +currently we require that the module define `get_name`, `get_version`, |
| 26 | +and `compute_argv` functions. |
| 27 | + |
| 28 | +We encourage you to submit your adapter upstream: it's not much code and |
| 29 | +probably we can manage to make changes to it if test runner internals |
| 30 | +change. Though we don't change internals too often, we don't intend for |
| 31 | +internal Python API of the test runner to be stable for external use. |
0 commit comments