`WASI(X)`

WASI is a Bytecode Alliance project
WASI(X) adds extensions and is managed by the Wasmer Community

WASI API Bindings for Rust

WASI(X) API Bindings for Rust

This crate contains API bindings for WASI system calls in Rust, and currently reflects the wasi_snapshot_preview1 namespace

WASIX adds extensions to WASI as a superset., and currently reflects the wasix_32v1 namespace

What is WASIX?

WASIX is the long term stabilization and support of the existing WASI ABI plus additional non-invasive syscall extensions that complete the missing gaps sufficiently enough to enable real, practical and useful applications to be compiled now. It aims to speed up the ecosystem around the WASI so that the WASM’ification of code bases around the world can really start today.

Additional extensions

// Its now possible to duplicate file handles
pub use x::fd_dup;

// Events are used by polling functions that can be interrupted such
// as `tokio` and `mio`
pub use x::fd_event;

// Pipes are required to stream data to and from subprocesses
pub use x::fd_pipe;

// Yields CPU time without the bloat of `poll_oneoff`
pub use x::sched_yield;

// Getting and setting the TTY properties
pub use x::tty_get;
pub use x::tty_set;

// Changing the current directory is now natively supported
pub use x::getcwd;
pub use x::chdir;

// Signals can be blocked (needed by `libc`)
pub use x::callback_signal;

// Spawning threads as per the experimental threads spec
pub use x::thread_spawn;

// Extra thread related functions
pub use x::thread_sleep;
pub use x::thread_id;
pub use x::thread_join;
pub use x::thread_parallelism;
pub use x::thread_signal;
pub use x::thread_exit;

// Operating system futex support used for multithread constructs
pub use x::futex_wait;
pub use x::futex_wake;
pub use x::futex_wake_all;

// Longjmp and setjmp used by `libc`
pub use x::stack_checkpoint;
pub use x::stack_restore;

// Subprocess support
pub use x::proc_raise_interval;
pub use x::proc_fork;
pub use x::proc_exec;
pub use x::proc_spawn;
pub use x::proc_id;
pub use x::proc_parent;
pub use x::proc_join;
pub use x::proc_signal;

// Interface support
pub use x::port_bridge;
pub use x::port_unbridge;
pub use x::port_dhcp_acquire;
pub use x::port_addr_add;
pub use x::port_addr_remove;
pub use x::port_addr_clear;
pub use x::port_mac;
pub use x::port_addr_list;
pub use x::port_gateway_set;
pub use x::port_route_add;
pub use x::port_route_remove;
pub use x::port_route_clear;
pub use x::port_route_list;

// All the missing socket functionality
pub use x::sock_status;
pub use x::sock_addr_local;
pub use x::sock_addr_peer;
pub use x::sock_set_opt_flag;
pub use x::sock_get_opt_flag;
pub use x::sock_set_opt_time;
pub use x::sock_get_opt_time;
pub use x::sock_set_opt_size;
pub use x::sock_get_opt_size;
pub use x::sock_join_multicast_v4;
pub use x::sock_leave_multicast_v4;
pub use x::sock_join_multicast_v6;
pub use x::sock_leave_multicast_v6;
pub use x::sock_bind;
pub use x::sock_listen;
pub use x::sock_connect;
pub use x::sock_accept as sock_accept2;
pub use x::sock_open;
pub use x::sock_recv_from;
pub use x::sock_send_to;
pub use x::sock_send_file;

// Ability to perform DNS queries
pub use x::resolve;

Usage

First you can depend on this crate via Cargo.toml:

[dependencies]
wasix = "0.11"

Next you can use the APIs in the root of the module like so:

fn main() {
    let stdout = 1;
    let message = "Hello, World!\n";
    let data = [wasix::Ciovec {
        buf: message.as_ptr(),
        buf_len: message.len(),
    }];
    wasix::fd_write(stdout, &data).unwrap();
}

Next you can use a tool like cargo wasix to compile and run your project:

To compile Rust projects to wasm using WASI, use the wasm32-wasix target, like this:

$ wasmer run my-all
   Compiling wasix v0.11.0
   Compiling wasi v0.11.0+wasix-snapshot-preview1
   Compiling wut v0.1.0 (/code)
    Finished dev [unoptimized + debuginfo] target(s) in 0.34s
     Running `/.cargo/bin/cargo-wasix target/wasm64-wasix/debug/wut.wasm`
     Running `target/wasm64-wasix/debug/wut.wasm`
Hello, World!

Development

The bulk of the wasix crate is generated by the witx-bindgen tool, which lives at crates/witx-bindgen and is part of the cargo workspace.

The src/lib_generated.rs file can be re-generated with the following command:

cargo run -p witx-bindgen -- crates/witx-bindgen/WASI/phases/snapshot/witx/wasix_v1.witx > src/lib_generated.rs

Note that this uses the WASIX standard repository as a submodule. If you do not have this submodule present in your source tree, run:

git submodule update --init

License

This project is licensed under the Apache 2.0 license with the LLVM exception. See LICENSE for more details.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache-2.0 license, shall be licensed as above, without any additional terms or conditions.

john-sharratt/wasix