]>
Commit | Line | Data |
---|---|---|
a2a8927a XL |
1 | # `thorin` |
2 | `thorin` is an DWARF packaging utility for creating DWARF packages (`*.dwp` files) out of input | |
3 | DWARF objects (`*.dwo` files; or `*.o` files with `.dwo` sections), supporting both the pre-standard | |
4 | GNU extension format for DWARF packages and the standardized format introduced in DWARF 5. | |
5 | ||
5099ac24 FG |
6 | `thorin` was written as part of the implementation of Split DWARF in `rustc`. A Rust implementation |
7 | of a DWARF packaging utility is easier to integrate into the compiler and can support features like | |
8 | loading dwarf objects from archive files (or rustc's rlibs) which are helpful in supporting | |
9 | cross-crate Split DWARF packaging in `rustc`. | |
10 | ||
a2a8927a XL |
11 | ## Usage |
12 | To use `thorin` in your own project, add it to your `Cargo.toml`: | |
13 | ||
14 | ```toml | |
5099ac24 | 15 | thorin-dwp = "0.2.0" |
a2a8927a XL |
16 | ``` |
17 | ||
18 | See the [`thorin-bin`](../thorin-bin/README.md) crate for an example of using `thorin`'s library | |
19 | interface. | |
20 | ||
21 | ## Stability | |
22 | `thorin`'s library interface is intended for use by `rustc` for its *Split DWARF* support, it | |
23 | currently comes with no stability guarantees and may change at any time. | |
24 | ||
25 | <br> | |
26 | ||
27 | #### Name | |
28 | <sup> | |
29 | <code>thorin</code> is named after <i>Thorin Oakenshield</i> from <i>The Hobbit</i>, as Thorin is | |
30 | a dwarf who leads other dwarves. <code>thorin</code> uses the <code>gimli</code> library | |
31 | (named after a dwarf from <i>Lord of the Rings</i>) to read <i>DWARF</i> format debug information, | |
32 | the name of which is a medieval fantasy complement to <i>ELF</i>, the file format for executables | |
33 | and object files. | |
34 | </sup> | |
35 | ||
36 | <br> | |
37 | ||
38 | <sub> | |
39 | You could also call this project <code>rust-dwp</code>, if you'd prefer that. | |
40 | </sub> | |
41 | ||
42 | <br> | |
43 | ||
44 | #### Author and acknowledgements | |
45 | <sup> | |
5099ac24 FG |
46 | <code>thorin</code> is authored by <a href="https://davidtw.co">David Wood</a> of <i>Huawei |
47 | Technologies Research & Development (UK) Ltd</i>. <code>thorin</code> is maintained by the | |
48 | <a href="https://rust-lang.org/governance/teams/compiler">Rust Compiler Team</a>. | |
a2a8927a XL |
49 | </sup> |
50 | ||
51 | <br> | |
52 | ||
53 | <sub> | |
54 | In addition, thanks to the authors of <code>object</code> and <code>gimli</code>, on which this | |
55 | utility depends heavily; and to <a href="https://github.com/philipc">Philip Craig</a> for advice | |
56 | and reviews during initial implementation of <code>thorin</code>. | |
57 | </sub> | |
58 | ||
59 | <br> | |
60 | ||
61 | #### License | |
62 | <sup> | |
63 | Licensed under either of <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache License, | |
64 | Version 2.0</a> or <a href="https://opensource.org/licenses/MIT">MIT license</a> at your option. | |
65 | </sup> | |
66 | ||
67 | <br> | |
68 | ||
69 | <sub> | |
70 | Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in | |
71 | this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without | |
72 | any additional terms or conditions. | |
73 | </sub> | |
74 | ||
75 | <br> | |
76 | ||
77 | #### Code of conduct | |
78 | <sup> | |
79 | When contributing or interacting with this project, we ask abide the | |
80 | <a href="https://www.rust-lang.org/en-US/conduct.html">Rust Code of Conduct</a> and ask that you do | |
81 | too. | |
82 | </sup> |