vendor/backtrace/README.md

   1 # backtrace-rs
   2
   3 [![Build Status](https://travis-ci.org/alexcrichton/backtrace-rs.svg?branch=master)](https://travis-ci.org/alexcrichton/backtrace-rs)
   4 [![Build status](https://ci.appveyor.com/api/projects/status/v4l9oj4aqbbgyx44?svg=true)](https://ci.appveyor.com/project/alexcrichton/backtrace-rs)
   5
   6 [Documentation](https://docs.rs/backtrace)
   7
   8 A library for acquiring backtraces at runtime for Rust. This library aims to
   9 enhance the support given by the standard library at `std::rt` by providing a
  10 more stable and programmatic interface.
  11
  12 ## Install
  13
  14 ```toml
  15 [dependencies]
  16 backtrace = "0.3"
  17 ```
  18
  19 ```rust
  20 extern crate backtrace;
  21 ```
  22
  23 Note that this crate requires `make`, `objcopy`, and `ar` to be present on Linux
  24 systems.
  25
  26 ## Usage
  27
  28 To simply capture a backtrace and defer dealing with it until a later time,
  29 you can use the top-level `Backtrace` type.
  30
  31 ```rust
  32 extern crate backtrace;
  33
  34 use backtrace::Backtrace;
  35
  36 fn main() {
  37     let bt = Backtrace::new();
  38
  39     // do_some_work();
  40
  41     println!("{:?}", bt);
  42 }
  43 ```
  44
  45 If, however, you'd like more raw access to the actual tracing functionality, you
  46 can use the `trace` and `resolve` functions directly.
  47
  48 ```rust
  49 extern crate backtrace;
  50
  51 fn main() {
  52     backtrace::trace(|frame| {
  53         let ip = frame.ip();
  54         let symbol_address = frame.symbol_address();
  55
  56         // Resolve this instruction pointer to a symbol name
  57         backtrace::resolve(ip, |symbol| {
  58             if let Some(name) = symbol.name() {
  59                 // ...
  60             }
  61             if let Some(filename) = symbol.filename() {
  62                 // ...
  63             }
  64         });
  65
  66         true // keep going to the next frame
  67     });
  68 }
  69 ```
  70
  71 ## Platform Support
  72
  73 This library currently supports OSX, Linux, and Windows. Support for other
  74 platforms is always welcome!
  75
  76 # License
  77
  78 This project is licensed under either of
  79
  80  * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
  81    http://www.apache.org/licenses/LICENSE-2.0)
  82  * MIT license ([LICENSE-MIT](LICENSE-MIT) or
  83    http://opensource.org/licenses/MIT)
  84
  85 at your option.
  86
  87 ### Contribution
  88
  89 Unless you explicitly state otherwise, any contribution intentionally submitted
  90 for inclusion in backtrace-rs by you, as defined in the Apache-2.0 license, shall be
  91 dual licensed as above, without any additional terms or conditions.