About WebAssembly Examples
The Fermyon WebAssembly Language Guide tracks languages that can be executed within a WebAssembly runtime. We do our best to keep things consistent across pages. This page explains how we create our examples.
The Typical Example
Providing detailed language-specific examples is beyond the scope of the language guide. Instead, we try to provide the following pieces of relevant information:
- How to get the tools necessary to work with the language
- How to create a simple “Hello World” style program
- How to compile that program
- How to execute that program
Our canonical example is to build a simple web page that prints Hello, World
in plain text. In order to serve it as a web page, we try to write the script using one of two tools:
- Spin, a framework for building WebAssembly-based web applications and microservices.
- Wagi, used in older content from before Spin was released. All Wagi applications run on Spin (though you must use a
spin.toml
instead of amodules.toml
).
For command line examples, the example runs with wasmtime, which is committed to implementing the WASI specification.
Other runtimes and execution environments are out of the scope of this documentation. However, you may find links to examples in the Learn More section at the bottom of each language page
To that end, the simplest example, written in Swift, looks like this:
print("content-type: text/plain\n\n");
print("Hello, World\n");
When run on wasmtime
, it should produce output like this:
$ wasmtime hello.wasm
content-type: text/plain
Hello, World
When executed on Spin (or Wagi) and accessed via Curl, it should look like this:
$ curl localhost:3000
Hello, World
Libraries, SDKs, and Helpers
Generally, if there is a useful library, SDK, or helper, examples will use the best one. Many times, a language’s CGI library can be used with Wagi-style invocations on Spin or Wagi. Additionally, Spin has SDKs for a growing list of languages.
In the end, though, every Wagi executor (on Spin) uses the same CGI-like mechanism to read a request and write a response.
Spin Configuration
Newer examples use a spin.toml
to show how the program is executed with Spin. The generic spin.toml
looks something like this:
spin_manifest_version = 2
[application]
name = "spin-hello"
version = "0.1.0"
authors = ["Fermyon Engineering <engineering@fermyon.com>"]
description = "Hello world app."
[[trigger.http]]
route = "/..."
component = "spin-hello"
[component.spin-hello]
source = "target/wasm32-wasi/release/spin_hello.wasm"
allowed_outbound_hosts = []
[component.spin-hello.build]
command = "cargo build --target wasm32-wasi --release"
watch = ["src/**/*.rs", "Cargo.toml"]
The format and fields are defined in the official Spin configuration docs.
The command to build and start a Spin application is spin build --up
. This will typically start a server on http://localhost:3000
unless you specify otherwise.
Wagi Configuration
Older examples us Wagi instead of Spin. They may provide examples that use a modules.toml
file instead of a spin.toml
file. A simple example looks like this:
[[module]]
module = "hello.wasm"
route = "/"
Then we start wagi
with wagi -c modules.toml
.
If you are interested in contributing to this guide, head on over to the GitHub repo.