Easier to read with cream paper, a tint, more contrast or larger text? Choose your colours and text, once, for every page.

Free lesson

Composing WebAssembly components

After this lesson: I can explain how two components are composed by matching an import to an export.

60 min lesson3 commandsWebAssembly lab: Wasmtime, WASI capabilities, WIT components and plugin limits

Two parts, one program, any languages

Composing WebAssembly components means plugging one component's export into another's import, so that the two become a single component. The parts can be written in different languages, because they meet only at a WIT interface.

Today you watch an import fail, then compose two components and run the result.

By the end of this lesson

Note

I can explain how two components are composed by matching an import to an export.

Key words

WordWhat it means
Compositionjoining components so one supplies another's import
Instantiateto make a running copy of a component
Linkerthe part of a runtime that supplies imports
Satisfyto supply an import with a matching export
Bindingscode generated from WIT for one language

The cells students fill in are left blank in this preview.

An import nobody supplies stops everything

doubler.wat is in the world doubler. It imports demo:calc/[email protected] and uses its add to double a number.

Run it on its own and Wasmtime refuses before any code runs. Its linker looked for that interface, found nothing, and named the missing import. A host checks every import first, which is why a component cannot reach anything it was not given.

Run doubler with nothing to plug in

Command
docker exec wasm wasmtime run --invoke 'double(21)' doubler.wat

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Composition plugs an export into an import

app.wat holds both components. It makes calc first, then makes doubler with calc's demo:calc/[email protected] plugged into the import of the same name. It exports double.

The result imports nothing at all, so Wasmtime can run it on its own. Tools such as wac do the same job with two .wasm files and write one new component.

Read the lines that compose them

Command
docker exec tools tail -4 app.wat

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Run the composed component

Command
docker exec wasm wasmtime run --invoke 'double(21)' app.wat

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Worked example: what each component needs and gives

ComponentImportsExportsRuns alone?
calc.watnothingdemo:calc/[email protected]Yes
doubler.watdemo:calc/[email protected]doubleNo, the import is missing
app.watnothingdoubleYes, it printed 42

The cells students fill in are left blank in this preview.

How other languages make components

A real project writes each part in its own language. wit-bindgen turns a WIT file into bindings for Rust, C and others, and cargo-component builds Rust into a component. componentize-py does it for Python, and jco for JavaScript.

None of these toolchains is in the lab, which downloads nothing. So the components here are written by hand, and the bytes they make are the same kind.

A common mistake

Warning

Many people think composing joins the source code and compiles it again. It joins components that are already built. Each keeps its own memory, and values cross only through the interface, so a Python part cannot reach into a Rust part's data.

Try it: a linker that matches names

Code: python
# What each component gives, by interface name.
exports = {
    "demo:calc/[email protected]": "calc",
}

# What doubler needs before it can start.
needs = ["demo:calc/[email protected]", "wasi:cli/[email protected]"]

for name in needs:
    if name in exports:
        print("plug in", name, "from", exports[name])
    else:
        print("missing", name, ": nothing gives it")
# Add "wasi:cli/[email protected]": "host" to exports and run again.

About this lab and its source: WebAssembly lab: Wasmtime, WASI capabilities, WIT components and plugin limits

Teaching a class? Set this module for your students with a teacher guide, marked assignments and a lab for every student.