wasmer/lib/c-api

wasmer-c-api

Wasmer is the most popular WebAssembly runtime for Rust (...and also the fastest!). It supports JIT (Just in Time) and AOT (Ahead of time) compilation as well as pluggable compilers suited to your needs.

It's designed to be safe and secure, and runnable in any kind of environment.

This crate exposes a C and a C++ API for the Wasmer runtime. It also fully supports the wasm-c-api common API.

Usage

The shared object files and the headers will be automatically available inside the Wasmer installed path.

Please check the following docs to see how to install Wasmer in your system.

The C (wasmer.h) and C++ (wasmer.hh) header files can be found in the Wasmer include directory:

wasmer config --includedir

The runtime shared libraries (.so, .dylib, .dll) can be found in the Wasmer lib directory:

wasmer config --libdir

Note: You can also download the libraries or header files directly from Wasmer release page.

The full C API documentation can be found here: https://wasmerio.github.io/wasmer/c-api/

Here is a simple example to use the C API:

#include <stdio.h>
#include "../wasmer.h"
#include <assert.h>
#include <stdint.h>

int main()
{
    // Read the Wasm file bytes.
    FILE *file = fopen("sum.wasm", "r");
    fseek(file, 0, SEEK_END);
    long len = ftell(file);
    uint8_t *bytes = malloc(len);
    fseek(file, 0, SEEK_SET);
    fread(bytes, 1, len, file);
    fclose(file);

    // Prepare the imports.
    wasmer_import_t imports[] = {};

    // Instantiate!
    wasmer_instance_t *instance = NULL;
    wasmer_result_t instantiation_result = wasmer_instantiate(&instance, bytes, len, imports, 0);

    assert(instantiation_result == WASMER_OK);

    // Let's call a function.
    // Start by preparing the arguments.

    // Value of argument #1 is `7i32`.
    wasmer_value_t argument_one;
    argument_one.tag = WASM_I32;
    argument_one.value.I32 = 7;

    // Value of argument #2 is `8i32`.
    wasmer_value_t argument_two;
    argument_two.tag = WASM_I32;
    argument_two.value.I32 = 8;

    // Prepare the arguments.
    wasmer_value_t arguments[] = {argument_one, argument_two};

    // Prepare the return value.
    wasmer_value_t result_one;
    wasmer_value_t results[] = {result_one};

    // Call the `sum` function with the prepared arguments and the return value.
    wasmer_result_t call_result = wasmer_instance_call(instance, "sum", arguments, 2, results, 1);

    // Let's display the result.
    printf("Call result:  %d\n", call_result);
    printf("Result: %d\n", results[0].value.I32);

    // `sum(7, 8) == 15`.
    assert(results[0].value.I32 == 15);
    assert(call_result == WASMER_OK);

    wasmer_instance_destroy(instance);

    return 0;
}

Testing

Tests are run using the release build of the library. If you make changes or compile with non-default features, please ensure you rebuild in release mode for the tests to see the changes.

The tests can be run via cargo test, such as:

$ cargo test --release -- --nocapture

To run tests manually, enter the lib/c-api/tests directory and run the following commands:

$ cmake .
$ make
$ make test

pkg-config

The Wasmer binary ships with an utility tool that outputs config in the pkg-config format.

You can use it like:

wasmer config --pkg-config > $PKG_CONFIG_PATH/wasmer.pc

License

Wasmer is primarily distributed under the terms of the MIT license (LICENSE).