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

     1  ## WASI example
     2  
     3  This example shows how to use I/O in your WebAssembly modules using WASI
     4  (WebAssembly System Interface).
     5  
     6  ```bash
     7  $ go run cat.go /test.txt
     8  greet filesystem
     9  ```
    10  
    11  If you do not set the environment variable `TOOLCHAIN`, main defaults
    12  to use Wasm built with "tinygo". Here are the included examples:
    13  
    14  * [cargo-wasi](testdata/cargo-wasi) - Built via `cargo wasi build --release; mv ./target/wasm32-wasi/release/cat.wasm .`
    15  * [tinygo](testdata/tinygo) - Built via `tinygo build -o cat.wasm -scheduler=none --no-debug -target=wasi cat.go`
    16  * [zig-cc](testdata/zig-cc) - Built via `zig cc cat.c -o cat.wasm --target=wasm32-wasi -O3`
    17  
    18  To run the same example with zig-cc:
    19  ```bash
    20  $ TOOLCHAIN=zig-cc go run cat.go /test.txt
    21  greet filesystem
    22  ```
    23  
    24  ### Toolchain notes
    25  
    26  Examples here check in the resulting binary, as doing so removes a potentially
    27  expensive toolchain setup. This means we have to be careful how wasm is built,
    28  so that the repository doesn't bloat (ex more bandwidth for `git clone`).
    29  
    30  While WASI attempts to be portable, there are no specification tests and
    31  some compilers partially implement features. Notes about portability follow.
    32  
    33  ### cargo-wasi (Rustlang)
    34  
    35  The [Rustlang source][testdata/cargo-wasi] uses [cargo-wasi][1] because the
    36  normal release target `wasm32-wasi` results in almost 2MB, which is too large
    37  to check into our source tree.
    38  
    39  Concretely, if you use `cargo build --target wasm32-wasi --release`, the binary
    40  `./target/wasm32-wasi/release/cat.wasm` is over 1.9MB. One explanation for this
    41  bloat is [`wasm32-wasi` target is not pure rust][2]. As that issue is over two
    42  years old, it is unlikely to change. This means the only way to create smaller
    43  wasm is via optimization.
    44  
    45  The [cargo-wasi][3] crate includes many optimizations in its release target,
    46  including `wasm-opt`, a part of [binaryen][4]. `cargo wasi build --release`
    47  generates 82KB of wasm, which is small enough to check in.
    48  
    49  ### emscripten
    50  
    51  Emscripten is not included as we cannot create a cat program without using
    52  custom filesystem code. Emscripten only supports WASI I/O for
    53  stdin/stdout/stderr and [suggest using wasi-libc instead][5]. This is used in
    54  the [zig-cc](testdata/zig-cc) example.
    55  
    56  [1]: https://github.com/bytecodealliance/cargo-wasi
    57  [2]: https://github.com/rust-lang/rust/issues/73432
    58  [3]: https://github.com/bytecodealliance/cargo-wasi
    59  [4]: https://github.com/WebAssembly/binaryen
    60  [5]: https://github.com/emscripten-core/emscripten/issues/17167#issuecomment-1150252755