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
| Word | What it means |
|---|---|
| Composition | joining components so one supplies another's import |
| Instantiate | to make a running copy of a component |
| Linker | the part of a runtime that supplies imports |
| Satisfy | to supply an import with a matching export |
| Bindings | code 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
docker exec wasm wasmtime run --invoke 'double(21)' doubler.watShown 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
docker exec tools tail -4 app.watShown here, not run. Press Start lab to type it into your own lab’s terminal.
Run the composed component
docker exec wasm wasmtime run --invoke 'double(21)' app.watShown here, not run. Press Start lab to type it into your own lab’s terminal.
Worked example: what each component needs and gives
| Component | Imports | Exports | Runs alone? |
|---|---|---|---|
| calc.wat | nothing | demo:calc/[email protected] | Yes |
| doubler.wat | demo:calc/[email protected] | double | No, the import is missing |
| app.wat | nothing | double | Yes, 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
# 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.