no_std support

Author: Aaron Power

Cargo.toml

@@ -11,6 +11,9 @@ documentation = "https://docs.rs/backtrace"
 description = """
 A library to acquire a stack trace (backtrace) at runtime in a Rust program.
 """
+autoexamples = true
+autotests = true
+
 [dependencies]
 cfg-if = "0.1"
 rustc-demangle = "0.1.4"
@@ -47,7 +50,10 @@ backtrace-sys = { path = "backtrace-sys", version = "0.1.17", 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 = ["libunwind", "libbacktrace", "coresymbolication", "dladdr", "dbghelp"]
+default = ["std", "libunwind", "libbacktrace", "coresymbolication", "dladdr", "dbghelp"]
+
+# Include std support.
+std = []
 
 #=======================================
 # Methods of acquiring a backtrace
@@ -86,7 +92,7 @@ kernel32 = []
 #   the moment, this is only possible when targetting Linux, since macOS
 #   splits DWARF out into a separate object file. Enabling this feature
 #   means one less C dependency.
-libbacktrace = ["backtrace-sys"]
+libbacktrace = ["backtrace-sys", "std"]
 dladdr = []
 coresymbolication = []
 gimli-symbolize = ["addr2line", "findshlibs", "gimli", "memmap", "object" ]
@@ -97,3 +103,23 @@ gimli-symbolize = ["addr2line", "findshlibs", "gimli", "memmap", "object" ]
 # Various features used for enabling rustc-serialize or syntex codegen.
 serialize-rustc = ["rustc-serialize"]
 serialize-serde = ["serde", "serde_derive"]
+
+[[example]]
+name = "backtrace"
+required-features = ["std"]
+
+[[example]]
+name = "raw"
+required-features = ["std"]
+
+[[test]]
+name = "skip_inner_frames"
+required-features = ["std"]
+
+[[test]]
+name = "long_fn_name"
+required-features = ["std"]
+
+[[test]]
+name = "smoke"
+required-features = ["std"]

backtrace-sys/src/lib.rs

@@ -2,8 +2,7 @@
 
 extern crate libc;
 
-use libc::uintptr_t;
-use std::os::raw::{c_void, c_char, c_int};
+use libc::{c_void, c_char, c_int, uintptr_t};
 
 pub type backtrace_syminfo_callback =
     extern fn(data: *mut c_void,

src/backtrace/dbghelp.rs

@@ -11,6 +11,7 @@
 #![allow(bad_style)]
 
 use std::mem;
+use std::prelude::v1::*;
 use winapi::ctypes::*;
 use winapi::shared::minwindef::*;
 use winapi::um::processthreadsapi;
@@ -33,49 +34,43 @@ impl Frame {
 }
 
 #[inline(always)]
-pub fn trace(cb: &mut FnMut(&super::Frame) -> bool) {
-    // According to windows documentation, all dbghelp functions are
-    // single-threaded.
-    let _g = ::lock::lock();
+pub unsafe fn trace(cb: &mut FnMut(&super::Frame) -> bool) {
+    // Allocate necessary structures for doing the stack walk
+    let process = processthreadsapi::GetCurrentProcess();
+    let thread = processthreadsapi::GetCurrentThread();
 
-    unsafe {
-        // Allocate necessary structures for doing the stack walk
-        let process = processthreadsapi::GetCurrentProcess();
-        let thread = processthreadsapi::GetCurrentThread();
+    // The CONTEXT structure needs to be aligned on a 16-byte boundary for
+    // 64-bit Windows, but currently we don't have a way to express that in
+    // Rust. Allocations are generally aligned to 16-bytes, though, so we
+    // box this up.
+    let mut context = Box::new(mem::zeroed::<CONTEXT>());
+    winnt::RtlCaptureContext(&mut *context);
+    let mut frame = super::Frame {
+        inner: Frame { inner: mem::zeroed() },
+    };
+    let image = init_frame(&mut frame.inner.inner, &context);
 
-        // The CONTEXT structure needs to be aligned on a 16-byte boundary for
-        // 64-bit Windows, but currently we don't have a way to express that in
-        // Rust. Allocations are generally aligned to 16-bytes, though, so we
-        // box this up.
-        let mut context = Box::new(mem::zeroed::<CONTEXT>());
-        winnt::RtlCaptureContext(&mut *context);
-        let mut frame = super::Frame {
-            inner: Frame { inner: mem::zeroed() },
-        };
-        let image = init_frame(&mut frame.inner.inner, &context);
+    // Initialize this process's symbols
+    let _c = ::dbghelp_init();
 
-        // Initialize this process's symbols
-        let _c = ::dbghelp_init();
+    // And now that we're done with all the setup, do the stack walking!
+    while dbghelp::StackWalk64(image as DWORD,
+                               process,
+                               thread,
+                               &mut frame.inner.inner,
+                               &mut *context as *mut _ as *mut _,
+                               None,
+                               Some(dbghelp::SymFunctionTableAccess64),
+                               Some(dbghelp::SymGetModuleBase64),
+                               None) == TRUE {
+        if frame.inner.inner.AddrPC.Offset == frame.inner.inner.AddrReturn.Offset ||
+            frame.inner.inner.AddrPC.Offset == 0 ||
+                frame.inner.inner.AddrReturn.Offset == 0 {
+                    break
+                }
 
-        // And now that we're done with all the setup, do the stack walking!
-        while dbghelp::StackWalk64(image as DWORD,
-                                   process,
-                                   thread,
-                                   &mut frame.inner.inner,
-                                   &mut *context as *mut _ as *mut _,
-                                   None,
-                                   Some(dbghelp::SymFunctionTableAccess64),
-                                   Some(dbghelp::SymGetModuleBase64),
-                                   None) == TRUE {
-            if frame.inner.inner.AddrPC.Offset == frame.inner.inner.AddrReturn.Offset ||
-               frame.inner.inner.AddrPC.Offset == 0 ||
-               frame.inner.inner.AddrReturn.Offset == 0 {
-                break
-            }
-
-            if !cb(&frame) {
-                break
-            }
+        if !cb(&frame) {
+            break
         }
     }
 }

src/backtrace/libunwind.rs

@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-use std::os::raw::c_void;
+use types::c_void;
 
 pub struct Frame {
     ctx: *mut uw::_Unwind_Context,
@@ -48,10 +48,8 @@ impl Frame {
 }
 
 #[inline(always)]
-pub fn trace(mut cb: &mut FnMut(&super::Frame) -> bool) {
-    unsafe {
-        uw::_Unwind_Backtrace(trace_fn, &mut cb as *mut _ as *mut _);
-    }
+pub unsafe fn trace(mut cb: &mut FnMut(&super::Frame) -> bool) {
+    uw::_Unwind_Backtrace(trace_fn, &mut cb as *mut _ as *mut _);
 
     extern fn trace_fn(ctx: *mut uw::_Unwind_Context,
                        arg: *mut c_void) -> uw::_Unwind_Reason_Code {
@@ -84,7 +82,7 @@ mod uw {
     pub use self::_Unwind_Reason_Code::*;
 
     use libc;
-    use std::os::raw::{c_int, c_void};
+    use types::{c_int, c_void};
 
     #[repr(C)]
     pub enum _Unwind_Reason_Code {

src/backtrace/mod.rs

@@ -1,6 +1,5 @@
-use std::fmt;
-
-use std::os::raw::c_void;
+use core::fmt;
+use types::c_void;
 
 /// Inspects the current call-stack, passing all active frames into the closure
 /// provided to calculate a stack trace.
@@ -37,10 +36,20 @@ use std::os::raw::c_void;
 /// }
 /// ```
 #[inline(never)]
+#[cfg(feature = "std")]
 pub fn trace<F: FnMut(&Frame) -> bool>(mut cb: F) {
+    let _guard = ::lock::lock();
+    unsafe { trace_imp(&mut cb) }
+}
+
+/// Without std this function now does not have synchronization guarentees.
+/// Please refer to std documentation for examples and explaination.
+#[inline(never)]
+pub unsafe fn trace_unsynchronized<F: FnMut(&Frame) -> bool>(mut cb: F) {
     trace_imp(&mut cb)
 }
 
+
 /// A trait representing one frame of a backtrace, yielded to the `trace`
 /// function of this crate.
 ///

src/backtrace/noop.rs

@@ -1,4 +1,4 @@
-use std::os::raw::c_void;
+use types::c_void;
 
 #[inline(always)]
 pub fn trace(_cb: &mut FnMut(&super::Frame) -> bool) {}

src/backtrace/unix_backtrace.rs

@@ -8,8 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-use std::mem;
-use std::os::raw::{c_void, c_int};
+use core::mem;
+use types::{c_void, c_int};
 
 pub struct Frame {
     addr: *mut c_void,
@@ -25,15 +25,14 @@ extern {
 }
 
 #[inline(always)]
-pub fn trace(cb: &mut FnMut(&super::Frame) -> bool) {
+pub unsafe fn trace(cb: &mut FnMut(&super::Frame) -> bool) {
     const SIZE: usize = 100;
 
     let mut buf: [*mut c_void; SIZE];
     let cnt;
-    unsafe {
-        buf = mem::zeroed();
-        cnt = backtrace(buf.as_mut_ptr(), SIZE as c_int);
-    }
+
+    buf = mem::zeroed();
+    cnt = backtrace(buf.as_mut_ptr(), SIZE as c_int);
 
     for addr in buf[..cnt as usize].iter() {
         let cx = super::Frame {

src/capture.rs

@@ -1,9 +1,10 @@
+use std::prelude::v1::*;
 use std::fmt;
 use std::mem;
-use std::os::raw::c_void;
 use std::path::{Path, PathBuf};
 
 use {trace, resolve, SymbolName};
+use types::c_void;
 
 /// Representation of an owned and self-contained backtrace.
 ///
@@ -144,7 +145,7 @@ impl Backtrace {
                 symbols.push(BacktraceSymbol {
                     name: symbol.name().map(|m| m.as_bytes().to_vec()),
                     addr: symbol.addr().map(|a| a as usize),
-                    filename: symbol.filename().map(|m| m.to_path_buf()),
+                    filename: symbol.filename().map(|m| m.to_owned()),
                     lineno: symbol.lineno(),
                 });
             });

src/lib.rs

@@ -46,6 +46,8 @@
 //! extern crate backtrace;
 //!
 //! fn main() {
+//! # // Unsafe here so test passes on no_std.
+//! # #[cfg(feature = "std")] {
 //!     backtrace::trace(|frame| {
 //!         let ip = frame.ip();
 //!         let symbol_address = frame.symbol_address();
@@ -63,10 +65,15 @@
 //!         true // keep going to the next frame
 //!     });
 //! }
+//! # }
 //! ```
 
 #![doc(html_root_url = "https://docs.rs/backtrace")]
 #![deny(missing_docs)]
+#![no_std]
+
+#[cfg(feature = "std")]
+#[macro_use] extern crate std;
 
 #[cfg(unix)]
 extern crate libc;
@@ -98,18 +105,27 @@ cfg_if! {
 }
 
 #[allow(dead_code)] // not used everywhere
-#[cfg(unix)]
+#[cfg(all(unix, feature = "std"))]
 #[macro_use]
 mod dylib;
 
-pub use backtrace::{trace, Frame};
+pub use backtrace::{trace_unsynchronized, Frame};
 mod backtrace;
 
-pub use symbolize::{resolve, Symbol, SymbolName};
+pub use symbolize::{resolve_unsynchronized, Symbol, SymbolName};
 mod symbolize;
 
-pub use capture::{Backtrace, BacktraceFrame, BacktraceSymbol};
-mod capture;
+pub use types::BytesOrWideString;
+mod types;
+
+cfg_if! {
+    if #[cfg(feature = "std")] {
+        pub use backtrace::trace;
+        pub use symbolize::resolve;
+        pub use capture::{Backtrace, BacktraceFrame, BacktraceSymbol};
+        mod capture;
+    }
+}
 
 #[allow(dead_code)]
 struct Bomb {
@@ -126,8 +142,10 @@ impl Drop for Bomb {
 }
 
 #[allow(dead_code)]
+#[cfg(feature = "std")]
 mod lock {
     use std::cell::Cell;
+    use std::boxed::Box;
     use std::sync::{Once, Mutex, MutexGuard, ONCE_INIT};
 
     pub struct LockGuard(MutexGuard<'static, ()>);