khuey / thorin

DWARF packaging utility, written in Rust, supporting GNU extension and DWARF 5 package formats.

thorin

thorin is an DWARF packaging utility for creating DWARF packages (*.dwp files) out of input DWARF objects (*.dwo files; or *.o files with .dwo sections), supporting both the pre-standard GNU extension format for DWARF packages and the standardized format introduced in DWARF 5.

thorin was written as part of the implementation of Split DWARF in rustc. A Rust implementation of a DWARF packaging utility is easier to integrate into the compiler and can support features like loading dwarf objects from archive files (or rustc's rlibs) which are helpful in supporting cross-crate Split DWARF packaging in rustc.

See the README documents of the thorin crate and the thorin-bin crate for usage details of the library and binary interfaces respectively.

Contributing to thorin

If you want help or mentorship, reach out to us in a GitHub issue, or ask davidtwco or in #t-compiler on the Rust Zulip instance.

thorin should always build on stable rustc. To build thorin:

$ cargo build

To run the tests, first install the relevant dependencies:

$ apt install --no-install-recommends --yes llvm-13 llvm-13-tools
$ pip install lit

Next, run the lit testsuite (replacing /path/to/llvm/bin with the correct path to your LLVM installation, if required):

$ cargo build # in debug mode..
$ lit -v --path "$PWD/target/debug/:/path/to/llvm/bin/" ./tests
$ cargo build --release # ..or in release mode
$ lit -v --path "$PWD/target/release/:/path/to/llvm/bin/" ./tests

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

$ rustup component add rustfmt
$ cargo fmt

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 thorin! thorin should never panic unless it is explicitly documented to panic in the specific circumstances provided.

Name

^{thorin is named after Thorin Oakenshield from The Hobbit, as Thorin is a dwarf who leads other dwarves. thorin uses the gimli library (named after a dwarf from Lord of the Rings) to read DWARF format debug information, the name of which is a medieval fantasy complement to ELF, the file format for executables and object files.}
_{You could also call this project rust-dwp, if you'd prefer that.}

Author and acknowledgements

^{thorin is authored by David Wood of Huawei Technologies Research & Development (UK) Ltd. thorin is maintained by the Rust Compiler Team.}
_{In addition, thanks to the authors of object and gimli, on which this utility depends heavily; and to Philip Craig for advice and reviews during initial implementation of thorin.}

License

^{Licensed under either of Apache License, Version 2.0 or MIT license at your option.}
_{Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.}

Code of conduct

^{When contributing or interacting with this project, we ask abide the Rust Code of Conduct and ask that you do too.}