Merge pull request #663 from fitzgen/contributing-docs

Contributing docs

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/

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)

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
+```

docs/contributing-coc.md

@@ -1,3 +1 @@
-# Code of Conduct
-
-... more coming soon
+{{#include ../CODE_OF_CONDUCT.md }}

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.

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.

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.