From 4bebd2ab1ea2406731316ce28060e1965531d0d4 Mon Sep 17 00:00:00 2001 From: David Tolnay Date: Sat, 14 Mar 2020 13:13:02 -0700 Subject: [PATCH] Explain backtrace env variable combinations --- README.md | 12 ++++++++++-- src/error.rs | 12 ++++++++++-- src/lib.rs | 13 +++++++++++-- 3 files changed, 31 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 16c0b42..f434e34 100644 --- a/README.md +++ b/README.md @@ -75,8 +75,16 @@ anyhow = "1.0" ``` - A backtrace is captured and printed with the error if the underlying error - type does not already provide its own. In order to see backtraces, the - `RUST_LIB_BACKTRACE=1` environment variable must be defined. + type does not already provide its own. In order to see backtraces, they must + be enabled through the environment variables described in [`std::backtrace`]: + + - If you want panics and errors to both have backtraces, set + `RUST_BACKTRACE=1`; + - If you want only errors to have backtraces, set `RUST_LIB_BACKTRACE=1`; + - If you want only panics to have backtraces, set `RUST_BACKTRACE=1` and + `RUST_LIB_BACKTRACE=0`. + + [`std::backtrace`]: https://doc.rust-lang.org/std/backtrace/index.html#environment-variables - Anyhow works with any error type that has an impl of `std::error::Error`, including ones defined in your crate. We do not bundle a `derive(Error)` macro diff --git a/src/error.rs b/src/error.rs index 88526df..fbb8379 100644 --- a/src/error.rs +++ b/src/error.rs @@ -290,11 +290,19 @@ impl Error { /// Backtraces are only available on the nightly channel. Tracking issue: /// [rust-lang/rust#53487][tracking]. /// - /// In order for the backtrace to be meaningful, the environment variable - /// `RUST_LIB_BACKTRACE=1` must be defined. Backtraces are somewhat + /// In order for the backtrace to be meaningful, one of the two environment + /// variables `RUST_LIB_BACKTRACE=1` or `RUST_BACKTRACE=1` must be defined + /// and `RUST_LIB_BACKTRACE` must not be `0`. Backtraces are somewhat /// expensive to capture in Rust, so we don't necessarily want to be /// capturing them all over the place all the time. /// + /// - If you want panics and errors to both have backtraces, set + /// `RUST_BACKTRACE=1`; + /// - If you want only errors to have backtraces, set + /// `RUST_LIB_BACKTRACE=1`; + /// - If you want only panics to have backtraces, set `RUST_BACKTRACE=1` and + /// `RUST_LIB_BACKTRACE=0`. + /// /// [tracking]: https://github.com/rust-lang/rust/issues/53487 #[cfg(backtrace)] pub fn backtrace(&self) -> &Backtrace { diff --git a/src/lib.rs b/src/lib.rs index 39bd6a0..98f1aba 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -121,8 +121,17 @@ //! ``` //! //! - A backtrace is captured and printed with the error if the underlying error -//! type does not already provide its own. In order to see backtraces, the -//! `RUST_LIB_BACKTRACE=1` environment variable must be defined. +//! type does not already provide its own. In order to see backtraces, they +//! must be enabled through the environment variables described in +//! [`std::backtrace`]: +//! +//! - If you want panics and errors to both have backtraces, set +//! `RUST_BACKTRACE=1`; +//! - If you want only errors to have backtraces, set `RUST_LIB_BACKTRACE=1`; +//! - If you want only panics to have backtraces, set `RUST_BACKTRACE=1` and +//! `RUST_LIB_BACKTRACE=0`. +//! +//! [`std::backtrace`]: https://doc.rust-lang.org/std/backtrace/index.html#environment-variables //! //! - Anyhow works with any error type that has an impl of `std::error::Error`, //! including ones defined in your crate. We do not bundle a `derive(Error)`