Build

Changing in 1.0+

The term "actor" is deprecated. wasmCloud 1.0 and later simply refer to this entity as a component, reflecting wasmCloud's standardization around WebAssembly components. You can learn more here.

The wash CLI includes a build command that is used to build all actor components. The wash build CLI reference page has more information on each of the command's flags. The rest of this page will focus on practical examples of using the wash build command.

You can see the list of supported languages in the wasmcloud.toml specification. At the time of writing this guide, this included Rust and TinyGo. If a language is supported in the wasmcloud.toml specification, then you can build it simply with:

bash

wash build

Rust

In a Rust project, the wash build command encapsulates a few commands. You can always use the standard Rust toolchain and Bytecode Alliance tools to build your actor components. However, the wash build command will automatically use the necessary tools and build your actor component for you. Under the hood, the wash build command will run the following commands:

bash

# Build the Wasm module
cargo build --release --target wasm32-wasi
# Create a Wasm component from the Wasm module by using the wasmtime adapter
wasm-tools component new ./target/wasm32-wasi/release/module.wasm -o ./build/component.wasm --adapt ./wasi_snapshot_preview1.wasm
# Sign the Wasm component with your generated keys, using information in wasmcloud.toml
wash claims sign ./build/component.wasm --destination ./build/component_s.wasm

TinyGo

In a TinyGo project, the wash build command encapsulates a few commands. You can always use the standard Go and TinyGo toolchain and Bytecode Alliance tools to build your actor components. However, the wash build command will automatically use the necessary tools and build your actor component for you. Under the hood, the wash build command will run the following commands:

bash

# Generate the types and bindings for the Wasm module
go generate
# Build the Wasm module
tinygo build -o ./build/module.wasm -target wasm32-wasi -scheduler none -no-debug .
# Embed the component wit metadata into the module
wasm-tools component embed wit ./build/module.wasm > ./build/embed.wasm
# Create a Wasm component from the embedded Wasm module by using the wasmtime adapter
wasm-tools component new ./build/embed.wasm -o ./build/component.wasm --adapt ./wasi_snapshot_preview1.wasm
# Sign the Wasm component with your generated keys, using information in wasmcloud.toml
wash claims sign ./build/component.wasm --destination ./build/component_s.wasm
# Remove temporarily created files
rm ./build/embed.wasm ./build/module.wasm

TypeScript

In a TypeScript project, the wash build command must be overridden in the wasmcloud.toml actor section to use external tools. TypeScript builds require an npm installation and, after running npm install, use ComponentizeJS to compile transpiled JavaScript code into a WebAssembly Component.

toml

[actor]
build_command = "npm run build"

In our quickstart example, wash build runs a few commands for you in order to turn TypeScript code into a WebAssembly component:

bash

# You must run `npm install` first
npm install
# Transpile TypeScript code to JavaScript
tsc
# Componentize JavaScript code
jco componentize -w wit -o dist/index.wasm dist/index.js
# Sign the Wasm component with your generated keys, using information in wasmcloud.toml
wash build --sign-only --config-path wasmcloud.toml

Python

In a Python project, the wash build command must be overridden in the wasmcloud.toml actor section to use external tools. Python builds require a Python, pip installation and a componentize-py to compile Python code into a WebAssembly Component.

toml

[actor]
build_command = "componentize-py -d ./wit -w hello componentize app -o build/http_hello_world.wasm"

In our quickstart example, wash build runs a few commands for you in order to turn Python code into a WebAssembly component:

bash

# Componentize Python code into a WebAssembly Component
componentize-py -d ./wit -w hello componentize app -o build/http_hello_world.wasm
# Sign the Wasm component with your generated keys, using information in wasmcloud.toml
wash build --sign-only --config-path wasmcloud.toml

My Language Isn't Listed

wash build has an escape hatch in the wasmcloud.toml specification which will let you specify your own build command for languages that we don't have official support for. For example, following the ComponentizeJS example to build a JavaScript Component, you can set up your wasmcloud.toml file like so:

toml

name = "componentize-js"
language = "rust"
type = "component"

[component]
build_command = "node componentize.mjs"
build_artifact = "hello.component.wasm"
destination = "hello_s.component.wasm"

Overriding the build_command allows you to use an external script or command to build the actor, then specifying where the build_artifact is (wherever the component should be after the build command completes) lets wash still sign the actor using your generated keys and information in the wasmcloud.toml file. Note that this command does not have full support for environment variables or multiple commands and should be in the form of "command arg1 arg2 arg...". It's recommended to use an external script to handle more complex build commands.