| 1 |
+++ |
| 2 |
title = "Specifications" |
| 3 |
+++ |
| 4 |
|
| 5 |
wazero understands that while no-one desired to create confusion, confusion |
| 6 |
exists both in what is a standard and what in practice is in fact a standard |
| 7 |
feature. To help with this, we created some guidance both on the status quo |
| 8 |
of WebAssembly portability and what we support. |
| 9 |
|
| 10 |
The WebAssembly Core Specification is the only specification relevant to |
| 11 |
wazero, governed by a standards body. Release [1.0][1] is a Web Standard (REC). |
| 12 |
Release [2.0][2] is a Working Draft (WD), so not yet a Web Standard. |
| 13 |
|
| 14 |
Many compilers implement system calls using the WebAssembly System Interface, |
| 15 |
[WASI][5]. WASI is a WebAssembly community [subgroup][3], but has not published |
| 16 |
any working drafts as a result of their work. WASI's last stable point was |
| 17 |
[wasi_snapshot_preview1][4], tagged at the end of 2020. |
| 18 |
|
| 19 |
While this seems scary, the confusion caused by pre-standard features is not as |
| 20 |
bad as it sounds. The WebAssembly ecosystem is generally responsive regardless |
| 21 |
of where things are written down and wazero provides tools, such as built-in |
| 22 |
support for WASI, to reduce pain. |
| 23 |
|
| 24 |
The goal of this section isn't to promote a W3C recommendation exclusive |
| 25 |
approach, rather to help you understand common language around portable |
| 26 |
features and which of those wazero supports at the moment. While we consider |
| 27 |
features formalized through W3C recommendation status mandatory, we actively |
| 28 |
pursue pre-standard features as well interop with commonly used infrastructure |
| 29 |
such as AssemblyScript. |
| 30 |
|
| 31 |
In summary, we hope this section can guide you in terms of what wazero supports |
| 32 |
as well as how to classify a request for a feature we don't yet support. |
| 33 |
|
| 34 |
### WebAssembly Core {#core} |
| 35 |
wazero conforms with tests defined alongside WebAssembly Core |
| 36 |
Specification [1.0][1] and [2.0][14]. |
| 37 |
|
| 38 |
By default, the runtime configuration enables features in WebAssembly Core |
| 39 |
Specification, despite it not yet being a Web Standard (REC). You can select |
| 40 |
version 1.0 like so: |
| 41 |
```go |
| 42 |
rConfig = wazero.NewRuntimeConfig().WithCoreFeatures(api.CoreFeaturesV1) |
| 43 |
``` |
| 44 |
|
| 45 |
One current limitation of wazero is that it doesn't implement the Text |
| 46 |
Format, e.g. compiling `.wat` files. Users can work around this using tools such as `wat2wasm` to |
| 47 |
compile the text format into the binary format. In practice, the text format is |
| 48 |
too low level for most users, so delays here have limited impact. |
| 49 |
|
| 50 |
#### Post 2.0 Features |
| 51 |
Features regardless of W3C release are inventoried in the [Proposals][10]. |
| 52 |
repository. wazero implements [Finished Proposals][11] based on user demand, |
| 53 |
using [wazero.RuntimeConfig][7] feature flags. As of late 2022, all finished |
| 54 |
proposals are included in [2.0][14] Working Draft. |
| 55 |
|
| 56 |
Features not yet assigned to a W3C release are not reliable. Encourage the |
| 57 |
[WebAssembly community][12] to formalize features you rely on, so that they |
| 58 |
become assigned to a release, and reach the W3C recommendation (REC) phase. |
| 59 |
|
| 60 |
### WebAssembly System Interface (WASI) {#wasi} |
| 61 |
|
| 62 |
Many compilers implement system calls using the WebAssembly System Interface, |
| 63 |
[WASI][5]. WASI is a WebAssembly community [subgroup][3], but has not published |
| 64 |
any working drafts as a result of their work. WASI's last stable point was |
| 65 |
[wasi_snapshot_preview1][4], tagged at the end of 2020. |
| 66 |
|
| 67 |
Some functions in this tag are used in practice while some others are not known |
| 68 |
to be used at all. Further confusion exists because some compilers, like |
| 69 |
GrainLang, import functions not used. Finally, some functions were added and |
| 70 |
removed after the git tag. For example, [`proc_raise`][13] was removed and |
| 71 |
[`sock_accept`][15] added. |
| 72 |
|
| 73 |
For all of these reasons, wazero will not implement all WASI features, just to |
| 74 |
complete the below chart. If you desire something not yet implemented, please |
| 75 |
[raise an issue](https://github.com/tetratelabs/wazero/issues/new) and include |
| 76 |
your use case (ex which language you are using to compile, a.k.a. target Wasm). |
| 77 |
|
| 78 |
Notes: |
| 79 |
* AssemblyScript has its own ABI which can optionally use [wasi-shim][17] |
| 80 |
* C (via clang) supports the maximum WASI functions due to [wasi-libc][16] |
| 81 |
* Rust supports WASI via its [wasm32-wasi][18] target. |
| 82 |
|
| 83 |
<details><summary>Click to see the full list of supported WASI functions</summary> |
| 84 |
<p> |
| 85 |
|
| 86 |
| Function | Status | Known Usage | |
| 87 |
|:------------------------|:------:|----------------:| |
| 88 |
| args_get | ✅ | TinyGo | |
| 89 |
| args_sizes_get | ✅ | TinyGo | |
| 90 |
| environ_get | ✅ | TinyGo | |
| 91 |
| environ_sizes_get | ✅ | TinyGo | |
| 92 |
| clock_res_get | ✅ | | |
| 93 |
| clock_time_get | ✅ | TinyGo | |
| 94 |
| fd_advise | 👷 | | |
| 95 |
| fd_allocate | ✅ | Rust | |
| 96 |
| fd_close | ✅ | TinyGo | |
| 97 |
| fd_datasync | ✅ | Rust | |
| 98 |
| fd_fdstat_get | ✅ | TinyGo | |
| 99 |
| fd_fdstat_set_flags | ✅ | Rust | |
| 100 |
| fd_fdstat_set_rights | 💀 | | |
| 101 |
| fd_filestat_get | ✅ | Zig | |
| 102 |
| fd_filestat_set_size | ✅ | Rust,Zig | |
| 103 |
| fd_filestat_set_times | ✅ | Rust,Zig | |
| 104 |
| fd_pread | ✅ | Zig | |
| 105 |
| fd_prestat_get | ✅ | Rust,TinyGo,Zig | |
| 106 |
| fd_prestat_dir_name | ✅ | Rust,TinyGo,Zig | |
| 107 |
| fd_pwrite | ✅ | Rust,Zig | |
| 108 |
| fd_read | ✅ | Rust,TinyGo,Zig | |
| 109 |
| fd_readdir | ✅ | Rust,Zig | |
| 110 |
| fd_renumber | ✅ | libc | |
| 111 |
| fd_seek | ✅ | TinyGo | |
| 112 |
| fd_sync | ✅ | Go | |
| 113 |
| fd_tell | ✅ | Rust | |
| 114 |
| fd_write | ✅ | Rust,TinyGo,Zig | |
| 115 |
| path_create_directory | ✅ | Rust,TinyGo,Zig | |
| 116 |
| path_filestat_get | ✅ | Rust,TinyGo,Zig | |
| 117 |
| path_filestat_set_times | ✅ | Rust,libc | |
| 118 |
| path_link | ✅ | Rust,Zig | |
| 119 |
| path_open | ✅ | Rust,TinyGo,Zig | |
| 120 |
| path_readlink | ✅ | Rust,Zig | |
| 121 |
| path_remove_directory | ✅ | Rust,TinyGo,Zig | |
| 122 |
| path_rename | ✅ | Rust,TinyGo,Zig | |
| 123 |
| path_symlink | ✅ | Rust,Zig | |
| 124 |
| path_unlink_file | ✅ | Rust,TinyGo,Zig | |
| 125 |
| poll_oneoff | ✅ | Rust,TinyGo,Zig | |
| 126 |
| proc_exit | ✅ | Rust,TinyGo,Zig | |
| 127 |
| proc_raise | 💀 | | |
| 128 |
| sched_yield | ✅ | Rust | |
| 129 |
| random_get | ✅ | Rust,TinyGo,Zig | |
| 130 |
| sock_accept | ✅ | Rust,Zig | |
| 131 |
| sock_recv | ✅ | Rust,Zig | |
| 132 |
| sock_send | ✅ | Rust,Zig | |
| 133 |
| sock_shutdown | ✅ | Rust,Zig | |
| 134 |
|
| 135 |
Note: 💀 means the function was later removed from WASI. |
| 136 |
|
| 137 |
</p> |
| 138 |
</details> |
| 139 |
|
| 140 |
[1]: https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/ |
| 141 |
[2]: https://www.w3.org/TR/2022/WD-wasm-core-2-20220419/ |
| 142 |
[3]: https://github.com/WebAssembly/meetings/blob/main/process/subgroups.md |
| 143 |
[4]: https://github.com/WebAssembly/WASI/blob/snapshot-01/phases/snapshot/docs.md |
| 144 |
[5]: https://github.com/WebAssembly/WASI |
| 145 |
[6]: https://github.com/WebAssembly/spec/tree/wg-1.0/test/core |
| 146 |
[7]: https://pkg.go.dev/github.com/tetratelabs/wazero#RuntimeConfig |
| 147 |
[9]: https://github.com/tetratelabs/wazero/issues/59 |
| 148 |
[10]: https://github.com/WebAssembly/proposals |
| 149 |
[11]: https://github.com/WebAssembly/proposals/blob/main/finished-proposals.md |
| 150 |
[12]: https://www.w3.org/community/webassembly/ |
| 151 |
[13]: https://github.com/WebAssembly/WASI/pull/136 |
| 152 |
[14]: https://github.com/WebAssembly/spec/tree/d39195773112a22b245ffbe864bab6d1182ccb06/test/core |
| 153 |
[15]: https://github.com/WebAssembly/WASI/pull/458 |
| 154 |
[16]: https://github.com/WebAssembly/wasi-libc |
| 155 |
[17]: https://github.com/AssemblyScript/wasi-shim |
| 156 |
[18]: https://github.com/rust-lang/rust/tree/1.68.0/library/std/src/sys/wasi |