Configuration and Build

Usage from CMake

CMake library Boost::stacktrace provides the best available implementation:

target_link_libraries(${PROJECT}
  PUBLIC
    Boost::stacktrace
)

There are also CMake libraries for fine grained selection of implementation:

Boost::stacktrace_windbg
Boost::stacktrace_windbg_cached
Boost::stacktrace_backtrace
Boost::stacktrace_addr2line
Boost::stacktrace_basic
Boost::stacktrace_noop

Note that Boost::stacktrace_from_exception is not used by default, so add it explicitly if its functionality is required:

target_link_libraries(${PROJECT}  # your project
  PUBLIC
    Boost::stacktrace
    Boost::stacktrace_from_exception
)

CMake build notes

When building the Boost.Stacktrace libraries using CMake the BOOST_STACKTRACE_ENABLE_* options control the build. For example:

cmake -DBOOST_STACKTRACE_ENABLE_NOOP=0 -DBOOST_STACKTRACE_ENABLE_BACKTRACE=1 -DBOOST_STACKTRACE_ENABLE_FROM_EXCEPTION=1 - do not build the noop implementation and force the builds of backtrace and from_exception.
cmake -DBOOST_STACKTRACE_ENABLE_NOOP=1 -DBOOST_STACKTRACE_ENABLE_WINDBG=1 -DBOOST_STACKTRACE_ENABLE_WINDBG_CACHED=0 - build the noop and windbg implementations and disable the build of windbg_cached.

If options are not provided they are auto-detected and the result of detection is printed and implicitly used during build.

B2 build notes

When building the Boost.Stacktrace libraries using b2 the boost.stacktrace.* options can be used to control the build. For example:

b2 boost.stacktrace.noop=off boost.stacktrace.backtrace=on boost.stacktrace.from_exception=on - do not build the noop implementation and force the builds of backtrace and from_exception.
b2 boost.stacktrace.noop=on boost.stacktrace.windbg=on boost.stacktrace.windbg_cached=off - build the noop and windbg implementations and disable the build of windbg_cached.

If options are not provided they are auto-detected and the result of detection is printed and implicitly used during build.

If CMake is not used then the Boost.Stacktrace is a header-only library by default. To change that (to improve build times or to be able to tune library without recompiling your project) use the following macros:

Table 34.1. Link macros

Macro name	Effect
BOOST_STACKTRACE_LINK	Disable header-only build and require linking with shared or static library that contains the tracing implementation. If BOOST_ALL_DYN_LINK is defined, then link with shared library.
BOOST_STACKTRACE_DYN_LINK	Disable header-only build and require linking with shared library that contains tracing implementation.

In header only mode library can be tuned by macro. If one of the link macro from above is defined, you have to manually link with one of the libraries:

Table 34.2. Config

Macro name or default	Library	Effect	Platforms	Uses debug information ^[a]	Uses dynamic exports information ^[b]
default for MSVC, Intel on Windows, MinGW-w64 / BOOST_STACKTRACE_USE_WINDBG	boost_stacktrace_windbg	Uses `dbgeng.h` to show debug info, stores the implementation internals in a static variable protected with mutex. May require linking with ole32 and dbgeng.	MSVC, MinGW-w64, Intel on Windows	yes	no
default for other platforms	boost_stacktrace_basic	Uses compiler intrinsics to collect stacktrace and if possible `::dladdr` to show information about the symbol. Requires linking with libdl library on POSIX platforms.	Any compiler on POSIX or MinGW	no	yes
BOOST_STACKTRACE_USE_WINDBG_CACHED	boost_stacktrace_windbg_cached	Uses `dbgeng.h` to show debug info and caches implementation internals in TLS for better performance. Useful only for cases when traces are gathered very often. May require linking with ole32 and dbgeng.	MSVC, Intel on Windows	yes	no
BOOST_STACKTRACE_USE_BACKTRACE	boost_stacktrace_backtrace	Requires linking with libdl on POSIX and libbacktrace libraries^[c]. libbacktrace is probably already installed in your system^[d], or built into your compiler. Otherwise (if you are a MinGW/MinGW-w64 user for example) it can be downloaded from here or from here.	Any compiler on POSIX, or MinGW, or MinGW-w64	yes	yes
BOOST_STACKTRACE_USE_ADDR2LINE	boost_stacktrace_addr2line	Use addr2line program to retrieve stacktrace. Requires linking with libdl library and `::fork` system call. Macro BOOST_STACKTRACE_ADDR2LINE_LOCATION must be defined to the absolute path to the addr2line executable if it is not located in /usr/bin/addr2line.	Any compiler on POSIX	yes	yes
BOOST_STACKTRACE_USE_NOOP	boost_stacktrace_noop	Use this if you wish to disable backtracing. `stacktrace::size()` with that macro always returns 0.	All	no	no
^[a] This will provide more readable backtraces with source code locations if the binary is built with debug information. ^[b] This will provide readable function names in backtrace for functions that are exported by the binary. Compiling with `-rdynamic` flag, without `-fvisibility=hidden` or marking functions as exported produce a better stacktraces. ^[c] Some libbacktrace packages SEGFAULT if there's a concurrent work with the same `backtrace_state` instance. To avoid that issue the Boost.Stacktrace library uses `thread_local` states, unfortunately this may consume a lot of memory if you often create and destroy execution threads in your application. Define BOOST_STACKTRACE_BACKTRACE_FORCE_STATIC to force single instance, but make sure that thread_safety_checking.cpp works well in your setup. ^[d] If you are using Clang with libstdc++ you can get into troubles of including `<backtrace.h>`, because on some platforms Clang does not search for headers in the GCC's include paths and any attempt to add GCC's include path leads to linker errors. To explicitly specify a path to the `<backtrace.h>` header you can define the BOOST_STACKTRACE_BACKTRACE_INCLUDE_FILE to a full path to the header. For example on Ubuntu Xenial use the command line option -DBOOST_STACKTRACE_BACKTRACE_INCLUDE_FILE=</usr/lib/gcc/x86_64-linux-gnu/5/include/backtrace.h> while building with Clang.

Examples:

if you wish to switch to more powerful implementation on Clang/MinGW and BOOST_STACKTRACE_LINK is defined, you just need link with "-lboost_stacktrace_backtrace -ldl -lbacktrace" or "-lboost_stacktrace_addr2line -ldl"
if you wish to disable backtracing and BOOST_STACKTRACE_LINK is defined, you just need link with -lboost_stacktrace_noop
if you wish to disable backtracing and you use the library in header only mode, you just need to define BOOST_STACKTRACE_USE_NOOP for the whole project and recompile it

MinGW and MinGW-w64 specific notes

MinGW-w64 and MinGW (without -w64) users have to install libbacktrace for getting better stacktraces. Follow the instruction:

Let's assume that you've installed MinGW into C:\MinGW and downloaded libbacktrace sources into C:\libbacktrace-master

Configure & build libbacktrace from console:
- C:\MinGW\msys\1.0\bin\sh.exe
- cd /c/libbacktrace-master
- ./configure CC=/c/MinGW/bin/gcc.exe CXX=/c/MinGW/bin/g++.exe
- make
- ./libtool --mode=install /usr/bin/install -c libbacktrace.la '/c/libbacktrace-master'
Add info to the project-config.jam in the Boost folder:
- using gcc : 6 : "C:\MinGW\bin\g++.exe" : <compileflags>-I"C:\libbacktrace-master\" <linkflags>-L"C:\libbacktrace-master\" ;
Now you can use a header only version by defining BOOST_STACKTRACE_USE_BACKTRACE for your project or build the stacktrace library from Boost folder:
- b2.exe toolset=gcc-6 --with-stacktrace

Windows deployment and symbol files

Function names may not be resolved after deployment of your application to a different system.

There are multiple ways to deal with that issue if you distribute PDB files along with your application:

Link your application and shared libraries with a properly set /PDBALTPATH flag, for example /PDBALTPATH:%_PDB%. See official documentation for more info.
Set the _NT_ALT_SYMBOL_PATH or _NT_SYMBOL_PATH environment variables of the target system to the path of the PDBs. See official documentation for more info.

Boost C++ Libraries