README.md

color-backtrace

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.7" }

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

Screenshot

Reducing transitive dependencies

It is possible to use the alternative btparse backtrace capturing backend instead of the default route that links backtrace:

[dependencies]
color-backtrace = {
  version = "0.7",
  default-features = false,
  features = ["use-btparse-crate"],
}

This reduces the number of transitive dependencies from around 12 to just 2. So why isn't this the default, you may ask? There's a stability tradeoff here: btparse relies on the undocumented and unstable std::fmt::Debug implementation of std::backtrace::Backtrace to remain unchanged. As of writing, this has been untouched for 4+ years, but there's no guarantee that it will always work.

Dependency tree with `use-backtrace-crate` (default)

$ cargo tree
color-backtrace v0.6.1 (/Users/ath/Development/color-backtrace)
├── backtrace v0.3.73
│   ├── addr2line v0.22.0
│   │   └── gimli v0.29.0
│   ├── cfg-if v1.0.0
│   ├── libc v0.2.155
│   ├── miniz_oxide v0.7.4
│   │   └── adler v1.0.2
│   ├── object v0.36.1
│   │   └── memchr v2.7.4
│   └── rustc-demangle v0.1.24
│   [build-dependencies]
│   └── cc v1.1.1
└── termcolor v1.4.1

Dependency tree with `use-btparse-crate`

$ cargo tree --no-default-features --features=use-btparse-crate
color-backtrace v0.6.1 (/Users/ath/Development/color-backtrace)
├── btparse v0.2.0 (https://github.com/yaahc/btparse.git?rev=54f9ddb8c7c8f8e034226fdcacab93cd76e1453b#54f9ddb8)
└── termcolor v1.4.1

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.