...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
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 35.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 35.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 COM to show debug info. 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 |
Any compiler on POSIX or MinGW |
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] 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. 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 |
Any compiler on POSIX |
yes |
yes |
BOOST_STACKTRACE_USE_NOOP |
boost_stacktrace_noop |
Use this if you wish to disable backtracing. |
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 [c]
This may affect other components of your program that use COM,
because this mode calls the [d]
If you are using Clang with libstdc++ you could get into troubles
of including |
Examples:
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
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:
/PDBALTPATH
flag, for example /PDBALTPATH:%_PDB%
. See official
documentation for more info.
_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.