github.com/wasilibs/wazerox@v0.0.0-20240124024944-4923be63ab5f/site/content/specs.md (about) 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