Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add lots of rustdocs and clean up one line of code #841

Merged
merged 3 commits into from
Sep 27, 2019
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ 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`
- [#836](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
Expand Down
2 changes: 1 addition & 1 deletion lib/runtime-c-api/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
5 changes: 3 additions & 2 deletions lib/runtime-core/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
7 changes: 5 additions & 2 deletions lib/runtime-core/src/backend.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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")]
Expand All @@ -41,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",
Expand Down Expand Up @@ -111,6 +113,7 @@ impl Default for MemoryBoundCheckMode {
}
}

/// Controls which experimental features will be enabled.
#[derive(Debug, Default)]
pub struct Features {
pub simd: bool,
Expand Down
2 changes: 1 addition & 1 deletion lib/runtime-core/src/backing.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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())
Expand Down
9 changes: 7 additions & 2 deletions lib/runtime/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
11 changes: 10 additions & 1 deletion lib/runtime/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -189,6 +189,10 @@ pub fn instantiate(wasm: &[u8], import_object: &ImportObject) -> error::Result<I
}

/// Get a single instance of the default compiler to use.
///
/// The output of this function can be controlled by the mutually
/// exclusive `default-backend-llvm`, `default-backend-singlepass`,
/// and `default-backend-cranelift` feature flags.
pub fn default_compiler() -> impl Compiler {
#[cfg(any(
all(
Expand Down Expand Up @@ -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 requested `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<Box<dyn Compiler>> {
match backend {
#[cfg(feature = "cranelift")]
Expand All @@ -241,5 +250,5 @@ pub fn compiler_for_backend(backend: Backend) -> Option<Box<dyn Compiler>> {
}
}

/// The current version of this crate
/// The current version of this crate.
pub const VERSION: &str = env!("CARGO_PKG_VERSION");
11 changes: 11 additions & 0 deletions lib/wasi/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand Down Expand Up @@ -37,6 +47,7 @@ pub struct ExitCode {
pub code: syscalls::types::__wasi_exitcode_t,
}

/// Creates a WasiImport object with `WasiState`.
pub fn generate_import_object(
args: Vec<Vec<u8>>,
envs: Vec<Vec<u8>>,
Expand Down
19 changes: 19 additions & 0 deletions lib/wasi/src/state/mod.rs
Original file line number Diff line number Diff line change
@@ -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;

Expand Down Expand Up @@ -44,6 +55,8 @@ pub struct InodeVal {
pub kind: Kind,
}

/// The core of the filesystem abstraction. Includes directories,
/// files, and symlinks.
#[derive(Debug, Serialize, Deserialize)]
pub enum Kind {
File {
Expand Down Expand Up @@ -998,6 +1011,12 @@ impl WasiFs {
}
}

/// 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,
Expand Down
6 changes: 6 additions & 0 deletions lib/wasi/src/state/types.rs
Original file line number Diff line number Diff line change
Expand Up @@ -626,6 +626,8 @@ fn host_file_bytes_available(_raw_fd: i32) -> Result<usize, WasiFsError> {
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 that implements `WasiFile` and
/// `Serialize` + `Deserialize`.
#[derive(Debug, Serialize, Deserialize)]
pub struct Stdout;
impl Read for Stdout {
Expand Down Expand Up @@ -717,6 +719,8 @@ impl WasiFile for Stdout {
}
}

/// A wrapper type around Stderr that implements `WasiFile` and
/// `Serialize` + `Deserialize`.
#[derive(Debug, Serialize, Deserialize)]
pub struct Stderr;
impl Read for Stderr {
Expand Down Expand Up @@ -808,6 +812,8 @@ impl WasiFile for Stderr {
}
}

/// A wrapper type around Stdin that implements `WasiFile` and
/// `Serialize` + `Deserialize`.
#[derive(Debug, Serialize, Deserialize)]
pub struct Stdin;
impl Read for Stdin {
Expand Down