1 # Contributing to `gimli`
3 Hi! We'd love to have your contributions! If you want help or mentorship, reach
4 out to us in a GitHub issue, or ping `fitzgen` in `#rust` on `irc.mozilla.org`.
6 * [Code of Conduct](#coc)
7 * [Filing an Issue](#issues)
8 * [Building `gimli`](#building)
9 * [Testing `gimli`](#testing)
10 * [Test Coverage](#coverage)
11 * [Using `test-assembler`](#test-assembler)
13 * [Benchmarking](#benchmarking)
16 ## <a id="coc"></a> Code of Conduct
19 [Rust Code of Conduct](https://www.rust-lang.org/en-US/conduct.html) and ask
22 ## <a id="issues"></a> Filing an Issue
24 Think you've found a bug? File an issue! To help us understand and reproduce the
25 issue, provide us with:
27 * The (preferably minimal) test case
28 * Steps to reproduce the issue using the test case
29 * The expected result of following those steps
30 * The actual result of following those steps
32 Definitely file an issue if you see an unexpected panic originating from within
33 `gimli`! `gimli` should never panic unless it is explicitly documented to panic
34 in the specific circumstances provided.
36 ## <a id="building"></a> Building `gimli`
38 `gimli` should always build on stable `rustc`, but we recommend using
39 [`rustup`](https://www.rustup.rs/) so you can switch to nightly `rustc` and run
48 ## <a id="testing"></a> Testing `gimli`
50 Run the tests with `cargo`:
56 ### <a id="coverage"></a> Test Coverage
58 If you have `kcov` installed under linux, then you can generate code coverage
59 results using the `coverage` script in the root of the repository, and view them
60 at `target/kcov/index.html`. Otherwise you can create a pull request and view
61 the coverage results on coveralls.io.
67 The ideal we aim to reach is having our unit tests exercise every branch in
68 `gimli`. We allow an exception for branches which propagate errors inside a
69 `try!(..)` invocation, but we *do* want to exercise the original error paths.
71 Pull requests adding new code should ensure that this ideal is met.
73 At the time of writing we have 94% test coverage according to our coveralls.io
74 continuous integration. That number should generally stay the same or go up ;)
75 This is a bit subjective, because -.001% is just noise and doesn't matter.
77 ### <a id="test-assembler"></a> Using `test-assembler`
80 [`test-assembler`](https://github.com/luser/rust-test-assembler) crate to
81 construct binary test data. It makes building complex test cases readable.
83 [Here is an example usage in `gimli`](https://github.com/gimli-rs/gimli/blob/156451f3fe6eeb2fa62b84b362c33fcb176e1171/src/loc.rs#L263)
85 ### <a id="fuzzing"></a> Fuzzing
87 First, install `cargo fuzz`:
90 $ cargo install cargo-fuzz
93 Optionally, [set up the corpora for our fuzz targets by following these
94 instructions](https://github.com/gimli-rs/gimli-libfuzzer-corpora/blob/master/README.md#using-these-corpora).
96 Finally, run a fuzz target! In this case, we are running the `eh_frame` fuzz
100 $ cargo fuzz run eh_frame
103 The fuzz target definitions live in `fuzz/fuzz_targets/*`. You can add new ones
104 via `cargo fuzz add <my_new_target>`.
106 ## <a id="benchmarking"></a> Benchmarking
108 The benchmarks require nightly `rustc`, so use `rustup`:
111 $ rustup run nightly cargo bench
114 We aim to be the fastest DWARF library. Period.
116 Please provide before and after benchmark results with your pull requests. You
117 may also find [`cargo benchcmp`](https://github.com/BurntSushi/cargo-benchcmp)
118 handy for comparing results.
120 Pull requests adding `#[bench]` micro-benchmarks that exercise a new edge case
123 ## <a id="style"></a> Style
125 We use `rustfmt` to automatically format and style all of our code.
127 To install `rustfmt`:
130 $ rustup component add rustfmt-preview
133 To run `rustfmt` on `gimli`: