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.
5 Sep 27, 2022
5 Apr 3, 2023
4 Oct 19, 2023
2 Jan 2, 2022
3 May 10, 2023
5 Sep 22, 2023
17 Mar 22, 2023
11 Dec 30, 2022
6 Dec 25, 2022
2 Jul 9, 2023
5 Jul 21, 2022
10 Aug 12, 2022
4 May 3, 2022
44 Dec 27, 2022
4 Jul 9, 2022
57 Dec 22, 2022
5 Dec 7, 2022
2 Dec 15, 2022
5 May 29, 2023