Document unwinding limitations (#407)

* Document unwinding limitations

Following the discussion in #397 seems like this is a missing section of
the documentation! It seems worthwhile to document some pitfalls and
mitigations if possible.

* Update split-debuginfo support to nightly

.github/workflows/main.yml

@@ -87,9 +87,11 @@ jobs:
       if: contains(matrix.os, 'ubuntu')
     - run: RUSTFLAGS="-C link-arg=-Wl,--compress-debug-sections=zlib-gnu" cargo test --features gimli-symbolize
       if: contains(matrix.os, 'ubuntu')
-    - run: cargo clean && RUSTFLAGS="-Z run-dsymutil=no" cargo test --features gimli-symbolize
+    - run: cargo clean && RUSTFLAGS="-C split-debuginfo=unpacked" cargo test --features gimli-symbolize
       if: matrix.thing == 'macos-nightly'
-    - run: cargo clean && RUSTFLAGS="-Z split-dwarf=split -C save-temps" cargo test --features gimli-symbolize
+    - run: cargo clean && RUSTFLAGS="-C split-debuginfo=unpacked -Zunstable-options" cargo test --features gimli-symbolize
+      if: matrix.thing == 'nightly'
+    - run: cargo clean && RUSTFLAGS="-C split-debuginfo=packed -Zunstable-options" cargo test --features gimli-symbolize
       if: matrix.thing == 'nightly'
     - run: cargo build --manifest-path crates/as-if-std/Cargo.toml
 

src/lib.rs

@@ -40,6 +40,51 @@
 //! }
 //! # }
 //! ```
+//!
+//! # Backtrace accuracy
+//!
+//! This crate implements best-effort attempts to get the native backtrace. This
+//! is not always guaranteed to work, and some platforms don't return any
+//! backtrace at all. If your application requires accurate backtraces then it's
+//! recommended to closely evaluate this crate to see whether it's suitable
+//! for your use case on your target platforms.
+//!
+//! Even on supported platforms, there's a number of reasons that backtraces may
+//! be less-than-accurate, including but not limited to:
+//!
+//! * Unwind information may not be available. This crate primarily implements
+//!   backtraces by unwinding the stack, but not all functions may have
+//!   unwinding information (e.g. DWARF unwinding information).
+//!
+//! * Rust code may be compiled without unwinding information for some
+//!   functions. This can also happen for Rust code compiled with
+//!   `-Cpanic=abort`. You can remedy this, however, with
+//!   `-Cforce-unwind-tables` as a compiler option.
+//!
+//! * Unwind information may be inaccurate or corrupt. In the worst case
+//!   inaccurate unwind information can lead this library to segfault. In the
+//!   best case inaccurate information will result in a truncated stack trace.
+//!
+//! * Backtraces may not report filenames/line numbers correctly due to missing
+//!   or corrupt debug information. This won't lead to segfaults unlike corrupt
+//!   unwinding information, but missing or malformed debug information will
+//!   mean that filenames and line numbers will not be available. This may be
+//!   because debug information wasn't generated by the compiler, or it's just
+//!   missing on the filesystem.
+//!
+//! * Not all platforms are supported. For example there's no way to get a
+//!   backtrace on WebAssembly at the moment.
+//!
+//! * Crate features may be disabled. Currently this crate supports using Gimli
+//!   libbacktrace on non-Windows platforms for reading debuginfo for
+//!   backtraces. If both crate features are disabled, however, then these
+//!   platforms will generate a backtrace but be unable to generate symbols for
+//!   it.
+//!
+//! In most standard workflows for most standard platforms you generally don't
+//! need to worry about these caveats. We'll try to fix ones where we can over
+//! time, but otherwise it's important to be aware of the limitations of
+//! unwinding-based backtraces!
 
 #![doc(html_root_url = "https://docs.rs/backtrace")]
 #![deny(missing_docs)]