WasmRunner

A command line tool to execute WebAssembly files.

./WasmRunner [version] [-h | --help] [--reactor] [run]
             [path_to_wasm_file] [entry_function] [args]

Building

As this tool uses wasmedge C library as a dependency, it needs to be installed first. Refer to this as a guide

You can install it with git and curl -

curl -sSf https://raw.githubusercontent.com/WasmEdge/WasmEdge/master/utils/install.sh | bash

After you install it, clone this repo -

git clone https://github.com/Subhra264/WasmRunner.git

Move to the /WasmRunner directory -

cd WasmRunner/

Now simply execute the build.sh file -

./build.sh

Once the build directory is created, move to the directory and use the tool -

cd build

./WasmRunner version

How is this built?

This tool is completely based on the wasmedge C library SDK and is written in C++11. There are two files in the /src directory -

• main.cc - Responsible for executing all the CLI related logic i.e. taking inputs, doing initial parsing and validation of inputs and printing results or errors to the console.
• WasmRunner.cc - Implements the WasmRunner class that wraps the internally used wasmedge C library SDK. It exposes various methods necessary for executing a given wasm file.

WasmRunner class

Public member functions -

Constructor

Instantiates the WasmRunner class. Also initializes internally used WasmEdge_ConfigureContext and WasmEdge_VMContext

Params

• SuccessHandler - A success handler function to be called with returned values from the execution of given wasm file
• ErrorHandler - A error handler function to be called with the error message occured during the execution of given wasm file.

Returns

• WasmRunner - A new WasmRunner instance.

static GetVersion()

A static member function that returns the wasmedge C library version as an array of chars.

Returns

• const char * - The version of wasmedge C SDK.

LoadWasmFile()

Loads the wasm file given using WasmEdge_VMLoadWasmFromFile C function.

Params

• std::string file_name - The wasm file path to load.

Returns

• bool - If true, the operation was successful, failed otherwise.

ValidateVM()

Internally uses WasmEdge_VMValidate C function to validate the VM after loading wasm file.

Returns

• bool - If true, the operation was successful, failed otherwise.

InstantiateVM()

Internally uses WasmEdge_VMInstantiate C function to instantiate the validated wasm module in the VM context.

Returns

• bool - If true, the operation was successful, failed otherwise.

RunWasm()

Executes the given wasm file.

Params

• std::vector<std::string>> params - A vector with all the wasm file arguments.
• bool reactor_enabled - A boolean representing if reactor flag is on.
• std::string entry_func - If reactor flag is on, a valid entry function name must be given

Returns

• int - If 0, the operation was successful and not successful otherwise.

Commands

Following are various commands to use with this tool.

Version

Prints the version of the underlying wasmedge library. All other commands and options are ignored when this command is run.

./WasmRunner version

Help

Prints the manual page in the console. When specified all the other options are ignored.

./WasmRunner -h

./WasmRunner --help

Run

Optional run command followed by a file path to a WebAssembly file.

./WasmRunner run <file_path> [args]

Without run

You can also execute WebAssembly files without the run command. In this case the command will be -

./WasmRunner [--reactor] <file_path> [entry_function_name] [args]

Reactor flag

When there are multiple funcitons exported by the given WebAssembly file, you can specify a entry function name to be executed. When using this flag, entry_function_name after file_path is required.

./WasmRunner --reactor <file_path> entry_function_name [args]

Errors

When something errorneous occurs, the tool fails with int code 1 (indicating error) and prints the error message to the CLI console. Here are few of those errors that may occur while running this tool -

Too few arguments

User passes smaller number of parameters than what actually is required by the exported WebAssembly function.

Entry function not found

When using with --reactor flag, if wrong entry function name (not actually exported) is given, this error message is printed on the console.

Entry function not given

When using with --reactor flag, if the user does not provide the entry function name at all after the file_path, this error message is printed.