color-backtrace 0.4.0

Colorful panic backtraces
Documentation

color-backtrace

Crates.io docs.rs MIT licensed

A Rust library that makes panics a little less painful by nicely colorizing them and printing the relevant source snippets.

[dependencies]
color-backtrace = { version = "0.3" }

To enable it, simply place this code somewhere in your app initialization code:

color_backtrace::install();

If you want to customize some settings, you can instead do:

use color_backtrace::{default_output_stream, BacktracePrinter};
BacktracePrinter::new().message("Custom message!").install(default_output_stream());

Features

  • Colorize backtraces to be easier on the eyes
  • Show source snippets if source files are found on disk
  • Print frames of application code vs dependencies in different color
  • Hide all the frames after the panic was already initiated
  • Hide language runtime initialization frames

Optional Features

  • failure-bt — Experimental support for printing failure::Backtrace backtraces.

Experimental Failure backtrace integration

failure backtraces are opaque and so this feature uses unsafe code to transmute the struct into a non private struct to allow access to the internal backtrace::Backtrace object.

The code is dependent on and only tested against failure version 0.1.5 and is considered a temporary hack while we work on getting backtraces from errors exposed properly. This feature is marked as unsafe, it relies on UB to work, and there is no guarantee that rust will pick this layout on a different crate type. User discretion is advised.

To enable, include the following in your Cargo.toml

[dependencies]
color-backtrace = { version = "0.3", features = ["failure-bt"] }

Reducing transitive dependencies

In order to reduce transitive dependencies, you can disable the default enabled gimli-symbolize feature by adding a default-features = false clause to your Cargo.toml dependency entry, e.g.:

[dependencies]
color-backtrace = { version = "0.3", default-features = false }

This will reduce dependencies from ~50 → ~10. However, you'll pay for it with inaccurate source info on macOS and Linux

Usage in tests

Unfortunately, defining custom init functions run before tests are started is currently not supported in Rust. Since initializing color-backtrace in each and every test is tedious even when wrapping it into a function, I recommended using the ctor crate for this.

Somewhere, preferably in your crate's main module, put the following code:

#[cfg(test)]
mod tests {
    use ctor::ctor;

    #[ctor]
    fn init_color_backtrace() {
        color_backtrace::install();
    }
}

You can also do this outside of a #[cfg(test)] section, in which case the panic handler is installed for both test and regular runs.

Screenshot

Screenshot