ceph/src/boost/tools/bcp/doc/html/index.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>BCP</title>
   5 <link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.77.1">
   7 <link rel="home" href="index.html" title="BCP">
   8 </head>
   9 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  10 <table cellpadding="2" width="100%"><tr>
  11 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td>
  12 <td align="center"><a href="../../../../index.html">Home</a></td>
  13 <td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td>
  14 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  15 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  16 <td align="center"><a href="../../../../more/index.htm">More</a></td>
  17 </tr></table>
  18 <hr>
  19 <div class="spirit-nav"></div>
  20 <div class="article">
  21 <div class="titlepage">
  22 <div>
  23 <div><h2 class="title">
  24 <a name="bcp"></a>BCP</h2></div>
  25 <div><div class="authorgroup"><div class="author"><h3 class="author">
  26 <span class="firstname">John</span> <span class="surname">Maddock</span>
  27 </h3></div></div></div>
  28 <div><p class="copyright">Copyright &#169; 2009 John Maddock</p></div>
  29 <div><div class="legalnotice">
  30 <a name="bcp.legal"></a><p>
  31         Distributed under the Boost Software License, Version 1.0. (See accompanying
  32         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>)
  33       </p>
  34 </div></div>
  35 </div>
  36 <hr>
  37 </div>
  38 <div class="toc">
  39 <p><b>Table of Contents</b></p>
  40 <dl>
  41 <dt><span class="section"><a href="index.html#bcp.overview">Overview</a></span></dt>
  42 <dt><span class="section"><a href="index.html#bcp.examples">Examples</a></span></dt>
  43 <dt><span class="section"><a href="index.html#bcp.syntax">Syntax</a></span></dt>
  44 <dd><dl>
  45 <dt><span class="section"><a href="index.html#bcp.syntax.main">Behaviour Selection</a></span></dt>
  46 <dt><span class="section"><a href="index.html#bcp.syntax.options">Options</a></span></dt>
  47 <dt><span class="section"><a href="index.html#bcp.syntax.module">module-list</a></span></dt>
  48 <dt><span class="section"><a href="index.html#bcp.syntax.output">output-path</a></span></dt>
  49 <dt><span class="section"><a href="index.html#bcp.syntax.dependencies">Dependencies</a></span></dt>
  50 </dl></dd>
  51 </dl>
  52 </div>
  53 <div class="section bcp_overview">
  54 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  55 <a name="bcp.overview"></a><a class="link" href="index.html#bcp.overview" title="Overview">Overview</a>
  56 </h2></div></div></div>
  57 <p>
  58       The bcp utility is a tool for extracting subsets of Boost, it's useful for
  59       Boost authors who want to distribute their library separately from Boost, and
  60       for Boost users who want to distribute a subset of Boost with their application.
  61     </p>
  62 <p>
  63       bcp can also report on which parts of Boost your code is dependent on, and
  64       what licences are used by those dependencies.
  65     </p>
  66 </div>
  67 <div class="section bcp_examples">
  68 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  69 <a name="bcp.examples"></a><a class="link" href="index.html#bcp.examples" title="Examples">Examples</a>
  70 </h2></div></div></div>
  71 <pre class="programlisting">bcp scoped_ptr /foo
  72 </pre>
  73 <p>
  74       Copies boost/scoped_ptr.hpp and dependencies to /foo.
  75     </p>
  76 <pre class="programlisting">bcp boost/regex.hpp /foo
  77 </pre>
  78 <p>
  79       Copies boost/regex.hpp and all dependencies including the regex source code
  80       (in libs/regex/src) and build files (in libs/regex/build) to /foo. Does not
  81       copy the regex documentation, test, or example code. Also does not copy the
  82       Boost.Build system.
  83     </p>
  84 <pre class="programlisting">bcp regex /foo
  85 </pre>
  86 <p>
  87       Copies the full regex lib (in libs/regex) including dependencies (such as the
  88       boost.test source required by the regex test programs) to /foo. Does not copy
  89       the Boost.Build system.
  90     </p>
  91 <pre class="programlisting">bcp --namespace=myboost --namespace-alias regex config build /foo
  92 </pre>
  93 <p>
  94       Copies the full regex lib (in libs/regex) plus the config lib (libs/config)
  95       and the build system (tools/build) to /foo including all the dependencies.
  96       Also renames the boost namespace to <span class="emphasis"><em>myboost</em></span> and changes
  97       the filenames of binary libraries to begin with the prefix "myboost"
  98       rather than "boost". The --namespace-alias option makes <code class="computeroutput"><span class="keyword">namespace</span> <span class="identifier">boost</span></code>
  99       an alias of the new name.
 100     </p>
 101 <pre class="programlisting">bcp --scan --boost=/boost foo.cpp bar.cpp boost
 102 </pre>
 103 <p>
 104       Scans the [non-boost] files foo.cpp and bar.cpp for boost dependencies and
 105       copies those dependencies to the sub-directory boost.
 106     </p>
 107 <pre class="programlisting">bcp --report regex.hpp boost-regex-report.html
 108 </pre>
 109 <p>
 110       Creates a HTML report called boost-regex-report.html for the boost module regex.hpp.
 111       The report contains license information, author details, and file dependencies.
 112     </p>
 113 </div>
 114 <div class="section bcp_syntax">
 115 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
 116 <a name="bcp.syntax"></a><a class="link" href="index.html#bcp.syntax" title="Syntax">Syntax</a>
 117 </h2></div></div></div>
 118 <div class="toc"><dl>
 119 <dt><span class="section"><a href="index.html#bcp.syntax.main">Behaviour Selection</a></span></dt>
 120 <dt><span class="section"><a href="index.html#bcp.syntax.options">Options</a></span></dt>
 121 <dt><span class="section"><a href="index.html#bcp.syntax.module">module-list</a></span></dt>
 122 <dt><span class="section"><a href="index.html#bcp.syntax.output">output-path</a></span></dt>
 123 <dt><span class="section"><a href="index.html#bcp.syntax.dependencies">Dependencies</a></span></dt>
 124 </dl></div>
 125 <div class="section bcp_syntax_main">
 126 <div class="titlepage"><div><div><h3 class="title">
 127 <a name="bcp.syntax.main"></a><a class="link" href="index.html#bcp.syntax.main" title="Behaviour Selection">Behaviour Selection</a>
 128 </h3></div></div></div>
 129 <pre class="programlisting">bcp --list [options] module-list
 130 </pre>
 131 <p>
 132         Outputs a list of all the files in module-list including dependencies.
 133       </p>
 134 <pre class="programlisting">bcp [options] module-list output-path
 135 </pre>
 136 <p>
 137         Copies all the files found in module-list to output-path
 138       </p>
 139 <pre class="programlisting">bcp --report [options] module-list html-file
 140 </pre>
 141 <p>
 142         Outputs a html report file containing:
 143       </p>
 144 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 145 <li class="listitem">
 146             All the licenses in effect, plus the files using each license, and the
 147             copyright holders using each license.
 148           </li>
 149 <li class="listitem">
 150             Any files with no recognizable license (please report these to the boost
 151             mailing lists).
 152           </li>
 153 <li class="listitem">
 154             Any files with no recognizable copyright holders (please report these
 155             to the boost mailing lists).
 156           </li>
 157 <li class="listitem">
 158             All the copyright holders and the files on which they hold copyright.
 159           </li>
 160 <li class="listitem">
 161             File dependency information - indicates the reason for the inclusion
 162             of any particular file in the dependencies found.
 163           </li>
 164 </ul></div>
 165 </div>
 166 <div class="section bcp_syntax_options">
 167 <div class="titlepage"><div><div><h3 class="title">
 168 <a name="bcp.syntax.options"></a><a class="link" href="index.html#bcp.syntax.options" title="Options">Options</a>
 169 </h3></div></div></div>
 170 <pre class="programlisting">--boost=path
 171 </pre>
 172 <p>
 173         Sets the location of the boost tree to path. If this option is not provided
 174         then the current path is assumed to be the root directory of the Boost tree.
 175       </p>
 176 <pre class="programlisting">--namespace=newname </pre>
 177 <p>
 178         When copying files, all occurances of the boost namespace will get renamed
 179         to "newname". Also renames Boost binaries to use "newname"
 180         rather than "boost" as a prefix.
 181       </p>
 182 <p>
 183         Often used in conjunction with the --namespace-alias option, this allows
 184         two different Boost versions to be used in the same program, but not in the
 185         same translation unit.
 186       </p>
 187 <pre class="programlisting">--namespace-alias</pre>
 188 <p>
 189         When used in conjunction with the --namespace option, then <code class="computeroutput"><span class="keyword">namespace</span> <span class="identifier">boost</span></code>
 190         will be declared as an alias of the new namespace name. This allows existing
 191         code that relies on Boost code being in <code class="computeroutput"><span class="keyword">namespace</span>
 192         <span class="identifier">boost</span></code> to compile unchanged, while
 193         retaining the "strong versioning" that can be achieved with a namespace
 194         change.
 195       </p>
 196 <pre class="programlisting">--scan
 197 </pre>
 198 <p>
 199         Treats the module list as a list of (probably non-boost) files to scan for
 200         boost dependencies, the files listed in the module list are not copied (or
 201         listed), only the boost files upon which they depend.
 202       </p>
 203 <pre class="programlisting">--svn
 204 </pre>
 205 <p>
 206         Only copy files under svn version control.
 207       </p>
 208 <pre class="programlisting">--unix-lines
 209 </pre>
 210 <p>
 211         Make sure that all copied files use Unix style line endings.
 212       </p>
 213 </div>
 214 <div class="section bcp_syntax_module">
 215 <div class="titlepage"><div><div><h3 class="title">
 216 <a name="bcp.syntax.module"></a><a class="link" href="index.html#bcp.syntax.module" title="module-list">module-list</a>
 217 </h3></div></div></div>
 218 <p>
 219         When the --scan option is not used then a list of boost files or library
 220         names to copy, this can be:
 221       </p>
 222 <div class="orderedlist"><ol class="orderedlist" type="1">
 223 <li class="listitem">
 224             The name of a tool: for example "build" will find "tools/build".
 225           </li>
 226 <li class="listitem">
 227             The name of a library: for example "regex".
 228           </li>
 229 <li class="listitem">
 230             The title of a header: for example "scoped_ptr" will find "boost/scoped_ptr.hpp".
 231           </li>
 232 <li class="listitem">
 233             The name of a header: for example "scoped_ptr.hpp" will find
 234             "boost/scoped_ptr.hpp".
 235           </li>
 236 <li class="listitem">
 237             The name of a file: for example "boost/regex.hpp".
 238           </li>
 239 </ol></div>
 240 <p>
 241         When the --scan option is used, then a list of (probably non-boost) files
 242         to scan for boost dependencies, the files in the module list are not therefore
 243         copied/listed.
 244       </p>
 245 </div>
 246 <div class="section bcp_syntax_output">
 247 <div class="titlepage"><div><div><h3 class="title">
 248 <a name="bcp.syntax.output"></a><a class="link" href="index.html#bcp.syntax.output" title="output-path">output-path</a>
 249 </h3></div></div></div>
 250 <p>
 251         The path to which files will be copied (this path must exist).
 252       </p>
 253 </div>
 254 <div class="section bcp_syntax_dependencies">
 255 <div class="titlepage"><div><div><h3 class="title">
 256 <a name="bcp.syntax.dependencies"></a><a class="link" href="index.html#bcp.syntax.dependencies" title="Dependencies">Dependencies</a>
 257 </h3></div></div></div>
 258 <p>
 259         File dependencies are found as follows:
 260       </p>
 261 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 262 <li class="listitem">
 263             C++ source files are scanned for #includes, all #includes present in
 264             the boost source tree will then be scanned for their dependencies and
 265             so on.
 266           </li>
 267 <li class="listitem">
 268             C++ source files are associated with the name of a library, if that library
 269             has source code (and possibly build data), then include that source in
 270             the dependencies.
 271           </li>
 272 <li class="listitem">
 273             C++ source files are checked for dependencies on Boost.test (for example
 274             to see if they use cpp_main as an entry point).
 275           </li>
 276 <li class="listitem">
 277             HTML files are scanned for immediate dependencies (images and style sheets,
 278             but not links).
 279           </li>
 280 </ul></div>
 281 <p>
 282         It should be noted that in practice bcp can produce a rather "fat"
 283         list of dependencies, reasons for this include:
 284       </p>
 285 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 286 <li class="listitem">
 287             It searches for library names first, so using "regex" as a
 288             name will give you everything in the libs/regex directory and everything
 289             that depends on. This can be a long list as all the regex test and example
 290             programs will get scanned for their dependencies. If you want a more
 291             minimal list, then try using the names of the headers you are actually
 292             including, or use the --scan option to scan your source code.
 293           </li>
 294 <li class="listitem">
 295             If you include the header of a library with separate source, then you
 296             get that libraries source and all it's dependencies. This is deliberate
 297             and in general those extra dependencies are needed.
 298           </li>
 299 <li class="listitem">
 300             When you include a header, bcp doesn't know what compiler you're using,
 301             so it follows all possible preprocessor paths. If you're distributing
 302             a subset of Boost with you're application then that is what you want
 303             to have happen in general.
 304           </li>
 305 </ul></div>
 306 <p>
 307         The last point above can result in a substantial increase in the number of
 308         headers found compared to most peoples expectations. For example bcp finds
 309         274 header dependencies for boost/shared_ptr.hpp: by running bcp in report
 310         mode we can see why all these headers have been found as dependencies:
 311       </p>
 312 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 313 <li class="listitem">
 314             All of the Config library headers get included (52 headers, would be
 315             about 6 for one compiler only).
 316           </li>
 317 <li class="listitem">
 318             A lot of MPL and type traits code that includes workarounds for broken
 319             compilers that you may or may not need. Tracing back through the code
 320             shows that most of these aren't needed unless the user has defined BOOST_SP_USE_QUICK_ALLOCATOR,
 321             however bcp isn't aware of whether that preprocessor path will be taken
 322             or not, so the headers get included just in case. This adds about 48
 323             headers (type traits), plus another 49 from MPL.
 324           </li>
 325 <li class="listitem">
 326             The Preprocessor library gets used heavily by MPL: this adds another
 327             96 headers.
 328           </li>
 329 <li class="listitem">
 330             The Shared Pointer library contains a lot of platform specific code,
 331             split up into around 22 headers: normally your compiler would need only
 332             a couple of these files.
 333           </li>
 334 </ul></div>
 335 <p>
 336         As you can see the number of dependencies found are much larger than those
 337         used by any single compiler, however if you want to distribute a subset of
 338         Boost that's usable in any configuration, by any compiler, on any platform
 339         then that's exactly what you need. If you want to figure out which Boost
 340         headers are being used by your specific compiler then the best way to find
 341         out is to prepocess the code and scan the output for boost header includes.
 342         You should be aware that the result will be very platform and compiler specific,
 343         and may not contain all the headers needed if you so much as change a compiler
 344         switch (for example turn on threading support).
 345       </p>
 346 </div>
 347 </div>
 348 </div>
 349 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 350 <td align="left"><p><small>Last revised: April 18, 2013 at 12:30:13 GMT</small></p></td>
 351 <td align="right"><div class="copyright-footer"></div></td>
 352 </tr></table>
 353 <hr>
 354 <div class="spirit-nav"></div>
 355 </body>
 356 </html>