wasmedge
CLI
After installation, users can execute the wasmedge
tool with commands.
$ wasmedge -v
wasmedge version 0.12.1
The usage of the wasmedge
tool will be:
$ wasmedge -h
USAGE
wasmedge [SUBCOMMANDS] [OPTIONS] [--] WASM_OR_SO [ARG ...]
...
If users install the WasmEdge from the install script with the option -e tf,image
, the WasmEdge CLI tools with TensorFlow and TensorFlow-Lite extensions will be installed.
wasmedge-tensorflow
CLI tool- The
wasmedge
tool with TensorFlow, TensorFlow-Lite, andwasmedge-image
extensions. - Only on
x86_64
andaarch64
Linux platforms andx86_64
MacOS.
- The
wasmedge-tensorflow-lite
CLI tool- The
wasmedge
tool with TensorFlow-Lite, andwasmedge-image
extensions. - Only on
x86_64
andaarch64
Linux platforms, Android, andx86_64
MacOS.
- The
The wasmedge
CLI tool will execute the WebAssembly in ahead-of-time(AOT) mode if available in the input WASM file.
For the pure WASM, the wasmedge
CLI tool will execute it in interpreter mode, which is much slower than AOT mode.
If you want to improve the performance, please refer here to compile your WASM file.
Subcommands
The subcommands of the wasmedge
CLI tool are as follows.
run
: execute the WebAssembly; the usage ofwasmedge run
is identical towasmedge
without-v|--version
option. Please refer here to get more details.compile
: compile WebAssembly into native machine code (i.e., the AOT compiler). Please refer here to get more details.
Options
The options of the wasmedge
CLI tool are as follows.
-v|--version
: Show the version information. Will ignore other arguments below.-h|--help
: Show the help messages. Will ignore other arguments below.- (Optional)
--reactor
: Enable the reactor mode.- In the reactor mode,
wasmedge
runs a specified function exported by the WebAssembly program. - WasmEdge will execute the function which name should be given in
ARG[0]
. - If there's exported function which names
_initialize
, the function will be executed with the empty parameter at first.
- In the reactor mode,
- (Optional)
--dir
: Bind directories into WASI virtual filesystem.- Use
--dir host_path
to bind the host path in WASI virtual system. Noted that it's same as--dir host_path:host_path
. - Use
--dir guest_path:host_path
to bind the host path in WASI virtual system and map it to the guest path.
- Use
- (Optional)
--env
: Assign the environment variables in WASI.- Use
--env ENV_NAME=VALUE
to assign the environment variable.
- Use
- (Optional) Statistics information:
- Use
--enable-time-measuring
to show the execution time. - Use
--enable-gas-measuring
to show the amount of used gas. - Use
--enable-instruction-count
to display the number of executed instructions. - Or use
--enable-all-statistics
to enable all of the statistics options.
- Use
- (Optional) Resource limitations:
- Use
--time-limit MILLISECOND_TIME
to limit the execution time. Default value is0
as no limitation. - Use
--gas-limit GAS_LIMIT
to limit the execution cost. - Use
--memory-page-limit PAGE_COUNT
to set the limitation of pages(as size of 64 KiB) in every memory instance.
- Use
- (Optional) WebAssembly proposals:
- Use
--disable-import-export-mut-globals
to disable the Import/Export of Mutable Globals proposal (DefaultON
). - Use
--disable-non-trap-float-to-int
to disable the Non-Trapping Float-to-Int Conversions proposal (DefaultON
). - Use
--disable-sign-extension-operators
to disable the Sign-Extension Operators proposal (DefaultON
). - Use
--disable-multi-value
to disable the Multi-value proposal (DefaultON
). - Use
--disable-bulk-memory
to disable the Bulk Memory Operations proposal (DefaultON
). - Use
--disable-reference-types
to disable the Reference Types proposal (DefaultON
). - Use
--disable-simd
to disable the Fixed-width SIMD proposal (DefaultON
). - Use
--enable-multi-memory
to enable the Multiple Memories proposal (DefaultOFF
). - Use
--enable-tail-call
to enable the Tail call proposal (DefaultOFF
). - Use
--enable-extended-const
to enable the Extended Constant Expressions proposal (DefaultOFF
). - Use
--enable-threads
to enable the Threads proposal (DefaultOFF
). - Use
--enable-all
to enable ALL proposals above.
- Use
- WASM file (
/path/to/wasm/file
). - (Optional)
ARG
command line arguments array.- In reactor mode, the first argument will be the function name, and the arguments after
ARG[0]
will be parameters of wasm functionARG[0]
. - In command mode, the arguments will be the command line arguments of the WASI
_start
function. They are also known as command line arguments(argv
) for a standalone C/C++ program.
- In reactor mode, the first argument will be the function name, and the arguments after
Examples
Call A WebAssembly Function Written in WAT
We created the hand-written fibonacci.wat and used the wat2wasm tool to convert it into the fibonacci.wasm WebAssembly program.
It exported a fib()
function which takes a single i32
integer as the input parameter. We can execute wasmedge
in reactor mode to invoke the exported function.
You can run:
wasmedge --reactor fibonacci.wasm fib 10
The output will be:
89
Call A WebAssembly Function Compiled From Rust
The add.wasm WebAssembly program contains an exported add()
function, which is compiled from Rust.
Checkout its Rust source code project here.
We can execute wasmedge
in reactor mode to invoke the add()
function with two i32
integer input parameters.
You can run:
wasmedge --reactor add.wasm add 2 2
The output will be:
4
Execute A Standalone WebAssembly Program: Hello world
The hello.wasm WebAssembly program contains a main()
function.
Checkout its Rust source code project here.
It prints out hello
followed by the command line arguments.
You can run:
wasmedge hello.wasm second state
The output will be:
hello
second
state
Execute With statistics
Enabled
The CLI supports --enable-all-statistics
flags for the statistics and gas metering.
You can run:
wasmedge --enable-all-statistics hello.wasm second state
The output will be:
hello
second
state
[2021-12-09 16:03:33.261] [info] ==================== Statistics ====================
[2021-12-09 16:03:33.261] [info] Total execution time: 268266 ns
[2021-12-09 16:03:33.261] [info] Wasm instructions execution time: 251610 ns
[2021-12-09 16:03:33.261] [info] Host functions execution time: 16656 ns
[2021-12-09 16:03:33.261] [info] Executed wasm instructions count: 20425
[2021-12-09 16:03:33.261] [info] Gas costs: 20425
[2021-12-09 16:03:33.261] [info] Instructions per second: 81177218
[2021-12-09 16:03:33.261] [info] ======================= End ======================
Execute With gas-limit
Enabled
The CLI supports --gas-limit
flags for controlling the execution costs.
For giving sufficient gas as the example, you can run:
wasmedge --enable-all-statistics --gas-limit 20425 hello.wasm second state
The output will be:
hello
second
state
[2021-12-09 16:03:33.261] [info] ==================== Statistics ====================
[2021-12-09 16:03:33.261] [info] Total execution time: 268266 ns
[2021-12-09 16:03:33.261] [info] Wasm instructions execution time: 251610 ns
[2021-12-09 16:03:33.261] [info] Host functions execution time: 16656 ns
[2021-12-09 16:03:33.261] [info] Executed wasm instructions count: 20425
[2021-12-09 16:03:33.261] [info] Gas costs: 20425
[2021-12-09 16:03:33.261] [info] Instructions per second: 81177218
[2021-12-09 16:03:33.261] [info] ======================= End ======================
For giving insufficient gas as the example, you can run:
wasmedge --enable-all-statistics --gas-limit 20 hello.wasm second state
The output will be:
[2021-12-23 15:19:06.690] [error] Cost exceeded limit. Force terminate the execution.
[2021-12-23 15:19:06.690] [error] In instruction: ref.func (0xd2) , Bytecode offset: 0x00000000
[2021-12-23 15:19:06.690] [error] At AST node: expression
[2021-12-23 15:19:06.690] [error] At AST node: element segment
[2021-12-23 15:19:06.690] [error] At AST node: element section
[2021-12-23 15:19:06.690] [error] At AST node: module
[2021-12-23 15:19:06.690] [info] ==================== Statistics ====================
[2021-12-23 15:19:06.690] [info] Total execution time: 0 ns
[2021-12-23 15:19:06.690] [info] Wasm instructions execution time: 0 ns
[2021-12-23 15:19:06.690] [info] Host functions execution time: 0 ns
[2021-12-23 15:19:06.690] [info] Executed wasm instructions count: 21
[2021-12-23 15:19:06.690] [info] Gas costs: 20
JavaScript Examples
It is possible to use WasmEdge as a high-performance, secure, extensible, easy to deploy, and Kubernetes-compliant JavaScript runtime.
The qjs.wasm program is a JavaScript interpreter compiled into WebAssembly. The hello.js file is a very simple JavaScript program.
You can run:
wasmedge --dir . qjs.wasm hello.js 1 2 3
Or the equal mapping as follow:
wasmedge --dir .:. qjs.wasm hello.js 1 2 3
The output will be:
Hello 1 2 3
The qjs_tf.wasm is a JavaScript interpreter with WasmEdge Tensorflow extension compiled into WebAssembly.
To run qjs_tf.wasm, you must use the wasmedge-tensorflow-lite
CLI tool, which is a build of WasmEdge with Tensorflow-Lite extension built-in.
You can download a full Tensorflow-based JavaScript example to classify images.
# Download the Tensorflow example
$ wget https://raw.githubusercontent.com/second-state/wasmedge-quickjs/main/example_js/tensorflow_lite_demo/aiy_food_V1_labelmap.txt
$ wget https://raw.githubusercontent.com/second-state/wasmedge-quickjs/main/example_js/tensorflow_lite_demo/food.jpg
$ wget https://raw.githubusercontent.com/second-state/wasmedge-quickjs/main/example_js/tensorflow_lite_demo/lite-model_aiy_vision_classifier_food_V1_1.tflite
$ wget https://raw.githubusercontent.com/second-state/wasmedge-quickjs/main/example_js/tensorflow_lite_demo/main.js
$ wasmedge-tensorflow-lite --dir .:. qjs_tf.wasm main.js
label: Hot dog
confidence: 0.8941176470588236