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/SUMMARY.md b/docs/SUMMARY.md index a58c615421..1de0e6749e 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -30,6 +30,8 @@ - [Sandboxing](./security-sandboxing.md) - [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-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 +``` 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 }} 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. diff --git a/docs/contributing-testing.md b/docs/contributing-testing.md new file mode 100644 index 0000000000..59f5c54932 --- /dev/null +++ b/docs/contributing-testing.md @@ -0,0 +1,109 @@ +# 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. 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. 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.