Crate stacktrace [] [src]

A library for using stack traces with Result.

Alex Crichton's excellent backtrace crate does the work required for actually getting information about the call stack on a variety of platforms. Stacktrace tries to make that information more ergonomic to use.

Quick Start

In your Cargo.toml:

stacktrace = "0.2"

In your project:

#[macro_use] extern crate stacktrace;


Example use

See also these examples.

#[macro_use] extern crate stacktrace;

pub struct Error1(usize);
pub struct Error2(String);

impl From<Error1> for Error2 {
    fn from(err: Error1) -> Error2 {
        Error2(format!("{}", err.0))

trace!{Error1 => Error2}

fn makes_a_traced_error() -> Result<(), Trace<Error1>> {
    try!(Err(Error1(1337))); // Uses generic instance of "From<Err>" for "Trace<Err>"

fn propagates_a_traced_error() -> Result<(), Trace<Error2>> {
    try!(makes_a_traced_error()); // Uses the macro-generated instance of "From<Trace<Error1>>" for "Trace<Error2>"

See the section Usage information for more.

Usage information

This crate is intended for use with binary crates. It provides a macro to define and use a Trace struct, which wraps errors with an associated stacktrace. The macro also defines instances of From for use with the standard try! macro.

These trait implementations are the reason the Trace struct needs to be defined with a macro in the user's crate, since two things prevent them being defined externally:

The call trace!{StructName; A => B, C => D, ...} will produce a struct StructName<E> with the following implementations:

If unspecified, StructName defaults to Trace.

Build profiles

For release builds, consider enabling debugging symbols if you want to keep useful stack trace information available. To do so, add the following to your Cargo.toml:

debug = true

For more information, see here.


pub extern crate backtrace;



Helper macro for defining a Trace struct, and instances of From<Trace<B>> for Trace<A>.