T0b1/wasmtime
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Spice up the project README, fill out more docs (#1010)

Browse Source 
* Spice up the project README, fill out more docs

This is an attempt to spruce up wasmtime's README.md file as well as
fill out more of the missing documentation in the `docs/` folder.
There's still a long way to go but I hoped here to mostly move around
existing information and add new information. As always happy to have
feedback!

* Tweak CLI wording

* Remove no-longer relevant clause

* Update sandboxing docs

* Handle comments
This commit is contained in:
Alex Crichton
2020-02-27 17:28:08 -06:00
committed by GitHub
parent 35d5c6bdde
commit 8caa5a9476
13 changed files with 388 additions and 89 deletions
Download Patch File Download Diff File Expand all files Collapse all files

131
README.md
View File

@@ -1,66 +1,99 @@
# Wasmtime: a WebAssembly Runtime
<div align="center">
<h1><code>wasmtime</code></h1>
**A [Bytecode Alliance][BA] project**
<p>
<strong>A standalone runtime for
<a href="https://webassembly.org/">WebAssembly</a></strong>
</p>
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.
<strong>A <a href="https://bytecodealliance.org/">Bytecode Alliance</a> project</strong>
To get started, visit [wasmtime.dev](https://wasmtime.dev/).
<p>
<a href="https://github.com/bytecodealliance/wasmtime/actions?query=workflow%3ACI"><img src="https://github.com/bytecodealliance/wasmtime/workflows/CI/badge.svg" alt="build status" /></a>
<a href="https://bytecodealliance.zulipchat.com/#narrow/stream/217126-wasmtime"><img src="https://img.shields.io/badge/zulip-join_chat-brightgreen.svg" alt="zulip chat" /></a>
<img src="https://img.shields.io/badge/rustc-1.37+-green.svg" alt="min rustc" />
</p>
[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
<h3>
<a href="https://bytecodealliance.github.io/wasmtime/">Guide</a>
<span> | </span>
<a href="https://bytecodealliance.github.io/wasmtime/contributing.html">Contributing</a>
<span> | </span>
<a href="https://wasmtime.dev/">Website</a>
<span> | </span>
<a href="https://bytecodealliance.zulipchat.com/#narrow/stream/217126-wasmtime">Chat</a>
</h3>
</div>
[![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.

1
docs/SUMMARY.md
View File

@@ -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)

34
docs/WASI-intro.md
View File

@@ -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 `<iostream>`, 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?

66
docs/cli-install.md
View File

@@ -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!

81
docs/cli-options.md
View File

@@ -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
```

23
docs/cli.md
View File

@@ -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).

4
docs/contributing.md
View File

@@ -6,8 +6,8 @@ the [Code of Conduct](./contributing-coc.html)!
## Join Our Chat
We chat about Wasmtime development on Gitter &mdash; [join
us!](https://gitter.im/CraneStation/Lobby)
We chat about Wasmtime development on Zulip &mdash; [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

28
docs/introduction.md
View File

@@ -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

21
docs/security-sandboxing.md
View File

@@ -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.

14
docs/wasm-c.md
View File

@@ -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/

6
docs/wasm-rust.md
View File

@@ -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

57
docs/wasm-wat.md Normal file
View File

@@ -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::<i32, i32, i32>()?;
println!("1 + 2 = {}", add(1, 2)?);
# Ok(())
# }
```
[spec]: https://webassembly.github.io/spec/core/text/index.html

11
docs/wasm.md
View File

@@ -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)