Configuration and Build

By default Boost.Stacktrace is a header-only library, but you may change that and use the following macros to improve build times or to be able to tune library without recompiling your project:

Table 37.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 could 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 37.2. Config

Macro name or default	Library	Effect	Platforms	Uses debug information ^[a]	Uses dynamic exports information ^[b]
default for MSVC / BOOST_STACKTRACE_USE_WINDBG	boost_stacktrace_windbg	Uses COM to show debug info.	Windows	yes	no
default 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.	Not MSVC compiler on POSIX or Windows	no	yes
BOOST_STACKTRACE_USE_WINDBG_CACHED	boost_stacktrace_windbg_cached	Uses COM to show debug info and caches COM instances in TLS for better performance. Useful only for cases when traces are gathered very often. ^[c]	Windows	yes	no
BOOST_STACKTRACE_USE_BACKTRACE	boost_stacktrace_backtrace	Requires linking with libdl on POSIX and libbacktrace libraries. libbacktrace is probably already installed in your system, or built into your compiler. Otherwise (if you are a MinGW user for example) it can be downloaded from here or from here.	GCC/MinGW/Clang... on POSIX or Windows	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.	GCC/MinGW/Clang... 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 `-fisibility=hidden` or marking functions as exported produce a better stacktraces. ^[c] This may affect other components of your program that use COM, because this mode calls the `CoInitializeEx(0, COINIT_MULTITHREADED)` on first use and does not call `::CoUninitialize();` until the current thread is destroyed.

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 you use the library in header only mode, you just need to define BOOST_STACKTRACE_USE_NOOP for the whole project
if you wish to disable backtracing and BOOST_STACKTRACE_LINK is defined, you just need link with -lboost_stacktrace_noop

Boost C++ Libraries

Configuration and Build