From 14823de237ea258826481202bc06dfc9ec165dfd Mon Sep 17 00:00:00 2001 From: Nick Fitzgerald Date: Tue, 3 Dec 2019 14:32:54 -0800 Subject: [PATCH 1/6] docs: Include the code of conduct directly into the mdbook Also update the link to the organizational code of conduct so that it works in the rendered mdbook as well as when viewed on github. --- CODE_OF_CONDUCT.md | 2 +- docs/contributing-coc.md | 4 +--- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 5c5ebdd259..b671a33264 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -44,6 +44,6 @@ Project maintainers who do not follow or enforce the Code of Conduct in good fai This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version] -[OCoC]: ORG_CODE_OF_CONDUCT.md +[OCoC]: https://github.com/bytecodealliance/wasmtime/blob/master/ORG_CODE_OF_CONDUCT.md [homepage]: https://www.contributor-covenant.org [version]: https://www.contributor-covenant.org/version/1/4/ diff --git a/docs/contributing-coc.md b/docs/contributing-coc.md index 3fcb32caca..83cb9cc90e 100644 --- a/docs/contributing-coc.md +++ b/docs/contributing-coc.md @@ -1,3 +1 @@ -# Code of Conduct - -... more coming soon +{{#include ../CODE_OF_CONDUCT.md }} From 4ba52205d7c0bc150a396c8fad5c847c42be2673 Mon Sep 17 00:00:00 2001 From: Nick Fitzgerald Date: Tue, 3 Dec 2019 15:15:08 -0800 Subject: [PATCH 2/6] docs: Fill out the top-level contributing page a little --- docs/contributing.md | 30 +++++++++++++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) diff --git a/docs/contributing.md b/docs/contributing.md index 6eb2498a2a..40f6509322 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,3 +1,31 @@ # Contributing -... more coming soon +We're excited to work on Wasmtime together with you! This guide should help you +get up and running with Wasmtime development. But first, make sure you've read +the [Code of Conduct](./contributing-coc.html)! + +## Join Our Chat + +We chat about Wasmtime development on Gitter — [join +us!](https://gitter.im/CraneStation/Lobby) + +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 +issue](https://github.com/bytecodealliance/wasmtime/issues/new)! + +## Finding Something to Hack On + +If you're looking for something to do, these are great places to start: + +* [Issues labeled "good first + issue"](https://github.com/bytecodealliance/wasmtime/labels/good%20first%20issue) + — these issues tend to be simple, what needs to be done is well known, + and are good for new contributors to tackle. The goal is to learn Wasmtime's + development workflow and make sure that you can build and test Wasmtime. + +* [Issues labeled "help + wanted"](https://github.com/bytecodealliance/wasmtime/labels/help%20wanted) + — these are issues that we need a little help with! + +If you're unsure if an issue is a good fit for you or not, feel free to ask in a +comment on the issue, or in chat. From aaa0dc4f191bdd4125dfa3c15a8e8df527b5c7a7 Mon Sep 17 00:00:00 2001 From: Nick Fitzgerald Date: Tue, 3 Dec 2019 15:58:10 -0800 Subject: [PATCH 3/6] docs: Add initial how-to-build documentation --- docs/contributing-building.md | 60 ++++++++++++++++++++++++++++++++++- 1 file changed, 59 insertions(+), 1 deletion(-) diff --git a/docs/contributing-building.md b/docs/contributing-building.md index 02861c7b48..676a5e355f 100644 --- a/docs/contributing-building.md +++ b/docs/contributing-building.md @@ -1,3 +1,61 @@ # Building -... more coming soon +This section describes everything required to build and run Wasmtime. + +## Prerequisites + +Before we can actually build Wasmtime, we'll need to make sure these things are +installed first. + +### The Rust Toolchain + +[Install the Rust toolchain here.](https://www.rust-lang.org/tools/install) This +includes `rustup`, `cargo`, `rustc`, etc... + +### `libclang` (optional) + +The `wasmtime-fuzzing` crate transitively depends on `bindgen`, which requires +that your system has a `libclang` installed. Therefore, if you want to hack on +Wasmtime's fuzzing infrastructure, you'll need `libclang`. [Details on how to +get `libclang` and make it available for `bindgen` are +here.](https://rust-lang.github.io/rust-bindgen/requirements.html#clang) + +## Building the `wasmtime` CLI + +To make an unoptimized, debug build of the `wasmtime` CLI tool, go to the root +of the repository and run this command: + +```shell +cargo build +``` + +The built executable will be located at `target/debug/wasmtime`. + +To make an optimized build, run this command in the root of the repository: + +```shell +cargo build --release +``` + +The built executable will be located at `target/release/wasmtime`. + +You can also build and run a local `wasmtime` CLI by replacing `cargo build` +with `cargo run`. + +## Building Other Wasmtime Crates + +You can build any of the Wasmtime crates by appending `-p wasmtime-whatever` to +the `cargo build` invocation. For example, to build the `wasmtime-jit` crate, +execute this command: + +```shell +cargo build -p wasmtime-jit +``` + +Alternatively, you can `cd` into the crate's directory, and run `cargo build` +there, without needing to supply the `-p` flag: + +```shell +cd crates/jit/ +cargo build +``` From b74b0bc49ecce7c4858373f3c5caa7250440ad3e Mon Sep 17 00:00:00 2001 From: Nick Fitzgerald Date: Tue, 3 Dec 2019 17:31:10 -0800 Subject: [PATCH 4/6] docs: Add a section about how to test Wasmtime --- docs/SUMMARY.md | 1 + docs/contributing-testing.md | 106 +++++++++++++++++++++++++++++++++++ 2 files changed, 107 insertions(+) create mode 100644 docs/contributing-testing.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index a58c615421..d79cd1fabd 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -30,6 +30,7 @@ - [Sandboxing](./security-sandboxing.md) - [Contributing](contributing.md) - [Building](./contributing-building.md) + - [Testing](./contributing-testing.md) - [CI](./contributing-ci.md) - [Governance](./contributing-governance.md) - [Code of Conduct](./contributing-coc.md) diff --git a/docs/contributing-testing.md b/docs/contributing-testing.md new file mode 100644 index 0000000000..a22781f8d5 --- /dev/null +++ b/docs/contributing-testing.md @@ -0,0 +1,106 @@ +# Testing + +This section describes how to run Wasmtime's tests and add new tests. + +Before continuing, make sure you can [build +Wasmtime](./contributing-building.html) successfully. Can't run the tests if you +can't build it! + +## Running All Tests + +To run all of Wasmtime's tests, execute this command: + +```shell +cargo test --all +``` + +You can also exclude a particular crate from testing with `--exclude`. For +example, if you want to avoid testing the `wastime-fuzzing` crate — which +requires that `libclang` is installed on your system, and for some reason maybe +you don't have it — you can run: + +```shell +cargo test --all --exclude wasmtime-fuzzing +``` + +## Testing a Specific Crate + +You can test a particular Wasmtime crate with `cargo test -p +wasmtime-whatever`. For example, to test the `wasmtime-environ` crate, execute +this command: + +```shell +cargo test -p wasmtime-environ +``` + +Alternatively, you can `cd` into the crate's directory, and run `cargo test` +there, without needing to supply the `-p` flag: + +```shell +cd crates/environ/ +cargo test +``` + +## Running the Wasm Spec Tests + +The spec testsuite itself is in a git submodule, so make sure you've +checked it out and initialized its submodule: + +```shell +git submodule update --init +``` + +When the submodule is checked out, Wasmtime runs the Wasm spec testsuite as part +of testing the `wasmtime-cli` crate: + +```shell +cargo test -p wasmtime-cli +``` + +## Adding New Tests + +### Adding Rust's `#[test]`-Style Tests + +For very "unit-y" tests, we add `test` modules in the same `.rs` file as the +code that is being tested. These `test` modules are configured to only get +compiled during testing with `#[cfg(test)]`. + +```rust +// some code... + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn some_test_for_that_code() { + // ... + } +} +``` + +If you're writing a unit test and a `test` module doesn't already exist, you can +create one. + +For more "integration-y" tests, we create a `tests` directory within the crate, +and put the tests inside there. For example, there are various code +cache-related tests at `crates/environ/tests/cache_*.rs`. Always feel free to +add a `tests` directory to a crate, if you want to add a new test and there +aren't any existing tests. + +### Adding Specification-Style Wast Tests + +We use the spec testsuite as-is and without custom patches or a forked +version. If you have a new test that you want to add to it, make sure it makes +sense for every Wasm implementation to run your test (i.e. it isn't +Wasmtime-specific) and send a pull request +[upstream](https://github.com/WebAssembly/testsuite/). Once it is accepted in +the upstream repo, we can update our git submodule and we'll start running the +new tests. + +Alternatively, if you have a Wasmtime-specific test that you'd like to write in +Wast and use the Wast-style assertions, you can add it to our "misc +testsuite". The misc testsuite uses the same syntax and assertions as the spec +testsuite, but lives in `tests/misc_testsuite`. Feel free to add new tests to +existing `tests/misc_testsuite/*.wast` files or create new ones as needed. These +tests are run as part of the `wasmtime-cli` crate. From 9c7079fd15bf02ddf8b564011fca8b06b9f29da8 Mon Sep 17 00:00:00 2001 From: Nick Fitzgerald Date: Tue, 3 Dec 2019 17:31:31 -0800 Subject: [PATCH 5/6] docs: Add a section about how to fuzz Wasmtime --- docs/SUMMARY.md | 1 + docs/contributing-fuzzing.md | 38 ++++++++++++++++++++++++++++++++++++ 2 files changed, 39 insertions(+) create mode 100644 docs/contributing-fuzzing.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index d79cd1fabd..1de0e6749e 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -31,6 +31,7 @@ - [Contributing](contributing.md) - [Building](./contributing-building.md) - [Testing](./contributing-testing.md) + - [Fuzzing](./contributing-fuzzing.md) - [CI](./contributing-ci.md) - [Governance](./contributing-governance.md) - [Code of Conduct](./contributing-coc.md) diff --git a/docs/contributing-fuzzing.md b/docs/contributing-fuzzing.md new file mode 100644 index 0000000000..1a0757e129 --- /dev/null +++ b/docs/contributing-fuzzing.md @@ -0,0 +1,38 @@ +# Fuzzing + +## Test Case Generators and Oracles + +Test case generators and oracles live in the `wasmtime-fuzzing` crate, located +in the `crates/fuzzing` directory. + +A *test case generator* takes raw, unstructured input from a fuzzer and +translates that into a test case. This might involve interpreting the raw input +as "DNA" or pre-determined choices through a decision tree and using it to +generate an in-memory data structure, or it might be a no-op where we interpret +the raw bytes as if they were Wasm. + +An *oracle* takes a test case and determines whether we have a bug. For example, +one of the simplest oracles is to take a Wasm binary as an input test case, +validate and instantiate it, and (implicitly) check that no assertions failed or +segfaults happened. A more complicated oracle might compare the result of +executing a Wasm file with and without optimizations enabled, and make sure that +the two executions are observably identical. + +Our test case generators and oracles strive to be fuzzer-agnostic: they can be +reused with libFuzzer or AFL or any other fuzzing engine or driver. + +## libFuzzer and `cargo fuzz` Fuzz Targets + +We combine a test case generator and one more more oracles into a *fuzz +target*. Because the target needs to pipe the raw input from a fuzzer into the +test case generator, it is specific to a particular fuzzer. This is generally +fine, since they're only a couple of lines of glue code. + +Currently, all of our fuzz targets are written for +[libFuzzer](https://www.llvm.org/docs/LibFuzzer.html) and [`cargo +fuzz`](https://rust-fuzz.github.io/book/cargo-fuzz.html). They are defined in +the `fuzz` subdirectory. + +See +[`fuzz/README.md`](https://github.com/bytecodealliance/wasmtime/blob/master/fuzz/README.md) +for details on how to run these fuzz targets and set up a corpus of seed inputs. From 06280401e0cde86b2f2c11a5fda9b741605d37e9 Mon Sep 17 00:00:00 2001 From: Nick Fitzgerald Date: Wed, 4 Dec 2019 08:57:58 -0800 Subject: [PATCH 6/6] docs: Wordsmith the specification-style tests contributing docs --- docs/contributing-testing.md | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/docs/contributing-testing.md b/docs/contributing-testing.md index a22781f8d5..59f5c54932 100644 --- a/docs/contributing-testing.md +++ b/docs/contributing-testing.md @@ -91,16 +91,19 @@ aren't any existing tests. ### Adding Specification-Style Wast Tests We use the spec testsuite as-is and without custom patches or a forked -version. If you have a new test that you want to add to it, make sure it makes -sense for every Wasm implementation to run your test (i.e. it isn't -Wasmtime-specific) and send a pull request +version. This probably isn't what you want to modify when adding a new Wasmtime +test! + +When you have a Wasmtime-specific test that you'd like to write in Wast and use +the Wast-style assertions, you can add it to our "misc testsuite". The misc +testsuite uses the same syntax and assertions as the spec testsuite, but lives +in `tests/misc_testsuite`. Feel free to add new tests to existing +`tests/misc_testsuite/*.wast` files or create new ones as needed. These tests +are run as part of the `wasmtime-cli` crate's tests. + +If you have a new test that you think really belongs in the spec testsuite, make +sure it makes sense for every Wasm implementation to run your test (i.e. it +isn't Wasmtime-specific) and send a pull request [upstream](https://github.com/WebAssembly/testsuite/). Once it is accepted in the upstream repo, we can update our git submodule and we'll start running the new tests. - -Alternatively, if you have a Wasmtime-specific test that you'd like to write in -Wast and use the Wast-style assertions, you can add it to our "misc -testsuite". The misc testsuite uses the same syntax and assertions as the spec -testsuite, but lives in `tests/misc_testsuite`. Feel free to add new tests to -existing `tests/misc_testsuite/*.wast` files or create new ones as needed. These -tests are run as part of the `wasmtime-cli` crate.