Migrate towards sunsetting features on this crate (#323)

* Move `kernel32` dependency to deprecated section

This hasn't been used in ages actually!

* Remove the `unix-backtrace` feature

AFAIK there's not actual use case for this. This was added ages ago when
backtrace functionality was first implemented but we've always preferred
libunwind as an unwinder since it's more accurate. No platform uses this
by default today, so this commit is removing the support and we can
re-add it pretty easily if necessary for a new platform.

* Make libunwind/dbghelp features defunkt

AFAIK there's no current users of this crate who are tweaking the
various methods of capturing a backtrace or symbolizing a backtrace. I
believe everyone's just largely using the default features. Additionally
it would be extremely hard to *not* use the default features given the
wide usage of this crate.

Given all this this commit simply removes the option of doing so.
Instead this crate will automatically select the best implementation
strategy per-platform and will provide the necessary support to enable
it. It's intended to that this should give a much better default
experience the avoids futzing around with features so much.

Author: alexcrichton

.github/workflows/main.yml

@@ -59,21 +59,14 @@ jobs:
     - run: cargo build
     - run: cargo test
     - run: cargo test --features "gimli-symbolize"
+    - run: cargo test --features "serialize-rustc"
+    - run: cargo test --features "serialize-serde"
+    - run: cargo test --features "verify-winapi"
+    - run: cargo test --features "cpp_demangle"
     - run: cargo test --no-default-features
+    - run: cargo test --no-default-features --features "libbacktrace"
+    - run: cargo test --no-default-features --features "gimli-symbolize"
     - run: cargo test --no-default-features --features "std"
-    - run: cargo test --no-default-features --features "libunwind std"
-    - run: cargo test --no-default-features --features "libunwind dladdr std"
-    - run: cargo test --no-default-features --features "libunwind libbacktrace std"
-    - run: cargo test --no-default-features --features "libunwind libbacktrace dbghelp std"
-    - run: cargo test --no-default-features --features "unix-backtrace std"
-    - run: cargo test --no-default-features --features "unix-backtrace dladdr std"
-    - run: cargo test --no-default-features --features "unix-backtrace libbacktrace std"
-    - run: cargo test --no-default-features --features "serialize-serde std"
-    - run: cargo test --no-default-features --features "serialize-rustc std"
-    - run: cargo test --no-default-features --features "serialize-rustc serialize-serde std"
-    - run: cargo test --no-default-features --features "cpp_demangle std"
-    - run: cargo test --no-default-features --features "dbghelp std"
-    - run: cargo test --no-default-features --features "dbghelp std verify-winapi"
     - run: cargo test --manifest-path crates/cpp_smoke_test/Cargo.toml
     - run: cargo test --manifest-path crates/macos_frames_test/Cargo.toml
     - run: cargo test --features libbacktrace --manifest-path crates/without_debuginfo/Cargo.toml

Cargo.toml

@@ -54,29 +54,11 @@ winapi = { version = "0.3.3", optional = true }
 # Note that not all features are available on all platforms, so even though a
 # feature is enabled some other feature may be used instead.
 [features]
-default = ["std", "libunwind", "libbacktrace", "dbghelp"]
+default = ["std", "libbacktrace"]
 
 # Include std support.
 std = []
 
-#=======================================
-# Methods of acquiring a backtrace
-#
-# - libunwind: when using this the libgcc library is linked against to get
-#   the unwinding support. This is generally the most reliable method to get
-#   a backtrace on unix.
-# - unix-backtrace: this uses the backtrace(3) function to acquire a
-#   backtrace, but is not as reliable as libunwind. It is, however,
-#   generally found in more locations.
-# - dbghelp: on windows this enables usage of dbghelp.dll to find a
-#   backtrace at runtime
-# - kernel32: on windows this enables using RtlCaptureStackBackTrace as the
-#   function to acquire a backtrace
-libunwind = []
-unix-backtrace = []
-dbghelp = []
-kernel32 = []
-
 #=======================================
 # Methods of resolving symbols
 #
@@ -107,6 +89,10 @@ serialize-serde = ["serde"]
 # Only here for backwards compatibility purposes, they do nothing now.
 coresymbolication = []
 dladdr = []
+kernel32 = []
+unix-backtrace = []
+libunwind = []
+dbghelp = []
 
 #=======================================
 # Internal features for testing and such.
@@ -153,7 +139,7 @@ edition = '2018'
 
 [[test]]
 name = "accuracy"
-required-features = ["std", "dbghelp", "libbacktrace", "libunwind"]
+required-features = ["std", "libbacktrace"]
 edition = '2018'
 
 [[test]]

src/backtrace/mod.rs

@@ -119,7 +119,6 @@ cfg_if::cfg_if! {
                 unix,
                 not(target_os = "emscripten"),
                 not(all(target_os = "ios", target_arch = "arm")),
-                feature = "libunwind",
             ),
             all(
                 target_env = "sgx",
@@ -130,17 +129,7 @@ cfg_if::cfg_if! {
         mod libunwind;
         use self::libunwind::trace as trace_imp;
         pub(crate) use self::libunwind::Frame as FrameImp;
-    } else if #[cfg(
-        all(
-            unix,
-            not(target_os = "emscripten"),
-            feature = "unix-backtrace",
-        )
-    )] {
-        mod unix_backtrace;
-        use self::unix_backtrace::trace as trace_imp;
-        pub(crate) use self::unix_backtrace::Frame as FrameImp;
-    } else if #[cfg(all(windows, feature = "dbghelp", not(target_vendor = "uwp")))] {
+    } else if #[cfg(all(windows, not(target_vendor = "uwp")))] {
         mod dbghelp;
         use self::dbghelp::trace as trace_imp;
         pub(crate) use self::dbghelp::Frame as FrameImp;

src/backtrace/unix_backtrace.rs

@@ -254,7 +254,6 @@ pub struct Init {
 /// Note that this function is **safe**, it internally has its own
 /// synchronization. Also note that it is safe to call this function multiple
 /// times recursively.
-#[cfg(all(windows, feature = "dbghelp"))]
 pub fn init() -> Result<Init, ()> {
     use core::sync::atomic::{AtomicUsize, Ordering::SeqCst};
 

src/dbghelp.rs

@@ -153,7 +153,7 @@ mod lock {
     }
 }
 
-#[cfg(all(windows, feature = "dbghelp", not(target_vendor = "uwp")))]
+#[cfg(all(windows, not(target_vendor = "uwp")))]
 mod dbghelp;
 #[cfg(windows)]
 mod windows;

src/lib.rs

@@ -456,7 +456,7 @@ pub fn clear_symbol_cache() {
 }
 
 cfg_if::cfg_if! {
-    if #[cfg(all(windows, target_env = "msvc", feature = "dbghelp", not(target_vendor = "uwp")))] {
+    if #[cfg(all(windows, target_env = "msvc", not(target_vendor = "uwp")))] {
         mod dbghelp;
         use self::dbghelp::resolve as resolve_imp;
         use self::dbghelp::Symbol as SymbolImp;

src/symbolize/mod.rs

@@ -18,7 +18,7 @@ mod _234567890_234567890_234567890_234567890_234567890 {
 // Long function names must be truncated to (MAX_SYM_NAME - 1) characters.
 // Only run this test for msvc, since gnu prints "<no info>" for all frames.
 #[test]
-#[cfg(all(windows, feature = "dbghelp", target_env = "msvc"))]
+#[cfg(all(windows, target_env = "msvc"))]
 fn test_long_fn_name() {
     use _234567890_234567890_234567890_234567890_234567890::_234567890_234567890_234567890_234567890_234567890 as S;
 

tests/long_fn_name.rs

@@ -9,9 +9,6 @@ const ENABLED: bool = cfg!(all(
     // Windows hasn't really been tested, and OSX doesn't support actually
     // finding an enclosing frame, so disable this
     target_os = "linux",
-    // This is the only method currently that supports accurate enough
-    // backtraces for this test to work.
-    feature = "libunwind",
     // On ARM finding the enclosing function is simply returning the ip itself.
     not(target_arch = "arm"),
 ));

tests/skip_inner_frames.rs

@@ -3,11 +3,7 @@ extern crate backtrace;
 use backtrace::Frame;
 use std::thread;
 
-static LIBUNWIND: bool = cfg!(all(unix, feature = "libunwind"));
-static UNIX_BACKTRACE: bool = cfg!(all(unix, feature = "unix-backtrace"));
 static LIBBACKTRACE: bool = cfg!(feature = "libbacktrace") && !cfg!(target_os = "fuchsia");
-static DBGHELP: bool = cfg!(all(windows, feature = "dbghelp"));
-static MSVC: bool = cfg!(target_env = "msvc");
 static GIMLI_SYMBOLIZE: bool = cfg!(all(feature = "gimli-symbolize", unix, target_os = "linux"));
 
 #[test]
@@ -26,13 +22,6 @@ fn smoke_test_frames() {
             true
         });
 
-        if v.len() < 5 {
-            assert!(!LIBUNWIND);
-            assert!(!UNIX_BACKTRACE);
-            assert!(!DBGHELP);
-            return;
-        }
-
         // Various platforms have various bits of weirdness about their
         // backtraces. To find a good starting spot let's search through the
         // frames
@@ -128,12 +117,12 @@ fn smoke_test_frames() {
         // right now...
         //
         // This assertion can also fail for release builds, so skip it there
-        if !DBGHELP && cfg!(debug_assertions) {
+        if cfg!(debug_assertions) {
             assert!(sym - actual_fn_pointer < 1024);
         }
 
         let mut resolved = 0;
-        let can_resolve = LIBBACKTRACE || DBGHELP || GIMLI_SYMBOLIZE;
+        let can_resolve = LIBBACKTRACE || GIMLI_SYMBOLIZE;
 
         let mut name = None;
         let mut addr = None;
@@ -149,12 +138,11 @@ fn smoke_test_frames() {
 
         // dbghelp doesn't always resolve symbols right now
         match resolved {
-            0 => return assert!(!can_resolve || DBGHELP),
+            0 => return assert!(!can_resolve),
             _ => {}
         }
 
-        // * windows dbghelp isn't great for GNU
-        if can_resolve && !(DBGHELP && !MSVC) {
+        if can_resolve {
             let name = name.expect("didn't find a name");
 
             // in release mode names get weird as functions can get merged
@@ -173,7 +161,7 @@ fn smoke_test_frames() {
             addr.expect("didn't find a symbol");
         }
 
-        if (LIBBACKTRACE || (DBGHELP && MSVC)) && cfg!(debug_assertions) {
+        if cfg!(debug_assertions) {
             let line = line.expect("didn't find a line number");
             let file = file.expect("didn't find a line number");
             if !expected_file.is_empty() {