From dc1744560c780dbe9b59ed46ff11a4590519efa2 Mon Sep 17 00:00:00 2001 From: Mark McCaskey Date: Thu, 26 Sep 2019 17:15:43 -0700 Subject: [PATCH 1/2] Add lots of rustdocs and clean up one line of code --- CHANGELOG.md | 1 + lib/runtime-c-api/README.md | 2 +- lib/runtime-core/README.md | 5 +++-- lib/runtime-core/src/backend.rs | 5 ++++- lib/runtime-core/src/backing.rs | 2 +- lib/runtime/README.md | 9 +++++++-- lib/runtime/src/lib.rs | 9 +++++++++ lib/wasi/src/lib.rs | 11 +++++++++++ lib/wasi/src/state/mod.rs | 13 +++++++++++++ lib/wasi/src/state/types.rs | 3 +++ 10 files changed, 53 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cde45b92e..aee32fdc4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ Blocks of changes will separated by version increments. ## **[Unreleased]** +- [#841](https://github.com/wasmerio/wasmer/pull/841) Slightly improve rustdoc documentation and small updates to outdated info in readme files - [#835](https://github.com/wasmerio/wasmer/pull/836) Update Cranelift fork version to `0.44.0` - [#839](https://github.com/wasmerio/wasmer/pull/839) Change supported version to stable Rust 1.37+ - [#834](https://github.com/wasmerio/wasmer/pull/834) Fix panic when unwraping `wasmer` arguments diff --git a/lib/runtime-c-api/README.md b/lib/runtime-c-api/README.md index 4557e0d8a..c652948b8 100644 --- a/lib/runtime-c-api/README.md +++ b/lib/runtime-c-api/README.md @@ -25,7 +25,7 @@ # Wasmer Runtime C API Wasmer is a standalone JIT WebAssembly runtime, aiming to be fully -compatible with Emscripten, Rust and Go. [Learn +compatible with WASI, Emscripten, Rust and Go. [Learn more](https://github.com/wasmerio/wasmer). This crate exposes a C and a C++ API for the Wasmer runtime. diff --git a/lib/runtime-core/README.md b/lib/runtime-core/README.md index d64a348bd..fafbcd85b 100644 --- a/lib/runtime-core/README.md +++ b/lib/runtime-core/README.md @@ -25,7 +25,8 @@ # Wasmer Runtime Core Wasmer is a standalone JIT WebAssembly runtime, aiming to be fully -compatible with Emscripten, Rust and Go. [Learn +compatible with WASI, Emscripten, Rust and Go. [Learn more](https://github.com/wasmerio/wasmer). -This crate represents the core of the runtime. +This crate represents the core of the runtime. Consider +[`wasmer-runtime`] for higher level APIs. diff --git a/lib/runtime-core/src/backend.rs b/lib/runtime-core/src/backend.rs index 0a062ba5f..6c581226e 100644 --- a/lib/runtime-core/src/backend.rs +++ b/lib/runtime-core/src/backend.rs @@ -22,6 +22,7 @@ pub mod sys { } pub use crate::sig_registry::SigRegistry; +/// Enum used to select which compiler should be used to generate code #[derive(Serialize, Deserialize, Debug, Copy, Clone, PartialEq, Eq)] pub enum Backend { Cranelift, @@ -30,6 +31,7 @@ pub enum Backend { } impl Backend { + /// Get a list of the currently enabled (via feature flag) backends pub fn variants() -> &'static [&'static str] { &[ #[cfg(feature = "backend-cranelift")] @@ -41,7 +43,7 @@ impl Backend { ] } - /// stable string representation of the backend + /// Stable string representation of the backend /// can be used as part of a cache key, for example pub fn to_string(&self) -> &'static str { match self { @@ -111,6 +113,7 @@ impl Default for MemoryBoundCheckMode { } } +/// Controls which experimental features will be enabled #[derive(Debug, Default)] pub struct Features { pub simd: bool, diff --git a/lib/runtime-core/src/backing.rs b/lib/runtime-core/src/backing.rs index fb9cb5714..e69943002 100644 --- a/lib/runtime-core/src/backing.rs +++ b/lib/runtime-core/src/backing.rs @@ -618,7 +618,7 @@ fn import_functions( } } - if link_errors.len() > 0 { + if !link_errors.is_empty() { Err(link_errors) } else { Ok(functions.into_boxed_map()) diff --git a/lib/runtime/README.md b/lib/runtime/README.md index 4f52a5557..7edbd877e 100644 --- a/lib/runtime/README.md +++ b/lib/runtime/README.md @@ -95,11 +95,16 @@ fn main() -> error::Result<()> { ## Additional Notes The `wasmer-runtime` crate is build to support multiple compiler -backends. Currently, we support the [Cranelift] compiler with the -[`wasmer-clif-backend`] crate by default. +backends. We support have a [Cranelift] backend in the +[`wasmer-clif-backend`] crate, a [LLVM] backend in the +[`wasmer-llvm-backend`] crate, and the [Singlepass] backend in the +[`wasmer-singlepass-backend`] crate. Currently, the Cranelift backend +is the default. You can specify the compiler you wish to use with the [`compile_with`] function. [Cranelift]: https://github.com/CraneStation/cranelift +[LLVM]: https://llvm.org +[Singlepass]: https://github.com/wasmerio/wasmer/tree/master/lib/singlepass-backend [`wasmer-clif-backend`]: https://crates.io/crates/wasmer-clif-backend [`compile_with`]: https://docs.rs/wasmer-runtime/*/wasmer_runtime/fn.compile_with.html diff --git a/lib/runtime/src/lib.rs b/lib/runtime/src/lib.rs index 9495dcb34..9fc201e46 100644 --- a/lib/runtime/src/lib.rs +++ b/lib/runtime/src/lib.rs @@ -189,6 +189,10 @@ pub fn instantiate(wasm: &[u8], import_object: &ImportObject) -> error::Result impl Compiler { #[cfg(any( all( @@ -219,6 +223,11 @@ pub fn default_compiler() -> impl Compiler { DefaultCompiler::new() } +/// Get the `Compiler` as a trait object for the given `Backend`. +/// Returns `Option` because support for the `Compiler` may not be enabled by +/// feature flags. +/// +/// To get a list of the enabled backends as strings, call `Backend::variants()` pub fn compiler_for_backend(backend: Backend) -> Option> { match backend { #[cfg(feature = "cranelift")] diff --git a/lib/wasi/src/lib.rs b/lib/wasi/src/lib.rs index c44798025..2cd544d67 100644 --- a/lib/wasi/src/lib.rs +++ b/lib/wasi/src/lib.rs @@ -10,6 +10,16 @@ #![doc(html_favicon_url = "https://wasmer.io/static/icons/favicon.ico")] #![doc(html_logo_url = "https://avatars3.githubusercontent.com/u/44205449?s=200&v=4")] +//! Wasmer's WASI implementation +//! +//! Use `generate_import_object` to create an `ImportObject`. This `ImportObject` +//! can be combined with a module to create an `Instance` which can execute WASI +//! Wasm functions. +//! +//! See `state` for the experimental WASI FS API. Also see the +//! [WASI plugin example](https://github.com/wasmerio/wasmer/blob/master/examples/plugin.rs) +//! for an example of how to extend WASI using the WASI FS API. + #[cfg(target = "windows")] extern crate winapi; @@ -37,6 +47,7 @@ pub struct ExitCode { pub code: syscalls::types::__wasi_exitcode_t, } +/// Create a WasiImport object with `WasiState` pub fn generate_import_object( args: Vec>, envs: Vec>, diff --git a/lib/wasi/src/state/mod.rs b/lib/wasi/src/state/mod.rs index ebf5573fc..754369015 100644 --- a/lib/wasi/src/state/mod.rs +++ b/lib/wasi/src/state/mod.rs @@ -1,6 +1,17 @@ //! WARNING: the API exposed here is unstable and very experimental. Certain things are not ready //! yet and may be broken in patch releases. If you're using this and have any specific needs, //! please let us know here https://github.com/wasmerio/wasmer/issues/583 or by filing an issue. +//! +//! Wasmer always has a virtual root directory located at `/` at which all pre-opened directories can +//! be found. It's possible to traverse between preopened directories this way as well (for example +//! `preopen-dir1/../preopen-dir2`). +//! +//! A preopened directory is a directory or directory + name combination passed into the +//! `generate_import_object` function. These are directories that the caller has given +//! the WASI module permission to access. +//! +//! You can implement `WasiFile` for your own types to get custom behavior and extend WASI, see the +//! [WASI plugin example](https://github.com/wasmerio/wasmer/blob/master/examples/plugin.rs). mod types; @@ -44,6 +55,7 @@ pub struct InodeVal { pub kind: Kind, } +/// The core file-object data type #[derive(Debug, Serialize, Deserialize)] pub enum Kind { File { @@ -998,6 +1010,7 @@ impl WasiFs { } } +/// Top level data type containing all the state that WASI can interact with #[derive(Debug, Serialize, Deserialize)] pub struct WasiState { pub fs: WasiFs, diff --git a/lib/wasi/src/state/types.rs b/lib/wasi/src/state/types.rs index 83c0426c3..d0faa997f 100644 --- a/lib/wasi/src/state/types.rs +++ b/lib/wasi/src/state/types.rs @@ -626,6 +626,7 @@ fn host_file_bytes_available(_raw_fd: i32) -> Result { unimplemented!("host_file_bytes_available not yet implemented for non-Unix-like targets. This probably means the program tried to use wasi::poll_oneoff") } +/// A wrapper type around Stdout #[derive(Debug, Serialize, Deserialize)] pub struct Stdout; impl Read for Stdout { @@ -717,6 +718,7 @@ impl WasiFile for Stdout { } } +/// A wrapper type around Stderr #[derive(Debug, Serialize, Deserialize)] pub struct Stderr; impl Read for Stderr { @@ -808,6 +810,7 @@ impl WasiFile for Stderr { } } +/// A wrapper type around Stdin #[derive(Debug, Serialize, Deserialize)] pub struct Stdin; impl Read for Stdin { From 871310a851367b2a92d38a7b5dd8eea9c443eee6 Mon Sep 17 00:00:00 2001 From: Mark McCaskey Date: Fri, 27 Sep 2019 10:15:40 -0700 Subject: [PATCH 2/2] Improve docs from feedback --- lib/runtime-core/src/backend.rs | 10 +++++----- lib/runtime/src/lib.rs | 10 +++++----- lib/wasi/src/lib.rs | 2 +- lib/wasi/src/state/mod.rs | 10 ++++++++-- lib/wasi/src/state/types.rs | 9 ++++++--- 5 files changed, 25 insertions(+), 16 deletions(-) diff --git a/lib/runtime-core/src/backend.rs b/lib/runtime-core/src/backend.rs index 6c581226e..f1086de0d 100644 --- a/lib/runtime-core/src/backend.rs +++ b/lib/runtime-core/src/backend.rs @@ -22,7 +22,7 @@ pub mod sys { } pub use crate::sig_registry::SigRegistry; -/// Enum used to select which compiler should be used to generate code +/// Enum used to select which compiler should be used to generate code. #[derive(Serialize, Deserialize, Debug, Copy, Clone, PartialEq, Eq)] pub enum Backend { Cranelift, @@ -31,7 +31,7 @@ pub enum Backend { } impl Backend { - /// Get a list of the currently enabled (via feature flag) backends + /// Get a list of the currently enabled (via feature flag) backends. pub fn variants() -> &'static [&'static str] { &[ #[cfg(feature = "backend-cranelift")] @@ -43,8 +43,8 @@ impl Backend { ] } - /// Stable string representation of the backend - /// can be used as part of a cache key, for example + /// Stable string representation of the backend. + /// It can be used as part of a cache key, for example. pub fn to_string(&self) -> &'static str { match self { Backend::Cranelift => "cranelift", @@ -113,7 +113,7 @@ impl Default for MemoryBoundCheckMode { } } -/// Controls which experimental features will be enabled +/// Controls which experimental features will be enabled. #[derive(Debug, Default)] pub struct Features { pub simd: bool, diff --git a/lib/runtime/src/lib.rs b/lib/runtime/src/lib.rs index 9fc201e46..2945ff3d5 100644 --- a/lib/runtime/src/lib.rs +++ b/lib/runtime/src/lib.rs @@ -190,7 +190,7 @@ pub fn instantiate(wasm: &[u8], import_object: &ImportObject) -> error::Result impl Compiler { @@ -224,10 +224,10 @@ pub fn default_compiler() -> impl Compiler { } /// Get the `Compiler` as a trait object for the given `Backend`. -/// Returns `Option` because support for the `Compiler` may not be enabled by -/// feature flags. +/// Returns `Option` because support for the requested `Compiler` may +/// not be enabled by feature flags. /// -/// To get a list of the enabled backends as strings, call `Backend::variants()` +/// To get a list of the enabled backends as strings, call `Backend::variants()`. pub fn compiler_for_backend(backend: Backend) -> Option> { match backend { #[cfg(feature = "cranelift")] @@ -250,5 +250,5 @@ pub fn compiler_for_backend(backend: Backend) -> Option> { } } -/// The current version of this crate +/// The current version of this crate. pub const VERSION: &str = env!("CARGO_PKG_VERSION"); diff --git a/lib/wasi/src/lib.rs b/lib/wasi/src/lib.rs index 2cd544d67..56ca851e4 100644 --- a/lib/wasi/src/lib.rs +++ b/lib/wasi/src/lib.rs @@ -47,7 +47,7 @@ pub struct ExitCode { pub code: syscalls::types::__wasi_exitcode_t, } -/// Create a WasiImport object with `WasiState` +/// Creates a WasiImport object with `WasiState`. pub fn generate_import_object( args: Vec>, envs: Vec>, diff --git a/lib/wasi/src/state/mod.rs b/lib/wasi/src/state/mod.rs index 754369015..3c92d93bd 100644 --- a/lib/wasi/src/state/mod.rs +++ b/lib/wasi/src/state/mod.rs @@ -55,7 +55,8 @@ pub struct InodeVal { pub kind: Kind, } -/// The core file-object data type +/// The core of the filesystem abstraction. Includes directories, +/// files, and symlinks. #[derive(Debug, Serialize, Deserialize)] pub enum Kind { File { @@ -1010,7 +1011,12 @@ impl WasiFs { } } -/// Top level data type containing all the state that WASI can interact with +/// Top level data type containing all* the state with which WASI can +/// interact. +/// +/// * The contents of files are not stored and may be modified by +/// other, concurrently running programs. Data such as the contents +/// of directories are lazily loaded. #[derive(Debug, Serialize, Deserialize)] pub struct WasiState { pub fs: WasiFs, diff --git a/lib/wasi/src/state/types.rs b/lib/wasi/src/state/types.rs index d0faa997f..2f97a5fe3 100644 --- a/lib/wasi/src/state/types.rs +++ b/lib/wasi/src/state/types.rs @@ -626,7 +626,8 @@ fn host_file_bytes_available(_raw_fd: i32) -> Result { unimplemented!("host_file_bytes_available not yet implemented for non-Unix-like targets. This probably means the program tried to use wasi::poll_oneoff") } -/// A wrapper type around Stdout +/// A wrapper type around Stdout that implements `WasiFile` and +/// `Serialize` + `Deserialize`. #[derive(Debug, Serialize, Deserialize)] pub struct Stdout; impl Read for Stdout { @@ -718,7 +719,8 @@ impl WasiFile for Stdout { } } -/// A wrapper type around Stderr +/// A wrapper type around Stderr that implements `WasiFile` and +/// `Serialize` + `Deserialize`. #[derive(Debug, Serialize, Deserialize)] pub struct Stderr; impl Read for Stderr { @@ -810,7 +812,8 @@ impl WasiFile for Stderr { } } -/// A wrapper type around Stdin +/// A wrapper type around Stdin that implements `WasiFile` and +/// `Serialize` + `Deserialize`. #[derive(Debug, Serialize, Deserialize)] pub struct Stdin; impl Read for Stdin {