Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
201 lines (147 loc) · 6.44 KB

CONTRIBUTING.md

File metadata and controls

201 lines (147 loc) · 6.44 KB

Contributing

This project welcomes contributions for bug fixes, documentation updates, new features, or whatever you might like. Development is done through GitHub pull requests. Feel free to reach out on the Bytecode Alliance Zulip as well if you'd like assistance in contributing or would just like to say hi.

Building From Source

To create a debug build of this project from source, execute this command at the root of the repository:

$ cargo build

And the resulting binary is located at ./target/debug/wasm-tools for the current platform.

An optimized build can be produced with:

$ cargo build --release

Testing

Many crates in this repository (located in crates/*) both have unit tests (#[test] functions throughout the source) and integration tests (crates/*/tests/*.rs). Testing an individual crate can be done with:

$ cargo test -p wasmparser

Running all tests can be done by first ensuring that the spec test suite is checked out:

$ git submodule update --init

and then using Cargo to execute all tests:

$ cargo test --workspace

The majority of all tests is located in tests/cli/* and can be run with:

$ cargo test --test cli

Each individual file is a standalone test and documents at the top how to run it. Running individual tests can be done through:

$ cargo test --test cli -- test_name_filter

Or you can use cargo run plus the test's arguments to run a single test.

$ cargo run wast tests/cli/empty.wast

Running just the spec test suite can be done with:

$ cargo test --test cli -- spec

and running a single spec test can be done with an argument to this command as a string filter on the filename.

$ cargo test --test cli binary-leb128.wast
$ cargo run wast tests/testsuite/binary-leb128.wast --ignore-error-messages

The tests/cli tests suite is documented as a self-describing test at tests/cli/readme.wat. Each test describes what subcommand of wasm-tools is run and the test is itself the input.

The tests/testsuite folder is a git submodule pointing to the upstream test suite repository and is where spec tests come from. The tests/snapshots folder contains golden output files which correspond to the wasmprinter-printed version of binaries of all tests. These files are used to view the impact of changes to wasmprinter.

Many tests throughout the repository have automatically generated files associated with them which reflect the expected output of an operation. This is done to view, during code review, the impact of changes made. It's not expected that these files need to be edited by hand, but instead setting the environment variable BLESS=1 when running tests will update all of these test expectations.

Continuous Integration

All changes to wasm-tools are required to pass the CI suite powered by GitHub Actions. Pull requests will automatically have checks performed and can only be merged once all tests are passing. CI checks currently include:

  • Code is all formatted correctly (use cargo fmt locally to pass this)
  • Tests pass on Rust stable, beta, and Nightly.
  • Tests pass on Linux, macOS, and Windows.
  • This tool can be compiled to WebAssembly using the wasm32-wasip1 target.
  • Fuzzers can be built.
  • Various miscellaneous checks such as building the tool with various combinations of Cargo features.

Fuzzing

This repository uses LLVM's libFuzzer through the cargo fuzz tool. Building fuzzers requires a Nightly Rust toolchain which can be acquired with Rustup-based installations of Rust by executing:

$ rustup update nightly

Next the cargo-fuzz runner should be installed:

$ cargo install cargo-fuzz

Fuzzers are then built with:

$ cargo +nightly fuzz build

Useful options to this can include:

  • --dev - build fuzzers in debug mode instead of release mode (default is release)
  • --sanitizer none - Rust doesn't benefit much from AddressSanitizer for example so disabling sanitizers can improve fuzzing performance and build more quickly too.

The fuzzing binary for this project is located at target/$host_target/release/run. Due to limitations on OSS-Fuzz all fuzzers are combined into a single binary at this time. This binary can be run with:

$ cargo +nightly fuzz run run

The main driver for fuzzing is located at fuzz/fuzz_targets/run.rs. This driver dispatches, based on the input, to a number of other fuzzers. Each individual fuzzer lives in fuzz/src/*.rs.

Running a single fuzzer can be done by configuring the FUZZER environment variable:

$ FUZZER=roundtrip cargo +nightly fuzz run run

More documentation of cargo fuzz can be found online.

Adding a new Crate

When a new crate is added to this repository it'll need to be accompanied with a reservation of the crate name on crates.io. That enables this repository to automatically manage publishing of the crate. The steps for adding a new crate are:

  • CI should fail when a new crate is added until the below steps are complete.
  • Update ci/publish.rs with the name of your crate in the array at the top.
  • A dummy empty crate should be published to crates.io with a small README pointing to this repository and indicating that it's a temporary name reservation until the first version is published from this repository's automation.
  • A "Trusted Publishing" workflow should be added for the new crate. The workflow filename is publish.yml and the environment name is release.
  • The crate should be exclusively owned by the wasmtime-publish crates.io user. This will require a wasm-tools maintainer to log in, accept the invite, and remove the prior owner.

After these steps have been completed CI should then pass and the crate will be auto-published from this repository on the next release.

Note that if you're adding a crate which is not published to crates.io you'll want to add publish = false to the manifest.

License

This project is licensed under the Apache 2.0 license with the LLVM exception. See LICENSE for more details.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache-2.0 license, shall be licensed as above, without any additional terms or conditions.