Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
129 lines (84 loc) · 3.4 KB

CONTRIBUTING.md

File metadata and controls

129 lines (84 loc) · 3.4 KB

Contributing to cpp_demangle

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 and introduce yourself.

Code of Conduct

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

Filing an Issue

When filing an issue, please provide:

  • The mangled C++ symbol name, and
  • The way that cpp_demangle demangled it (or failed to)

cpp_demangle should never panic or crash. If you find some input that causes a panic or crash, please file an issue!

Building

$ cargo build

Testing

To run all the tests:

$ cargo test

Testing libiberty Compatibility

We currently have partial compatibility with the canonical GNU C++ demangler in libiberty. Work towards full compatibility is ongoing. To run all of libiberty's tests (many of which are failing due to formatting differences and malformatting on cpp_demangle's part) you can enable the run_libiberty_tests feature when testing:

$ cargo test --features run_libiberty_tests

As more libiberty tests start passing, we start including them in our test suite by default. Help getting more of libiberty's tests passing is very appreciated! See LIBIBERTY_TEST_THRESHOLD in build.rs for details.

Debugging

The logging feature adds debug logging that is very helpful when trying to determine how a mangled symbol is parsed, and what its substitutions table looks like:

$ cargo test --feature logging <some-test-you-are-debugging>

Fuzzing

Fuzzing with cargo-fuzz and libFuzzer

This is a bit easier to set up than AFL. See the cargo-fuzz book for details.

  1. $ cargo install cargo-fuzz
  2. $ cargo fuzz parse_and_stringify

Alternatively, run cargo fuzz list to get a list of fuzz targets to run instead of the parse_and_stringify target.

Fuzzing with AFL

What follows is a TLDR, for detailed instructions see the afl.rs book.

  1. Install the afl.rs command line tool:

    cargo install afl

  2. Build the cpp_mangle AFL fuzz target:

    cargo afl build --features afl

  3. Run AFL:

    cargo afl fuzz -i in -o out target/debug/afl_runner

Automatic code formatting

We use rustfmt to enforce a consistent code style across the whole cpp_demangle code base.

You can install the latest version of rustfmt with this command:

$ cargo install -f rustfmt

Ensure that ~/.cargo/bin is on your path.

Once that is taken care of, you can (re)format all code by running this command:

$ cargo fmt

The code style is described in the rustfmt.toml file in top level of the repo.