github.com/bananabytelabs/wazero@v0.0.0-20240105073314-54b22a776da8/README.md (about) 1 # wazero: the zero dependency WebAssembly runtime for Go developers 2 3 [![WebAssembly Core Specification Test](https://github.com/bananabytelabs/wazero/actions/workflows/spectest.yaml/badge.svg)](https://github.com/bananabytelabs/wazero/actions/workflows/spectest.yaml) [![Go Reference](https://pkg.go.dev/badge/github.com/bananabytelabs/wazero.svg)](https://pkg.go.dev/github.com/bananabytelabs/wazero) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) 4 5 WebAssembly is a way to safely run code compiled in other languages. Runtimes 6 execute WebAssembly Modules (Wasm), which are most often binaries with a `.wasm` 7 extension. 8 9 wazero is a WebAssembly Core Specification [1.0][1] and [2.0][2] compliant 10 runtime written in Go. It has *zero dependencies*, and doesn't rely on CGO. 11 This means you can run applications in other languages and still keep cross 12 compilation. 13 14 Import wazero and extend your Go application with code written in any language! 15 16 ## Example 17 18 The best way to learn wazero is by trying one of our [examples](examples/README.md). The 19 most [basic example](examples/basic) extends a Go application with an addition 20 function defined in WebAssembly. 21 22 ## Runtime 23 24 There are two runtime configurations supported in wazero: _Compiler_ is default: 25 26 By default, ex `wazero.NewRuntime(ctx)`, the Compiler is used if supported. You 27 can also force the interpreter like so: 28 ```go 29 r := wazero.NewRuntimeWithConfig(ctx, wazero.NewRuntimeConfigInterpreter()) 30 ``` 31 32 ### Interpreter 33 Interpreter is a naive interpreter-based implementation of Wasm virtual 34 machine. Its implementation doesn't have any platform (GOARCH, GOOS) specific 35 code, therefore _interpreter_ can be used for any compilation target available 36 for Go (such as `riscv64`). 37 38 ### Compiler 39 Compiler compiles WebAssembly modules into machine code ahead of time (AOT), 40 during `Runtime.CompileModule`. This means your WebAssembly functions execute 41 natively at runtime. Compiler is faster than Interpreter, often by order of 42 magnitude (10x) or more. This is done without host-specific dependencies. 43 44 If interested, check out the [RATIONALE.md][8] and help us optimize further! 45 46 ### Conformance 47 48 Both runtimes pass WebAssembly Core [1.0][7] and [2.0][14] specification tests 49 on supported platforms: 50 51 | Runtime | Usage | amd64 | arm64 | others | 52 |:-----------:|:--------------------------------------:|:-----:|:-----:|:------:| 53 | Interpreter | `wazero.NewRuntimeConfigInterpreter()` | ✅ | ✅ | ✅ | 54 | Compiler | `wazero.NewRuntimeConfigCompiler()` | ✅ | ✅ | ❌ | 55 56 ## Support Policy 57 58 The below support policy focuses on compatability concerns of those embedding 59 wazero into their Go applications. 60 61 ### wazero 62 63 wazero's [1.0 release][15] happened in March 2023, and is [in use][16] by many 64 projects and production sites. 65 66 We offer an API stability promise with semantic versioning. In other words, we 67 promise to not break any exported function signature without incrementing the 68 major version. This does not mean no innovation: New features and behaviors 69 happen with a minor version increment, e.g. 1.0.11 to 1.2.0. We also fix bugs 70 or change internal details with a patch version, e.g. 1.0.0 to 1.0.1. 71 72 You can get the latest version of wazero like this. 73 ```bash 74 go get github.com/bananabytelabs/wazero@latest 75 ``` 76 77 Please give us a [star][17] if you end up using wazero! 78 79 ### Go 80 81 wazero has no dependencies except Go, so the only source of conflict in your 82 project's use of wazero is the Go version. 83 84 wazero follows the same version policy as Go's [Release Policy][10]: two 85 versions. wazero will ensure these versions work and bugs are valid if there's 86 an issue with a current Go version. 87 88 Additionally, wazero intentionally delays usage of language or standard library 89 features one additional version. For example, when Go 1.29 is released, wazero 90 can use language features or standard libraries added in 1.27. This is a 91 convenience for embedders who have a slower version policy than Go. However, 92 only supported Go versions may be used to raise support issues. 93 94 ### Platform 95 96 wazero has two runtime modes: Interpreter and Compiler. The only supported operating 97 systems are ones we test, but that doesn't necessarily mean other operating 98 system versions won't work. 99 100 We currently test Linux (Ubuntu and scratch), MacOS and Windows as packaged by 101 [GitHub Actions][11], as well compilation of 32-bit Linux and 64-bit FreeBSD. 102 103 * Interpreter 104 * Linux is tested on amd64 (native) as well arm64 and riscv64 via emulation. 105 * MacOS and Windows are only tested on amd64. 106 * Compiler 107 * Linux is tested on amd64 (native) as well arm64 via emulation. 108 * MacOS and Windows are only tested on amd64. 109 110 wazero has no dependencies and doesn't require CGO. This means it can also be 111 embedded in an application that doesn't use an operating system. This is a main 112 differentiator between wazero and alternatives. 113 114 We verify zero dependencies by running tests in Docker's [scratch image][12]. 115 This approach ensures compatibility with any parent image. 116 117 ----- 118 wazero is a registered trademark of Tetrate.io, Inc. in the United States and/or other countries 119 120 [1]: https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/ 121 [2]: https://www.w3.org/TR/2022/WD-wasm-core-2-20220419/ 122 [4]: https://github.com/WebAssembly/meetings/blob/main/process/subgroups.md 123 [5]: https://github.com/WebAssembly/WASI 124 [6]: https://pkg.go.dev/golang.org/x/sys/unix 125 [7]: https://github.com/WebAssembly/spec/tree/wg-1.0/test/core 126 [8]: internal/engine/compiler/RATIONALE.md 127 [9]: https://github.com/bananabytelabs/wazero/issues/506 128 [10]: https://go.dev/doc/devel/release 129 [11]: https://github.com/actions/virtual-environments 130 [12]: https://docs.docker.com/develop/develop-images/baseimages/#create-a-simple-parent-image-using-scratch 131 [13]: https://github.com/WebAssembly/WASI/blob/snapshot-01/phases/snapshot/docs.md 132 [14]: https://github.com/WebAssembly/spec/tree/d39195773112a22b245ffbe864bab6d1182ccb06/test/core 133 [15]: https://tetrate.io/blog/introducing-wazero-from-tetrate/ 134 [16]: https://wazero.io/community/users/ 135 [17]: https://github.com/bananabytelabs/wazero/stargazers