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
131
README.md
131
README.md
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user