diff --git a/README.md b/README.md index 1ef16059fc..afac75192a 100644 --- a/README.md +++ b/README.md @@ -1,66 +1,99 @@ -# Wasmtime: a WebAssembly Runtime +
+

wasmtime

-**A [Bytecode Alliance][BA] project** +

+ A standalone runtime for + WebAssembly +

-Wasmtime is a standalone wasm-only optimizing runtime for [WebAssembly] and -[WASI]. It runs WebAssembly code [outside of the Web], and can be used both -as a command-line utility or as a library embedded in a larger application. + A Bytecode Alliance project -To get started, visit [wasmtime.dev](https://wasmtime.dev/). +

+ build status + zulip chat + min rustc +

-[BA]: https://bytecodealliance.org/ -[WebAssembly]: https://webassembly.org/ -[WASI]: https://wasi.dev -[outside of the Web]: https://webassembly.org/docs/non-web/ -[build-status]: https://github.com/bytecodealliance/wasmtime/workflows/CI/badge.svg -[github-actions]: https://github.com/bytecodealliance/wasmtime/actions?query=workflow%3ACI -[gitter-chat-badge]: https://badges.gitter.im/CraneStation/CraneStation.svg -[gitter-chat]: https://gitter.im/CraneStation/Lobby -[minimum-rustc]: https://img.shields.io/badge/rustc-1.37+-green.svg +

+ Guide + | + Contributing + | + Website + | + Chat +

+
-[![build-status]][github-actions] -[![gitter-chat-badge]][gitter-chat] -![minimum-rustc] +## Installation -There are Rust, C, and C++ toolchains that can compile programs with WASI. See -the [WASI intro][WASI intro] for more information, and the [WASI tutorial][WASI tutorial] -for a tutorial on compiling and running programs using WASI and wasmtime, as -well as an overview of the filesystem sandboxing system. +The Wasmtime CLI can be installed on Linux and macOS with a small install +script: -Wasmtime passes the [WebAssembly spec testsuite]. To run it, update the -`tests/spec_testsuite` submodule with `git submodule update --remote`, and it -will be run as part of `cargo test`. +```sh +$ curl https://wasmtime.dev/install.sh -sSf | bash +``` -Wasmtime does not yet implement Spectre mitigations, however this is a subject -of ongoing research. +Windows or otherwise interested users can download installers and +binaries directly from the [GitHub +Releases](https://github.com/bytecodealliance/wasmtime/releases) page. -[WebAssembly spec testsuite]: https://github.com/WebAssembly/testsuite -[CloudABI]: https://cloudabi.org/ -[WebAssembly System Interface]: docs/WASI-overview.md -[WASI intro]: docs/WASI-intro.md -[WASI tutorial]: docs/WASI-tutorial.md +## Example -Additional goals for Wasmtime include: - - Support a variety of host APIs (not just WASI), with fast calling sequences, - and develop proposals for additional API modules to be part of WASI. - - Facilitate development and testing around the [Cranelift] and [Lightbeam] JITs, - and other WebAssembly execution strategies. - - Develop a native ABI used for compiling WebAssembly suitable for use in both - JIT and AOT to native object files. +If you've got the [Rust compiler +installed](https://www.rust-lang.org/tools/install) then you can take some Rust +source code: -[Cranelift]: https://github.com/bytecodealliance/cranelift -[Lightbeam]: https://github.com/bytecodealliance/wasmtime/tree/master/crates/lightbeam +```rust +fn main() { + println!("Hello, world!"); +} +``` -#### Including Wasmtime in your project +and compile/run it with: -Wasmtime exposes an API for embedding as a library through the `wasmtime` subcrate, -which contains both a [high-level and safe Rust API], as well as a C-compatible API -compatible with the [proposed WebAssembly C API]. +```sh +$ rustup target add wasm32-wasi +$ rustc hello.rs --target wasm32-wasi +$ wasmtime hello.wasm +Hello, world! +``` -For more information, see the [Rust API embedding chapter] of the Wasmtime documentation. +## Features -[high-level and safe Rust API]: https://docs.rs/wasmtime/ -[proposed WebAssembly C API]: https://github.com/WebAssembly/wasm-c-api -[Rust API embedding chapter]: https://bytecodealliance.github.io/wasmtime/embed-rust.html +* **Lightweight**. Wasmtime is a standalone runtime for WebAssembly that scales + with your needs. It fits on tiny chips as well as makes use of huge servers. + Wasmtime can be embedded into almost any application too. + +* **Fast**. Wasmtime is built on the optimizing Cranelift code generator to + quickly generate high-quality machine code at runtime. + +* **Configurable**. Whether you need to precompile your wasm ahead of time, + generate code blazingly fast with Lightbeam, or interpret it at runtime, + Wasmtime has you covered for all your wasm-executing needs. + +* **WASI**. Wasmtime supports a rich set of APIs for interacting with the host + environment through the [WASI standard](https://wasi.dev). + +* **Standards Compliant**. Wasmtime passes the [official WebAssembly test + suite](https://github.com/WebAssembly/testsuite), implements the [official C + API of wasm](https://github.com/WebAssembly/wasm-c-api), and implements + [future proposals to WebAssembly](https://github.com/WebAssembly/proposals) as + well. Wasmtime developers are intimately engaged with the WebAssembly + standards process all along the way too. + +## Documentation + +[📚 Read the Wasmtime guide here! 📚][guide] + +The [wasmtime guide][guide] is the best starting point to learn about what +Wasmtime can do for you or help answer your questions about Wasmtime. If you're +curious in contributing to Wasmtime, [it can also help you do +that][contributing]!. + +[contributing]: https://bytecodealliance.github.io/wasmtime/contributing.html +[guide]: https://bytecodealliance.github.io/wasmtime + +--- It's Wasmtime. diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 7fd70ec92a..2eb5b2b35b 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -18,6 +18,7 @@ - [Writing WebAssembly](./wasm.md) - [Rust](./wasm-rust.md) - [C/C++](./wasm-c.md) + - [WebAssembly Text Format (`*.wat`)](./wasm-wat.md) - [Example: Markdown Parser](./wasm-markdown.md) - [Embedding Wasmtime](embed.md) - [Rust API](./embed-rust.md) diff --git a/docs/WASI-intro.md b/docs/WASI-intro.md index 32a462b11f..6f4d485845 100644 --- a/docs/WASI-intro.md +++ b/docs/WASI-intro.md @@ -26,39 +26,13 @@ toolchains will be able to implement WASI as well! ### Rust -To install a WASI-enabled Rust toolchain: - -``` -rustup target add wasm32-wasi -cargo build --target wasm32-wasi -``` - -Until now, Rust's WebAssembly support has had two main options, the -Emscripten-based option, and the wasm32-unknown-unknown option. The latter -option is lighter-weight, but only supports `no_std`. WASI enables a new -wasm32-wasi target, which is similar to wasm32-unknown-unknown in -that it doesn't depend on Emscripten, but it can use WASI to provide a -decent subset of libstd. +To install a WASI-enabled Rust toolchain, see the [online section of the +guide](https://bytecodealliance.github.io/wasmtime/wasm-rust.html) ### C/C++ -All the parts needed to support wasm are included in upstream clang, lld, and -compiler-rt, as of the LLVM 8.0 release. However, to use it, you'll need -to build WebAssembly-targeted versions of the library parts, and it can -be tricky to get all the CMake invocations lined up properly. - -To make things easier, we provide -[prebuilt packages](https://github.com/CraneStation/wasi-sdk/releases) -that provide builds of Clang and sysroot libraries. - -WASI doesn't yet support `setjmp`/`longjmp` or C++ exceptions, as it is -waiting for [unwinding support in WebAssembly]. - -[unwinding support in WebAssembly]: https://github.com/WebAssembly/exception-handling/ - -Some C++ programs, particularly those using ``, may see warnings -about function signature mismatches; this is a -[known bug](https://bugs.llvm.org/show_bug.cgi?id=40412). +To install a WASI-enabled C/C++ toolchain, see the [online section of the +guide](https://bytecodealliance.github.io/wasmtime/wasm-c.html) ## How can I run programs that use WASI? diff --git a/docs/cli-install.md b/docs/cli-install.md index 34fae6f50b..801d2f5a31 100644 --- a/docs/cli-install.md +++ b/docs/cli-install.md @@ -1,3 +1,67 @@ # Installing `wasmtime` -... more coming soon +Here we'll show you how to install the `wasmtime` command line tool. Note that +this is distinct from embedding the Wasmtime project into another, for that +you'll want to consult the [embedding documentation](embed.md). + +The easiest way to install the `wasmtime` CLI tool is through our installation +script. Linux and macOS users can execute the following: + +```sh +$ curl https://wasmtime.dev/install.sh -sSf | bash +``` + +This will download a precompiled version of `wasmtime` and place it in +`$HOME/.wasmtime`, and update your shell configuration to place the right +directory in `PATH`. + +Windows users will want to visit our [releases page][releases] and can download +the MSI installer (`wasmtime-dev-x86_64-windows.msi` for example) and use that +to install. + +[releases]: https://github.com/bytecodealliance/wasmtime/releases + +You can confirm your installation works by executing: + +```sh +$ wasmtime -V +wasmtime 0.12.0 +``` + +And now you're off to the races! Be sure to check out the [various CLI +options](cli-options.md) as well. + +## Download Precompiled Binaries + +If you'd prefer to not use an installation script, or you're perhaps +orchestrating something in CI, you can also download one of our precompiled +binaries of `wasmtime`. We have two channels of releases right now for +precompiled binaries: + +1. Each tagged release will have a full set of release artifacts on the [GitHub + releases page][releases]. +2. The [`dev` release] is also continuously updated with the latest build of the + `master` branch. If you want the latest-and-greatest and don't mind a bit of + instability, this is the release for you. + +[`dev` release]: https://github.com/bytecodealliance/wasmtime/releases/tag/dev + +When downloading binaries you'll likely want one of the following archives (for +the `dev` release) + +* Linux users - [`wasmtime-dev-x86_64-linux.tar.xz`] +* macOS users - [`wasmtime-dev-x86_64-macos.tar.xz`] +* Windows users - [`wasmtime-dev-x86_64-windows.zip`] + +Each of these archives has a `wasmtime` binary placed inside which can be +executed normally as the CLI would. + +[wasmtime-dev-x86_64-linux.tar.xz`]: https://github.com/bytecodealliance/wasmtime/releases/download/dev/wasmtime-dev-x86_64-linux.tar.xz +[wasmtime-dev-x86_64-macos.tar.xz`]: https://github.com/bytecodealliance/wasmtime/releases/download/dev/wasmtime-dev-x86_64-macos.tar.xz +[wasmtime-dev-x86_64-windows.zip`]: https://github.com/bytecodealliance/wasmtime/releases/download/dev/wasmtime-dev-x86_64-windows.zip + +## Compiling from Source + +If you'd prefer to compile the `wasmtime` CLI from source, you'll want to +consult the [contributing documentation for building](contributing-building.md). +Be sure to use a `--release` build if you're curious to do benchmarking! diff --git a/docs/cli-options.md b/docs/cli-options.md index 3b7926b440..4f382cc677 100644 --- a/docs/cli-options.md +++ b/docs/cli-options.md @@ -1,3 +1,82 @@ # CLI Options for `wasmtime` -... more coming soon +The `wasmtime` CLI is organized into a few subcommands. If no subcommand is +provided it'll assume `run`, which is to execute a wasm file. The subcommands +supported by `wasmtime` are: + +## `help` + +This is a general subcommand used to print help information to the terminal. You +can execute any number of the following: + +```sh +$ wasmtime help +$ wasmtime --help +$ wasmtime -h +$ wasmtime help run +$ wasmtime run -h +``` + +When in doubt, try running the `help` command to learn more about functionality! + +## `run` + +This is the `wasmtime` CLI's main subcommand, and it's also the default if no +other subcommand is provided. The `run` command will execute a WebAssembly +module. This means that the module will be compiled to native code, +instantiated, and then optionally have an export executed. + +The `wasmtime` CLI will automatically hook up any WASI-related imported +functionality, but at this time if your module imports anything else it will +fail instantiation. + +The `run` command takes one positional argument which is the name of the module +to run: + +```sh +$ wasmtime run foo.wasm +$ wasmtime foo.wasm +``` + +Note that the `wasmtime` CLI can take both a binary WebAssembly file (`*.wasm`) +as well as the text format for WebAssembly (`*.wat`): + +```sh +$ wasmtime foo.wat +``` + +## `wast` + +The `wast` command executes a `*.wast` file which is the test format for the +official WebAssembly spec test suite. This subcommand will execute the script +file which has a number of directives supported to instantiate modules, link +tests, etc. + +Executing this looks like: + +```sh +$ wasmtime wast foo.wast +``` + +## `config` + +This subcomand is used to control and edit local Wasmtime configuration +settings. The primary purpose of this currently is to configure [how Wasmtime's +code caching works](./cli-cache.md). You can create a new configuration file for +you to edit with: + +```sh +$ wasmtime config new +``` + +And that'll print out the path to the file you can edit. + +## `wasm2obj` + +This is an experimental subcommand to compile a WebAssembly module to native +code. Work for this is still heavily under development, but you can execute this +with: + +```sh +$ wasmtime wasm2obj foo.wasm foo.o +``` diff --git a/docs/cli.md b/docs/cli.md index c12e0bc9d5..f1ee314aa0 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -1,3 +1,24 @@ # Using the `wasmtime` CLI -... more coming soon +In addition to the embedding API which allows you to use Wasmtime as a +library, the Wasmtime project also provies a `wasmtime` CLI tool to conveniently +execute WebAssembly modules from the command line. + +This section will provide a guide to the `wasmtime` CLI and major functionality +that it contains. In short, however, you can execute a WebAssembly file +(actually doing work as part of the `start` function) like so: + +```sh +$ wasmtime foo.wasm +``` + +Or similarly if you want to invoke a "start" function, such as with WASI +modules, you can execute + +```sh +$ wasmtime --invoke _start foo.wasm +``` + +For more information be sure to check out [how to install the +CLI](cli-install.md) as well as [the list of options you can +pass](cli-options.md). diff --git a/docs/contributing.md b/docs/contributing.md index 40f6509322..72c9a67762 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -6,8 +6,8 @@ the [Code of Conduct](./contributing-coc.html)! ## Join Our Chat -We chat about Wasmtime development on Gitter — [join -us!](https://gitter.im/CraneStation/Lobby) +We chat about Wasmtime development on Zulip — [join +us!](https://bytecodealliance.zulipchat.com/#narrow/stream/217126-wasmtime) If you're having trouble building Wasmtime, aren't sure why a test is failing, or have any other questions, feel free to ask here. You can also [open an diff --git a/docs/introduction.md b/docs/introduction.md index 925cc87a8a..5ea7d32ea3 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -1,3 +1,29 @@ # Introduction -... more coming soon +[Wasmtime][github] is a [Bytecode Alliance][BA] project that is a standalone +wasm-only optimizing runtime for [WebAssembly] and [WASI]. It runs WebAssembly +code [outside of the Web], and can be used both as a command-line utility or as +a library embedded in a larger application. + +Wasmtime strives to be a highly configurable and embeddable runtime to run on +any scale of application. Many features are still under development so if you +have a question don't hesitate to [file an issue][issue]. + +This guide is intended to server a number of purposes and within you'll find: + +* [How to create simple wasm modules](tutorial-create-hello-world.md) +* [How to use Wasmtime from a number of languages](lang.md) +* [How to use install and use the `wasmtime` CLI](cli.md) +* Information about [stability](stability.md) and [security](security.md) in + Wasmtime. + +... and more! The source for this guide [lives on +GitHub](https://github.com/bytecodealliance/wasmtime/tree/master/docs) and +contributions are welcome! + +[github]: https://github.com/bytecodealliance/wasmtime +[BA]: https://bytecodealliance.org/ +[WebAssembly]: https://webassembly.org/ +[WASI]: https://wasi.dev +[outside of the Web]: https://webassembly.org/docs/non-web/ +[issue]: https://github.com/bytecodealliance/wasmtime/issues/new diff --git a/docs/security-sandboxing.md b/docs/security-sandboxing.md index 64c80954ed..5b74628037 100644 --- a/docs/security-sandboxing.md +++ b/docs/security-sandboxing.md @@ -1,3 +1,22 @@ # Sandboxing -... more coming soon +One of WebAssembly (and Wasmtime's) main goals is to execute untrusted code in +a safe manner inside of a sandbox. WebAssembly is inherently sandboxed by design +(must import all functionality, etc). This document is intended to cover the +various sandboxing implementation strategies that Wasmtime has as they are +developed. + +At this time Wasmtime implements what's necessary for the WebAssembly +specification, for example memory isolation between instances. Additionally the +safe Rust API is intended to mitigate accidental bugs in hosts. + +Different sandboxing implementation techniques will also come with different +tradeoffs in terms of performance and feature limitations, and Wasmtime plans to +offer users choices of which tradeoffs they want to make. + +More will be added here over time! + +## Spectre + +Wasmtime does not yet implement Spectre mitigations, however this is a subject +of ongoing research. diff --git a/docs/wasm-c.md b/docs/wasm-c.md index 40a32b22a2..d9455759b0 100644 --- a/docs/wasm-c.md +++ b/docs/wasm-c.md @@ -1 +1,15 @@ # C/C++ + +All the parts needed to support wasm are included in upstream clang, lld, and +compiler-rt, as of the LLVM 8.0 release. However, to use it, you'll need +to build WebAssembly-targeted versions of the library parts, and it can +be tricky to get all the CMake invocations lined up properly. + +To make things easier, we provide +[prebuilt packages](https://github.com/CraneStation/wasi-sdk/releases) +that provide builds of Clang and sysroot libraries. + +WASI doesn't yet support `setjmp`/`longjmp` or C++ exceptions, as it is +waiting for [unwinding support in WebAssembly]. + +[unwinding support in WebAssembly]: https://github.com/WebAssembly/exception-handling/ diff --git a/docs/wasm-rust.md b/docs/wasm-rust.md index 9f3f0c8f14..b24db17824 100644 --- a/docs/wasm-rust.md +++ b/docs/wasm-rust.md @@ -28,10 +28,10 @@ Cross-compiling to WebAssembly involves a number of knobs that need configuration, but you can often gloss over these internal details by using build tooling intended for the WASI target. For example we can start out writing a WebAssembly binary with [`cargo -wasi`](https://github.com/alexcrichton/cargo-wasi). +wasi`](https://github.com/bytecodealliance/cargo-wasi). First up we'll [install `cargo -wasi`](https://alexcrichton.github.io/cargo-wasi/install.html): +wasi`](https://bytecodealliance.github.io/cargo-wasi/install.html): ```sh $ cargo install cargo-wasi @@ -71,7 +71,7 @@ Hello, world! ``` You can check out the [introductory documentation of -`cargo-wasi`](https://alexcrichton.github.io/cargo-wasi/hello-world.html) as +`cargo-wasi`](https://bytecodealliance.github.io/cargo-wasi/hello-world.html) as well for some more information. ## Writing Libraries diff --git a/docs/wasm-wat.md b/docs/wasm-wat.md new file mode 100644 index 0000000000..e1f519b332 --- /dev/null +++ b/docs/wasm-wat.md @@ -0,0 +1,57 @@ +# WebAssembly Text Format (`*.wat`) + +While not necessarily a full-blown language you might be curious how Wasmtime +interacts with [the `*.wat` text format][spec]! The `wasmtime` CLI and Rust +embedding API both support the `*.wat` text format by default. + +"Hello, World!" is pretty nontrivial in the `*.wat` format since it's +assembly-like and not really intended to be a primary programming language. That +being said we can create a simple add function to call it! + +For example if you have a file `add.wat` like so: + +```wat +(module + (func (export "add") (param i32 i32) (result i32) + local.get 0 + local.get 1 + i32.add)) +``` + +Then you can execute this on the CLI with: + +```sh +$ wasmtime add.wat --invoke add 1 2 +warning: ... +warning: ... +3 +``` + +And we can see that we're already adding numbers! + +You can also see how this works in the Rust API like so: + +```rust +# extern crate wasmtime; +# extern crate anyhow; +use wasmtime::*; + +# fn main() -> anyhow::Result<()> { +let store = Store::default(); +let wat = r#" + (module + (func (export "add") (param i32 i32) (result i32) + local.get 0 + local.get 1 + i32.add)) +"#; +let module = Module::new(&store, wat)?; +let instance = Instance::new(&module, &[])?; +let add = instance.get_export("add").and_then(|f| f.func()).unwrap(); +let add = add.get2::()?; +println!("1 + 2 = {}", add(1, 2)?); +# Ok(()) +# } +``` + +[spec]: https://webassembly.github.io/spec/core/text/index.html diff --git a/docs/wasm.md b/docs/wasm.md index 62ff997e65..b524cc811e 100644 --- a/docs/wasm.md +++ b/docs/wasm.md @@ -1 +1,12 @@ # Writing WebAssembly + +Wasmtime is a runtime for *executing* WebAssembly but you also at some point +need to actually produce the WebAssembly module to feed into Wasmtime! This +section of the guide is intended to provide some introductory documentation for +compiling source code to WebAssembly to later run in Wasmtime. There's plenty of +other documentation on the web for doing this, so you'll want to be sure to +check out your language's documentation for WebAssembly as well. + +* [Rust](wasm-rust.md) +* [C/C++](wasm-c.md) +* [WebAssembly Text Format (`*.wat`)](wasm-wat.md)