itsscb/eyre
1
0
Fork 0
mirror of https://github.com/eyre-rs/eyre.git synced 2025-09-28 05:21:34 +00:00
Code Issues Packages Projects Releases Wiki Activity

Explain backtrace env variable combinations

Browse Source
This commit is contained in:
David Tolnay 2020-03-14 13:13:02 -07:00
parent c01ceafc87
commit 4bebd2ab1e
No known key found for this signature in database
GPG Key ID: F9BA143B95FF6D82
3 changed files with 31 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
README.md
View File

@ -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

12
src/error.rs
View File

@ -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 {

13
src/lib.rs
View File

@ -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)`