Add a wasi-ephemeral crate to build with ephemeral WASI interfaces (WebAssembly#31)

* Add a wasi-ephemeral crate to build with ephemeral WASI interfaces

Developers working on WASI interfaces can use the wasi-ephemeral crate
as a path dependency or git dependency, to build and run with the
ephemeral WASI interface rather than the latest snapshot.
(wasi-ephemeral uses publish=false and will not be uploaded to
crates.io.)

wasi-ephemeral builds with a build.rs script, so that it automatically
rebuilds on changes to the witx file.

wasi-ephemeral also supports building with an arbitrary witx file, using
the WASI_EPHEMERAL_WITX environment variable.

* Build-test wasi-ephemeral in CI

Author: joshtriplett

.github/workflows/main.yml

@@ -19,6 +19,7 @@ jobs:
     - run: cargo build --no-default-features
     - run: cargo build --target wasm32-wasi
     - run: cargo build --target wasm32-wasi --no-default-features
+    - run: cargo build -p wasi-ephemeral
 
   rustfmt:
     name: Rustfmt

Cargo.toml

@@ -12,7 +12,7 @@ readme = "README.md"
 documentation = "https://docs.rs/wasi"
 
 [workspace]
-members = ['crates/generate-raw']
+members = ['crates/generate-raw', 'crates/wasi-ephemeral']
 
 [dependencies]
 # When built as part of libstd

crates/wasi-ephemeral/Cargo.toml

@@ -0,0 +1,21 @@
+[package]
+name = "wasi-ephemeral"
+version = "0.0.0"
+publish = false
+authors = ["Bytecode Alliance"]
+license = "Apache-2.0 WITH LLVM-exception OR Apache-2.0 OR MIT"
+description = "Experimental WASI API bindings for Rust"
+edition = "2018"
+categories = ["no-std", "wasm"]
+keywords = ["webassembly", "wasm"]
+repository = "https://github.com/bytecodealliance/wasi"
+
+[build-dependencies]
+generate-raw = { path = "../generate-raw" }
+
+[features]
+default = ["std"]
+std = []
+
+[badges]
+maintenance = { status = "experimental" }

crates/wasi-ephemeral/README.md

@@ -0,0 +1,18 @@
+This crate contains API bindings for the [ephemeral
+phase](https://github.com/WebAssembly/WASI/blob/master/phases/README.md) of
+[WASI](https://github.com/WebAssembly/WASI). The ephemeral phase exists for
+experimentation prior to snapshotting.
+
+This crate will never be released, and should only be used by path dependency
+or git dependency. By default, this crate provides bindings for the ephemeral
+phase from the included git submodule of the [WASI
+repository](https://github.com/WebAssembly/WASI), but you can set the
+`WASI_EPHEMERAL_WITX` environment variable to the full path to a witx file to
+build bindings for that witx file instead.
+
+This crate makes it easier to test bindings to arbitrary witx interfaces. Note
+that WebAssembly runtimes typically do not implement the ephemeral phase of
+WASI, so a WebAssembly program built against the default wasi-ephemeral may not
+load. Instead, for development, you may want to build with
+`WASI_EPHEMERAL_WITX` pointing to an edited version of the latest snapshot, and
+a correspondingly modified version of a WebAssembly runtime.

crates/wasi-ephemeral/build.rs

@@ -0,0 +1,20 @@
+use std::{env, fs::File, io::Write, path::PathBuf};
+
+fn main() {
+    let out_path: PathBuf = env::var_os("OUT_DIR").unwrap().into();
+    let mut f = File::create(out_path.join("lib_generated.rs")).unwrap();
+    const WASI_EPHEMERAL_WITX: &str =
+        "../generate-raw/WASI/phases/ephemeral/witx/wasi_ephemeral_preview.witx";
+    let witx_path: PathBuf = env::var_os("WASI_EPHEMERAL_WITX")
+        .unwrap_or_else(|| WASI_EPHEMERAL_WITX.into())
+        .into();
+    let out = generate_raw::generate(&witx_path);
+    write!(f, "{}", out).unwrap();
+    println!("cargo:rerun-if-env-changed=WASI_EPHEMERAL_WITX");
+    println!("cargo:rerun-if-changed={}", witx_path.display());
+    println!(
+        "cargo:rerun-if-changed={}",
+        witx_path.with_file_name("typenames.witx").display(),
+    );
+    // TODO: Account for changes in use directives.
+}

crates/wasi-ephemeral/src/error.rs

@@ -0,0 +1 @@
+../../../src/error.rs

crates/wasi-ephemeral/src/lib.rs

@@ -0,0 +1,33 @@
+//! Raw API bindings to the WebAssembly System Interface (WASI)
+//!
+//! This crate provides Rust API bindings to WASI APIs. All WASI APIs are
+//! exported from this crate and provided with the appropriate type signatures.
+//! This crate is entirely procedurally generated from the `*.witx` files that
+//! describe the WASI API.
+//!
+//! # WASI API Version
+//!
+//! The WASI API is evolving over time. It is both gaining new features as well
+//! as tweaking the ABI of existing features. As a result it's important to
+//! understand what version of this crate you're using and how it relates to
+//! the WASI version of the spec.
+//!
+//! The WASI specification is organized into phases where there is a snapshot
+//! at any one point in time describing the current state of the specification.
+//! This crate implements the latest "ephemeral" version, not yet snapshotted.
+//!
+//! This crate will never be released, and should only be used by path
+//! dependency or git dependency.
+//!
+//! # Crate Features
+//!
+//! This crate supports one feature, `std`, which implements the standard
+//! `Error` trait for the exported [`Error`] type in this crate. This is
+//! enabled by default but can be disabled to make the library `no_std`
+//! compatible.
+
+#![no_std]
+
+mod error;
+
+include!(concat!(env!("OUT_DIR"), "/lib_generated.rs"));