wa-lang.org/wazero@v1.0.2/README.md (about)

     1  # wazero: the zero dependency WebAssembly runtime for Go developers
     2  
     3  [![WebAssembly Core Specification Test](https://github.com/tetratelabs/wazero/actions/workflows/spectest.yaml/badge.svg)](https://github.com/tetratelabs/wazero/actions/workflows/spectest.yaml) [![Go Reference](https://pkg.go.dev/badge/github.com/tetratelabs/wazero.svg)](https://pkg.go.dev/github.com/tetratelabs/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). The
    19  most [basic example](examples/basic) extends a Go application with an addition
    20  function defined in WebAssembly.
    21  
    22  ## Deeper dive
    23  
    24  The former example is a pure function. While a good start, you probably are
    25  wondering how to do something more realistic, like read a file. WebAssembly
    26  Modules (Wasm) are sandboxed similar to containers. They can't read anything
    27  on your machine unless you explicitly allow it.
    28  
    29  The WebAssembly Core Specification is a standard, governed by W3C process, but
    30  it has no scope to specify how system resources like files are accessed.
    31  Instead, WebAssembly defines "host functions" and the signatures they can use.
    32  In wazero, "host functions" are written in Go, and let you do anything
    33  including access files. The main constraint is that WebAssembly only allows
    34  numeric types. wazero includes [imports](imports) for common languages and
    35  compiler toolchains.
    36  
    37  For example, you can grant WebAssembly code access to your console by exporting
    38  a function written in Go. The below function can be imported into standard
    39  WebAssembly as the module "env" and the function name "log_i32".
    40  ```go
    41  _, err := r.NewHostModuleBuilder("env").
    42  	ExportFunction("log_i32", func(v uint32) {
    43  		fmt.Println("log_i32 >>", v)
    44  	}).
    45  	Instantiate(ctx, r)
    46  if err != nil {
    47  	log.Panicln(err)
    48  }
    49  ```
    50  
    51  The WebAssembly community has [subgroups][4] which maintain work that may not
    52  result in a Web Standard. One such group is the WebAssembly System Interface
    53  ([WASI][5]), which defines functions similar to Go's [x/sys/unix][6].
    54  
    55  The [wasi_snapshot_preview1][13] tag of WASI is widely implemented, so wazero
    56  bundles an implementation. That way, you don't have to write these functions.
    57  
    58  For example, here's how you can allow WebAssembly modules to read
    59  "/work/home/a.txt" as "/a.txt" or "./a.txt" as well the system clock:
    60  ```go
    61  _, err := wasi_snapshot_preview1.Instantiate(ctx, r)
    62  if err != nil {
    63  	log.Panicln(err)
    64  }
    65  
    66  config := wazero.NewModuleConfig().
    67  	WithFS(os.DirFS("/work/home")). // instead of no file system
    68  	WithSysWalltime().WithSysNanotime() // instead of fake time
    69  
    70  module, err := r.InstantiateModule(ctx, compiled, config)
    71  ...
    72  ```
    73  
    74  While we hope this deeper dive was useful, we also provide [examples](examples)
    75  to elaborate each point. Please try these before raising usage questions as
    76  they may answer them for you!
    77  
    78  ## Runtime
    79  
    80  There are two runtime configurations supported in wazero: _Compiler_ is default:
    81  
    82  By default, ex `wazero.NewRuntime(ctx)`, the Compiler is used if supported. You
    83  can also force the interpreter like so:
    84  ```go
    85  r := wazero.NewRuntimeWithConfig(ctx, wazero.NewRuntimeConfigInterpreter())
    86  ```
    87  
    88  ### Interpreter
    89  Interpreter is a naive interpreter-based implementation of Wasm virtual
    90  machine. Its implementation doesn't have any platform (GOARCH, GOOS) specific
    91  code, therefore _interpreter_ can be used for any compilation target available
    92  for Go (such as `riscv64`).
    93  
    94  ### Compiler
    95  Compiler compiles WebAssembly modules into machine code ahead of time (AOT),
    96  during `Runtime.CompileModule`. This means your WebAssembly functions execute
    97  natively at runtime. Compiler is faster than Interpreter, often by order of
    98  magnitude (10x) or more. This is done without host-specific dependencies.
    99  
   100  If interested, check out the [RATIONALE.md][8] and help us optimize further!
   101  
   102  ### Conformance
   103  
   104  Both runtimes pass WebAssembly Core [1.0][7] and [2.0][14] specification tests
   105  on supported platforms:
   106  
   107  |   Runtime   |                 Usage                  | amd64 | arm64 | others |
   108  |:-----------:|:--------------------------------------:|:-----:|:-----:|:------:|
   109  | Interpreter | `wazero.NewRuntimeConfigInterpreter()` |   ✅   |   ✅   |   ✅    |
   110  |  Compiler   |  `wazero.NewRuntimeConfigCompiler()`   |   ✅   |   ✅   |   ❌    |
   111  
   112  ## Support Policy
   113  
   114  The below support policy focuses on compatability concerns of those embedding
   115  wazero into their Go applications.
   116  
   117  ### wazero
   118  
   119  wazero is an early project, so APIs are subject to change until version 1.0.
   120  To use wazero meanwhile, you need to use the latest pre-release like this:
   121  
   122  ```bash
   123  go get github.com/tetratelabs/wazero@latest
   124  ```
   125  
   126  wazero will tag a new pre-release at least once a month until 1.0. 1.0 is
   127  scheduled for Feb 2023, following the release of Go 1.20. wazero 1.0 will build
   128  with Go 1.18 and above per the below policy.
   129  
   130  Meanwhile, please practice the current APIs to ensure they work for you, and
   131  give us a [star][15] if you are enjoying it so far!
   132  
   133  ### Go
   134  
   135  wazero has no dependencies except Go, so the only source of conflict in your
   136  project's use of wazero is the Go version.
   137  
   138  wazero follows the same version policy as Go's [Release Policy][10]: two
   139  versions. wazero will ensure these versions work and bugs are valid if there's
   140  an issue with a current Go version.
   141  
   142  Additionally, wazero intentionally delays usage of language or standard library
   143  features one additional version. For example, when Go 1.29 is released, wazero
   144  can use language features or standard libraries added in 1.27. This is a
   145  convenience for embedders who have a slower version policy than Go. However,
   146  only supported Go versions may be used to raise support issues.
   147  
   148  ### Platform
   149  
   150  wazero has two runtime modes: Interpreter and Compiler. The only supported operating
   151  systems are ones we test, but that doesn't necessarily mean other operating
   152  system versions won't work.
   153  
   154  We currently test Linux (Ubuntu and scratch), MacOS and Windows as packaged by
   155  [GitHub Actions][11], as well FreeBSD via Vagrant/VirtualBox.
   156  
   157  * Interpreter
   158    * Linux is tested on amd64 (native) as well arm64 and riscv64 via emulation.
   159    * FreeBSD, MacOS and Windows are only tested on amd64.
   160  * Compiler
   161    * Linux is tested on amd64 (native) as well arm64 via emulation.
   162    * FreeBSD, MacOS and Windows are only tested on amd64.
   163  
   164  wazero has no dependencies and doesn't require CGO. This means it can also be
   165  embedded in an application that doesn't use an operating system. This is a main
   166  differentiator between wazero and alternatives.
   167  
   168  We verify zero dependencies by running tests in Docker's [scratch image][12].
   169  This approach ensures compatibility with any parent image.
   170  
   171  -----
   172  wazero is a registered trademark of Tetrate.io, Inc. in the United States and/or other countries
   173  
   174  [1]: https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/
   175  [2]: https://www.w3.org/TR/2022/WD-wasm-core-2-20220419/
   176  [4]: https://github.com/WebAssembly/meetings/blob/main/process/subgroups.md
   177  [5]: https://github.com/WebAssembly/WASI
   178  [6]: https://pkg.go.dev/golang.org/x/sys/unix
   179  [7]: https://github.com/WebAssembly/spec/tree/wg-1.0/test/core
   180  [8]: internal/engine/compiler/RATIONALE.md
   181  [9]: https://github.com/tetratelabs/wazero/issues/506
   182  [10]: https://go.dev/doc/devel/release
   183  [11]: https://github.com/actions/virtual-environments
   184  [12]: https://docs.docker.com/develop/develop-images/baseimages/#create-a-simple-parent-image-using-scratch
   185  [13]: https://github.com/WebAssembly/WASI/blob/snapshot-01/phases/snapshot/docs.md
   186  [14]: https://github.com/WebAssembly/spec/tree/d39195773112a22b245ffbe864bab6d1182ccb06/test/core
   187  [15]: https://github.com/tetratelabs/wazero/stargazers