Spice up the project README, fill out more docs (#1010)
* 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
@@ -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)
|
||||
|
||||
@@ -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?
|
||||
|
||||
|
||||
@@ -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!
|
||||
|
||||
@@ -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
23
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).
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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/
|
||||
|
||||
@@ -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
57
docs/wasm-wat.md
Normal 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
11
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)
|
||||
|
||||
Reference in New Issue
Block a user