Skip to content

Commit a59b8ee

Browse files
davidtwcoDavid Wood
davidtwco
authored and
David Wood
committed
release version 0.1.1 and add per-crate readme
Instead of using the same README for both the library and binary crates, use a separate specific README for each. Upgrade the version to 0.1.1, including nagisa's patches. Signed-off-by: David Wood <david.wood@huawei.com>
1 parent 1dcaa5b commit a59b8ee

File tree

6 files changed

+181
-33
lines changed

6 files changed

+181
-33
lines changed

‎Cargo.lock

Lines changed: 2 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎README.md

Lines changed: 4 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -3,31 +3,9 @@
33
DWARF objects (`*.dwo` files; or `*.o` files with `.dwo` sections), supporting both the pre-standard
44
GNU extension format for DWARF packages and the standardized format introduced in DWARF 5.
55

6-
## Usage
7-
`thorin` can read input DWARF objects from executables or can package arbitrary input dwarf
8-
objects (including DWARF objects in archive files, such as Rust rlibs)!
9-
10-
```
11-
thorin 0.1.0
12-
merge dwarf objects into dwarf packages
13-
14-
USAGE:
15-
thorin [OPTIONS] [--] [inputs]...
16-
17-
FLAGS:
18-
-h, --help Prints help information
19-
-V, --version Prints version information
20-
21-
OPTIONS:
22-
-e, --exec <executables>... Specify path to executables to read list of dwarf objects from
23-
-o, --output <output> Specify path to write the dwarf package to [default: -]
24-
25-
ARGS:
26-
<inputs>... Specify path to input dwarf objects and packages
27-
```
28-
29-
If the input objects are of DWARF version 5 or greater, then the output package will be in DWARF 5
30-
format. For version 4 and below, the GNU Extension format will be used for the output package.
6+
See the README documents of the [`thorin` crate](thorin/README.md) and the
7+
[`thorin-bin` crate](thorin-bin/README.md) for usage details of the library and binary interfaces
8+
respectively.
319

3210
## Contributing to `thorin`
3311
If you want help or mentorship, reach out to us in a GitHub issue, or ask `davidtwco` on the
@@ -63,7 +41,7 @@ $ rustup component add rustfmt
6341
$ cargo fmt
6442
```
6543

66-
### Filing an Issue
44+
### Filing an issue
6745
Think you've found a bug? File an issue! To help us understand and reproduce the
6846
issue, provide us with:
6947

‎thorin-bin/Cargo.toml

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,13 @@ description = "Merge DWARF objects and packages into DWARF packages"
66
homepage = "https://github.com/davidtwco/thorin"
77
keywords = ["dwarf", "split-dwarf", "dwarf-package", "dwarf-object", "dwp"]
88
license = "MIT OR Apache-2.0"
9-
readme = "../README.md"
9+
readme = "README.md"
1010
repository = "https://github.com/davidtwco/thorin"
11-
version = "0.1.0"
11+
version = "0.1.1"
1212
edition = "2021"
1313

1414
[dependencies]
15-
thorin-dwp = { version = "0.1.0", path = "../thorin" }
15+
thorin-dwp = { version = "0.1.1", path = "../thorin" }
1616

1717
anyhow = "1.0.51"
1818
memmap2 = "0.5.0"

‎thorin-bin/README.md

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
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+
6+
## Usage
7+
`thorin` can read input DWARF objects from executables or can package arbitrary input dwarf
8+
objects (including DWARF objects in archive files, such as Rust rlibs)! Install `thorin` using
9+
`cargo`:
10+
11+
```shell-session
12+
$ cargo install thorin-dwp-bin
13+
$ thorin --help
14+
thorin 0.1.1
15+
merge dwarf objects into dwarf packages
16+
17+
USAGE:
18+
thorin [OPTIONS] [--] [inputs]...
19+
20+
FLAGS:
21+
-h, --help Prints help information
22+
-V, --version Prints version information
23+
24+
OPTIONS:
25+
-e, --exec <executables>... Specify path to executables to read list of dwarf objects from
26+
-o, --output <output> Specify path to write the dwarf package to [default: -]
27+
28+
ARGS:
29+
<inputs>... Specify path to input dwarf objects and packages
30+
```
31+
32+
If the input objects are of DWARF version 5 or greater, then the output package will be in DWARF 5
33+
format. For version 4 and below, the GNU Extension format will be used for the output package.
34+
35+
## Stability
36+
`thorin`'s command-line interface is intended to be stable and have limited breaking changes.
37+
38+
<br>
39+
40+
#### Name
41+
<sup>
42+
<code>thorin</code> is named after <i>Thorin Oakenshield</i> from <i>The Hobbit</i>, as Thorin is
43+
a dwarf who leads other dwarves. <code>thorin</code> uses the <code>gimli</code> library
44+
(named after a dwarf from <i>Lord of the Rings</i>) to read <i>DWARF</i> format debug information,
45+
the name of which is a medieval fantasy complement to <i>ELF</i>, the file format for executables
46+
and object files.
47+
</sup>
48+
49+
<br>
50+
51+
<sub>
52+
You could also call this project <code>rust-dwp</code>, if you'd prefer that.
53+
</sub>
54+
55+
<br>
56+
57+
#### Author and acknowledgements
58+
<sup>
59+
<code>thorin</code> is authored by <a href="https://davidtw.co">David Wood</a> of
60+
<i>Huawei Technologies Research & Development (UK) Ltd</i>.
61+
</sup>
62+
63+
<br>
64+
65+
<sub>
66+
In addition, thanks to the authors of <code>object</code> and <code>gimli</code>, on which this
67+
utility depends heavily; and to <a href="https://github.com/philipc">Philip Craig</a> for advice
68+
and reviews during initial implementation of <code>thorin</code>.
69+
</sub>
70+
71+
<br>
72+
73+
#### License
74+
<sup>
75+
Licensed under either of <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache License,
76+
Version 2.0</a> or <a href="https://opensource.org/licenses/MIT">MIT license</a> at your option.
77+
</sup>
78+
79+
<br>
80+
81+
<sub>
82+
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in
83+
this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without
84+
any additional terms or conditions.
85+
</sub>
86+
87+
<br>
88+
89+
#### Code of conduct
90+
<sup>
91+
When contributing or interacting with this project, we ask abide the
92+
<a href="https://www.rust-lang.org/en-US/conduct.html">Rust Code of Conduct</a> and ask that you do
93+
too.
94+
</sup>

‎thorin/Cargo.toml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,9 @@ description = "Library for building DWARF packages from input DWARF objects and
66
homepage = "https://docs.rs/thorin-dwp"
77
keywords = ["dwarf", "split-dwarf", "dwarf-package", "dwarf-object", "dwp"]
88
license = "MIT OR Apache-2.0"
9-
readme = "../README.md"
9+
readme = "README.md"
1010
repository = "https://github.com/davidtwco/thorin"
11-
version = "0.1.0"
11+
version = "0.1.1"
1212
edition = "2021"
1313

1414
[dependencies]

‎thorin/README.md

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
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+
6+
## Usage
7+
To use `thorin` in your own project, add it to your `Cargo.toml`:
8+
9+
```toml
10+
thorin-dwp = "0.1.1"
11+
```
12+
13+
See the [`thorin-bin`](../thorin-bin/README.md) crate for an example of using `thorin`'s library
14+
interface.
15+
16+
## Stability
17+
`thorin`'s library interface is intended for use by `rustc` for its *Split DWARF* support, it
18+
currently comes with no stability guarantees and may change at any time.
19+
20+
<br>
21+
22+
#### Name
23+
<sup>
24+
<code>thorin</code> is named after <i>Thorin Oakenshield</i> from <i>The Hobbit</i>, as Thorin is
25+
a dwarf who leads other dwarves. <code>thorin</code> uses the <code>gimli</code> library
26+
(named after a dwarf from <i>Lord of the Rings</i>) to read <i>DWARF</i> format debug information,
27+
the name of which is a medieval fantasy complement to <i>ELF</i>, the file format for executables
28+
and object files.
29+
</sup>
30+
31+
<br>
32+
33+
<sub>
34+
You could also call this project <code>rust-dwp</code>, if you'd prefer that.
35+
</sub>
36+
37+
<br>
38+
39+
#### Author and acknowledgements
40+
<sup>
41+
<code>thorin</code> is authored by <a href="https://davidtw.co">David Wood</a> of
42+
<i>Huawei Technologies Research & Development (UK) Ltd</i>.
43+
</sup>
44+
45+
<br>
46+
47+
<sub>
48+
In addition, thanks to the authors of <code>object</code> and <code>gimli</code>, on which this
49+
utility depends heavily; and to <a href="https://github.com/philipc">Philip Craig</a> for advice
50+
and reviews during initial implementation of <code>thorin</code>.
51+
</sub>
52+
53+
<br>
54+
55+
#### License
56+
<sup>
57+
Licensed under either of <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache License,
58+
Version 2.0</a> or <a href="https://opensource.org/licenses/MIT">MIT license</a> at your option.
59+
</sup>
60+
61+
<br>
62+
63+
<sub>
64+
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in
65+
this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without
66+
any additional terms or conditions.
67+
</sub>
68+
69+
<br>
70+
71+
#### Code of conduct
72+
<sup>
73+
When contributing or interacting with this project, we ask abide the
74+
<a href="https://www.rust-lang.org/en-US/conduct.html">Rust Code of Conduct</a> and ask that you do
75+
too.
76+
</sup>

0 commit comments

Comments
 (0)