wasmtimeコマンドのTips
WebAssemblyのランタイムはいくつかありますが、有力なもののひとつがByteCode Allianceによって開発されているWasmtimeです。WasmtimeはRust向けのクレートやC言語向けのライブラリーとして提供されていますが、単体で利用できるコマンドも用意されています。この記事では、wasmtimeコマンドと、いくつかのTipsを紹介します。
インストール
次のいずれかの方法でインストールできます：
- インストールスクリプトを利用する方法
-
cargo installコマンドを利用してインストールする方法 - GitHub上のリリースページからバイナリーをダウンロードしてインストールする
- ソースコードをビルドしてインストールする
この中で簡単なのは最初の2つです。
1つ目の方法では、次のようにダウンロードしたインストールスクリプトをダウンロードして実行することで、wasmtimeコマンドをインストールできます：
% $ curl https://wasmtime.dev/install.sh -sSf | bash
Rustの開発環境をお持ちの方は、2つ目の方法でインストールされるとバージョンアップやアンインストールが簡単に行えるので良いように思います。
% cargo install wasmtime-cli
Wasmファイルの実行
引数に実行するWasmファイルを指定します。
% wasmtime hello-world.wasm
Hello, world!
次のいずれかの場合にのみ、上記のようにWasmファイルを実行でます：
- wasi:cli/commandワールドを実装しているWasmコンポーネントであること
-
_start関数をエキスポートしているWasmモジュールであること
特定の関数を実行するには
Wasmモジュールがエキスポートする特定の関数を実行するには、--invokeオプションを利用します。例えば次のようなライブラリークレートがあったとします：
このプログラムをビルドして得られたWasmモジュールはaddとfourの2つの関数をエキスポートしています。このうちパラメーターのないfour関数は、次のように実行できます：
% wasmtime --invoke four target/wasm32-wasip1/release/hello_lib.wasm
2 + 2 = 4
環境変数を指定するには
次のような環境変数を利用するプログラムがあったとします：
このプログラムは環境変数nameの値をHello, {name}!へ埋め込み、標準出力へ出力します。次のようにchikoskiを指定した場合は、Hello, chikoskiと出力します：
% name=chikoski cargo run
Hello, chikoski!
Wasmtimeはサンドボックス内でWasmファイルを実行します。wasmtimeコマンドを実行したシェルに設定されている環境変数は、サンドボックス内には露出されません。そのため、次のように設定された環境変数は、Wasmファイルからは読み取ることができません：
% name=chikoski wasmtime target/wasm32-wasip1/release/env.wasm
Hello, world!
サンドボックス内に環境変数を露出するには、次のように--envオプションで露出する環境変数を明示します：
% name=chikoski wasmtime --env name target/wasm32-wasip1/release/env.wasm
また--envオプションを使うと環境変数の値を上書きすることもできます。次の例では、chikoskiと設定されている環境変数nameの値を上書きしています：
% name=chikoski wasmtime --env name=wasm target/wasm32-wasip1/release/env.wasm
Hello, wasm!
ディレクトリへのアクセスを許可するには
Wasmtimeはサンドボックスの中でWasmファイルを実行するため、Wasmファイルからは実行時に許可されたファイルにのみアクセスできます。許可されていないファイルやフォルダーへアクセスした場合、次のようなエラーメッセージが表示されます：
failed to find a pre-opened file descriptor through which "./a/text/file" could be opened
アクセスを許可するフォルダーは--dirオプションで指定できます。次の例では、ls.wasmに対して/some/whereに対するアクセスを許可しています：
% wasmtime --dir=/some/where ls.wasm
a.txt
b.txt
c.txt
サンドボックス内での位置
アクセスを許可する際に、Wasmファイルから見えるパスを指定することもできます。次の例では、/some/whereは、Wasmファイルからは/dataとして見えます：
% wasmtime --dir=/some/where::/data ls.wasm
なお::/dataを省略した場合、次のように指定したものとして扱われます：
% wasmtime --dir=/some/where::/ ls.wasm
--dirオプションは複数指定できます
--dirオプションを複数指定できます。次の例では、/some/whereを/dataに、/another/folderを/homeに設定しています。
% wasmtime --dir=/some/where::/data --dir=/another/folder::/home ls.wasm
同じ位置へ異なるフォルダーが設定されている場合は、後に指定したものが有効となります。次の例では、/another/folderが/dataとして設定されます。
% wasmtime --dir=/some/where::/data --dir=/another/folder::/data ls.wasm
対応しているWasmプロポザールの一覧
-W helpで対応しているプロポーザルを一覧できます。28.0.0は次のようになっています。
% wasmtime -W help
wasmtime -W help
Available wasm options:
-W nan-canonicalization[=y|n] -- Enable canonicalization of all NaN values.
-W fuel=N -- Enable execution fuel with N units fuel, trapping after running out of fuel.
-W epoch-interruption[=y|n] -- Yield when a global epoch counter changes, allowing for async operation without blocking the executor.
-W max-wasm-stack=N -- Maximum stack size, in bytes, that wasm is allowed to consume before a stack overflow is reported.
-W async-stack-size=N -- Stack size, in bytes, that will be allocated for async stacks.
-W unknown-exports-allow[=y|n] -- Allow unknown exports when running commands.
-W unknown-imports-trap[=y|n] -- Allow the main module to import unknown functions, using an implementation that immediately traps, when running commands.
-W unknown-imports-default[=y|n] -- Allow the main module to import unknown functions, using an implementation that returns default values, when running commands.
-W wmemcheck[=y|n] -- Enables memory error checking. (see wmemcheck.md for more info)
-W max-memory-size=N -- Maximum size, in bytes, that a linear memory is allowed to reach.
-W max-table-elements=N -- Maximum size, in table elements, that a table is allowed to reach.
-W max-instances=N -- Maximum number of WebAssembly instances allowed to be created.
-W max-tables=N -- Maximum number of WebAssembly tables allowed to be created.
-W max-memories=N -- Maximum number of WebAssembly linear memories allowed to be created.
-W trap-on-grow-failure[=y|n] -- Force a trap to be raised on `memory.grow` and `table.grow` failure instead of returning -1 from these instructions.
-W timeout=N|Ns|Nms|.. -- Maximum execution time of wasm code before timing out (1, 2s, 100ms, etc)
-W all-proposals[=y|n] -- Configures support for all WebAssembly proposals implemented.
-W bulk-memory[=y|n] -- Configure support for the bulk memory proposal.
-W multi-memory[=y|n] -- Configure support for the multi-memory proposal.
-W multi-value[=y|n] -- Configure support for the multi-value proposal.
-W reference-types[=y|n] -- Configure support for the reference-types proposal.
-W simd[=y|n] -- Configure support for the simd proposal.
-W relaxed-simd[=y|n] -- Configure support for the relaxed-simd proposal.
-W relaxed-simd-deterministic[=y|n] -- Configure forcing deterministic and host-independent behavior of the relaxed-simd instructions.
-W tail-call[=y|n] -- Configure support for the tail-call proposal.
-W threads[=y|n] -- Configure support for the threads proposal.
-W memory64[=y|n] -- Configure support for the memory64 proposal.
-W component-model[=y|n] -- Configure support for the component-model proposal.
-W component-model-more-flags[=y|n] -- Configure support for 33+ flags in the component model.
-W component-model-multiple-returns[=y|n] -- Component model support for more than one return value.
-W function-references[=y|n] -- Configure support for the function-references proposal.
-W gc[=y|n] -- Configure support for the GC proposal.
-W custom-page-sizes[=y|n] -- Configure support for the custom-page-sizes proposal.
対応しているシステムインターフェース一覧
-S helpオプションで、対応しているシステムインターフェースを一覧できます。28.0.0の場合、次のようになっています：
% wasmtime -S help
Available wasi options:
-S cli[=y|n] -- Enable support for WASI CLI APIs, including filesystems, sockets, clocks, and random.
-S common[=y|n] -- Deprecated alias for `cli`
-S nn[=y|n] -- Enable support for WASI neural network API (experimental)
-S threads[=y|n] -- Enable support for WASI threading API (experimental)
-S http[=y|n] -- Enable support for WASI HTTP API (experimental)
-S runtime-config[=y|n] -- Enable support for WASI runtime config API (experimental)
-S keyvalue[=y|n] -- Enable support for WASI key-value API (experimental)
-S listenfd[=y|n] -- Inherit environment variables and file descriptors following the systemd listen fd specification (UNIX only)
-S tcplisten=val -- Grant access to the given TCP listen socket
-S preview2[=y|n] -- Implement WASI CLI APIs with preview2 primitives (experimental).
-S nn-graph=<format>::<dir> -- Pre-load machine learning graphs (i.e., models) for use by wasi-nn.
-S inherit-network[=y|n] -- Flag for WASI preview2 to inherit the host's network within the guest so it has full access to all addresses/ports/etc.
-S allow-ip-name-lookup[=y|n] -- Indicates whether `wasi:sockets/ip-name-lookup` is enabled or not.
-S tcp[=y|n] -- Indicates whether `wasi:sockets` TCP support is enabled or not.
-S udp[=y|n] -- Indicates whether `wasi:sockets` UDP support is enabled or not.
-S preview0[=y|n] -- Allows imports from the `wasi_unstable` core wasm module.
-S inherit-env[=y|n] -- Inherit all environment variables from the parent process.
-S runtime-config-var=<name>=<val> -- Pass a wasi runtime config variable to the program.
-S keyvalue-in-memory-data=<name>=<val> -- Preset data for the In-Memory provider of WASI key-value API.
Discussion