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