Imports & exports

Search…
🔁
Imports & exports
A Wasm module can import and export entities, like functions, memories, globals and tables. This example illustrates the basics of using these entities.
In this example we'll be using a sample Wasm module which exports some entities and requires us to also import some of them.
The goal here is to give you an idea of how to work with imports and exports. We won't go into the details of each entity, they'll be covered in more details in the other examples.
First we are going to want to initialize a new project. To do this we can navigate to our project folder, or create one. In this example, we will create a new project. Lets create it and navigate to it:
Rust
Go
Python
C/C++
The final Rust code for this example can be found on Github: imports_exports.rs.
Please take a look at the setup steps for Rust.
1
cargo new imports-exports
2
cd imports-exports
Copied!
We have to modify Cargo.toml to add the Wasmer dependencies as shown below:
1
[dependencies]
2
# The Wasmer API
3
wasmer = "2.0"
Copied!
The final Go code for this example can be found on Github: imports_exports.go.
Please take a look at the setup steps for Go.
1
mkdir wasmer-example-imports-exports
2
cd wasmer-example-imports-exports
3
go mod init github.com/$USER/wasmer-example-imports-exports
Copied!
The final Python code for this example can be found on Github: imports_exports.py.
Please take a look at the setup steps for Python.
1
mkdir wasmer-example-imports-exports
2
cd wasmer-example-imports-exports
3
pip install wasmer wasmer_compiler_cranelift
Copied!
The final C code for this example can be found on Github: imports-exports.c.
Please take a look at the setup steps for C/C++.
1
mkdir wasmer-example-imports-exports
2
cd wasmer-example-imports-exports
3
vim Makefile
Copied!
Let's create a simple Makefile:
1
CFLAGS = -g -I$(shell $(WASMER_DIR)/bin/wasmer config --includedir)
2
LDFLAGS = -Wl,-rpath,$(shell $(WASMER_DIR)/bin/wasmer config --libdir)
3
LDLIBS = $(shell $(WASMER_DIR)/bin/wasmer config --libs)
4
​
5
.SILENT: imports-exports imports-exports.o
6
imports-exports: imports-exports.o
7
​
8
.PHONY: clean
9
.SILENT: clean
10
clean:
11
    rm -f imports-exports.o imports-exports
Copied!
Now that we have everything set up, let's go ahead and try it out!
Declaring imports
When a Wasm modules declares imports you will have to make them available before you can instantiate the module. Our first task will be to create the required entities.
The module we are using needs two imports:
A function named host_function in a namespace with an empty name;
A global named host_global in the env namespace.
Let's create the import object:
Rust
Go
Python
C/C++
1
let import_object = imports! {
2
    "" => {
3
        "host_function" => host_function,
4
    },
5
    "env" => {
6
        "host_global" => host_global,
7
    },
8
};
Copied!
1
importObject := wasmer.NewImportObject()
2
​
3
importObject.Register(
4
    "",
5
    map[string]wasmer.IntoExtern{
6
        "host_function": hostFunction,
7
    },
8
)
9
​
10
importObject.Register(
11
    "env",
12
    map[string]wasmer.IntoExtern{
13
        "host_global":   hostGlobal,
14
    },
15
)
Copied!
1
import_object = ImportObject()
2
import_object.register(
3
    "",
4
    {
5
        "host_function": host_function,
6
    }
7
)
8
import_object.register(
9
    "env",
10
    {
11
        "host_global": host_global,
12
    }
13
)
Copied!
1
wasm_functype_t* host_func_type = wasm_functype_new_0_1(wasm_valtype_new_i32());
2
wasm_func_t* host_func = wasm_func_new(store, host_func_type, host_func_callback);
3
wasm_functype_delete(host_func_type);
4
​
5
wasm_globaltype_t* host_global_type = wasm_globaltype_new(wasm_valtype_new(WASM_F32), WASM_CONST);
6
wasm_val_t host_global_val = WASM_I32_VAL(42);
7
wasm_global_t* host_global = wasm_global_new(store, host_global_type, &host_global_val);
8
wasm_globaltype_delete(host_global_type);
9
​
10
wasm_extern_t* externs[] = {
11
  wasm_func_as_extern(host_func),
12
  wasm_global_as_extern(host_global)
13
};
14
​
15
wasm_extern_vec_t import_object = WASM_ARRAY_VEC(externs);
Copied!
Now that we have our import object ready, we'll need to use it when instantiating the module:
Rust
Go
Python
C/C++
1
let instance = Instance::new(&module, &import_object)?;
Copied!
1
instance, err := wasmer.NewInstance(module, importObject)
Copied!
1
instance = Instance(module, import_object)
Copied!
1
wasm_instance_t* instance = wasm_instance_new(store, module, &import_object, NULL);
Copied!
That's it! Easy right?
We did not go into the details of how to create the imported entities, we encourage you to read other examples to know more about this:
↩️ Exposing host (imported) functions
Fetching exports
Let's have a look at our module again: it exports some entities for us in our host program:
A function named guest_function;
A global name guest_global;
A table name guest_table;
A memory named guest_memory.
To get these entities we'll use the exports API:
Rust
Go
Python
C/C++
1
let function = instance.exports.get::<Function>("guest_function")?;
2
​
3
let global = instance.exports.get::<Global>("guest_global")?;
4
​
5
let memory = instance.exports.get::<Memory>("guest_memory")?;
6
​
7
let table = instance.exports.get::<Table>("guest_table")?;
Copied!
1
function, err := instance.Exports.GetFunction("guest_function")
2
if err != nil {
3
  panic(fmt.Sprintln("Failed to get the exported function:", err))
4
}
5
​
6
global, err := instance.Exports.GetGlobal("guest_global")
7
if err != nil {
8
    panic(fmt.Sprintln("Failed to get the exported global:", err))
9
}
10
​
11
table, err := instance.Exports.GetTable("guest_table")
12
if err != nil {
13
    panic(fmt.Sprintln("Failed to get the exported table:", err))
14
}
15
​
16
memory, err := instance.Exports.GetMemory("guest_memory")
17
if err != nil {
18
    panic(fmt.Sprintln("Failed to get the exported memory:", err))
19
}
Copied!
1
function = instance.exports.guest_function
2
global = instance.exports.guest_global
3
memory = instance.exports.guest_memory
4
table = instance.exports.guest_table
Copied!
1
wasm_func_t* func = wasm_extern_as_func(exports.data[0]);
2
if (func == NULL) {
3
    printf("> Failed to get the exported function!\n");
4
​
5
    return 1;
6
}
7
​
8
wasm_global_t* global = wasm_extern_as_global(exports.data[1]);
9
if (global == NULL) {
10
    printf("> Failed to get the exported global!\n");
11
​
12
    return 1;
13
}
14
​
15
wasm_table_t* table = wasm_extern_as_table(exports.data[2]);
16
if (table == NULL) {
17
    printf("> Failed to get the exported table!\n");
18
​
19
    return 1;
20
}
21
​
22
wasm_memory_t* memory = wasm_extern_as_memory(exports.data[3]);
23
if (memory == NULL) {
24
    printf("> Failed to get the exported memory!\n");
25
​
26
    return 1;
27
}
Copied!
Again, we'll not cover how to use these entities here as this is the topic of other, more detailed, examples:
↪️ Calling guest (exported) functions
↩️ Exposing host (imported) functions
✏️ Using guest (exported) globals
💾
Interacting with memory
Running
We now have everything we need to run the Wasm module, let's do it!
Rust
Go
Python
C/C++
You should be able to run it using the cargo run command. The output should look like this:
1
Compiling module...
2
Creating the imported function...
3
Creating the imported global...
4
Instantiating module...
5
Getting the exported function...
6
Got exported function of type: FunctionType { params: [], results: [I32] }
7
Getting the exported global...
8
Got exported global of type: GlobalType { ty: I32, mutability: Const }
9
Getting the exported memory...
10
Got exported memory of type: MemoryType { minimum: 1 pages, maximum: None, shared: false }
11
Getting the exported table...
12
Got exported table of type: TableType { ty: FuncRef, minimum: 1, maximum: Some(1) }
Copied!
If you want to run the examples from the Wasmer repository codebase directly, you can also do:
1
git clone https://github.com/wasmerio/wasmer.git
2
cd wasmer
3
cargo run --example imports-exports --release --features "cranelift"
Copied!
You should be able to run it using the go run main.go command. The output should look like this:
1
Compiling module...
2
Creating the imported function...
3
Creating the imported global...
4
Instantiating module...
5
Getting the exported function...
6
Got the exported function: func(...interface {}) (interface {}, error)
7
Getting the exported global...
8
Got the exported global: *wasmer.Global
9
Getting the exported memory...
10
Got the exported memory: *wasmer.Memory
11
Getting the exported table...
12
Got the exported table: *wasmer.Table
Copied!
If you want to run the examples from the Wasmer repository codebase directly, you can also do:
1
git clone https://github.com/wasmerio/wasmer-go.git
2
cd wasmer-go
3
go test examples/example_imports_exports_test.go
Copied!
You should be able to run it using the python imports_exports.py command.
If you want to run the examples from the Wasmer repository codebase directly, you can also do:
1
git clone https://github.com/wasmerio/wasmer-python.git
2
cd wasmer-python
3
python examples/imports_exports.py
Copied!
You should be able to run it using the make clean imports-exports && ./imports-exports command. The output should look like this:
1
Creating the store...
2
Compiling module...
3
Creating the imported function...
4
Creating the imported global...
5
Instantiating module...
6
Retrieving exports...
7
Retrieving the exported function...
8
Got the exported function: 0x7f9317e05e00
9
Retrieving the exported global...
10
Got the exported global: 0x7f9317e05e90
11
Retrieving the exported table...
12
Got the exported table: 0x7f9317e05ec0
13
Retrieving the exported memory...
14
Got the exported memory: 0x7f9317e05ef0
Copied!
If you want to run the examples from the Wasmer repository codebase directly, you can also do:
1
git clone https://github.com/wasmerio/wasmer.git
2
cd wasmer/lib/c-api/examples/imports-exports.c
3
make clean imports-exports
4
./imports-exports
Copied!
⭐️ Instantiating a Wasm module
↪️ Calling guest (exported) functions
Last modified 6mo ago
Copy link
Contents
Declaring imports
Fetching exports
Running