1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<head> 4<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 5<title>Configuration and Build</title> 6<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css"> 7<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 8<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> 9<link rel="up" href="../stacktrace.html" title="Chapter 36. Boost.Stacktrace 1.0"> 10<link rel="prev" href="getting_started.html" title="Getting Started"> 11<link rel="next" href="acknowledgements.html" title="Acknowledgements"> 12</head> 13<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 14<table cellpadding="2" width="100%"><tr> 15<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td> 16<td align="center"><a href="../../../index.html">Home</a></td> 17<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td> 18<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 19<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 20<td align="center"><a href="../../../more/index.htm">More</a></td> 21</tr></table> 22<hr> 23<div class="spirit-nav"> 24<a accesskey="p" href="getting_started.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../stacktrace.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="acknowledgements.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> 25</div> 26<div class="section"> 27<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 28<a name="stacktrace.configuration_and_build"></a><a class="link" href="configuration_and_build.html" title="Configuration and Build">Configuration and Build</a> 29</h2></div></div></div> 30<div class="toc"><dl class="toc"> 31<dt><span class="section"><a href="configuration_and_build.html#stacktrace.configuration_and_build.mingw_and_mingw_w64_specific_not">MinGW 32 and MinGW-w64 specific notes</a></span></dt> 33<dt><span class="section"><a href="configuration_and_build.html#stacktrace.configuration_and_build.windows_deployment_and_symbol_fi">Windows 34 deployment and symbol files</a></span></dt> 35</dl></div> 36<p> 37 By default Boost.Stacktrace is a header-only library, but you may change that 38 and use the following macros to improve build times or to be able to tune library 39 without recompiling your project: 40 </p> 41<div class="table"> 42<a name="stacktrace.configuration_and_build.linkmacro"></a><p class="title"><b>Table 36.1. Link macros</b></p> 43<div class="table-contents"><table class="table" summary="Link macros"> 44<colgroup> 45<col> 46<col> 47</colgroup> 48<thead><tr> 49<th> 50 <p> 51 Macro name 52 </p> 53 </th> 54<th> 55 <p> 56 Effect 57 </p> 58 </th> 59</tr></thead> 60<tbody> 61<tr> 62<td> 63 <p> 64 <span class="bold"><strong>BOOST_STACKTRACE_LINK</strong></span> 65 </p> 66 </td> 67<td> 68 <p> 69 Disable header-only build and require linking with shared or static 70 library that contains the tracing implementation. If <span class="bold"><strong>BOOST_ALL_DYN_LINK</strong></span> 71 is defined, then link with shared library. 72 </p> 73 </td> 74</tr> 75<tr> 76<td> 77 <p> 78 <span class="bold"><strong>BOOST_STACKTRACE_DYN_LINK</strong></span> 79 </p> 80 </td> 81<td> 82 <p> 83 Disable header-only build and require linking with shared library 84 that contains tracing implementation. 85 </p> 86 </td> 87</tr> 88</tbody> 89</table></div> 90</div> 91<br class="table-break"><p> 92 In header only mode library could be tuned by macro. If one of the link macro 93 from above is defined, you have to manually link with one of the libraries: 94 </p> 95<div class="table"> 96<a name="stacktrace.configuration_and_build.libconfig"></a><p class="title"><b>Table 36.2. Config</b></p> 97<div class="table-contents"><table class="table" summary="Config"> 98<colgroup> 99<col> 100<col> 101<col> 102<col> 103<col> 104<col> 105</colgroup> 106<thead><tr> 107<th> 108 <p> 109 Macro name or default 110 </p> 111 </th> 112<th> 113 <p> 114 Library 115 </p> 116 </th> 117<th> 118 <p> 119 Effect 120 </p> 121 </th> 122<th> 123 <p> 124 Platforms 125 </p> 126 </th> 127<th> 128 <p> 129 Uses debug information <a href="#ftn.stacktrace.configuration_and_build.f0" class="footnote" name="stacktrace.configuration_and_build.f0"><sup class="footnote">[a]</sup></a> 130 </p> 131 </th> 132<th> 133 <p> 134 Uses dynamic exports information <a href="#ftn.stacktrace.configuration_and_build.f1" class="footnote" name="stacktrace.configuration_and_build.f1"><sup class="footnote">[b]</sup></a> 135 </p> 136 </th> 137</tr></thead> 138<tbody> 139<tr> 140<td> 141 <p> 142 <span class="emphasis"><em>default for MSVC, Intel on Windows, MinGW-w64</em></span> 143 / <span class="bold"><strong>BOOST_STACKTRACE_USE_WINDBG</strong></span> 144 </p> 145 </td> 146<td> 147 <p> 148 <span class="bold"><strong>boost_stacktrace_windbg</strong></span> 149 </p> 150 </td> 151<td> 152 <p> 153 Uses COM to show debug info. May require linking with <span class="bold"><strong>ole32</strong></span> 154 and <span class="bold"><strong>dbgeng</strong></span>. 155 </p> 156 </td> 157<td> 158 <p> 159 MSVC, MinGW-w64, Intel on Windows 160 </p> 161 </td> 162<td> 163 <p> 164 yes 165 </p> 166 </td> 167<td> 168 <p> 169 no 170 </p> 171 </td> 172</tr> 173<tr> 174<td> 175 <p> 176 <span class="emphasis"><em>default for other platforms</em></span> 177 </p> 178 </td> 179<td> 180 <p> 181 <span class="bold"><strong>boost_stacktrace_basic</strong></span> 182 </p> 183 </td> 184<td> 185 <p> 186 Uses compiler intrinsics to collect stacktrace and if possible <code class="computeroutput"><span class="special">::</span><span class="identifier">dladdr</span></code> 187 to show information about the symbol. Requires linking with <span class="bold"><strong>libdl</strong></span> library on POSIX platforms. 188 </p> 189 </td> 190<td> 191 <p> 192 Any compiler on POSIX or MinGW 193 </p> 194 </td> 195<td> 196 <p> 197 no 198 </p> 199 </td> 200<td> 201 <p> 202 yes 203 </p> 204 </td> 205</tr> 206<tr> 207<td> 208 <p> 209 <span class="bold"><strong>BOOST_STACKTRACE_USE_WINDBG_CACHED</strong></span> 210 </p> 211 </td> 212<td> 213 <p> 214 <span class="bold"><strong>boost_stacktrace_windbg_cached</strong></span> 215 </p> 216 </td> 217<td> 218 <p> 219 Uses COM to show debug info and caches COM instances in TLS for better 220 performance. Useful only for cases when traces are gathered very 221 often. <a href="#ftn.stacktrace.configuration_and_build.f2" class="footnote" name="stacktrace.configuration_and_build.f2"><sup class="footnote">[c]</sup></a> May require linking with <span class="bold"><strong>ole32</strong></span> 222 and <span class="bold"><strong>dbgeng</strong></span>. 223 </p> 224 </td> 225<td> 226 <p> 227 MSVC, Intel on Windows 228 </p> 229 </td> 230<td> 231 <p> 232 yes 233 </p> 234 </td> 235<td> 236 <p> 237 no 238 </p> 239 </td> 240</tr> 241<tr> 242<td> 243 <p> 244 <span class="bold"><strong>BOOST_STACKTRACE_USE_BACKTRACE</strong></span> 245 </p> 246 </td> 247<td> 248 <p> 249 <span class="bold"><strong>boost_stacktrace_backtrace</strong></span> 250 </p> 251 </td> 252<td> 253 <p> 254 Requires linking with <span class="bold"><strong>libdl</strong></span> on POSIX 255 and <span class="bold"><strong>libbacktrace</strong></span> libraries. <span class="bold"><strong>libbacktrace</strong></span> is probably already installed 256 in your system<a href="#ftn.stacktrace.configuration_and_build.f3" class="footnote" name="stacktrace.configuration_and_build.f3"><sup class="footnote">[d]</sup></a>, or built into your compiler. 257 </p> 258 <p> 259 Otherwise (if you are a <span class="bold"><strong>MinGW</strong></span>/<span class="bold"><strong>MinGW-w64</strong></span> user for example) it can be downloaded 260 <a href="https://github.com/ianlancetaylor/libbacktrace" target="_top">from 261 here</a> or <a href="https://github.com/gcc-mirror/gcc/tree/master/libbacktrace" target="_top">from 262 here</a>. 263 </p> 264 </td> 265<td> 266 <p> 267 Any compiler on POSIX, or MinGW, or MinGW-w64 268 </p> 269 </td> 270<td> 271 <p> 272 yes 273 </p> 274 </td> 275<td> 276 <p> 277 yes 278 </p> 279 </td> 280</tr> 281<tr> 282<td> 283 <p> 284 <span class="bold"><strong>BOOST_STACKTRACE_USE_ADDR2LINE</strong></span> 285 </p> 286 </td> 287<td> 288 <p> 289 <span class="bold"><strong>boost_stacktrace_addr2line</strong></span> 290 </p> 291 </td> 292<td> 293 <p> 294 Use <span class="bold"><strong>addr2line</strong></span> program to retrieve 295 stacktrace. Requires linking with <span class="bold"><strong>libdl</strong></span> 296 library and <code class="computeroutput"><span class="special">::</span><span class="identifier">fork</span></code> 297 system call. Macro <span class="bold"><strong>BOOST_STACKTRACE_ADDR2LINE_LOCATION</strong></span> 298 must be defined to the absolute path to the addr2line executable 299 if it is not located in /usr/bin/addr2line. 300 </p> 301 </td> 302<td> 303 <p> 304 Any compiler on POSIX 305 </p> 306 </td> 307<td> 308 <p> 309 yes 310 </p> 311 </td> 312<td> 313 <p> 314 yes 315 </p> 316 </td> 317</tr> 318<tr> 319<td> 320 <p> 321 <span class="bold"><strong>BOOST_STACKTRACE_USE_NOOP</strong></span> 322 </p> 323 </td> 324<td> 325 <p> 326 <span class="bold"><strong>boost_stacktrace_noop</strong></span> 327 </p> 328 </td> 329<td> 330 <p> 331 Use this if you wish to disable backtracing. <code class="computeroutput"><span class="identifier">stacktrace</span><span class="special">::</span><span class="identifier">size</span><span class="special">()</span></code> with that macro always returns 332 0. 333 </p> 334 </td> 335<td> 336 <p> 337 All 338 </p> 339 </td> 340<td> 341 <p> 342 no 343 </p> 344 </td> 345<td> 346 <p> 347 no 348 </p> 349 </td> 350</tr> 351</tbody> 352<tbody class="footnotes"><tr><td colspan="6"> 353<div id="ftn.stacktrace.configuration_and_build.f0" class="footnote"><p><a href="#stacktrace.configuration_and_build.f0" class="para"><sup class="para">[a] </sup></a> 354 This will provide more readable backtraces with <span class="bold"><strong>source 355 code locations</strong></span> if the binary is built with debug information. 356 </p></div> 357<div id="ftn.stacktrace.configuration_and_build.f1" class="footnote"><p><a href="#stacktrace.configuration_and_build.f1" class="para"><sup class="para">[b] </sup></a> 358 This will provide readable function names in backtrace for functions 359 that are exported by the binary. Compiling with <code class="computeroutput"><span class="special">-</span><span class="identifier">rdynamic</span></code> flag, without <code class="computeroutput"><span class="special">-</span><span class="identifier">fisibility</span><span class="special">=</span><span class="identifier">hidden</span></code> 360 or marking functions as exported produce a better stacktraces. 361 </p></div> 362<div id="ftn.stacktrace.configuration_and_build.f2" class="footnote"><p><a href="#stacktrace.configuration_and_build.f2" class="para"><sup class="para">[c] </sup></a> 363 This may affect other components of your program that use COM, 364 because this mode calls the <code class="computeroutput"><span class="identifier">CoInitializeEx</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="identifier">COINIT_MULTITHREADED</span><span class="special">)</span></code> on first use and does not call 365 <code class="computeroutput"><span class="special">::</span><span class="identifier">CoUninitialize</span><span class="special">();</span></code> until the current thread is 366 destroyed. 367 </p></div> 368<div id="ftn.stacktrace.configuration_and_build.f3" class="footnote"><p><a href="#stacktrace.configuration_and_build.f3" class="para"><sup class="para">[d] </sup></a> 369 If you are using Clang with libstdc++ you could get into troubles 370 of including <code class="computeroutput"><span class="special"><</span><span class="identifier">backtrace</span><span class="special">.</span><span class="identifier">h</span><span class="special">></span></code>, 371 because on some platforms Clang does not search for headers in 372 the GCC's include paths and any attempt to add GCC's include path 373 leads to linker errors. To explicitly specify a path to the <code class="computeroutput"><span class="special"><</span><span class="identifier">backtrace</span><span class="special">.</span><span class="identifier">h</span><span class="special">></span></code> header you could define the 374 <span class="bold"><strong>BOOST_STACKTRACE_BACKTRACE_INCLUDE_FILE</strong></span> 375 to a full path to the header. For example on Ubuntu Xenial use 376 the command line option <span class="bold"><strong>-DBOOST_STACKTRACE_BACKTRACE_INCLUDE_FILE=</usr/lib/gcc/x86_64-linux-gnu/5/include/backtrace.h></strong></span> 377 while building with Clang. 378 </p></div> 379</td></tr></tbody> 380</table></div> 381</div> 382<br class="table-break"><p> 383 <span class="bold"><strong>Examples:</strong></span> 384 </p> 385<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 386<li class="listitem"> 387 if you wish to switch to more powerful implementation on Clang/MinGW and 388 <span class="bold"><strong>BOOST_STACKTRACE_LINK</strong></span> is defined, you 389 just need link with "<span class="bold"><strong>-lboost_stacktrace_backtrace 390 -ldl -lbacktrace</strong></span>" or "<span class="bold"><strong>-lboost_stacktrace_addr2line 391 -ldl</strong></span>" 392 </li> 393<li class="listitem"> 394 if you wish to disable backtracing and <span class="bold"><strong>BOOST_STACKTRACE_LINK</strong></span> 395 is defined, you just need link with <span class="bold"><strong>-lboost_stacktrace_noop</strong></span> 396 </li> 397<li class="listitem"> 398 if you wish to disable backtracing and you use the library in header only 399 mode, you just need to define <span class="bold"><strong>BOOST_STACKTRACE_USE_NOOP</strong></span> 400 for the whole project and recompile it 401 </li> 402</ul></div> 403<div class="section"> 404<div class="titlepage"><div><div><h3 class="title"> 405<a name="stacktrace.configuration_and_build.mingw_and_mingw_w64_specific_not"></a><a class="link" href="configuration_and_build.html#stacktrace.configuration_and_build.mingw_and_mingw_w64_specific_not" title="MinGW and MinGW-w64 specific notes">MinGW 406 and MinGW-w64 specific notes</a> 407</h3></div></div></div> 408<p> 409 MinGW-w64 and MinGW (without -w64) users have to install libbacktrace for 410 getting better stacktraces. Follow the instruction: 411 </p> 412<p> 413 Let's assume that you've installed MinGW into C:\MinGW and downloaded <a href="https://github.com/ianlancetaylor/libbacktrace" target="_top">libbacktrace sources</a> 414 into C:\libbacktrace-master 415 </p> 416<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 417<li class="listitem"> 418 Configure & build libbacktrace from console: 419 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "> 420<li class="listitem"> 421 C:\MinGW\msys\1.0\bin\sh.exe 422 </li> 423<li class="listitem"> 424 cd /c/libbacktrace-master 425 </li> 426<li class="listitem"> 427 ./configure CC=/c/MinGW/bin/gcc.exe CXX=/c/MinGW/bin/g++.exe 428 </li> 429<li class="listitem"> 430 make 431 </li> 432<li class="listitem"> 433 ./libtool --mode=install /usr/bin/install -c libbacktrace.la '/c/libbacktrace-master' 434 </li> 435</ul></div> 436 </li> 437<li class="listitem"> 438 Add info to the project-config.jam in the Boost folder: 439 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"> 440 using gcc : 6 : "C:\MinGW\bin\g++.exe" : <compileflags>-I"C:\libbacktrace-master\" 441 <linkflags>-L"C:\libbacktrace-master\" ; 442 </li></ul></div> 443 </li> 444<li class="listitem"> 445 Now you can use a header only version by defining <span class="bold"><strong>BOOST_STACKTRACE_USE_BACKTRACE</strong></span> 446 for your project or build the stacktrace library from Boost folder: 447 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"> 448 b2.exe toolset=gcc-6 --with-stacktrace 449 </li></ul></div> 450 </li> 451</ul></div> 452</div> 453<div class="section"> 454<div class="titlepage"><div><div><h3 class="title"> 455<a name="stacktrace.configuration_and_build.windows_deployment_and_symbol_fi"></a><a class="link" href="configuration_and_build.html#stacktrace.configuration_and_build.windows_deployment_and_symbol_fi" title="Windows deployment and symbol files">Windows 456 deployment and symbol files</a> 457</h3></div></div></div> 458<p> 459 Function names may not be resolved after deployment of your application to 460 a different system. 461 </p> 462<p> 463 There are multiple ways to deal with that issue if you distribute PDB files 464 along with your application: 465 </p> 466<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 467<li class="listitem"> 468 Link your application and shared libraries with a properly set <code class="computeroutput"><span class="special">/</span><span class="identifier">PDBALTPATH</span></code> 469 flag, for example <code class="computeroutput"><span class="special">/</span><span class="identifier">PDBALTPATH</span><span class="special">:%</span><span class="identifier">_PDB</span><span class="special">%</span></code>. See <a href="https://docs.microsoft.com/en-us/cpp/build/reference/pdbaltpath-use-alternate-pdb-path" target="_top">official 470 documentation for more info</a>. 471 </li> 472<li class="listitem"> 473 Set the <code class="computeroutput"><span class="identifier">_NT_ALT_SYMBOL_PATH</span></code> 474 or <code class="computeroutput"><span class="identifier">_NT_SYMBOL_PATH</span></code> environment 475 variables of the target system to the path of the PDBs. See <a href="https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/symbol-path#controlling-the-symbol-path" target="_top">official 476 documentation for more info</a>. 477 </li> 478</ul></div> 479</div> 480</div> 481<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 482<td align="left"></td> 483<td align="right"><div class="copyright-footer">Copyright © 2016-2020 Antony Polukhin<p> 484 Distributed under the Boost Software License, Version 1.0. (See accompanying 485 file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) 486 </p> 487</div></td> 488</tr></table> 489<hr> 490<div class="spirit-nav"> 491<a accesskey="p" href="getting_started.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../stacktrace.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="acknowledgements.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> 492</div> 493</body> 494</html> 495
