Home Explore Help
Register Sign In
samien
/
boost
mirror of https://github.com/boostorg/boost
1
0
Fork 0
Files Issues 0 Wiki
Tree: bfbedca1dc
Branches Tags
boost
/
more
/
getting_started.html

getting_started.html 51 KB
History Raw

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843 
  1. <?xml version="1.0" encoding="utf-8" ?>
    2. 

  2. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
    3. 

  3. <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
    4. 

  4. <head>
    5. 

  5. <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    6. 

  6. <meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
    7. 

  7. <title>Getting Started With Boost  Boost</title>
    8. 

  8. <link rel="stylesheet" href="../rst.css" type="text/css" />
    9. 

  9. </head>
    10. 

  10. <body>
    11. 

  11. <div class="document" id="getting-started-with-boost-logo">
    12. 

  12. <h1 class="title">Getting Started With Boost  <a class="reference" href="../index.htm"><img alt="Boost" src="../boost.png" /></a></h1>
    13. 

  13. 

  14. <p>This guide will help you get started using the Boost libraries.
    15. 

  15. Have fun!</p>
    16. 

  16. <div class="contents topic">
    17. 

  17. <p class="topic-title first"><a id="index" name="index">Index</a></p>
    18. 

  18. <ul class="auto-toc simple">
    19. 

  19. <li><a class="reference" href="#getting-boost" id="id20" name="id20">1&nbsp;&nbsp;&nbsp;Getting Boost</a></li>
    20. 

  20. <li><a class="reference" href="#the-structure-of-a-boost-distribution" id="id21" name="id21">2&nbsp;&nbsp;&nbsp;The Structure of a Boost Distribution</a></li>
    21. 

  21. <li><a class="reference" href="#building-a-simple-boost-program" id="id22" name="id22">3&nbsp;&nbsp;&nbsp;Building a Simple Boost Program</a><ul class="auto-toc">
    22. 

  22. <li><a class="reference" href="#nix-e-g-unix-linux-macos-cygwin" id="id23" name="id23">3.1&nbsp;&nbsp;&nbsp;*nix (e.g. Unix, Linux, MacOS, Cygwin)</a></li>
    23. 

  23. <li><a class="reference" href="#microsoft-windows-command-line-using-visual-c" id="id24" name="id24">3.2&nbsp;&nbsp;&nbsp;Microsoft Windows Command-Line using Visual C++</a></li>
    24. 

  24. <li><a class="reference" href="#visual-studio-net-2003-or-visual-studio-2005" id="id25" name="id25">3.3&nbsp;&nbsp;&nbsp;Visual Studio .NET 2003 or Visual Studio 2005</a></li>
    25. 

  25. <li><a class="reference" href="#other-compilers-environments" id="id26" name="id26">3.4&nbsp;&nbsp;&nbsp;Other Compilers/Environments</a></li>
    26. 

  26. </ul>
    27. 

  27. </li>
    28. 

  28. <li><a class="reference" href="#getting-boost-library-binaries" id="id27" name="id27">4&nbsp;&nbsp;&nbsp;Getting Boost Library Binaries</a><ul class="auto-toc">
    29. 

  29. <li><a class="reference" href="#microsoft-visual-c-8-0-or-7-1-visual-studio-2005-net-2003-binaries" id="id28" name="id28">4.1&nbsp;&nbsp;&nbsp;Microsoft Visual C++ 8.0 or 7.1 (Visual Studio 2005/.NET 2003) Binaries</a></li>
    30. 

  30. <li><a class="reference" href="#nix-e-g-unix-linux-macos-cygwin-binaries" id="id29" name="id29">4.2&nbsp;&nbsp;&nbsp;*nix (e.g. Unix, Linux, MacOS, Cygwin) Binaries</a></li>
    31. 

  31. <li><a class="reference" href="#id7" id="id30" name="id30">4.3&nbsp;&nbsp;&nbsp;Other Compilers/Environments</a></li>
    32. 

  32. <li><a class="reference" href="#building-boost-binaries-with-boost-build" id="id31" name="id31">4.4&nbsp;&nbsp;&nbsp;Building Boost Binaries with Boost.Build</a><ul class="auto-toc">
    33. 

  33. <li><a class="reference" href="#getting-bjam" id="id32" name="id32">4.4.1&nbsp;&nbsp;&nbsp;Getting <tt class="docutils literal"><span class="pre">bjam</span></tt></a></li>
    34. 

  34. <li><a class="reference" href="#identify-your-toolset" id="id33" name="id33">4.4.2&nbsp;&nbsp;&nbsp;Identify Your Toolset</a></li>
    35. 

  35. <li><a class="reference" href="#select-a-build-directory" id="id34" name="id34">4.4.3&nbsp;&nbsp;&nbsp;Select a Build Directory</a></li>
    36. 

  36. <li><a class="reference" href="#invoke-bjam" id="id35" name="id35">4.4.4&nbsp;&nbsp;&nbsp;Invoke <tt class="docutils literal"><span class="pre">bjam</span></tt></a></li>
    37. 

  37. <li><a class="reference" href="#stage" id="id36" name="id36">4.4.5&nbsp;&nbsp;&nbsp;<tt class="docutils literal"><span class="pre">stage</span></tt></a></li>
    38. 

  38. <li><a class="reference" href="#select-a-prefix-directory" id="id37" name="id37">4.4.6&nbsp;&nbsp;&nbsp;Select a Prefix Directory</a></li>
    39. 

  39. </ul>
    40. 

  40. </li>
    41. 

  41. </ul>
    42. 

  42. </li>
    43. 

  43. <li><a class="reference" href="#linking-a-program-with-a-boost-library" id="id38" name="id38">5&nbsp;&nbsp;&nbsp;Linking A Program with a Boost Library</a><ul class="auto-toc">
    44. 

  44. <li><a class="reference" href="#microsoft-windows" id="id39" name="id39">5.1&nbsp;&nbsp;&nbsp;Microsoft Windows</a><ul class="auto-toc">
    45. 

  45. <li><a class="reference" href="#visual-c-command-line" id="id40" name="id40">5.1.1&nbsp;&nbsp;&nbsp;Visual C++ Command Line</a></li>
    46. 

  46. <li><a class="reference" href="#visual-studio-ide" id="id41" name="id41">5.1.2&nbsp;&nbsp;&nbsp;Visual Studio IDE</a></li>
    47. 

  47. </ul>
    48. 

  48. </li>
    49. 

  49. <li><a class="reference" href="#id13" id="id42" name="id42">5.2&nbsp;&nbsp;&nbsp;*nix (e.g. Unix, Linux, MacOS, Cygwin)</a></li>
    50. 

  50. <li><a class="reference" href="#library-naming" id="id43" name="id43">5.3&nbsp;&nbsp;&nbsp;Library Naming</a></li>
    51. 

  51. </ul>
    52. 

  52. </li>
    53. 

  53. </ul>
    54. 

  54. </div>
    55. 

  55. <!-- ## Update this substitution for each release -->
    56. 

  56. <div class="section">
    57. 

  57. <h1><a class="toc-backref" href="#id20" id="getting-boost" name="getting-boost">1&nbsp;&nbsp;&nbsp;Getting Boost</a></h1>
    58. 

  58. <p>There are basically three ways to get Boost on your system:</p>
    59. 

  59. <ol class="arabic simple">
    60. 

  60. <li>Download and run the <a class="reference" href="http://www.boost-consulting.com/download.html">Windows installer</a> supplied by Boost
    61. 

  61. Consulting (not available for Boost alpha/beta releases).</li>
    62. 

  62. </ol>
    63. 

  63. <!-- ## remove the parenthesized note for full releases -->
    64. 

  64. <ol class="arabic simple" start="2">
    65. 

  65. <li>or, <a class="reference" href="http://sourceforge.net/project/showfiles.php?group_id=7586&amp;package_id=8041&amp;release_id=376197">download a complete Boost distribution</a> from SourceForge.</li>
    66. 

  66. </ol>
    67. 

  67. <!-- ## Update this link for each release -->
    68. 

  68. <blockquote>
    69. 

  69. <table class="docutils field-list" frame="void" rules="none">
    70. 

  70. <col class="field-name" />
    71. 

  71. <col class="field-body" />
    72. 

  72. <tbody valign="top">
    73. 

  73. <tr class="field"><th class="field-name">Windows users:</th><td class="field-body"><p class="first"><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt><tt class="docutils literal"><span class="pre">.exe</span></tt> is a program you can
    74. 

  74. run to unpack the distribution; if you prefer not to download
    75. 

  75. executable programs, get <tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt><tt class="docutils literal"><span class="pre">.zip</span></tt> and use an
    76. 

  76. external tool to decompress it.  We don't recommend using
    77. 

  77. Windows' built-in decompression as it can be painfully slow
    78. 

  78. for large archives.</p>
    79. 

  79. </td>
    80. 

  80. </tr>
    81. 

  81. <tr class="field"><th class="field-name">*nix users:</th><td class="field-body"><p class="first">Download <tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt><tt class="docutils literal"><span class="pre">.tar.bz2</span></tt>, then, in the
    82. 

  82. directory where you want to put the Boost installation,
    83. 

  83. execute</p>
    84. 

  84. <pre class="last literal-block">
    85. 

  85. tar --bzip2 -xf <em>/path/to/</em><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt>.tar.bz2
    86. 

  86. </pre>
    87. 

  87. </td>
    88. 

  88. </tr>
    89. 

  89. </tbody>
    90. 

  90. </table>
    91. 

  91. </blockquote>
    92. 

  92. <ol class="arabic simple" start="3">
    93. 

  93. <li>or use a Boost package from RedHat, Debian, or some other
    94. 

  94. distribution packager.  These instructions may not work for you
    95. 

  95. if you use this method, because other packagers sometimes choose
    96. 

  96. to break Boost up into several packages or to reorganize the
    97. 

  97. directory structure of the Boost distribution.<a class="footnote-reference" href="#packagers" id="id3" name="id3"><sup>1</sup></a></li>
    98. 

  98. </ol>
    99. 

  99. </div>
    100. 

  100. <div class="section">
    101. 

  101. <h1><a class="toc-backref" href="#id21" id="the-structure-of-a-boost-distribution" name="the-structure-of-a-boost-distribution">2&nbsp;&nbsp;&nbsp;The Structure of a Boost Distribution</a></h1>
    102. 

  102. <p>This is is a sketch of the directory structure you'll get when you
    103. 

  103. unpack your Boost installation (windows users replace forward
    104. 

  104. slashes with backslashes):</p>
    105. 

  105. <pre class="literal-block">
    106. 

  106. <strong>boost_1_34_0/</strong> .................<em>The “boost root directory”</em>
    107. 

  107.    <strong>index.html</strong> ....................<em>A copy of www.boost.org</em>
    108. 

  108.    <strong>boost/</strong> .........................<em>All Boost Header files</em>
    109. 

  109.    <strong>libs/</strong> ............<em>Tests, .cpp</em>s<em>, docs, etc., by library</em><a class="footnote-reference" href="#installer-src" id="id4" name="id4"><sup>2</sup></a>
    110. 

  110.      <strong>index.html</strong> ........<em>Library documentation starts here</em>
    111. 

  111.      <strong>algorithm/</strong>
    112. 

  112.      <strong>any/</strong>
    113. 

  113.      <strong>array/</strong>
    114. 

  114.                      <em>…more libraries…</em>
    115. 

  115.    <strong>status/</strong> .........................<em>Boost-wide test suite</em>
    116. 

  116.    <strong>tools/</strong> ...........<em>Utilities, e.g. bjam, quickbook, bcp</em>
    117. 

  117.    <strong>more/</strong> ..........................<em>Policy documents, etc.</em>
    118. 

  118.    <strong>doc/</strong> ...............<em>A subset of all Boost library docs</em>
    119. 

  119. </pre>
    120. 

  120. <div class="sidebar">
    121. 

  121. <p class="first sidebar-title">Header Organization</p>
    122. 

  122. <p>The organization of Boost library headers isn't entirely uniform,
    123. 

  123. but most libraries follow a few patterns:</p>
    124. 

  124. <ul class="last simple">
    125. 

  125. <li>Some older libraries and most very small libraries place all
    126. 

  126. public headers directly into <tt class="docutils literal"><span class="pre">boost/</span></tt>.</li>
    127. 

  127. <li>Most libraries' public headers live in a subdirectory of
    128. 

  128. <tt class="docutils literal"><span class="pre">boost/</span></tt> named after the library.  For example, you'll find
    129. 

  129. the Type Traits Library's <tt class="docutils literal"><span class="pre">is_void.hpp</span></tt> header in
    130. 

  130. <tt class="docutils literal"><span class="pre">boost/type_traits/is_void.hpp</span></tt>.</li>
    131. 

  131. <li>Some libraries have an “aggregate header” in <tt class="docutils literal"><span class="pre">boost/</span></tt> that
    132. 

  132. <tt class="docutils literal"><span class="pre">#include</span></tt>s all of the library's other headers.  For
    133. 

  133. example, Boost.Python's aggregate header is
    134. 

  134. <tt class="docutils literal"><span class="pre">boost/python.hpp</span></tt>.</li>
    135. 

  135. <li>Most libraries place private headers in a subdirectory called
    136. 

  136. <tt class="docutils literal"><span class="pre">detail/</span></tt> or <tt class="docutils literal"><span class="pre">aux_/</span></tt>.  Don't look in these directories and
    137. 

  137. expect to find anything you can use.</li>
    138. 

  138. </ul>
    139. 

  139. </div>
    140. 

  140. <p>A few things are worth noting right off the bat:</p>
    141. 

  141. <ol class="arabic">
    142. 

  142. <li><p class="first">The path to the “boost root directory” is sometimes referred to
    143. 

  143. as <tt class="docutils literal"><span class="pre">$BOOST_ROOT</span></tt> in documentation and mailing lists.  If you
    144. 

  144. used the Windows installer, that will usually be <tt class="docutils literal"><span class="pre">C:\Program</span> <span class="pre">Files\boost\</span></tt><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt>.</p>
    145. 

  145. </li>
    146. 

  146. <li><p class="first">To compile anything in Boost, you need a directory containing
    147. 

  147. the <tt class="docutils literal"><span class="pre">boost/</span></tt> subdirectory in your <tt class="docutils literal"><span class="pre">#include</span></tt> path.  For most
    148. 

  148. compilers, that means adding</p>
    149. 

  149. <pre class="literal-block">
    150. 

  150. -I<tt class="docutils literal"><span class="pre">/</span></tt><em>path</em><tt class="docutils literal"><span class="pre">/</span></tt><em>to</em><tt class="docutils literal"><span class="pre">/</span></tt><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt>
    151. 

  151. </pre>
    152. 

  152. <p>to the command line.  Specific steps for setting up <tt class="docutils literal"><span class="pre">#include</span></tt>
    153. 

  153. paths in Microsoft Visual Studio follow later in this document;
    154. 

  154. if you use another IDE, please consult your product's
    155. 

  155. documentation for instructions.</p>
    156. 

  156. </li>
    157. 

  157. <li><p class="first">Since all of Boost's header files have the <tt class="docutils literal"><span class="pre">.hpp</span></tt> extension,
    158. 

  158. and live in the <tt class="docutils literal"><span class="pre">boost/</span></tt> subdirectory of the boost root, your
    159. 

  159. Boost <tt class="docutils literal"><span class="pre">#include</span></tt> directives will look like:</p>
    160. 

  160. <pre class="literal-block">
    161. 

  161. #include &lt;boost/<em>whatever</em>.hpp&gt;
    162. 

  162. </pre>
    163. 

  163. <p>or</p>
    164. 

  164. <pre class="literal-block">
    165. 

  165. #include &quot;boost/<em>whatever</em>.hpp&quot;
    166. 

  166. </pre>
    167. 

  167. </li>
    168. 

  168. </ol>
    169. 

  169. <blockquote>
    170. 

  170. depending on your religion as regards the use of angle bracket
    171. 

  171. includes.  Even Windows users can use forward slashes in
    172. 

  172. <tt class="docutils literal"><span class="pre">#include</span></tt> directives; your compiler doesn't care.</blockquote>
    173. 

  173. <ol class="arabic simple" start="4">
    174. 

  174. <li>Don't be distracted by the <tt class="docutils literal"><span class="pre">doc/</span></tt> subdirectory; it only
    175. 

  175. contains a subset of the Boost documentation.  Start with
    176. 

  176. <tt class="docutils literal"><span class="pre">libs/index.html</span></tt> if you're looking for the whole enchilada.</li>
    177. 

  177. </ol>
    178. 

  178. </div>
    179. 

  179. <div class="section">
    180. 

  180. <h1><a class="toc-backref" href="#id22" id="building-a-simple-boost-program" name="building-a-simple-boost-program">3&nbsp;&nbsp;&nbsp;Building a Simple Boost Program</a></h1>
    181. 

  181. <p>The first thing many people want to know is, “how do I build
    182. 

  182. Boost?”  The good news is that often, there's nothing to build.</p>
    183. 

  183. <div class="admonition-header-only-libraries admonition">
    184. 

  184. <p class="first admonition-title">Header-Only Libraries</p>
    185. 

  185. <p>Nearly all Boost libraries are <strong>header-only</strong>.  That is, most
    186. 

  186. consist entirely of header files containing templates and inline
    187. 

  187. functions, and require no separately-compiled library binaries
    188. 

  188. or special treatment when linking.</p>
    189. 

  189. <p>The only Boost libraries that are <em>not</em> header-only are:</p>
    190. 

  190. <ul class="simple">
    191. 

  191. <li>Boost.Filesystem</li>
    192. 

  192. <li>Boost.IOStreams</li>
    193. 

  193. <li>Boost.ProgramOptions</li>
    194. 

  194. <li>Boost.Python</li>
    195. 

  195. <li>Boost.Regex</li>
    196. 

  196. <li>Boost.Serialization</li>
    197. 

  197. <li>Boost.Signals</li>
    198. 

  198. <li>Boost.Test</li>
    199. 

  199. <li>Boost.Thread</li>
    200. 

  200. <li>Boost.Wave</li>
    201. 

  201. </ul>
    202. 

  202. <p class="last">The DateTime library has a separately-compiled
    203. 

  203. binary which is only needed if you're using a “legacy
    204. 

  204. compiler”(such as?).  The Graph library has a
    205. 

  205. separately-compiled binary, but you won't need it unless you
    206. 

  206. intend to <a class="reference" href="../libs/graph/doc/read_graphviz.html">parse GraphViz files</a>.</p>
    207. 

  207. </div>
    208. 

  208. <!-- ## Keep the list of non-header-only libraries up-to-date -->
    209. 

  209. <p>The following program reads a sequence of integers from standard
    210. 

  210. input, uses Boost.Lambda (a header-only library) to multiply each
    211. 

  211. one by three, and writes them to standard output:</p>
    212. 

  212. <pre class="literal-block">
    213. 

  213. #include &lt;boost/lambda/lambda.hpp&gt;
    214. 

  214. #include &lt;iostream&gt;
    215. 

  215. #include &lt;iterator&gt;
    216. 

  216. #include &lt;algorithm&gt;
    217. 

  217. 

  218. int main()
    219. 

  219. {
    220. 

  220.     using namespace boost::lambda;
    221. 

  221.     typedef std::istream_iterator&lt;int&gt; in;
    222. 

  222. 

  223.     std::for_each(
    224. 

  224.         in(std::cin), in(), std::cout &lt;&lt; (_1 * 3) &lt;&lt; &quot; &quot; );
    225. 

  225. }
    226. 

  226. </pre>
    227. 

  227. <p>Start by copying the text of this program into a file called
    228. 

  228. <tt class="docutils literal"><span class="pre">example.cpp</span></tt>.</p>
    229. 

  229. <div class="section">
    230. 

  230. <h2><a class="toc-backref" href="#id23" id="nix-e-g-unix-linux-macos-cygwin" name="nix-e-g-unix-linux-macos-cygwin"><span id="unix-header-only"></span>3.1&nbsp;&nbsp;&nbsp;*nix (e.g. Unix, Linux, MacOS, Cygwin)</a></h2>
    231. 

  231. <p>Simply issue the following command (<tt class="docutils literal"><span class="pre">$</span></tt> represents the
    232. 

  232. prompt issued by the shell, so don't type that):</p>
    233. 

  233. <pre class="literal-block">
    234. 

  234. <strong>$</strong> c++ -I <tt class="docutils literal"><span class="pre">/</span></tt><em>path</em><tt class="docutils literal"><span class="pre">/</span></tt><em>to</em><tt class="docutils literal"><span class="pre">/</span></tt><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt> example.cpp -o example
    235. 

  235. </pre>
    236. 

  236. <p>To test the result, type:</p>
    237. 

  237. <pre class="literal-block">
    238. 

  238. <strong>$</strong> echo 1 2 3 | ./example
    239. 

  239. </pre>
    240. 

  240. </div>
    241. 

  241. <div class="section">
    242. 

  242. <h2><a class="toc-backref" href="#id24" id="microsoft-windows-command-line-using-visual-c" name="microsoft-windows-command-line-using-visual-c">3.2&nbsp;&nbsp;&nbsp;Microsoft Windows Command-Line using Visual C++</a></h2>
    243. 

  243. <p>From your computer's <em>Start</em> menu, select if you are a Visual
    244. 

  244. Studio 2005 user, select</p>
    245. 

  245. <blockquote>
    246. 

  246. <em>All Programs</em> &gt; <em>Microsoft Visual Studio 2005</em>
    247. 

  247. &gt; <em>Visual Studio Tools</em> &gt; <em>Visual Studio 2005 Command Prompt</em></blockquote>
    248. 

  248. <p>or if you're a Visual Studio .NET 2003 user, select</p>
    249. 

  249. <blockquote>
    250. 

  250. <em>All Programs</em> &gt; <em>Microsoft Visual Studio .NET 2003</em>
    251. 

  251. &gt; <em>Visual Studio .NET Tools</em> &gt; <em>Visual Studio .NET 2003 Command Prompt</em></blockquote>
    252. 

  252. <p>to bring up a special command prompt window set up for the Visual
    253. 

  253. Studio compiler.  In that window, type the following command and
    254. 

  254. hit the return key (<tt class="docutils literal"><span class="pre">C:\PROMPT&gt;</span></tt> represents the prompt issued by
    255. 

  255. the shell, so don't type that):</p>
    256. 

  256. <pre class="literal-block">
    257. 

  257. <strong>C:PROMPT&gt;</strong> cl /EHsc /I <em>C:</em><tt class="docutils literal"><span class="pre">\</span></tt><em>path</em><tt class="docutils literal"><span class="pre">\</span></tt><em>to</em><tt class="docutils literal"><span class="pre">\</span></tt><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt> example.cpp
    258. 

  258. </pre>
    259. 

  259. <p>To test the result, type:</p>
    260. 

  260. <pre class="literal-block">
    261. 

  261. <strong>C:PROMPT&gt;</strong> echo 1 2 3 | example
    262. 

  262. </pre>
    263. 

  263. </div>
    264. 

  264. <div class="section">
    265. 

  265. <h2><a class="toc-backref" href="#id25" id="visual-studio-net-2003-or-visual-studio-2005" name="visual-studio-net-2003-or-visual-studio-2005"><span id="vs-header-only"></span>3.3&nbsp;&nbsp;&nbsp;Visual Studio .NET 2003 or Visual Studio 2005</a></h2>
    266. 

  266. <ul class="simple">
    267. 

  267. <li>From Visual Studio's <em>File</em> menu, select <em>New</em> &gt; <em>Project…</em></li>
    268. 

  268. <li>In the left-hand pane of the resulting <em>New Project</em> dialog,
    269. 

  269. select <em>Visual C++</em> &gt; <em>Win32</em>.</li>
    270. 

  270. <li>In the right-hand pane, select <em>Win32 Console Application</em>
    271. 

  271. (VS8.0) or <em>Win32 Console Project</em> (VS7.1).</li>
    272. 

  272. <li>In the <em>name</em> field, enter “example”</li>
    273. 

  273. <li>Right-click <strong>example</strong> in the <em>Solution Explorer</em> pane and
    274. 

  274. select <em>Properties</em> from the resulting pop-up menu</li>
    275. 

  275. <li>In <em>Configuration Properties</em> &gt; <em>C/C++</em> &gt; <em>General</em> &gt; <em>Additional Include
    276. 

  276. Directories</em>, enter the path to the Boost root directory, e.g.
    277. 

  277. <tt class="docutils literal"><span class="pre">C:\Program</span> <span class="pre">Files\boost\</span></tt><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt>.</li>
    278. 

  278. <li>In <em>Configuration Properties</em> &gt; <em>C/C++</em> &gt; <em>Precompiled Headers</em>, change
    279. 

  279. <em>Use Precompiled Header (/Yu)</em> to <em>Not Using Precompiled
    280. 

  280. Headers</em>.<a class="footnote-reference" href="#pch" id="id6" name="id6"><sup>3</sup></a></li>
    281. 

  281. <li>Replace the contents of the <tt class="docutils literal"><span class="pre">example.cpp</span></tt> generated by the IDE
    282. 

  282. with the example code above.</li>
    283. 

  283. <li>From the <em>Build</em> menu, select <em>Build Solution</em>.</li>
    284. 

  284. </ul>
    285. 

  285. <p>To test your application, hit the F5 key and type the following
    286. 

  286. into the resulting window, followed by the return key:</p>
    287. 

  287. <pre class="literal-block">
    288. 

  288. 1 2 3
    289. 

  289. </pre>
    290. 

  290. <p>Then hold down the control key and press &quot;Z&quot;, followed by the
    291. 

  291. return key.</p>
    292. 

  292. </div>
    293. 

  293. <div class="section">
    294. 

  294. <h2><a class="toc-backref" href="#id26" id="other-compilers-environments" name="other-compilers-environments">3.4&nbsp;&nbsp;&nbsp;Other Compilers/Environments</a></h2>
    295. 

  295. <p>Consult your vendor's documentation; if you have trouble adapting
    296. 

  296. these instructions to your build environment, request assistance on
    297. 

  297. the <a class="reference" href="mailing_lists.htm#users">Boost Users' mailing list</a>.</p>
    298. 

  298. </div>
    299. 

  299. </div>
    300. 

  300. <div class="section">
    301. 

  301. <h1><a class="toc-backref" href="#id27" id="getting-boost-library-binaries" name="getting-boost-library-binaries">4&nbsp;&nbsp;&nbsp;Getting Boost Library Binaries</a></h1>
    302. 

  302. <p>If you want to use any of the separately-compiled Boost libraries,
    303. 

  303. you'll need to get ahold of library binaries.</p>
    304. 

  304. <div class="section">
    305. 

  305. <h2><a class="toc-backref" href="#id28" id="microsoft-visual-c-8-0-or-7-1-visual-studio-2005-net-2003-binaries" name="microsoft-visual-c-8-0-or-7-1-visual-studio-2005-net-2003-binaries">4.1&nbsp;&nbsp;&nbsp;Microsoft Visual C++ 8.0 or 7.1 (Visual Studio 2005/.NET 2003) Binaries</a></h2>
    306. 

  306. <p>The <a class="reference" href="http://www.boost-consulting.com/download.html">Windows installer</a> supplied by Boost Consulting will download
    307. 

  307. and install pre-compiled binaries into the <tt class="docutils literal"><span class="pre">lib\</span></tt> subdirectory of
    308. 

  308. the boost root, typically <tt class="docutils literal"><span class="pre">C:\Program</span> <span class="pre">Files\boost\</span></tt><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt><tt class="docutils literal"><span class="pre">\lib\</span></tt>.</p>
    309. 

  309. </div>
    310. 

  310. <div class="section">
    311. 

  311. <h2><a class="toc-backref" href="#id29" id="nix-e-g-unix-linux-macos-cygwin-binaries" name="nix-e-g-unix-linux-macos-cygwin-binaries">4.2&nbsp;&nbsp;&nbsp;*nix (e.g. Unix, Linux, MacOS, Cygwin) Binaries</a></h2>
    312. 

  312. <p>Issue the following commands in the shell (again, <tt class="docutils literal"><span class="pre">$</span></tt> represents
    313. 

  313. the shell's prompt):</p>
    314. 

  314. <pre class="literal-block">
    315. 

  315. <strong>$</strong> cd <tt class="docutils literal"><span class="pre">/</span></tt><em>path</em><tt class="docutils literal"><span class="pre">/</span></tt><em>to</em><tt class="docutils literal"><span class="pre">/</span></tt><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt>
    316. 

  316. <strong>$</strong> ./configure --help
    317. 

  317. </pre>
    318. 

  318. <p>Select your configuration options and invoke <tt class="docutils literal"><span class="pre">./configure</span></tt> again.
    319. 

  319. Unless you have write permission in your system's <tt class="docutils literal"><span class="pre">/usr/local/</span></tt>
    320. 

  320. directory, you'll probably want to at least use</p>
    321. 

  321. <pre class="literal-block">
    322. 

  322. <strong>$</strong> ./configure <strong>--prefix=</strong><em>path</em>/<em>to</em>/<em>installation</em>/<em>prefix</em>
    323. 

  323. </pre>
    324. 

  324. <p>to install somewhere else.  Finally,</p>
    325. 

  325. <pre class="literal-block">
    326. 

  326. <strong>$</strong> make install
    327. 

  327. </pre>
    328. 

  328. <p>which will leave Boost binaries in the <tt class="docutils literal"><span class="pre">lib/</span></tt> subdirectory of
    329. 

  329. your installation prefix.  You will also find a copy of the Boost
    330. 

  330. headers in the <tt class="docutils literal"><span class="pre">include/</span></tt> subdirectory of the installation
    331. 

  331. prefix, so you can henceforth use that directory as an <tt class="docutils literal"><span class="pre">#include</span></tt>
    332. 

  332. path in place of the Boost root directory.</p>
    333. 

  333. </div>
    334. 

  334. <div class="section">
    335. 

  335. <h2><a class="toc-backref" href="#id30" id="id7" name="id7">4.3&nbsp;&nbsp;&nbsp;Other Compilers/Environments</a></h2>
    336. 

  336. <p>If you're not using Visual C++ 7.1 or 8.0, or you're a *nix user
    337. 

  337. who wants want to build with a toolset other than your system's
    338. 

  338. default, or if you want a nonstandard variant build of Boost
    339. 

  339. (e.g. optimized, but with debug symbols), you'll need to use
    340. 

  340. <a class="reference" href="../tools/build/index.html">Boost.Build</a> to create your own binaries.</p>
    341. 

  341. </div>
    342. 

  342. <div class="section">
    343. 

  343. <h2><a id="building-boost-binaries-with-boost-build" name="building-boost-binaries-with-boost-build">4.4&nbsp;&nbsp;&nbsp;Building Boost Binaries with <a class="reference" href="../tools/build/index.html">Boost.Build</a></a></h2>
    344. 

  344. <p>Like an IDE, <a class="reference" href="../tools/build/index.html">Boost.Build</a> is a system for developing, testing, and
    345. 

  345. installing software.  Instead of using a GUI, though, <a class="reference" href="../tools/build/index.html">Boost.Build</a>
    346. 

  346. is text-based, like <tt class="docutils literal"><span class="pre">make</span></tt>.  <a class="reference" href="../tools/build/index.html">Boost.Build</a> is written in the
    347. 

  347. interpreted <a class="reference" href="../tools/jam/index.html">Boost.Jam</a> language.</p>
    348. 

  348. <p>To use <a class="reference" href="../tools/build/index.html">Boost.Build</a>, you'll need an executable called <tt class="docutils literal"><span class="pre">bjam</span></tt>, the
    349. 

  349. <a class="reference" href="../tools/jam/index.html">Boost.Jam</a> interpreter.</p>
    350. 

  350. <!-- nosidebar .. sidebar:: Using Boost.Build for your own project
    351. 

  351. 

  352. When you use Boost.Build to build your *own* project, you don't
    353. 

  353. need a separate step to create Boost binaries: you simply refer
    354. 

  354. to the boost library targets from your Jamfile and the are built
    355. 

  355. automatically (refer to the `Boost.Build documentation`_ for
    356. 

  356. detailed instructions).  Here, we're assuming you're using a
    357. 

  357. different build system for your own code, so you need to
    358. 

  358. explicitly generate Boost binaries.  We're also assuming that
    359. 

  359. you have a complete Boost distribution somewhere. -->
    360. 

  360. <div class="section">
    361. 

  361. <h3><a class="toc-backref" href="#id32" id="getting-bjam" name="getting-bjam">4.4.1&nbsp;&nbsp;&nbsp;Getting <tt class="docutils literal"><span class="pre">bjam</span></tt></a></h3>
    362. 

  362. <div class="sidebar">
    363. 

  363. <p class="first sidebar-title">Using command-line tools in Windows</p>
    364. 

  364. <p>In Windows, a command-line tool is invoked by typing its name,
    365. 

  365. optionally followed by arguments, into a <em>Command Prompt</em> window
    366. 

  366. and pressing the Return (or Enter) key.</p>
    367. 

  367. <p>To open <em>Command Prompt</em>, click the <em>Start</em> menu button, click
    368. 

  368. <em>Run</em>, type “cmd”, and then click OK.</p>
    369. 

  369. <p>All commands are executed within the context of a <strong>current
    370. 

  370. directory</strong> in the filesystem.  To set the current directory,
    371. 

  371. type:</p>
    372. 

  372. <pre class="literal-block">
    373. 

  373. cd <em>path</em>\<em>to</em>\<em>some</em>\<em>directory</em>
    374. 

  374. </pre>
    375. 

  375. <p>followed by Return.  For example,</p>
    376. 

  376. <pre class="literal-block">
    377. 

  377. cd <tt class="docutils literal"><span class="pre">C:\Program</span> <span class="pre">Files\boost\</span></tt><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt>
    378. 

  378. </pre>
    379. 

  379. <p>One way to name a directory you know about is to write</p>
    380. 

  380. <pre class="literal-block">
    381. 

  381. %HOMEDRIVE%%HOMEPATH%\<em>directory-name</em>
    382. 

  382. </pre>
    383. 

  383. <p>which indicates a sibling folder of your “My Documents” folder.</p>
    384. 

  384. <p class="last">Long commands can be continued across several lines by typing
    385. 

  385. backslashes at the ends of all but the last line.  Many of the
    386. 

  386. examples on this page use that technique to save horizontal
    387. 

  387. space.</p>
    388. 

  388. </div>
    389. 

  389. <p>Boost provides <a class="reference" href="http://sourceforge.net/project/showfiles.php?group_id=7586&amp;package_id=72941">pre-compiled <tt class="docutils literal"><span class="pre">bjam</span></tt> executables</a> for a variety of platforms.
    390. 

  390. Alternatively, you can build <tt class="docutils literal"><span class="pre">bjam</span></tt> yourself using the
    391. 

  391. <a class="reference" href="http://www.boost.org/doc/html/jam/building.html">instructions</a> given in the <a class="reference" href="../tools/jam/index.html">Boost.Jam documentation</a>.</p>
    392. 

  392. <p><tt class="docutils literal"><span class="pre">bjam</span></tt> is a command-line tool.  To build Boost binaries, you'll
    393. 

  393. invoke <tt class="docutils literal"><span class="pre">bjam</span></tt> with the current directory set to the Boost root,
    394. 

  394. and with options described in the following sections.</p>
    395. 

  395. </div>
    396. 

  396. <div class="section">
    397. 

  397. <h3><a class="toc-backref" href="#id33" id="identify-your-toolset" name="identify-your-toolset"><span id="toolset-name"></span><span id="toolset"></span>4.4.2&nbsp;&nbsp;&nbsp;Identify Your Toolset</a></h3>
    398. 

  398. <p>First, find the toolset corresponding to your compiler in the
    399. 

  399. following table.</p>
    400. 

  400. <table border="1" class="docutils">
    401. 

  401. <colgroup>
    402. 

  402. <col width="18%" />
    403. 

  403. <col width="33%" />
    404. 

  404. <col width="48%" />
    405. 

  405. </colgroup>
    406. 

  406. <thead valign="bottom">
    407. 

  407. <tr><th class="head">Toolset
    408. 

  408. Name</th>
    409. 

  409. <th class="head">Vendor</th>
    410. 

  410. <th class="head">Notes</th>
    411. 

  411. </tr>
    412. 

  412. </thead>
    413. 

  413. <tbody valign="top">
    414. 

  414. <tr><td><tt class="docutils literal"><span class="pre">acc</span></tt></td>
    415. 

  415. <td>Hewlett Packard</td>
    416. 

  416. <td>Only very recent versions are
    417. 

  417. known to work well with Boost</td>
    418. 

  418. </tr>
    419. 

  419. <tr><td><tt class="docutils literal"><span class="pre">borland</span></tt></td>
    420. 

  420. <td>Borland</td>
    421. 

  421. <td>&nbsp;</td>
    422. 

  422. </tr>
    423. 

  423. <tr><td><tt class="docutils literal"><span class="pre">como</span></tt></td>
    424. 

  424. <td>Comeau Computing</td>
    425. 

  425. <td>Using this toolset may
    426. 

  426. require <a class="reference" href="../tools/build/index.html">configuring</a> another
    427. 

  427. toolset to act as its backend</td>
    428. 

  428. </tr>
    429. 

  429. <tr><td><tt class="docutils literal"><span class="pre">cw</span></tt></td>
    430. 

  430. <td>Metrowerks/FreeScale</td>
    431. 

  431. <td>The CodeWarrior compiler.  We
    432. 

  432. have not tested versions of
    433. 

  433. this compiler produced since
    434. 

  434. it was sold to FreeScale.</td>
    435. 

  435. </tr>
    436. 

  436. <tr><td><tt class="docutils literal"><span class="pre">dmc</span></tt></td>
    437. 

  437. <td>Digital Mars</td>
    438. 

  438. <td>As of this Boost release, no
    439. 

  439. version of dmc is known to
    440. 

  440. handle Boost well.</td>
    441. 

  441. </tr>
    442. 

  442. <tr><td><tt class="docutils literal"><span class="pre">gcc</span></tt></td>
    443. 

  443. <td>The Gnu Project</td>
    444. 

  444. <td>&nbsp;</td>
    445. 

  445. </tr>
    446. 

  446. <tr><td><tt class="docutils literal"><span class="pre">hp_cxx</span></tt></td>
    447. 

  447. <td>Hewlett Packard</td>
    448. 

  448. <td>Targeted at the Tru64
    449. 

  449. operating system.</td>
    450. 

  450. </tr>
    451. 

  451. <tr><td><tt class="docutils literal"><span class="pre">intel</span></tt></td>
    452. 

  452. <td>Intel</td>
    453. 

  453. <td>&nbsp;</td>
    454. 

  454. </tr>
    455. 

  455. <tr><td><tt class="docutils literal"><span class="pre">kylix</span></tt></td>
    456. 

  456. <td>Borland</td>
    457. 

  457. <td>&nbsp;</td>
    458. 

  458. </tr>
    459. 

  459. <tr><td><tt class="docutils literal"><span class="pre">msvc</span></tt></td>
    460. 

  460. <td>Microsoft</td>
    461. 

  461. <td>&nbsp;</td>
    462. 

  462. </tr>
    463. 

  463. <tr><td><tt class="docutils literal"><span class="pre">qcc</span></tt></td>
    464. 

  464. <td>QNX Software Systems</td>
    465. 

  465. <td>&nbsp;</td>
    466. 

  466. </tr>
    467. 

  467. <tr><td><tt class="docutils literal"><span class="pre">sun</span></tt></td>
    468. 

  468. <td>Sun</td>
    469. 

  469. <td>&nbsp;</td>
    470. 

  470. </tr>
    471. 

  471. <tr><td><tt class="docutils literal"><span class="pre">vacpp</span></tt></td>
    472. 

  472. <td>IBM</td>
    473. 

  473. <td>The VisualAge C++ compiler.</td>
    474. 

  474. </tr>
    475. 

  475. </tbody>
    476. 

  476. </table>
    477. 

  477. <p>If you have multiple versions of a particular compiler installed,
    478. 

  478. you can apend the version number to the toolset name, preceded by a
    479. 

  479. hyphen, e.g. <tt class="docutils literal"><span class="pre">msvc-7.1</span></tt> or <tt class="docutils literal"><span class="pre">gcc-3.4</span></tt>.</p>
    480. 

  480. <div class="note">
    481. 

  481. <p class="first admonition-title">Note</p>
    482. 

  482. <p class="last">if you built <tt class="docutils literal"><span class="pre">bjam</span></tt> yourself, you may
    483. 

  483. have selected a toolset name for that purpose, but that does not
    484. 

  484. affect this step in any way; you still need to select a Boost.Build
    485. 

  485. toolset from the table.</p>
    486. 

  486. </div>
    487. 

  487. </div>
    488. 

  488. <div class="section">
    489. 

  489. <h3><a class="toc-backref" href="#id34" id="select-a-build-directory" name="select-a-build-directory"><span id="id10"></span><span id="build-directory"></span>4.4.3&nbsp;&nbsp;&nbsp;Select a Build Directory</a></h3>
    490. 

  490. <p><a class="reference" href="../tools/build/index.html">Boost.Build</a> will place all intermediate files it generates while
    491. 

  491. building into the <strong>build directory</strong>.  If your Boost root
    492. 

  492. directory is writable, this step isn't strictly necessary: by
    493. 

  493. default Boost.Build will create a <tt class="docutils literal"><span class="pre">bin.v2/</span></tt> subdirectory for that
    494. 

  494. purpose in your current working directory.</p>
    495. 

  495. </div>
    496. 

  496. <div class="section">
    497. 

  497. <h3><a class="toc-backref" href="#id35" id="invoke-bjam" name="invoke-bjam">4.4.4&nbsp;&nbsp;&nbsp;Invoke <tt class="docutils literal"><span class="pre">bjam</span></tt></a></h3>
    498. 

  498. <p>Change your current directory to the Boost root directory and
    499. 

  499. invoke <tt class="docutils literal"><span class="pre">bjam</span></tt> as follows:</p>
    500. 

  500. <pre class="literal-block">
    501. 

  501. bjam --build-dir=<a class="reference" href="#id10"><em>build-directory</em></a> <strong>\</strong>
    502. 

  502.      --toolset=<a class="reference" href="#toolset-name"><em>toolset-name</em></a> stage
    503. 

  503. </pre>
    504. 

  504. <p>For example, on Windows, your session might look like:</p>
    505. 

  505. <pre class="literal-block">
    506. 

  506. C:WINDOWS&gt; cd <tt class="docutils literal"><span class="pre">C:\Program</span> <span class="pre">Files\boost\</span></tt><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt>
    507. 

  507. <tt class="docutils literal"><span class="pre">C:\Program</span> <span class="pre">Files\boost\</span></tt><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt>&gt; bjam   <strong>\</strong>
    508. 

  508.   <strong>--build-dir=</strong>%HOMEDRIVE%%HOMEPATH%\build-boost    <strong>\</strong>
    509. 

  509.   <strong>--toolset=msvc stage</strong>
    510. 

  510. </pre>
    511. 

  511. <div class="note">
    512. 

  512. <p class="first admonition-title">Note</p>
    513. 

  513. <p class="last"><tt class="docutils literal"><span class="pre">bjam</span></tt> is case-sensitive; it is important that all the
    514. 

  514. parts shown in <strong>bold</strong> type above be entirely lower-case.</p>
    515. 

  515. </div>
    516. 

  516. <p>And on Unix:</p>
    517. 

  517. <pre class="literal-block">
    518. 

  518. ~$ cd ~/<tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt>
    519. 

  519. ~/<tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt>$ bjam --build-dir=~/build-boost --prefix=~/boost
    520. 

  520. </pre>
    521. 

  521. <p>In either case, Boost.Build will place the Boost binaries in the
    522. 

  522. <tt class="docutils literal"><span class="pre">stage/</span></tt> subdirectory of your <em>build directory</em>.</p>
    523. 

  523. </div>
    524. 

  524. <div class="section">
    525. 

  525. <h3><a class="toc-backref" href="#id36" id="stage" name="stage">4.4.5&nbsp;&nbsp;&nbsp;<tt class="docutils literal"><span class="pre">stage</span></tt></a></h3>
    526. 

  526. <p>You already have the Boost headers on your system (in the
    527. 

  527. <tt class="docutils literal"><span class="pre">boost/</span></tt> subdirectory of your Boost distribution), so if you
    528. 

  528. prefer not to create an additional copy, instead of installing
    529. 

  529. Boost you can simply “stage” the Boost binaries, which leaves them
    530. 

  530. in the <tt class="docutils literal"><span class="pre">stage/</span></tt> subdirectory of your chosen <a class="reference" href="#build-directory">build directory</a>:</p>
    531. 

  531. <pre class="literal-block">
    532. 

  532. bjam --build-dir=<a class="reference" href="#id10"><em>build-directory</em></a>   <strong>\</strong>
    533. 

  533.      --toolset=<a class="reference" href="#toolset-name"><em>toolset-name</em></a> stage
    534. 

  534. </pre>
    535. 

  535. </div>
    536. 

  536. <div class="section">
    537. 

  537. <h3><a class="toc-backref" href="#id37" id="select-a-prefix-directory" name="select-a-prefix-directory"><span id="id11"></span><span id="prefix-directory"></span>4.4.6&nbsp;&nbsp;&nbsp;Select a Prefix Directory</a></h3>
    538. 

  538. <p>Choose a <strong>prefix directory</strong>.  The installation process will
    539. 

  539. leave you with the following subdirectories of the prefix directory:</p>
    540. 

  540. <ul class="simple">
    541. 

  541. <li><tt class="docutils literal"><span class="pre">lib</span></tt>, containing the Boost binaries</li>
    542. 

  542. <li><tt class="docutils literal"><span class="pre">include/</span></tt><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt>, containing the Boost headers.</li>
    543. 

  543. </ul>
    544. 

  544. <p>Change your current directory to the Boost root directory and
    545. 

  545. invoke <tt class="docutils literal"><span class="pre">bjam</span></tt> as follows:</p>
    546. 

  546. <pre class="literal-block">
    547. 

  547. bjam --build-dir=<a class="reference" href="#id10"><em>build-directory</em></a>   <strong>\</strong>
    548. 

  548.      --toolset=<a class="reference" href="#toolset-name"><em>toolset-name</em></a>        <strong>\</strong>
    549. 

  549.       --prefix=<a class="reference" href="#id11"><em>prefix-directory</em></a> install
    550. 

  550. </pre>
    551. 

  551. <p>For example, on Windows your session might look like:</p>
    552. 

  552. <pre class="literal-block">
    553. 

  553. C:WINDOWS&gt; cd <tt class="docutils literal"><span class="pre">C:\Program</span> <span class="pre">Files\boost\</span></tt><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt>
    554. 

  554. <tt class="docutils literal"><span class="pre">C:\Program</span> <span class="pre">Files\boost\</span></tt><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt>&gt; bjam   <strong>\</strong>
    555. 

  555.     --build-dir=C:\TEMP\build-boost         <strong>\</strong>
    556. 

  556.     --prefix=C:\boost
    557. 

  557. </pre>
    558. 

  558. <p>And on Unix:</p>
    559. 

  559. <pre class="literal-block">
    560. 

  560. ~$ cd ~/<tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt>
    561. 

  561. ~/<tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt>$ bjam --build-dir=/tmp/build-boost <strong>\</strong>
    562. 

  562.      --prefix=~/boost
    563. 

  563. </pre>
    564. 

  564. </div>
    565. 

  565. </div>
    566. 

  566. </div>
    567. 

  567. <div class="section">
    568. 

  568. <h1><a class="toc-backref" href="#id38" id="linking-a-program-with-a-boost-library" name="linking-a-program-with-a-boost-library">5&nbsp;&nbsp;&nbsp;Linking A Program with a Boost Library</a></h1>
    569. 

  569. <p>To demonstrate linking with a Boost binary library, we'll use the
    570. 

  570. following simple program that extracts the subject lines from
    571. 

  571. emails.  It uses the <a class="reference" href="../libs/regex">Boost.Regex</a> library, which has a
    572. 

  572. separately-compiled binary component.</p>
    573. 

  573. <pre class="literal-block">
    574. 

  574. #include &lt;boost/regex.hpp&gt;
    575. 

  575. #include &lt;iostream&gt;
    576. 

  576. #include &lt;string&gt;
    577. 

  577. 

  578. int main()
    579. 

  579. {
    580. 

  580.     std::string line;
    581. 

  581.     boost::regex pat( &quot;^Subject: (Re: |Aw: )*(.*)&quot; );
    582. 

  582. 

  583.     while (std::cin)
    584. 

  584.     {
    585. 

  585.         std::getline(std::cin, line);
    586. 

  586.         boost::smatch matches;
    587. 

  587.         if (boost::regex_match(line, matches, pat))
    588. 

  588.             std::cout &lt;&lt; matches[2];
    589. 

  589.     }
    590. 

  590. }
    591. 

  591. </pre>
    592. 

  592. <p>There are two main challenges associated with linking:</p>
    593. 

  593. <ol class="arabic simple">
    594. 

  594. <li>Tool configuration, e.g. choosing command-line options or IDE
    595. 

  595. build settings.</li>
    596. 

  596. <li>Identifying the library binary, among all the build variants,
    597. 

  597. whose compile configuration is compatible with the rest of your
    598. 

  598. project.</li>
    599. 

  599. </ol>
    600. 

  600. <div class="section">
    601. 

  601. <h2><a class="toc-backref" href="#id39" id="microsoft-windows" name="microsoft-windows">5.1&nbsp;&nbsp;&nbsp;Microsoft Windows</a></h2>
    602. 

  602. <p>Most Windows compilers and linkers have so called “auto-linking
    603. 

  603. support,” which is used by many Boost libraries to eliminate the
    604. 

  604. second challenge.  Special code in Boost header files detects your
    605. 

  605. compiler options and uses that information to encode the name of
    606. 

  606. the correct library into your object files; the linker selects the
    607. 

  607. library with that name from the directories you've told it to
    608. 

  608. search.</p>
    609. 

  609. <div class="note">
    610. 

  610. <p class="first admonition-title">Note</p>
    611. 

  611. <p>As of this writing, a few Boost libraries don't support
    612. 

  612. auto-linking:</p>
    613. 

  613. <ul class="last simple">
    614. 

  614. <li>Boost.Python</li>
    615. 

  615. <li>…others?…</li>
    616. 

  616. </ul>
    617. 

  617. </div>
    618. 

  618. <div class="section">
    619. 

  619. <h3><a class="toc-backref" href="#id40" id="visual-c-command-line" name="visual-c-command-line">5.1.1&nbsp;&nbsp;&nbsp;Visual C++ Command Line</a></h3>
    620. 

  620. <p>For example, we can compile and link the above program from the
    621. 

  621. Visual C++ command-line by simply adding the <strong>bold</strong> text below to
    622. 

  622. the command line we used earlier, assuming your Boost binaries are
    623. 

  623. in <tt class="docutils literal"><span class="pre">C:\Program</span> <span class="pre">Files\boost\</span></tt><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt><tt class="docutils literal"><span class="pre">\lib</span></tt>:</p>
    624. 

  624. <pre class="literal-block">
    625. 

  625. C:PROMPT&gt; cl /EHsc /I <em>C:</em><tt class="docutils literal"><span class="pre">\</span></tt><em>path</em><tt class="docutils literal"><span class="pre">\</span></tt><em>to</em><tt class="docutils literal"><span class="pre">\</span></tt><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt> example.cpp   <strong>\</strong>
    626. 

  626.      <strong>/link /LIBPATH:</strong> <strong>C:\Program Files\boost\</strong><strong>boost_1_34_0</strong><strong>\lib</strong>
    627. 

  627. </pre>
    628. 

  628. <p>To link with a library that doesn't use auto-linking support, you
    629. 

  629. need to specify the library name.  For example,</p>
    630. 

  630. <pre class="literal-block">
    631. 

  631. C:PROMPT&gt; cl /EHsc /I <em>C:</em><tt class="docutils literal"><span class="pre">\</span></tt><em>path</em><tt class="docutils literal"><span class="pre">\</span></tt><em>to</em><tt class="docutils literal"><span class="pre">\</span></tt><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt> example.cpp   <strong>\</strong>
    632. 

  632.      /link /LIBPATH: <tt class="docutils literal"><span class="pre">C:\Program</span> <span class="pre">Files\boost\</span></tt><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt>    <strong>\</strong>
    633. 

  633.      <strong>boost_regex-msvc-7.1-mt-d-1_34.lib</strong>
    634. 

  634. </pre>
    635. 

  635. <p>See <a class="reference" href="#library-naming">Library Naming</a> for details about how to select the right
    636. 

  636. library name.</p>
    637. 

  637. </div>
    638. 

  638. <div class="section">
    639. 

  639. <h3><a class="toc-backref" href="#id41" id="visual-studio-ide" name="visual-studio-ide">5.1.2&nbsp;&nbsp;&nbsp;Visual Studio IDE</a></h3>
    640. 

  640. <p>Starting with the <a class="reference" href="#vs-header-only">header-only example project</a> we created
    641. 

  641. earlier:</p>
    642. 

  642. <ol class="arabic simple">
    643. 

  643. <li>Right-click <strong>example</strong> in the <em>Solution Explorer</em> pane and
    644. 

  644. select <em>Properties</em> from the resulting pop-up menu</li>
    645. 

  645. <li>In <em>Configuration Properties</em> &gt; <em>Linker</em> &gt; <em>Additional Library
    646. 

  646. Directories</em>, enter the path to the Boost binaries,
    647. 

  647. e.g. <tt class="docutils literal"><span class="pre">C:\Program</span> <span class="pre">Files\boost\</span></tt><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt><tt class="docutils literal"><span class="pre">\lib\</span></tt>.</li>
    648. 

  648. <li>From the <em>Build</em> menu, select <em>Build Solution</em>.</li>
    649. 

  649. </ol>
    650. 

  650. <p>To link with a library that doesn't use auto-linking support,
    651. 

  651. before building (step 3 above), you also need to specify the library
    652. 

  652. name:</p>
    653. 

  653. <ul class="simple">
    654. 

  654. <li>In <em>Configuration Properties</em> &gt; <em>Linker</em> &gt; <em>Input</em> &gt;
    655. 

  655. <em>Additional Dependencies</em>, enter the name of the binary library
    656. 

  656. to link with, e.g. <strong>boost_regex-msvc-7.1-mt-d-1_34.lib</strong>.</li>
    657. 

  657. </ul>
    658. 

  658. <p>See <a class="reference" href="#library-naming">Library Naming</a> for details about how to select the right
    659. 

  659. library name.</p>
    660. 

  660. </div>
    661. 

  661. </div>
    662. 

  662. <div class="section">
    663. 

  663. <h2><a class="toc-backref" href="#id42" id="id13" name="id13">5.2&nbsp;&nbsp;&nbsp;*nix (e.g. Unix, Linux, MacOS, Cygwin)</a></h2>
    664. 

  664. <p>There are two main ways to link to libraries:</p>
    665. 

  665. <ol class="loweralpha">
    666. 

  666. <li><p class="first">You can specify the full path to each library:</p>
    667. 

  667. <pre class="literal-block">
    668. 

  668. $ c++ -I <tt class="docutils literal"><span class="pre">/</span></tt><em>path</em><tt class="docutils literal"><span class="pre">/</span></tt><em>to</em><tt class="docutils literal"><span class="pre">/</span></tt><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt> example.cpp -o example <strong>\</strong>
    669. 

  669.    <strong>~/boost/lib/libboost_regex-msvc-7.1-mt-d-1_34.a</strong>
    670. 

  670. </pre>
    671. 

  671. </li>
    672. 

  672. <li><p class="first">You can separately specify a directory to search (with <tt class="docutils literal"><span class="pre">-L</span></tt><em>directory</em>) and a library name to search for (with <tt class="docutils literal"><span class="pre">-l</span></tt><em>library</em>,<a class="footnote-reference" href="#lowercase-l" id="id14" name="id14"><sup>4</sup></a> dropping the filename's leading <tt class="docutils literal"><span class="pre">lib</span></tt> and trailing
    673. 

  673. suffix (<tt class="docutils literal"><span class="pre">.a</span></tt> in this case):</p>
    674. 

  674. <pre class="literal-block">
    675. 

  675. $ c++ -I <tt class="docutils literal"><span class="pre">/</span></tt><em>path</em><tt class="docutils literal"><span class="pre">/</span></tt><em>to</em><tt class="docutils literal"><span class="pre">/</span></tt><tt class="docutils literal"><span class="pre">boost_1_34_0</span></tt> example.cpp -o example <strong>\</strong>
    676. 

  676.    <strong>-L~/boost/lib/ -lboost_regex-msvc-7.1-mt-d-1_34</strong>
    677. 

  677. </pre>
    678. 

  678. <p>As you can see, this method is just as terse as method a. for
    679. 

  679. one library; it <em>really</em> pays off when you're using multiple
    680. 

  680. libraries from the same directory.</p>
    681. 

  681. </li>
    682. 

  682. </ol>
    683. 

  683. <p>In both cases above, the bold text is what you'd add to <a class="reference" href="#unix-header-only">the
    684. 

  684. command lines we explored earlier</a>.</p>
    685. 

  685. </div>
    686. 

  686. <div class="section">
    687. 

  687. <h2><a class="toc-backref" href="#id43" id="library-naming" name="library-naming">5.3&nbsp;&nbsp;&nbsp;Library Naming</a></h2>
    688. 

  688. <p>In order to choose the right library binary to link with, you'll
    689. 

  689. need to know something about how Boost libraries are named.  Each
    690. 

  690. library binary filename is composed of a common sequence of
    691. 

  691. elements that describe how it was built.  For example,
    692. 

  692. <tt class="docutils literal"><span class="pre">libboost_regex-msvc-7.1-mt-d-1_34.lib</span></tt> can be broken down into the
    693. 

  693. following elements:</p>
    694. 

  694. <dl class="docutils">
    695. 

  695. <dt><tt class="docutils literal"><span class="pre">lib</span></tt></dt>
    696. 

  696. <dd><em>Prefix</em>: except on Microsoft Windows, every Boost library
    697. 

  697. name begins with this string.  On Windows, only ordinary static
    698. 

  698. libraries use the <tt class="docutils literal"><span class="pre">lib</span></tt> prefix; import libraries and DLLs do
    699. 

  699. not.<a class="footnote-reference" href="#distinct" id="id16" name="id16"><sup>5</sup></a></dd>
    700. 

  700. <dt><tt class="docutils literal"><span class="pre">boost_regex</span></tt></dt>
    701. 

  701. <dd><em>Library name</em>: all boost library filenames begin with <tt class="docutils literal"><span class="pre">boost_</span></tt>.</dd>
    702. 

  702. <dt><tt class="docutils literal"><span class="pre">-msvc-7.1</span></tt></dt>
    703. 

  703. <dd><em>Toolset tag</em>: one of the <a class="reference" href="#toolset-name">Boost.Build toolset names</a>,
    704. 

  704. possibly followed by a dash and a version number.</dd>
    705. 

  705. <dt><tt class="docutils literal"><span class="pre">-mt</span></tt></dt>
    706. 

  706. <dd><em>Threading tag</em>: indicates that the library was
    707. 

  707. built with multithreading support enabled.  Libraries built
    708. 

  708. without multithreading support can be identified by the absence
    709. 

  709. of <tt class="docutils literal"><span class="pre">-mt</span></tt>.</dd>
    710. 

  710. <dt><tt class="docutils literal"><span class="pre">-d</span></tt></dt>
    711. 

  711. <dd><p class="first"><em>ABI tag</em>: encodes details that affect the library's
    712. 

  712. interoperability with other compiled code.  For each such
    713. 

  713. feature, a single letter is added to the tag:</p>
    714. 

  714. <table border="1" class="docutils">
    715. 

  715. <colgroup>
    716. 

  716. <col width="6%" />
    717. 

  717. <col width="94%" />
    718. 

  718. </colgroup>
    719. 

  719. <thead valign="bottom">
    720. 

  720. <tr><th class="head">Key</th>
    721. 

  721. <th class="head">Use this library when:</th>
    722. 

  722. </tr>
    723. 

  723. </thead>
    724. 

  724. <tbody valign="top">
    725. 

  725. <tr><td><tt class="docutils literal"><span class="pre">s</span></tt></td>
    726. 

  726. <td>linking statically to the C++ standard library and compiler runtime support
    727. 

  727. libraries.</td>
    728. 

  728. </tr>
    729. 

  729. <tr><td><tt class="docutils literal"><span class="pre">g</span></tt></td>
    730. 

  730. <td>using debug versions of the standard and runtime support libraries.</td>
    731. 

  731. </tr>
    732. 

  732. <tr><td><tt class="docutils literal"><span class="pre">y</span></tt></td>
    733. 

  733. <td>using a special <a class="reference" href="../libs/python/doc/building.html#variants">debug build of Python</a>.</td>
    734. 

  734. </tr>
    735. 

  735. <tr><td><tt class="docutils literal"><span class="pre">d</span></tt></td>
    736. 

  736. <td>building a debug version of your code.<a class="footnote-reference" href="#debug-abi" id="id17" name="id17"><sup>6</sup></a></td>
    737. 

  737. </tr>
    738. 

  738. <tr><td><tt class="docutils literal"><span class="pre">p</span></tt></td>
    739. 

  739. <td>using the STLPort standard library rather than the default one supplied with
    740. 

  740. your compiler.</td>
    741. 

  741. </tr>
    742. 

  742. <tr><td><tt class="docutils literal"><span class="pre">n</span></tt></td>
    743. 

  743. <td>using STLPort's deprecated “native iostreams” feature.<a class="footnote-reference" href="#native" id="id18" name="id18"><sup>7</sup></a></td>
    744. 

  744. </tr>
    745. 

  745. </tbody>
    746. 

  746. </table>
    747. 

  747. <p class="last">For example, if you build a debug version of your code for use
    748. 

  748. with debug versions of the static runtime library and the
    749. 

  749. STLPort standard library in “native iostreams” mode,
    750. 

  750. the tag would be: <tt class="docutils literal"><span class="pre">-sgdpn</span></tt>.  If none of the above apply, the
    751. 

  751. ABI tag is ommitted.</p>
    752. 

  752. </dd>
    753. 

  753. <dt><tt class="docutils literal"><span class="pre">-1_34</span></tt></dt>
    754. 

  754. <dd><em>Version tag</em>: the full Boost release number,
    755. 

  755. with periods replaced by underscores. The major and minor version
    756. 

  756. numbers are taken together separated by an underscore. For
    757. 

  757. example, version 1.31.1 would be tagged as &quot;-1_31_1&quot;.</dd>
    758. 

  758. <dt><tt class="docutils literal"><span class="pre">.lib</span></tt></dt>
    759. 

  759. <dd><em>Extension</em>: determined according to the
    760. 

  760. operating system's usual convention.  On Windows, <tt class="docutils literal"><span class="pre">.dll</span></tt>
    761. 

  761. indicates a shared library and <tt class="docutils literal"><span class="pre">.lib</span></tt> indicates a static or
    762. 

  762. import library.  On most *nix platforms the extensions are
    763. 

  763. <tt class="docutils literal"><span class="pre">.a</span></tt> and <tt class="docutils literal"><span class="pre">.so</span></tt> for static libraries (archives) and shared
    764. 

  764. libraries, respectively.  Where supported by *nix toolsets, a
    765. 

  765. full version extension is added (e.g. &quot;.so.1.34&quot;); a symbolic
    766. 

  766. link to the library file, named without the trailing version
    767. 

  767. number, will also be created.</dd>
    768. 

  768. </dl>
    769. 

  769. <hr class="docutils" />
    770. 

  770. <table class="docutils footnote" frame="void" id="packagers" rules="none">
    771. 

  771. <colgroup><col class="label" /><col /></colgroup>
    772. 

  772. <tbody valign="top">
    773. 

  773. <tr><td class="label"><a class="fn-backref" href="#id3" name="packagers">[1]</a></td><td>If developers of Boost packages would like to work
    774. 

  774. with us to make sure these instructions can be used with their
    775. 

  775. packages, we'd be glad to help.  Please make your interest known
    776. 

  776. to the <a class="reference" href="mailing_lists.htm#main">Boost developers' list</a>.</td></tr>
    777. 

  777. </tbody>
    778. 

  778. </table>
    779. 

  779. <table class="docutils footnote" frame="void" id="installer-src" rules="none">
    780. 

  780. <colgroup><col class="label" /><col /></colgroup>
    781. 

  781. <tbody valign="top">
    782. 

  782. <tr><td class="label"><a class="fn-backref" href="#id4" name="installer-src">[2]</a></td><td>If you used the <a class="reference" href="http://www.boost-consulting.com/download.html">Windows installer</a> from Boost
    783. 

  783. Consulting and deselected “Source and Documentation”  (it's
    784. 

  784. selected by default), you won't see the <tt class="docutils literal"><span class="pre">libs/</span></tt> subdirectory.
    785. 

  785. That won't affect your ability to use precompiled binaries, but
    786. 

  786. you won't be able to rebuild libraries from scratch.</td></tr>
    787. 

  787. </tbody>
    788. 

  788. </table>
    789. 

  789. <table class="docutils footnote" frame="void" id="pch" rules="none">
    790. 

  790. <colgroup><col class="label" /><col /></colgroup>
    791. 

  791. <tbody valign="top">
    792. 

  792. <tr><td class="label"><a class="fn-backref" href="#id6" name="pch">[3]</a></td><td>There's no problem using Boost with precompiled headers;
    793. 

  793. these instructions merely avoid precompiled headers because it
    794. 

  794. would require Visual Studio-specific changes to the source code
    795. 

  795. used in the examples.</td></tr>
    796. 

  796. </tbody>
    797. 

  797. </table>
    798. 

  798. <table class="docutils footnote" frame="void" id="lowercase-l" rules="none">
    799. 

  799. <colgroup><col class="label" /><col /></colgroup>
    800. 

  800. <tbody valign="top">
    801. 

  801. <tr><td class="label"><a class="fn-backref" href="#id14" name="lowercase-l">[4]</a></td><td>That option is a dash followed by a lowercase “L”
    802. 

  802. character, which looks very much like a numeral 1 in some fonts.</td></tr>
    803. 

  803. </tbody>
    804. 

  804. </table>
    805. 

  805. <table class="docutils footnote" frame="void" id="distinct" rules="none">
    806. 

  806. <colgroup><col class="label" /><col /></colgroup>
    807. 

  807. <tbody valign="top">
    808. 

  808. <tr><td class="label"><a class="fn-backref" href="#id16" name="distinct">[5]</a></td><td>This convention distinguishes the static version of
    809. 

  809. a Boost library from the import library for an
    810. 

  810. identically-configured Boost DLL, which would otherwise have the
    811. 

  811. same name.</td></tr>
    812. 

  812. </tbody>
    813. 

  813. </table>
    814. 

  814. <table class="docutils footnote" frame="void" id="debug-abi" rules="none">
    815. 

  815. <colgroup><col class="label" /><col /></colgroup>
    816. 

  816. <tbody valign="top">
    817. 

  817. <tr><td class="label"><a class="fn-backref" href="#id17" name="debug-abi">[6]</a></td><td>These libraries were compiled without optimization
    818. 

  818. or inlining, with full debug symbols enabled, and without
    819. 

  819. <tt class="docutils literal"><span class="pre">NDEBUG</span></tt> <tt class="docutils literal"><span class="pre">#define</span></tt>d.  All though it's true that sometimes
    820. 

  820. these choices don't affect binary compatibility with other
    821. 

  821. compiled code, you can't count on that with Boost libraries.</td></tr>
    822. 

  822. </tbody>
    823. 

  823. </table>
    824. 

  824. <table class="docutils footnote" frame="void" id="native" rules="none">
    825. 

  825. <colgroup><col class="label" /><col /></colgroup>
    826. 

  826. <tbody valign="top">
    827. 

  827. <tr><td class="label"><a class="fn-backref" href="#id18" name="native">[7]</a></td><td>This feature of STLPort is deprecated because it's
    828. 

  828. impossible to make it work transparently to the user; we don't
    829. 

  829. recommend it.</td></tr>
    830. 

  830. </tbody>
    831. 

  831. </table>
    832. 

  832. </div>
    833. 

  833. </div>
    834. 

  834. </div>
    835. 

  835. <div class="footer">
    836. 

  836. <hr class="footer" />
    837. 

  837. <a class="reference" href="./getting_started.rst">View document source</a>.
    838. 

  838. Generated on: 2006-11-20 13:06 UTC.
    839. 

  839. Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
    840. 

  840. 

  841. </div>
    842. 

  842. </body>
    843. 

  843. </html>
    844.
粤ICP备19079148号