README.md
1# addr2line
2
3[](https://crates.io/crates/addr2line)
4[](https://docs.rs/addr2line)
5[](https://coveralls.io/github/gimli-rs/addr2line?branch=master)
6
7A cross-platform library for retrieving per-address debug information
8from files with DWARF debug information.
9
10`addr2line` uses [`gimli`](https://github.com/gimli-rs/gimli) to parse
11the debug information, and exposes an interface for finding
12the source file, line number, and wrapping function for instruction
13addresses within the target program. These lookups can either be
14performed programmatically through `Context::find_location` and
15`Context::find_frames`, or via the included example binary,
16`addr2line` (named and modelled after the equivalent utility from
17[GNU binutils](https://sourceware.org/binutils/docs/binutils/addr2line.html)).
18
19# Quickstart
20 - Add the [`addr2line` crate](https://crates.io/crates/addr2line) to your `Cargo.toml`
21 - Load the file and parse it with [`addr2line::object::read::File::parse`](https://docs.rs/object/*/object/read/struct.File.html#method.parse)
22 - Pass the parsed file to [`addr2line::Context::new` ](https://docs.rs/addr2line/*/addr2line/struct.Context.html#method.new)
23 - Use [`addr2line::Context::find_location`](https://docs.rs/addr2line/*/addr2line/struct.Context.html#method.find_location)
24 or [`addr2line::Context::find_frames`](https://docs.rs/addr2line/*/addr2line/struct.Context.html#method.find_frames)
25 to look up debug information for an address
26
27# Performance
28
29`addr2line` optimizes for speed over memory by caching parsed information.
30The DWARF information is parsed lazily where possible.
31
32The library aims to perform similarly to equivalent existing tools such
33as `addr2line` from binutils, `eu-addr2line` from elfutils, and
34`llvm-symbolize` from the llvm project, and in the past some benchmarking
35was done that indicates a comparable performance.
36
37## License
38
39Licensed under either of
40
41 * Apache License, Version 2.0 ([`LICENSE-APACHE`](./LICENSE-APACHE) or https://www.apache.org/licenses/LICENSE-2.0)
42 * MIT license ([`LICENSE-MIT`](./LICENSE-MIT) or https://opensource.org/licenses/MIT)
43
44at your option.
45
46Unless you explicitly state otherwise, any contribution intentionally submitted
47for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
48dual licensed as above, without any additional terms or conditions.
49
){kind=link}
){kind=link}
){kind=link}