From b017dd3f8eb99971a3b63c18bc8d07e688f978ed Mon Sep 17 00:00:00 2001 From: Ivan Enderlin Date: Mon, 31 May 2021 15:53:32 +0200 Subject: [PATCH 01/15] doc(readme) Improve the `README.md`. --- README.md | 135 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 109 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 1dd4c54f748..41e1bf1071f 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ Wasmer logo - +

Build Status @@ -12,7 +12,7 @@ Slack channel - +

@@ -27,56 +27,139 @@
-[Wasmer](https://wasmer.io/) enables super lightweight containers based on [WebAssembly](https://webassembly.org/) that can run anywhere: from Desktop to the Cloud and IoT devices, and also embedded in [*any programming language*](https://github.com/wasmerio/wasmer#language-integrations). +[Wasmer](https://wasmer.io/) is a runtime that enables super +lightweight containers based on [WebAssembly](https://webassembly.org) +to run anywhere: from Desktop to the Cloud and IoT devices, and also +embedded in [*numerous programming +language*](https://github.com/wasmerio/wasmer#language-integrations). -> This readme is also available in: [🇨🇳 中文-Chinese](https://github.com/wasmerio/wasmer/blob/master/docs/cn/README.md) • [🇪🇸 Español-Spanish](https://github.com/wasmerio/wasmer/blob/master/docs/es/README.md) • [🇫🇷 Français-French](https://github.com/wasmerio/wasmer/blob/master/docs/fr/README.md) • [🇯🇵 日本語-Japanese](https://github.com/wasmerio/wasmer/blob/master/docs/ja/README.md). +_This document is also available in: +[🇨🇳 中 文 -Chinese](https://github.com/wasmerio/wasmer/blob/master/docs/cn/README.md), +[🇪🇸 Español-Spanish](https://github.com/wasmerio/wasmer/blob/master/docs/es/README.md), +[🇫🇷 Français-French](https://github.com/wasmerio/wasmer/blob/master/docs/fr/README.md), +[🇯🇵 日本 語 -Japanese](https://github.com/wasmerio/wasmer/blob/master/docs/ja/README.md)_. ## Features -* **Fast & Safe**. Wasmer runs WebAssembly at *near-native* speed in a fully sandboxed environment. +* **Fast & Safe**. Wasmer runs WebAssembly at _near-native_ speed in a + fully sandboxed environment. -* **Pluggable**. Wasmer supports different compilation frameworks to best suit your needs (LLVM, Cranelift...). +* **Pluggable**. To best suit your needs, Wasmer supports different + compilation strategies (_aka_ the compilers — based on LLVM, based + on Cranelift, or Singlepass) and artifact strategies (_aka_ the + engines — Universal, Dylib, Staticlib). -* **Universal**. You can run Wasmer in any *platform* (macOS, Linux and Windows) and *chipset*. +* **Universal**. You can run Wasmer in any _platform_ (Linux, macOS + and Windows) and _chipset_. -* **Standards compliant**. The runtime passes [official WebAssembly test - suite](https://github.com/WebAssembly/testsuite) supporting [WASI](https://github.com/WebAssembly/WASI) and [Emscripten](https://emscripten.org/). +* **Standards compliant**. The runtime passes [official WebAssembly + test suite](https://github.com/WebAssembly/testsuite) supporting + [WASI](https://github.com/WebAssembly/WASI) and + [Emscripten](https://emscripten.org/). ## Quickstart -Wasmer ships with no dependencies. You can install it using the installers below: +The quickest way to get fun with Wasmer is to install its CLI. It +ships with no dependency. Let's first start by installing it, then +let's see how to execute a WebAssembly file. -```sh -curl https://get.wasmer.io -sSfL | sh -``` +### Installing the Wasmer CLI -
- With PowerShell (Windows) -

+Wasmer can be installed from various package managers, scripts, or +built from sources… Pick what is best for you: -```powershell -iwr https://win.wasmer.io -useb | iex -``` +*

+ With curl + + ```sh + curl https://get.wasmer.io -sSfL | sh + ``` + +
+ +*
+ With PowerShell + + ```powershell + iwr https://win.wasmer.io -useb | iex + ``` + +
+ +*
+ With Homebrew + + ```sh + brew install wasmer + ``` + +
+ +*
+ With Scoop + + ```sh + scopp install wasmer + ``` + +
+ +*
+ With Chocolatey + + ```sh + choco install wasmer + ``` + +
+ +*
+ With Cargo + + The following command will install `wasmer-cli`. All the available + features are described in the [`wasmer-cli` + documentation](https://github.com/wasmerio/wasmer/tree/master/lib/cli/README.md). + + ```sh + cargo install wasmer-cli + ``` + +
+ +*
+ From source + + Inside the root of this repository (in this case, you're likely to + need some dependencies): -

-
+ ```sh + make build-wasmer + ``` -> See [wasmer-install](https://github.com/wasmerio/wasmer-install) for more installation options: Homebrew, Scoop, Cargo... +
+* More installation options? See [the `wasmer-install` + repository](https://github.com/wasmerio/wasmer-install) to learn + more! -#### Executing a WebAssembly file +### Executing a WebAssembly file After installing Wasmer you should be ready to execute your first WebAssembly file! 🎉 -You can start by running QuickJS: [qjs.wasm](https://registry-cdn.wapm.io/contents/_/quickjs/0.0.3/build/qjs.wasm) +You can start by running +[QuickJS](https://github.com/bellard/quickjs/), which is a small and +embeddable Javascript engine, compiled as a WebAssembly module, +[`qjs.wasm`](https://registry-cdn.wapm.io/contents/_/quickjs/0.0.3/build/qjs.wasm): ```bash $ wasmer qjs.wasm QuickJS - Type "\h" for help -qjs > +qjs > const i = 1 + 2; +qjs > console.log("hello " + i); +hello 3 ``` -#### Here is what you can do next: +### Here is what you can do next: - [Use Wasmer from your Rust application](https://docs.wasmer.io/integrations/rust) - [Publish a Wasm package on WAPM](https://docs.wasmer.io/ecosystem/wapm/publishing-your-package) From d8c2795dc26c3e1af3ab71edbee25013e39f9b4b Mon Sep 17 00:00:00 2001 From: Ivan Enderlin Date: Mon, 31 May 2021 16:09:16 +0200 Subject: [PATCH 02/15] doc(readme) Improve the `README.md`. --- README.md | 40 +++++++++++++++++++++++----------------- 1 file changed, 23 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 41e1bf1071f..d3561c6821c 100644 --- a/README.md +++ b/README.md @@ -136,6 +136,10 @@ built from sources… Pick what is best for you: make build-wasmer ``` + [Read the + documentation](https://docs.wasmer.io/ecosystem/wasmer/building-from-source) + to learn more about this approach. + * More installation options? See [the `wasmer-install` @@ -169,21 +173,21 @@ hello 3 📦 Wasmer runtime can be used as a library **embedded in different languages**, so you can use WebAssembly _anywhere_. -|   | Language | Package | Docs | +| | Language | Package | Documentation | |-|-|-|-| -| ![Rust logo] | [**Rust**][Rust integration] | [`wasmer` Rust crate] | [Docs][rust docs] -| ![C logo] | [**C/C++**][C integration] | [`wasmer.h` headers] | [Docs][c docs] | -| ![C# logo] | [**C#**][C# integration] | [`WasmerSharp` NuGet package] | [Docs][c# docs] | -| ![D logo] | [**D**][D integration] | [`wasmer` Dub package] | [Docs][d docs] | -| ![Python logo] | [**Python**][Python integration] | [`wasmer` PyPI package] | [Docs][python docs] | -| ![JS logo] | [**Javascript**][JS integration] | [`@wasmerio` NPM packages] | [Docs][js docs] | -| ![Go logo] | [**Go**][Go integration] | [`wasmer` Go package] | [Docs][go docs] | -| ![PHP logo] | [**PHP**][PHP integration] | [`wasm` PECL package] | [Docs][php docs] | -| ![Ruby logo] | [**Ruby**][Ruby integration] | [`wasmer` Ruby Gem] | [Docs][ruby docs] | -| ![Java logo] | [**Java**][Java integration] | [`wasmer/wasmer-jni` Bintray package] | [Docs][java docs] | -| ![Elixir logo] | [**Elixir**][Elixir integration] | [`wasmex` hex package] | [Docs][elixir docs] | -| ![R logo] | [**R**][R integration] | *no published package* | [Docs][r docs] | -| ![Postgres logo] | [**Postgres**][Postgres integration] | *no published package* | [Docs][postgres docs] | +| ![Rust logo] | [**Rust**][Rust integration] | [`wasmer` Rust crate] | [Learn][rust docs] +| ![C logo] | [**C/C++**][C integration] | [`wasmer.h` headers] | [Learn][c docs] | +| ![C# logo] | [**C#**][C# integration] | [`WasmerSharp` NuGet package] | [Learn][c# docs] | +| ![D logo] | [**D**][D integration] | [`wasmer` Dub package] | [Learn][d docs] | +| ![Python logo] | [**Python**][Python integration] | [`wasmer` PyPI package] | [Learn][python docs] | +| ![JS logo] | [**Javascript**][JS integration] | [`@wasmerio` NPM packages] | [Learn][js docs] | +| ![Go logo] | [**Go**][Go integration] | [`wasmer` Go package] | [Learn][go docs] | +| ![PHP logo] | [**PHP**][PHP integration] | [`wasm` PECL package] | [Learn][php docs] | +| ![Ruby logo] | [**Ruby**][Ruby integration] | [`wasmer` Ruby Gem] | [Learn][ruby docs] | +| ![Java logo] | [**Java**][Java integration] | [`wasmer/wasmer-jni` Bintray package] | [Learn][java docs] | +| ![Elixir logo] | [**Elixir**][Elixir integration] | [`wasmex` hex package] | [Learn][elixir docs] | +| ![R logo] | [**R**][R integration] | *no published package* | [Learn][r docs] | +| ![Postgres logo] | [**Postgres**][Postgres integration] | *no published package* | [Learn][postgres docs] | | | [**Swift**][Swift integration] | *no published package* | | | ![Zig logo] | [**Zig**][Zig integration] | *no published package* | | @@ -261,15 +265,17 @@ hello 3 **We welcome any form of contribution, especially from new members of our community** 💜 -You can check how to build the Wasmer runtime in [our awesome docs](https://docs.wasmer.io/ecosystem/wasmer/building-from-source)! +You can check [how to build the Wasmer runtime documentation from +sources](https://docs.wasmer.io/ecosystem/wasmer/building-from-source)! ### Testing -Test you want? The [Wasmer docs will show you how](https://docs.wasmer.io/ecosystem/wasmer/building-from-source/testing). +Test you want? The [Wasmer docs will show you +how](https://docs.wasmer.io/ecosystem/wasmer/building-from-source/testing). ## Community -Wasmer has an amazing community of developers and contributors. Welcome, please join us! 👋 +Wasmer has an amazing community of developers and contributors. You are very welcome! 👋 ### Channels From 4cfaf39e26f94e5d7f84eb42dd0283298012aa9c Mon Sep 17 00:00:00 2001 From: Ivan Enderlin Date: Mon, 31 May 2021 16:27:25 +0200 Subject: [PATCH 03/15] =?UTF-8?q?doc(readme)=20Start=20drafting=20a=20?= =?UTF-8?q?=E2=80=9Ccrate=20index=E2=80=9D.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- lib/README.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 lib/README.md diff --git a/lib/README.md b/lib/README.md new file mode 100644 index 00000000000..cdb168ae5f4 --- /dev/null +++ b/lib/README.md @@ -0,0 +1,41 @@ +# The Wasmer runtime crates + +The crates can be grouped as follows. + +* `api` — The public Rust API exposes everything a user needs to use Wasmer + programatically through the `wasmer` crate, +* `c-api` — The public C API exposes everything a C user needs to use + Wasmer programatically, +* `cache` — The traits and types to cache compiled WebAssembly + modules, +* `cli` — The Wasmer CLI itself, +* `compiler` — The base for the compiler implementations, it defines + the framework for the compilers and provides everything they need: + * `compiler-cranelift` — A WebAssembly compiler based on the + Cranelift compiler infrastructure, + * `compiler-llvm` — A WebAssembly compiler based on the LLVM + compiler infrastructure; recommended for runtime speed + performance, + * `compiler-singlepass` — A WebAssembly compiler based on our own + compilation infrastructure; recommended for compilation-time speed + performance. +* `deprecated` — The deprecated and old public Rust API, must not be + used except if you don't want to migrate an old code using the 0.x + version of Wasmer to 1.x, +* `derive` — A set of procedural macros used inside Wasmer, +* ABI: + * `emscripten` — Emscripten ABI implementation inside Wasmer, + * `wasi` — WASI ABI implementation inside Wasmer. +* `engine` — The general abstraction for creating an engine, which is + responsible of leading the compiling and running flow: + * `engine-universal` — + * `engine-dylib` — + * `engine-staticlib` — +* `middlewares` — +* `types` — +* `vm` — + +Extra crates: + +* `object` — +* `wasi-experimental-io-devices` — From a2a3c5886a14e44112bd57a0160afb0c73a5607f Mon Sep 17 00:00:00 2001 From: Ivan Enderlin Date: Tue, 1 Jun 2021 09:26:24 +0200 Subject: [PATCH 04/15] doc(readme) Fix typos. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d3561c6821c..35c4d9a761e 100644 --- a/README.md +++ b/README.md @@ -49,7 +49,7 @@ _This document is also available in: on Cranelift, or Singlepass) and artifact strategies (_aka_ the engines — Universal, Dylib, Staticlib). -* **Universal**. You can run Wasmer in any _platform_ (Linux, macOS +* **Universal**. You can run Wasmer on any _platform_ (Linux, macOS and Windows) and _chipset_. * **Standards compliant**. The runtime passes [official WebAssembly @@ -99,7 +99,7 @@ built from sources… Pick what is best for you: With Scoop ```sh - scopp install wasmer + scoop install wasmer ``` From ab37e95dd067982409e01b439f9b9aa7ab67a59e Mon Sep 17 00:00:00 2001 From: Ivan Enderlin Date: Tue, 1 Jun 2021 10:00:40 +0200 Subject: [PATCH 05/15] doc(readme) Fix links, improve headings etc. --- README.md | 60 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 38 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 35c4d9a761e..f12adbe9f46 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ _This document is also available in: [🇫🇷 Français-French](https://github.com/wasmerio/wasmer/blob/master/docs/fr/README.md), [🇯🇵 日本 語 -Japanese](https://github.com/wasmerio/wasmer/blob/master/docs/ja/README.md)_. -## Features +## ✨ Features * **Fast & Safe**. Wasmer runs WebAssembly at _near-native_ speed in a fully sandboxed environment. @@ -57,7 +57,7 @@ _This document is also available in: [WASI](https://github.com/WebAssembly/WASI) and [Emscripten](https://emscripten.org/). -## Quickstart +## 🏁 Quickstart The quickest way to get fun with Wasmer is to install its CLI. It ships with no dependency. Let's first start by installing it, then @@ -71,6 +71,9 @@ built from sources… Pick what is best for you: *
With curl + This is kind of the universal way to install Wasmer. If you don't + trust this approach, please see other installation options. + ```sh curl https://get.wasmer.io -sSfL | sh ``` @@ -80,6 +83,8 @@ built from sources… Pick what is best for you: *
With PowerShell + This installation process is dedicated to Windows users: + ```powershell iwr https://win.wasmer.io -useb | iex ``` @@ -89,6 +94,8 @@ built from sources… Pick what is best for you: *
With Homebrew + Homebrew is mainly a package manager for macOS: + ```sh brew install wasmer ``` @@ -98,6 +105,8 @@ built from sources… Pick what is best for you: *
With Scoop + Scoop is a package manager for Windows: + ```sh scoop install wasmer ``` @@ -107,6 +116,8 @@ built from sources… Pick what is best for you: *
With Chocolatey + Chocolatey is a package manager for Windows: + ```sh choco install wasmer ``` @@ -116,6 +127,8 @@ built from sources… Pick what is best for you: *
With Cargo + Cargo is the crate installer for Rust. + The following command will install `wasmer-cli`. All the available features are described in the [`wasmer-cli` documentation](https://github.com/wasmerio/wasmer/tree/master/lib/cli/README.md). @@ -163,20 +176,23 @@ qjs > console.log("hello " + i); hello 3 ``` -### Here is what you can do next: +### Discover -- [Use Wasmer from your Rust application](https://docs.wasmer.io/integrations/rust) -- [Publish a Wasm package on WAPM](https://docs.wasmer.io/ecosystem/wapm/publishing-your-package) -- [Read more about Wasmer](https://medium.com/wasmer/) +Here are some clues about what you can do next: -## Language Integrations +- [Use Wasmer from your Rust application](https://docs.wasmer.io/integrations/rust), +- [Publish a Wasm package on WAPM](https://docs.wasmer.io/ecosystem/wapm/publishing-your-package), +- [Read more about Wasmer](https://medium.com/wasmer/). -📦 Wasmer runtime can be used as a library **embedded in different languages**, so you can use WebAssembly _anywhere_. +## 📦 Language Integrations + +The Wasmer runtime can be used as a library **embedded in different +languages**, so you can use WebAssembly _anywhere_. | | Language | Package | Documentation | |-|-|-|-| | ![Rust logo] | [**Rust**][Rust integration] | [`wasmer` Rust crate] | [Learn][rust docs] -| ![C logo] | [**C/C++**][C integration] | [`wasmer.h` headers] | [Learn][c docs] | +| ![C logo] | [**C/C++**][C integration] | [`wasmer_wasm.h` header] | [Learn][c docs] | | ![C# logo] | [**C#**][C# integration] | [`WasmerSharp` NuGet package] | [Learn][c# docs] | | ![D logo] | [**D**][D integration] | [`wasmer` Dub package] | [Learn][d docs] | | ![Python logo] | [**Python**][Python integration] | [`wasmer` PyPI package] | [Learn][python docs] | @@ -200,8 +216,8 @@ hello 3 [c logo]: https://raw.githubusercontent.com/wasmerio/wasmer/master/assets/languages/c.svg [c integration]: https://github.com/wasmerio/wasmer/tree/master/lib/c-api -[`wasmer.h` headers]: https://wasmerio.github.io/wasmer/c/ -[c docs]: https://wasmerio.github.io/wasmer/c/ +[`wasmer_wasm.h` header]: https://github.com/wasmerio/wasmer/blob/master/lib/c-api/wasmer_wasm.h +[c docs]: https://wasmerio.github.io/wasmer/crates/wasmer_c_api [c# logo]: https://raw.githubusercontent.com/wasmerio/wasmer/master/assets/languages/csharp.svg [c# integration]: https://github.com/migueldeicaza/WasmerSharp @@ -216,7 +232,7 @@ hello 3 [python logo]: https://raw.githubusercontent.com/wasmerio/wasmer/master/assets/languages/python.svg [python integration]: https://github.com/wasmerio/wasmer-python [`wasmer` pypi package]: https://pypi.org/project/wasmer/ -[python docs]: https://github.com/wasmerio/wasmer-python#api-of-the-wasmer-extensionmodule +[python docs]: https://wasmerio.github.io/wasmer-python/api/wasmer/ [go logo]: https://raw.githubusercontent.com/wasmerio/wasmer/master/assets/languages/go.svg [go integration]: https://github.com/wasmerio/wasmer-go @@ -236,7 +252,7 @@ hello 3 [ruby logo]: https://raw.githubusercontent.com/wasmerio/wasmer/master/assets/languages/ruby.svg [ruby integration]: https://github.com/wasmerio/wasmer-ruby [`wasmer` ruby gem]: https://rubygems.org/gems/wasmer -[ruby docs]: https://www.rubydoc.info/gems/wasmer/ +[ruby docs]: https://wasmerio.github.io/wasmer-ruby/wasmer_ruby/index.html [java logo]: https://raw.githubusercontent.com/wasmerio/wasmer/master/assets/languages/java.svg [java integration]: https://github.com/wasmerio/wasmer-java @@ -261,11 +277,11 @@ hello 3 [zig logo]: https://raw.githubusercontent.com/ziglang/logo/master/zig-favicon.png [zig integration]: https://github.com/zigwasm/wasmer-zig -## Contribute - -**We welcome any form of contribution, especially from new members of our community** 💜 +## 🤲 Contribute -You can check [how to build the Wasmer runtime documentation from +We welcome any form of contribution, especially from new members of +our community 💜. You can check [how to build the Wasmer runtime +documentation from sources](https://docs.wasmer.io/ecosystem/wasmer/building-from-source)! ### Testing @@ -273,13 +289,13 @@ sources](https://docs.wasmer.io/ecosystem/wasmer/building-from-source)! Test you want? The [Wasmer docs will show you how](https://docs.wasmer.io/ecosystem/wasmer/building-from-source/testing). -## Community +## 👐 Community Wasmer has an amazing community of developers and contributors. You are very welcome! 👋 ### Channels -- [Slack](https://slack.wasmer.io/) -- [Twitter](https://twitter.com/wasmerio) -- [Facebook](https://www.facebook.com/wasmerio) -- [Email](mailto:hello@wasmer.io) +- [Community Slack workspace](https://slack.wasmer.io/), +- [Official Twitter account](https://twitter.com/wasmerio), +- [Official Facebook acount](https://www.facebook.com/wasmerio), +- [Email](mailto:hello@wasmer.io). From ba22eca815a008d4889ccbd4761355ec2686b5b9 Mon Sep 17 00:00:00 2001 From: Ivan Enderlin Date: Tue, 1 Jun 2021 10:22:38 +0200 Subject: [PATCH 06/15] doc(readme) Improve the `README.md` for our fuzz testing framework. This patch introduces Fuzz Testing, adds links, fix typos etc. --- fuzz/README.md | 44 +++++++++++++++++++++++++++++++------------- 1 file changed, 31 insertions(+), 13 deletions(-) diff --git a/fuzz/README.md b/fuzz/README.md index a187b5cc229..13e40a304cb 100644 --- a/fuzz/README.md +++ b/fuzz/README.md @@ -1,9 +1,19 @@ -This directory contains the fuzz tests for wasmer. To fuzz, we use the -`cargo-fuzz` package. +# Wasmer Fuzz Testing + +[Fuzz testing](https://en.wikipedia.org/wiki/Fuzzing) is: + +> An automated testing technique that involves providing invalid, +> unexpected, or random data as inputs to a program. + +We use fuzz testing to automatically discover bugs in the Wasmer runtime. + +This `fuzz/` directory contains the configuration and the fuzz tests +for Wasmer. To generate and to run the fuzz tests, we use the +[`cargo-fuzz`] library. ## Installation -You may need to install the `cargo-fuzz` package to get the `cargo +You may need to install the [`cargo-fuzz`] library to get the `cargo fuzz` subcommand. Use ```sh @@ -13,17 +23,23 @@ $ cargo install cargo-fuzz `cargo-fuzz` is documented in the [Rust Fuzz Book](https://rust-fuzz.github.io/book/cargo-fuzz.html). -## Running a fuzzer (`validate`, `universal_llvm`, `dylib_cranelift`…) +## Running a fuzzer + +This directory provides multiple fuzzers, like for example `validate`. You can run it with: -Once `cargo-fuzz` is installed, you can run the `validate` fuzzer with ```sh -cargo fuzz run validate +$ cargo fuzz run validate ``` -or the `universal_cranelift` fuzzer + +Another example with the `universal_cranelift` fuzzer: + ```sh -cargo fuzz run universal_cranelift +$ cargo fuzz run universal_cranelift ``` -See the [fuzz/fuzz_targets](https://github.com/wasmerio/wasmer/tree/fuzz/fuzz_targets/) directory for the full list of targets. + +See the +[`fuzz/fuzz_targets`](https://github.com/wasmerio/wasmer/tree/fuzz/fuzz_targets/) +directory for the full list of fuzzers. You should see output that looks something like this: @@ -47,16 +63,18 @@ universal_cranelift /path/to/testcase`. ## The corpus -Each fuzzer has an individual corpus under fuzz/corpus/test_name, +Each fuzzer has an individual corpus under `fuzz/corpus/test_name`, created on first run if not already present. The fuzzers use `wasm-smith` which means that the testcase files are random number -seeds input to the wasm generator, not `.wasm` files themselves. In +seeds input to the Wasm generator, not `.wasm` files themselves. In order to debug a testcase, you may find that you need to convert it into a `.wasm` file. Using the standalone `wasm-smith` tool doesn't work for this purpose because we use a custom configuration to our `wasm_smith::Module`. Instead, our fuzzers use an environment variable `DUMP_TESTCASE=path`. For example: +```sh +$ DUMP_TESTCASE=/tmp/crash.wasm cargo fuzz run --features=universal,singlepass universal_singlepass fuzz/artifacts/universal_singlepass/crash-0966412eab4f89c52ce5d681807c8030349470f6 ``` -DUMP_TESTCASE=/tmp/crash.wasm cargo fuzz run --features=universal,singlepass universal_singlepass fuzz/artifacts/universal_singlepass/crash-0966412eab4f89c52ce5d681807c8030349470f6 -``` + +[`cargo-fuzz`]: https://github.com/rust-fuzz/cargo-fuzz From 2f6143fd668247196b0a69c19ece2328d4fb5859 Mon Sep 17 00:00:00 2001 From: Ivan Enderlin Date: Tue, 1 Jun 2021 10:25:24 +0200 Subject: [PATCH 07/15] doc: Move a `README.md` to its correct place. --- assets/{diagrams => }/README.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename assets/{diagrams => }/README.md (100%) diff --git a/assets/diagrams/README.md b/assets/README.md similarity index 100% rename from assets/diagrams/README.md rename to assets/README.md From a3ff668f50bc15369173bf6beec8d0574313a808 Mon Sep 17 00:00:00 2001 From: Ivan Enderlin Date: Tue, 1 Jun 2021 10:26:06 +0200 Subject: [PATCH 08/15] doc(readme) Add a `README.md` for `benches/`. --- benches/README.md | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 benches/README.md diff --git a/benches/README.md b/benches/README.md new file mode 100644 index 00000000000..cb81186a4e7 --- /dev/null +++ b/benches/README.md @@ -0,0 +1,4 @@ +# Wasmer Benches + +This directory contains small, punctual benches. Other benchmarks are +landing somewhere else. We will update this section soon. From 77e93b6f2b1880052442af4c84f61ba9a6419140 Mon Sep 17 00:00:00 2001 From: Ivan Enderlin Date: Tue, 1 Jun 2021 10:30:12 +0200 Subject: [PATCH 09/15] doc(readme) Add an index to all documentations. --- docs/README.md | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 docs/README.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000000..3ef7f303789 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,8 @@ +# Wasmer Documentation + +Wasmer provides multiple documentations. Here are some pointers: + +* [The public documentation](https://docs.wasmer.io/), +* [The Rust crates documentation](https://wasmerio.github.io/wasmer/), +* [The collection of examples](https://github.com/wasmerio/wasmer/blob/master/examples/README.md), +* [Documentations for all embeddings/language integrations](https://github.com/wasmerio/wasmer/blob/master/README.md). From 9361d61bb9448957e34e2860848e04d934147834 Mon Sep 17 00:00:00 2001 From: Ivan Enderlin Date: Tue, 1 Jun 2021 10:32:52 +0200 Subject: [PATCH 10/15] doc(security) Update `SECURITY.md`. --- SECURITY.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/SECURITY.md b/SECURITY.md index 11b5c0f1344..6a1254a5867 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,18 +2,20 @@ ## Supported Versions -While in beta, the latest published version of `wasmer` (`0.x`) will be supported with security updates. +The table below summarizes which versions are still supported, and which aren't. -| Version | Supported | -| ------- | ------------------ | -| 0.x | :white_check_mark: | +| Version | Supported | +|-|-| +| 0.x | ❌ | +| 1.x | ✅ | ## Reporting a Vulnerability The Wasmer team and community take security bugs in Wasmer seriously. We appreciate your efforts to responsibly disclose your findings, and will make every effort to acknowledge your contributions. -To report a security issue, email security@wasmer.io and include the word "SECURITY" in the subject line. +To report a security issue, email security@wasmer.io or +hello@wasmer.io and include the word "SECURITY" in the subject line. The Wasmer team will send a response indicating the next steps in handling your report. After the initial reply to your report, the security team will keep you informed of the progress towards a fix and full announcement, and may ask for additional information or guidance. From 3f0e2540bf58cedc5be23e945919319ce9bedba9 Mon Sep 17 00:00:00 2001 From: Ivan Enderlin Date: Tue, 1 Jun 2021 10:52:26 +0200 Subject: [PATCH 11/15] doc(packaging) Reformat, rephrase, improve. --- PACKAGING.md | 64 +++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 46 insertions(+), 18 deletions(-) diff --git a/PACKAGING.md b/PACKAGING.md index 896fd815a1f..b5775d514da 100644 --- a/PACKAGING.md +++ b/PACKAGING.md @@ -1,18 +1,46 @@ -## Wasmer distro packaging notes - -* Where possible, do not directly invoke cargo, but use the supplied Makefile - * wasmer has several compiler backends and the Makefile autodetects whether to enable llvm and singlepass. - Set `ENABLE_{CRANELIFT,LLVM,SINGLEPASS}=1` to build the full set or fail trying - * Set `WASMER_CAPI_USE_SYSTEM_LIBFFI=1` to force dynamic linking of libffi on the shared library - * `make install` respects `DESTDIR`, but `prefix` must be configured as e.g. `WASMER_INSTALL_PREFIX=/usr make all` -* In case you must build/install directly with cargo, make sure to enable at least one compiler backend feature - * Beware that compiling with `cargo build --workspace/--all --features ...` will not enable features on the subcrates in the workspace and result in a headless wasmer binary that can not run wasm files directly. -* If you split the package into several subpackages, beware that the create-exe command of wasmer requires `libwasmer.a` to be installed at `$WASMER_INSTALL_PREFIX/lib/libwasmer.a`. - Suggestion for splitting: - * `wasmer` and `wasmer-headless`, containing the respective executables - * `wasmer-headless` contains a subset of `wasmer`'s functionality and should only be packaged when splitting - it must be built explicitly with `make build-wasmer-headless-minimal install-wasmer-headless-minimal` - * `libwasmer`, containing `libwasmer.so*` - * `libwasmer-dev`, containing the header files and a `.pc` file - * `libwasmer-static`, containing `libwasmer.a` - -The wasmer distro packaging story is still in its infancy, so feedback is very welcome. +# Wasmer OS distro packaging notes + +* Wasmer is written in Rust. To build Wasmer, where possible, do not + directly invoke `cargo`, but use the supplied `Makefile` + +* Wasmer provides several compilers and the `Makefile` autodetects + when compilers can be compiled and/or installed. Set the environment + variables `ENABLE_{CRANELIFT,LLVM,SINGLEPASS}=1` to force compiler + to be build or to fail trying, e.g: + + ```sh + $ ENABLE_LLVM=1 make build-wasmer + ``` + +* `make install` respects `DESTDIR`, but `prefix` must be configured + with `WASMER_INSTALL_PREFIX`, e.g.: + + ```sh + $ WASMER_INSTALL_PREFIX=/usr make install + ``` + +* In case you must build/install directly with `cargo`, make sure to + enable at least one compiler feature, like e.g. `--features + cranelift`, + + * Beware that compiling with `cargo build --workspace --features …` + will not enable features on the subcrates in the workspace and + result in a headless Wasmer binary that can not compile Wasm files + directly. + +* If you split the package into several subpackages, beware that the + `create-exe` command of the `wasmer` CLI requires `libwasmer.a` to + be installed at `$WASMER_INSTALL_PREFIX/lib/libwasmer.a`. Suggestions for splitting: + + * The `wasmer-headless` CLI contains a subset of the `wasmer`'s functionalities + and should only be packaged when splitting — it must be built + explicitly with: + + ```sh + $ make build-wasmer-headless-minimal install-wasmer-headless-minimal + ``` + * `libwasmer`, containing `libwasmer.so*`, + * `libwasmer-dev`, containing the header files and a `.pc` file, + * `libwasmer-static`, containing `libwasmer.a`. + +The Wasmer distro packaging story is still in its infancy, so feedback is very welcome. From 53086019af833f024823f51cf3c8805ff9d177b5 Mon Sep 17 00:00:00 2001 From: Ivan Enderlin Date: Tue, 1 Jun 2021 10:52:54 +0200 Subject: [PATCH 12/15] chore(makefile) Fix CS. --- Makefile | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/Makefile b/Makefile index 6b9b1194e67..d6467e485f7 100644 --- a/Makefile +++ b/Makefile @@ -364,18 +364,19 @@ $(info ) # Building # ############ -# Not really "all", just the default target that builds enough so make install will go through +# Not really "all", just the default target that builds enough so make +# install will go through. all: build-wasmer build-capi -bench: - cargo bench $(compiler_features) - build-wasmer: cargo build --release --manifest-path lib/cli/Cargo.toml $(compiler_features) --bin wasmer build-wasmer-debug: cargo build --manifest-path lib/cli/Cargo.toml $(compiler_features) --bin wasmer +bench: + cargo bench $(compiler_features) + # For best results ensure the release profile looks like the following # in Cargo.toml: # [profile.release] From e4798ad7414913210fcc6e76464a854a5b18c3be Mon Sep 17 00:00:00 2001 From: Ivan Enderlin Date: Tue, 1 Jun 2021 10:53:17 +0200 Subject: [PATCH 13/15] doc(readme) Add more indexes to more documentations. --- docs/README.md | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) diff --git a/docs/README.md b/docs/README.md index 3ef7f303789..7d397daffcb 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,7 +2,23 @@ Wasmer provides multiple documentations. Here are some pointers: -* [The public documentation](https://docs.wasmer.io/), -* [The Rust crates documentation](https://wasmerio.github.io/wasmer/), -* [The collection of examples](https://github.com/wasmerio/wasmer/blob/master/examples/README.md), -* [Documentations for all embeddings/language integrations](https://github.com/wasmerio/wasmer/blob/master/README.md). +* [The Wasmer runtime + `README.md`](https://github.com/wasmerio/wasmer/blob/master/README.md) + is a good start for the first steps, like installations, first runs etc., +* [The public documentation](https://docs.wasmer.io/) contains all the + documentation you need to learn about Wasmer and WebAssembly, +* [The Rust crates documentations](https://wasmerio.github.io/wasmer/) + contain all the documentations to use the `wasmer-*` Rust crates, + with many examples, +* [The collection of + examples](https://github.com/wasmerio/wasmer/blob/master/examples/README.md) + illustrates how to use Wasmer and its numerous features through very + commented examples, +* [Documentations for all embeddings/language + integrations](https://github.com/wasmerio/wasmer/blob/master/README.md): + the Wasmer runtime can be embeddeded in various languages or + environments, each embedding provides its own documentation, book + etc., +* [OS distro packaging + notes](https://github.com/wasmerio/wasmer/blob/master/PACKAGING.md) + contains notes about how to package Wasmer for OS distributions. From ea49b914f8a4d4961416e03228c9c62a80368fa7 Mon Sep 17 00:00:00 2001 From: Ivan Enderlin Date: Tue, 1 Jun 2021 11:21:04 +0200 Subject: [PATCH 14/15] doc(readme) Improve the `lib/` presentation. --- lib/README.md | 42 ++++++++++++++++++++++++++---------------- 1 file changed, 26 insertions(+), 16 deletions(-) diff --git a/lib/README.md b/lib/README.md index cdb168ae5f4..f6f621df886 100644 --- a/lib/README.md +++ b/lib/README.md @@ -1,6 +1,7 @@ # The Wasmer runtime crates -The crates can be grouped as follows. +The philosophy of Wasmer is to be very modular by design. It's +composed of a set of crates. We can group them as follows: * `api` — The public Rust API exposes everything a user needs to use Wasmer programatically through the `wasmer` crate, @@ -19,23 +20,32 @@ The crates can be grouped as follows. * `compiler-singlepass` — A WebAssembly compiler based on our own compilation infrastructure; recommended for compilation-time speed performance. -* `deprecated` — The deprecated and old public Rust API, must not be - used except if you don't want to migrate an old code using the 0.x - version of Wasmer to 1.x, * `derive` — A set of procedural macros used inside Wasmer, * ABI: * `emscripten` — Emscripten ABI implementation inside Wasmer, * `wasi` — WASI ABI implementation inside Wasmer. + * `wasi-experimental-io-devices` — An experimental extension of + WASI for basic graphics. * `engine` — The general abstraction for creating an engine, which is - responsible of leading the compiling and running flow: - * `engine-universal` — - * `engine-dylib` — - * `engine-staticlib` — -* `middlewares` — -* `types` — -* `vm` — - -Extra crates: - -* `object` — -* `wasi-experimental-io-devices` — + responsible of leading the compiling and running flow. Using the + same compiler, the runtime performance will be approximately the + same, however the way it stores and loads the executable code will + differ: + * `engine-universal` — stores the code in a custom file format, and + loads it in memory, + * `engine-dylib` — stores Position-Independent Code in a native + shared object library (`.dylib`, `.so`, `.dll`) and loads it with + Operating System shared library loader (via `dlopen`), + * `engine-staticlib` — stores executable code in a native static + object library, in addition to emitting a C header file, which + both can be linked against a sandboxed WebAssembly runtime + environment for the compiled module with no need for runtime + compilation, + * `object` — A library to cross-generate native objects for various + platforms. +* `middlewares` — A collection of middlewares, like `metering` that + tracks how many operators are executed in total and putting a limit + on the total number of operators executed, +* `types` — The basic structures to use WebAssembly, +* `vm` — The Wasmer VM runtime library, the low-level base of + everything. From c6e0135a7ce294d3fca1be0161641ae9806a1285 Mon Sep 17 00:00:00 2001 From: Ivan Enderlin Date: Tue, 1 Jun 2021 11:26:06 +0200 Subject: [PATCH 15/15] chore(scripts) Remove `runtime-core`. --- scripts/update-version.sh | 1 - 1 file changed, 1 deletion(-) diff --git a/scripts/update-version.sh b/scripts/update-version.sh index a14faf9a146..1afa8984d5f 100755 --- a/scripts/update-version.sh +++ b/scripts/update-version.sh @@ -16,7 +16,6 @@ echo "manually check changes to wasmer.iss" # Order to upload packages in ## wasmer-types -## runtime-core ## win-exception-handler ## compiler ## compiler-cranelift