wazero v1.0.0-pre.2

wazero v1.0.0-pre.2 adds a CLI, simplifies syntax and increases performance. This was the result of a lot of feedback and help and we are grateful for so much attention.

If you like what we are doing, please star our repo as folks appreciate it. As usual, you can expect another release next month end.

Also, don't forget to look at the increasing amount of projects using wazero. Regardless of whether a project is an experiment or a largely re-used tool, we're together moving Go forward in WebAssembly.

wazero CLI

We've had a number of requests for a CLI to run wasm, though no one ever raised an issue about it. The most recent request was from @dgryski and @anuraaga stepped up to implement the first cut.

For example, if you have a calculator, you can run it like this:

$ go run github.com/tetratelabs/wazero/cmd/wazero run testdata/cli.wasm 3 4
result: 7

You can also install as a binary like usual in go:

$ go install github.com/tetratelabs/wazero/cmd/wazero@latest
$ wazero run testdata/cli.wasm 3 4
result: 7

Notably, this also supports basic filesystem mounts in a way familiar to docker users.

$ wazero run -mount=/host/path:/ cat.wasm /test.txt
Hello world!

One limitation is that while you can read or modify existing files, adding new files is not yet supported. Watch this issue for updates, but we'll have this working by next release.

We also understand CLI users may want to discuss features on chat. Please join us on gophers slack #wazero to talk about this or anything else. Note: You may need an invite to join gophers.

Simplified syntax

@anuraaga noticed some improvements we could make in terms of simplicity, and a few of us including @inkeliz dug deeper to identify rarely used features which could be removed or hidden to improve developer experience. Here are a few diffs of interest:

Defaults to features in WebAssembly Core Specification 2.0 (DRAFT)

While compilers should be conservative when targeting WebAssembly Core features, runtimes should be lenient as otherwise people need to constantly turn on all features. Currently, most folks had to to turn on 2.0 features because compilers such as AssemblyScript and TinyGo use some of them by default. Call sites are simpler for most users as a result:

-	rc := wazero.NewRuntimeConfig().WithWasmCore2()
-	r := wazero.NewRuntimeWithConfig(ctx, rc)
+	r := wazero.NewRuntime(ctx)

Note: You can still customize whatever features you want like so

features := api.CoreFeaturesV2.SetEnabled(api.CoreFeatureMutableGlobal, false)
rConfig = wazero.NewRuntimeConfig().WithCoreFeatures(features)

MustInstantiate if all you do is panic on error

Folks setting up infrastructure layer code often know there is no source of conflict. For example, a module name conflict due to someone else adding WASI. Such call sites can now be simplified like so:

-	_, err := wasi_snapshot_preview1.Instantiate(ctx, wasm)
-	if err != nil {
-		panic(err)
-	}
+	wasi_snapshot_preview1.MustInstantiate(ctx, wasm)

ModuleBuilder is now HostModuleBuilder

The most common mistake we saw in practice was people exporting memory from host modules. This memory would never be used as host functions use the caller's memory. We removed the confusing APIs and renamed the type accordingly: host modules only define functions your guest (%.wasm) imports!

-	envBuilder := r.NewModuleBuilder("env")
+	envBuilder := r.NewHostModuleBuilder("env")

No more CompileConfig

We originally introduced CompileConfig to do transformations, and the first was memory limit in nature. Later, we introduced our experimental compilation cache, and noticed that this config was not only never used in open source, but also would make it hard to reason with cache invalidation. We moved relevant settings to RuntimeConfig and removed CompileConfig, which stopped this sort of boilerplate:

-	if m.compiled, err = r.CompileModule(ctx, guest, wazero.NewCompileConfig()); err != nil {
+	if m.compiled, err = r.CompileModule(ctx, guest); err != nil {

Note: You can still limit memory like so

// Ex. To reduce the largest possible memory size from 4GB to 128KB:
rConfig = wazero.NewRuntimeConfig().WithMemoryLimitPages(2)

Moreover, you can change the %.wasm binary if your defaults aren't correct, via compiler flags or in worst case manipulating it. If the compiler you use for WebAssembly cannot control max memory, consider raising an issue with them to make that possible.

Better performance

When compiling wasm into native code, we formerly had to check function call boundaries twice (value and call frame stacks). This resulted in inefficient performance for code that calls functions a lot. Thanks to a very focused week of effort from @mathetake, the wazero's calling convention is simplified and consolidated into one stack. While your performance may vary, the best case gains for Fibonacci were between 10 and 25% faster depending on architecture.