From 46860b50a9edc4cfd6fe656feb0e97f1b40f8f85 Mon Sep 17 00:00:00 2001 From: Antony Polukhin Date: Tue, 11 Oct 2016 23:23:45 +0300 Subject: [PATCH] Docs updated, now all the macro are documented --- doc/stacktrace.qbk | 43 +++++++++++++++++++ .../boost/stacktrace/detail/stacktrace.ipp | 1 - 2 files changed, 43 insertions(+), 1 deletion(-) diff --git a/doc/stacktrace.qbk b/doc/stacktrace.qbk index 32de8ea..aaba99b 100644 --- a/doc/stacktrace.qbk +++ b/doc/stacktrace.qbk @@ -183,8 +183,51 @@ Backtrace: [endsect] +[section Enabling and Disabling stacktraces] + +At some point arises a requirement to easily enable/disable stacktraces for a whole project. That could be easily achived. + +Just define *BOOST_STACKTRACE_LINK* for a whole project. Now you can enable/disable stacktraces by just linking with different backends: + +* link with `boost_stacktrace_noop` to disable backtracing +* link with other backends to output becktraces + +See [link boost_stacktrace.build_macros_and_backends section "Build, Macros and Backends"] for more info. + [endsect] +[endsect] + +[section Build, Macros and Backends] + +By default Boost.Stacktrace is a header-only library and it attempts to detect the tracing backend automatically. + +You can define the following macros to explicitly specify backend that you're willing to use in header-only mode (those macros have no effect if defined *BOOST_STACKTRACE_LINK* or *BOOST_STACKTRACE_DYN_LINK*): + +[table:configbackend Header only backend specifications + [[Macro name] [Effect] [Platforms] [Uses debug information [footnote This will provide more readable backtraces if the binary is build with debug information.]] [Uses dynamic exports information [footnote This will provide readable function names in backtrace for functions that are exported by the binary.]]] + [[*BOOST_STACKTRACE_USE_LIBUNWIND*] [Use libunwind tracing backend. This is the best known backend for POSIX systems that requires linking with libunwind library.] [POSIX] [yes] [yes]] + [[*BOOST_STACKTRACE_USE_WINDBG*] [Use Windows specific tracing backend that uses DbgHelp. This is the best and only known backend for Windows platform that requires linking with DbgHelp library.] [Windows] [yes] [yes]] + [[*BOOST_STACKTRACE_USE_BACKTRACE*] [Use tracing backend that calls POSIX function backtrace. This is a fallback backend for POSIX platforms that requires linking with libdl library.] [POSIX] [no] [yes]] + [[*BOOST_STACKTRACE_USE_NOOP*] [Use noop tracing backend that does nothing. Use this backend if you wish to disable backtracing.] [POSIX and Windows] [no] [no]] +] + + +You may use following macro to improve build times or to be able to switch backends without recompiling your project: +[table:linkmacro Link macros + [[Macro name] [Effect]] + [[*BOOST_STACKTRACE_LINK*] [Disable header-only build and require linking with shared or static library that has contains the tracing backend. If *BOOST_ALL_DYN_LINK* is defined - link with shared library.]] + [[*BOOST_STACKTRACE_DYN_LINK*] [Disable header-only build and require linking with shared library that has contains tracing backend.]] +] + +If one of the link macros defined you have to manually link your binary with one of the libraries that has the backend implementation: + +* boost_stacktrace_libunwind +* boost_stacktrace_windbg +* boost_stacktrace_backtrace +* boost_stacktrace_noop + +[endsect] [xinclude autodoc.xml] diff --git a/include/boost/stacktrace/detail/stacktrace.ipp b/include/boost/stacktrace/detail/stacktrace.ipp index 0338747..3464692 100644 --- a/include/boost/stacktrace/detail/stacktrace.ipp +++ b/include/boost/stacktrace/detail/stacktrace.ipp @@ -13,7 +13,6 @@ #endif #include -#include #if defined(BOOST_STACKTRACE_USE_NOOP) # include