...

Text file src/github.com/tetratelabs/wazero/site/content/specs.md

Documentation: github.com/tetratelabs/wazero/site/content

     1+++
     2title = "Specifications"
     3+++
     4
     5wazero understands that while no-one desired to create confusion, confusion
     6exists both in what is a standard and what in practice is in fact a standard
     7feature. To help with this, we created some guidance both on the status quo
     8of WebAssembly portability and what we support.
     9
    10The WebAssembly Core Specification is the only specification relevant to
    11wazero, governed by a standards body. Release [1.0][1] is a Web Standard (REC).
    12Release [2.0][2] is a Working Draft (WD), so not yet a Web Standard.
    13
    14Many compilers implement system calls using the WebAssembly System Interface,
    15[WASI][5]. WASI is a WebAssembly community [subgroup][3], but has not published
    16any 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
    19While this seems scary, the confusion caused by pre-standard features is not as
    20bad as it sounds. The WebAssembly ecosystem is generally responsive regardless
    21of where things are written down and wazero provides tools, such as built-in
    22support for WASI, to reduce pain.
    23
    24The goal of this section isn't to promote a W3C recommendation exclusive
    25approach, rather to help you understand common language around portable
    26features and which of those wazero supports at the moment. While we consider
    27features formalized through W3C recommendation status mandatory, we actively
    28pursue pre-standard features as well interop with commonly used infrastructure
    29such as AssemblyScript.
    30
    31In summary, we hope this section can guide you in terms of what wazero supports
    32as well as how to classify a request for a feature we don't yet support.
    33
    34### WebAssembly Core {#core}
    35wazero conforms with tests defined alongside WebAssembly Core
    36Specification [1.0][1] and [2.0][14].
    37
    38By default, the runtime configuration enables features in WebAssembly Core
    39Specification, despite it not yet being a Web Standard (REC). You can select
    40version 1.0 like so:
    41```go
    42rConfig = wazero.NewRuntimeConfig().WithCoreFeatures(api.CoreFeaturesV1)
    43```
    44
    45One current limitation of wazero is that it doesn't implement the Text
    46Format, e.g. compiling `.wat` files. Users can work around this using tools such as `wat2wasm` to
    47compile the text format into the binary format. In practice, the text format is
    48too low level for most users, so delays here have limited impact.
    49
    50#### Post 2.0 Features
    51Features regardless of W3C release are inventoried in the [Proposals][10].
    52repository. wazero implements [Finished Proposals][11] based on user demand,
    53using [wazero.RuntimeConfig][7] feature flags. As of late 2022, all finished
    54proposals are included in [2.0][14] Working Draft.
    55
    56Features 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
    58become assigned to a release, and reach the W3C recommendation (REC) phase.
    59
    60### WebAssembly System Interface (WASI) {#wasi}
    61
    62Many compilers implement system calls using the WebAssembly System Interface,
    63[WASI][5]. WASI is a WebAssembly community [subgroup][3], but has not published
    64any 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
    67Some functions in this tag are used in practice while some others are not known
    68to be used at all. Further confusion exists because some compilers, like
    69GrainLang, import functions not used. Finally, some functions were added and
    70removed after the git tag. For example, [`proc_raise`][13] was removed and
    71[`sock_accept`][15] added.
    72
    73For all of these reasons, wazero will not implement all WASI features, just to
    74complete the below chart. If you desire something not yet implemented, please
    75[raise an issue](https://github.com/tetratelabs/wazero/issues/new) and include
    76your use case (ex which language you are using to compile, a.k.a. target Wasm).
    77
    78Notes:
    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
   135Note: 💀 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

View as plain text