|
| 1 | +## Language Agnostic Tooling |
| 2 | + |
| 3 | +[`wasm-tools`](https://github.com/bytecodealliance/wasm-tools) provides a suite of subcommands for |
| 4 | +working with WebAssembly modules and components. |
| 5 | + |
| 6 | +### WAT (WebAssembly Text Format) |
| 7 | + |
| 8 | +WAT (WebAssembly Text Format) is a text-based language |
| 9 | +that can be compiled to the WebAssembly binary format |
| 10 | +by `wasm-tools` and other tools. |
| 11 | +It's useful for writing small examples for testing and experimentation. |
| 12 | + |
| 13 | +Here's an example of a module expressed in WAT: |
| 14 | +```wat |
| 15 | +{{#include ../../examples/tutorial/wat/adder/add.wat}} |
| 16 | +``` |
| 17 | + |
| 18 | +The module contains two top-level declarations, a function and an export. |
| 19 | + |
| 20 | +The function declaration declares a function named `$add` |
| 21 | +with two arguments, `$lhs` and `$rhs`. |
| 22 | +(Variable names in WAT always start with a `$`.) |
| 23 | +Argument and result types need to be provided explicitly. |
| 24 | +In this case, the types of both arguments and the result |
| 25 | +are `i32` (32-bit integer). |
| 26 | +The body of the function is a list of WebAssembly instructions. |
| 27 | +The two `local.get` instructions push the values of `$lhs` and `$rhs` |
| 28 | +onto the stack. |
| 29 | +The `i32.add` instruction pops the two top values off the stack |
| 30 | +and adds them, leaving the result on the stack. |
| 31 | + |
| 32 | +The `export` declaration connects the function that was just declared |
| 33 | +to a name that should be used for calling it externally. |
| 34 | +We want to use this WAT code to implement the interface specified in a WIT file, |
| 35 | +so the external name has to follow a certain convention. |
| 36 | +The name `"docs:adder/add@0.1.0#add"` can be broken down as follows: |
| 37 | +* `docs` is the package name. |
| 38 | +* `adder` is the name of a world inside the `docs` package. |
| 39 | +* `add` is the name of an interface defined in that world. |
| 40 | +* 0.1.0 is a version number. |
| 41 | +* Separately, `add` is the name of a function defined in the `add` interface. |
| 42 | +All of these pieces come from the specific `.wit` file we are using |
| 43 | +(see below). |
| 44 | + |
| 45 | +There's much more than WAT can do; |
| 46 | +see the Mozilla Developer Network's [a detailed guide to WAT](https://developer.mozilla.org/en-US/docs/WebAssembly/Guides/Understanding_the_text_format) |
| 47 | +for more information. |
| 48 | + |
| 49 | +The [wat2wasm](https://github.com/WebAssembly/wabt) tool converts |
| 50 | +from WAT to the binary `.wasm` format, |
| 51 | +but it does not create components. |
| 52 | + |
| 53 | +### Building a Component from WAT with `wasm-tools` |
| 54 | + |
| 55 | +`wasm-tools` can be used to create a component from WAT. |
| 56 | +Here's how to create a component from WAT |
| 57 | +that implements the [`adder` world](https://github.com/bytecodealliance/component-docs/blob/main/component-model/examples/tutorial/wit/adder/world.wit) |
| 58 | +and simply adds two numbers. |
| 59 | + |
| 60 | +1. Install [`wasm-tools`](https://github.com/bytecodealliance/wasm-tools/tree/main#installation), a |
| 61 | + tool for low-level manipulation of Wasm modules and components. |
| 62 | + |
| 63 | +2. The `add` function is defined inside the following world. |
| 64 | + Create a file called `adder.wit` whose contents are as follows: |
| 65 | + |
| 66 | + ```wit |
| 67 | + {{#include ../../examples/tutorial/wit/adder/world.wit}} |
| 68 | + ``` |
| 69 | + |
| 70 | +3. Define an `add` core module in WAT that exports an `add` function that adds two parameters. |
| 71 | + Create a file called `add.wat` whose contents are as follows |
| 72 | + (the same as the example in the WAT section): |
| 73 | + |
| 74 | +```wat |
| 75 | +{{#include ../../examples/tutorial/wat/adder/add.wat}} |
| 76 | +``` |
| 77 | + |
| 78 | +4. Use `wasm-tools` to create a binary core module with component metadata embedded inside it: |
| 79 | + |
| 80 | + ```sh |
| 81 | + wasm-tools component embed adder.wit add.wat -o add.wasm |
| 82 | + ``` |
| 83 | + |
| 84 | +5. Use `wasm-tools` to create a new component `.wasm` file |
| 85 | + from the binary core module you just created: |
| 86 | + |
| 87 | + ```sh |
| 88 | + wasm-tools component new add.wasm -o add.component.wasm |
| 89 | + ``` |
| 90 | + |
| 91 | + The suffix `.component.wasm` is just a convention. |
| 92 | + You could also name the output file `add_component.wasm` or anything else |
| 93 | + with the `.wasm` suffix. |
| 94 | + |
| 95 | +### Running a Component with Wasmtime |
| 96 | + |
| 97 | +You can "run" a component by calling one of its exports. |
| 98 | +Hosts and runtimes often only support running components with certain exports. |
| 99 | + |
| 100 | +Using the [`wasmtime`](https://github.com/bytecodealliance/wasmtime) CLI, |
| 101 | +we can execute the `add` function in the component you just built, |
| 102 | +passing in arguments: |
| 103 | + |
| 104 | +```sh |
| 105 | +wasmtime run --invoke 'add(1, 2)' add.component.wasm |
| 106 | +``` |
| 107 | + |
| 108 | +The output is ```3```. |
| 109 | +You can try passing other arguments to `add()` |
| 110 | +by changing the arguments inside the parentheses. |
| 111 | + |
| 112 | +This example was tested with `wasmtime` 34.0.1. |
| 113 | +Earlier versions of `wasmtime` may not support the `--invoke` option. |
| 114 | +Any other compliant WebAssembly runtime that supports components |
| 115 | +can also run this component. |
0 commit comments