1# Contributing to `cpp_demangle`
2
3Hi! We'd love to have your contributions! If you want help or mentorship, reach
4out to us in a GitHub issue, or ping `fitzgen`
5in [#rust on irc.mozilla.org](irc://irc.mozilla.org#rust) and introduce
6yourself.
7
8<!-- START doctoc generated TOC please keep comment here to allow auto update -->
9<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
10
11
12- [Code of Conduct](#code-of-conduct)
13- [Filing an Issue](#filing-an-issue)
14- [Building](#building)
15- [Testing](#testing)
16  - [Testing `libiberty` Compatibility](#testing-libiberty-compatibility)
17- [Debugging](#debugging)
18- [Fuzzing with AFL](#fuzzing-with-afl)
19- [Automatic code formatting](#automatic-code-formatting)
20
21<!-- END doctoc generated TOC please keep comment here to allow auto update -->
22
23## Code of Conduct
24
25We abide by the [Rust Code of Conduct][coc] and ask that you do as well.
26
27[coc]: https://www.rust-lang.org/en-US/conduct.html
28
29## Filing an Issue
30
31When filing an issue, please provide:
32
33* The mangled C++ symbol name, and
34* The way that `cpp_demangle` demangled it (or failed to)
35
36`cpp_demangle` should *never* panic or crash. If you find some input that causes
37a panic or crash, **please file an issue!**
38
39## Building
40
41```
42$ cargo build
43```
44
45## Testing
46
47To run all the tests:
48
49```
50$ cargo test
51```
52
53### Testing `libiberty` Compatibility
54
55We currently have partial compatibility with the canonical GNU C++ demangler in
56`libiberty`. Work towards full compatibility is ongoing. To run all of
57`libiberty`'s tests (many of which are failing due to formatting differences and
58malformatting on `cpp_demangle`'s part) you can enable the `run_libiberty_tests`
59feature when testing:
60
61```
62$ cargo test --features run_libiberty_tests
63```
64
65As more `libiberty` tests start passing, we start including them in our test
66suite by default. Help getting more of `libiberty`'s tests passing is very
67appreciated! See `LIBIBERTY_TEST_THRESHOLD` in `build.rs` for details.
68
69## Debugging
70
71The `logging` feature adds debug logging that is very helpful when trying to
72determine how a mangled symbol is parsed, and what its substitutions table looks
73like:
74
75```
76$ cargo test --feature logging <some-test-you-are-debugging>
77```
78
79## Fuzzing
80
81### Fuzzing with `cargo-fuzz` and `libFuzzer`
82
83This is a bit easier to set up than
84AFL. See
85[the `cargo-fuzz` book for details](https://rust-fuzz.github.io/book/cargo-fuzz/tutorial.html).
86
871. `$ cargo install cargo-fuzz`
882. `$ cargo fuzz parse_and_stringify`
89
90Alternatively, run `cargo fuzz list` to get a list of fuzz targets to run
91instead of the `parse_and_stringify` target.
92
93### Fuzzing with AFL
94
95What follows is a TLDR, for detailed instructions see
96the [`afl.rs` book](https://rust-fuzz.github.io/book/afl/setup.html).
97
981. Install the afl.rs command line tool:
99
100    `cargo install afl`
101
1021. Build the cpp_mangle AFL fuzz target:
103
104    `cargo afl build --features afl`
105
1061. Run AFL:
107
108     `cargo afl fuzz -i in -o out target/debug/afl_runner`
109
110## Automatic code formatting
111
112We use [`rustfmt`](https://github.com/rust-lang-nursery/rustfmt) to enforce a
113consistent code style across the whole `cpp_demangle` code base.
114
115You can install the latest version of `rustfmt` with this command:
116
117```
118$ cargo install -f rustfmt
119```
120
121Ensure that `~/.cargo/bin` is on your path.
122
123Once that is taken care of, you can (re)format all code by running this command:
124
125```
126$ cargo fmt
127```
128
129The code style is described in the `rustfmt.toml` file in top level of the repo.
130