Added libunwind support to Linux and macOS

libunwind interprets the signal handler frame and provides better
stacktraces. Because it lets us inspect the stack we can manipulate it
to unwind across bad function dereferences.

Clang in macOS provides an API compatible version of libunwind, so
there's no need to link against any library.

Author: Pedro Navarro

Diff for: BackwardConfig.cmake

@@ -28,6 +28,8 @@ set(STACK_WALKING_UNWIND TRUE CACHE BOOL
 	"Use compiler's unwind API")
 set(STACK_WALKING_BACKTRACE FALSE CACHE BOOL
 	"Use backtrace from (e)glibc for stack walking")
+set(STACK_WALKING_LIBUNWIND FALSE CACHE BOOL
+	"Use libunwind for stack walking")
 
 set(STACK_DETAILS_AUTO_DETECT TRUE CACHE BOOL
 	"Auto detect backward's stack details dependencies")
@@ -50,9 +52,37 @@ endif()
 ###############################################################################
 # CONFIGS
 ###############################################################################
-if (${STACK_DETAILS_AUTO_DETECT})
-	include(FindPackageHandleStandardArgs)
+include(FindPackageHandleStandardArgs)
 
+if (STACK_WALKING_LIBUNWIND)
+	# libunwind works on the macOS without having to add special include
+	# paths or libraries
+	if (NOT APPLE)
+		find_path(LIBUNWIND_INCLUDE_DIR NAMES "libunwind.h")
+		find_library(LIBUNWIND_LIBRARY unwind)
+
+		if (LIBUNWIND_LIBRARY)
+			include(CheckSymbolExists)
+			check_symbol_exists(UNW_INIT_SIGNAL_FRAME libunwind.h HAVE_UNW_INIT_SIGNAL_FRAME)
+			if (NOT HAVE_UNW_INIT_SIGNAL_FRAME)
+				message(STATUS "libunwind does not support unwinding from signal handler frames")
+			endif()
+		endif()
+
+		set(LIBUNWIND_INCLUDE_DIRS ${LIBUNWIND_INCLUDE_DIR})
+		set(LIBDWARF_LIBRARIES ${LIBUNWIND_LIBRARY})
+		find_package_handle_standard_args(libunwind DEFAULT_MSG
+			LIBUNWIND_LIBRARY LIBUNWIND_INCLUDE_DIR)
+		mark_as_advanced(LIBUNWIND_INCLUDE_DIR LIBUNWIND_LIBRARY)
+		list(APPEND _BACKWARD_LIBRARIES ${LIBUNWIND_LIBRARY})
+	endif()
+
+	# Disable other unwinders if libunwind is found
+	set(STACK_WALKING_UNWIND FALSE)
+	set(STACK_WALKING_BACKTRACE FALSE)	
+endif()
+
+if (${STACK_DETAILS_AUTO_DETECT})
 	# find libdw
 	find_path(LIBDW_INCLUDE_DIR NAMES "elfutils/libdw.h" "elfutils/libdwfl.h")
 	find_library(LIBDW_LIBRARY dw)
@@ -152,7 +182,7 @@ macro(map_definitions var_prefix define_prefix)
 endmacro()
 
 if (NOT _BACKWARD_DEFINITIONS)
-	map_definitions("STACK_WALKING_" "BACKWARD_HAS_" UNWIND BACKTRACE)
+	map_definitions("STACK_WALKING_" "BACKWARD_HAS_" UNWIND LIBUNWIND BACKTRACE)
 	map_definitions("STACK_DETAILS_" "BACKWARD_HAS_" BACKTRACE_SYMBOL DW BFD DWARF)
 endif()
 

Diff for: README.md

@@ -93,6 +93,35 @@ find_package(Backward)
 # through an IMPORTED target.
 target_link_libraries(mytarget PUBLIC Backward::Backward)
 ```
+### Libraries to unwind the stack
+
+On Linux and macOS, backtrace can back-trace or "walk" the stack using the
+following libraries:
+
+#### unwind
+
+Unwind comes from libgcc, but there is an equivalent inside clang itself. With
+unwind, the stacktrace is as accurate as it can possibly be, since this is
+used by the C++ runtine in gcc/clang for stack unwinding on exception.
+
+Normally libgcc is already linked to your program by default.
+
+#### libunwind from the [libunwind project](https://github.com/libunwind/libunwind)
+
+	apt-get install binutils-dev (or equivalent)
+
+Libunwind provides, in some cases, a more accurate stacktrace as it knows
+to decode signal handler frames and lets us edit the context registers when
+unwinding, allowing stack traces over bad function references.
+
+For best results make sure you are using libunwind 1.3 or later, which added
+`unw_init_local2` and support for handling signal frames.
+
+CMake will warn you when configuring if your libunwind version doesn't support
+signal frames.
+
+On macOS clang provides a libunwind API compatible library as part of its
+environment, so no third party libraries are necessary.
 
 ### Compile with debug info
 
@@ -110,17 +139,17 @@ your sources.
 
 ### Libraries to read the debug info
 
-Backward support pretty printed stack traces on GNU/Linux only, it will compile
-fine under other platforms but will not do anything.  **Pull requests are
-welcome :)**
+Backward supports pretty printed stack traces on GNU/Linux, macOS and Windows,
+it will compile fine under other platforms but will not do anything. **Pull
+requests are welcome :)**
 
 Also, by default you will get a really basic stack trace, based on the
 `backtrace_symbols` API:
 
 ![default trace](doc/nice.png)
 
-You will need to install some dependencies to get the ultimate stack trace. Two
-libraries are currently supported, the only difference is which one is the
+You will need to install some dependencies to get the ultimate stack trace.
+Three libraries are currently supported, the only difference is which one is the
 easiest for you to install, so pick your poison:
 
 #### libbfd from the [GNU/binutils](http://www.gnu.org/software/binutils/)

Diff for: backward.cpp

@@ -11,7 +11,7 @@
 //	- line and column numbers
 //	- source code snippet (assuming the file is accessible)
 
-// Install one of the following library then uncomment one of the macro (or
+// Install one of the following libraries then uncomment one of the macro (or
 // better, add the detection of the lib and the macro definition in your build
 // system)
 
@@ -23,6 +23,16 @@
 // - g++/clang++ -lbfd ...
 // #define BACKWARD_HAS_BFD 1
 
+// - apt-get install libdwarf-dev ...
+// - g++/clang++ -ldwarf ...
+// #define BACKWARD_HAS_DWARF 1
+
+// Regardless of the library you choose to read the debug information,
+// for potentially more detailed stack traces you can use libunwind
+// - apt-get install libunwind-dev
+// - g++/clang++ -lunwind
+// #define BACKWARD_HAS_LIBUNWIND 1
+
 #include "backward.hpp"
 
 namespace backward {