CONTRIBUTING.md

Contributing to gimli

Hi! We'd love to have your contributions! If you want help or mentorship, reach out to us in a GitHub issue, or ping fitzgen in #rust on irc.mozilla.org.

• Code of Conduct
• Filing an Issue
• Building gimli
• Testing gimli
  • Test Coverage
  • Using test-assembler
  • Fuzzing
• Benchmarking
• Style

Code of Conduct

We abide by the Rust Code of Conduct and ask that you do as well.

Filing an Issue

Think you've found a bug? File an issue! To help us understand and reproduce the issue, provide us with:

• The (preferably minimal) test case
• Steps to reproduce the issue using the test case
• The expected result of following those steps
• The actual result of following those steps

Definitely file an issue if you see an unexpected panic originating from within gimli! gimli should never panic unless it is explicitly documented to panic in the specific circumstances provided.

Building gimli

gimli should always build on stable rustc, but we recommend using rustup so you can switch to nightly rustc and run benchmarks.

To build gimli:

$ cargo build

Testing gimli

Run the tests with cargo:

$ cargo test

Test Coverage

If you have kcov installed under linux, then you can generate code coverage results using the coverage script in the root of the repository, and view them at target/kcov/index.html. Otherwise you can create a pull request and view the coverage results on coveralls.io.

$ ./coverage

The ideal we aim to reach is having our unit tests exercise every branch in gimli. We allow an exception for branches which propagate errors inside a try!(..) invocation, but we do want to exercise the original error paths.

Pull requests adding new code should ensure that this ideal is met.

At the time of writing we have 94% test coverage according to our coveralls.io continuous integration. That number should generally stay the same or go up ;) This is a bit subjective, because -.001% is just noise and doesn't matter.

Using test-assembler

We use the awesome test-assembler crate to construct binary test data. It makes building complex test cases readable.

Here is an example usage in gimli

Fuzzing

First, install cargo fuzz:

$ cargo install cargo-fuzz

Optionally, set up the corpora for our fuzz targets by following these instructions.

Finally, run a fuzz target! In this case, we are running the eh_frame fuzz target:

$ cargo fuzz run eh_frame

The fuzz target definitions live in fuzz/fuzz_targets/*. You can add new ones via cargo fuzz add <my_new_target>.

Benchmarking

The benchmarks require nightly rustc, so use rustup:

$ rustup run nightly cargo bench

We aim to be the fastest DWARF library. Period.

Please provide before and after benchmark results with your pull requests. You may also find cargo benchcmp handy for comparing results.

Pull requests adding #[bench] micro-benchmarks that exercise a new edge case are very welcome!

Style

We use rustfmt to automatically format and style all of our code.

To install rustfmt:

$ rustup component add rustfmt-preview

To run rustfmt on gimli:

$ cargo fmt