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