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