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:

[dependencies]
stacktrace = "0.2"

In your project:

#[macro_use] extern crate stacktrace;

trace!{}

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>"
    Ok(())
}

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>"
    Ok(())
}

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:

Because of the generic impl<A> From<A> for A in the standard library, we can't implement a generic impl<A, B: From<A>> From<Trace<A>> for Trace, since rustc first sees this as impl From<Trace<_>> for Trace<_>.
If Trace were defined in this crate, then users wouldn't be able to implement From<A> for Trace because of the trait coherence rules.

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

Deref<E>
DerefMut<E>
From<A> for StructName, which requires From<A> for B
From<C> for StructName<D>, etc.
From<StructName<A>> for StructName, which also requires From<A> for B
From<StructName<C>> for StructName<D>, etc.
Debug, which will print the inner error then the stack trace in the same format as the one defined for Backtrace.

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:

[profile.release]
debug = true

For more information, see here.

Reexports

pub extern crate backtrace;

Macros

trace!

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