vendor/addr2line-0.14.0/README.md

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