| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> | |
| <html> | |
| <head> | |
| <title>bcp</title> | |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> | |
| <link rel="stylesheet" type="text/css" href="../../doc/html/boostbook.css"> | |
| </head> | |
| <body> | |
| <P> | |
| <TABLE id="Table1" cellSpacing="1" cellPadding="1" width="100%" border="0"> | |
| <TR> | |
| <td valign="top" width="300"> | |
| <h3><a href="../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../boost.png" border="0"></a></h3> | |
| </td> | |
| <TD width="353"> | |
| <H1 align="center">The bcp utility</H1> | |
| </TD> | |
| <td width="50"> | |
| <h3><a href="../../index.htm"><img alt="Boost.Regex Index" src="../../doc/html/images/up.png" | |
| border="0"></a></h3> | |
| </td> | |
| </TR> | |
| </TABLE> | |
| </P> | |
| <HR> | |
| <p></p> | |
| <P>The bcp utility is a tool for extracting subsets of Boost, it's useful for | |
| Boost authors who want to distribute their library separately from Boost, and | |
| for Boost users who want to distribute a subset of Boost with their | |
| application.</P> | |
| <P>bcp can also report on which parts of Boost your code is dependent on, and what | |
| licences are used by those dependencies.</P> | |
| <H2>Examples:</H2> | |
| <PRE>bcp scoped_ptr /foo</PRE> | |
| <P>Copies boost/scoped_ptr.hpp and dependencies to /foo.</P> | |
| <PRE>bcp boost/regex.hpp /foo</PRE> | |
| <P>Copies boost/regex.hpp and all dependencies including the regex source code (in | |
| libs/regex/src) and build files (in libs/regex/build) to /foo. Does not | |
| copy the regex documentation, test, or example code.</P> | |
| <PRE>bcp regex /foo</PRE> | |
| <P>Copies the full regex lib (in libs/regex) including dependencies (such as the | |
| boost.test source required by the regex test programs) to /foo.</P> | |
| <PRE>bcp regex config build /foo</PRE> | |
| <P>Copies the full regex lib (in libs/regex) plus the config lib (libs/config) and | |
| the build system (tools/build) to /foo including all the dependencies.</P> | |
| <PRE>bcp --scan --boost=/boost foo.cpp bar.cpp boost</PRE> | |
| <P>Scans the [non-boost] files foo.cpp and bar.cpp for boost dependencies and | |
| copies those dependencies to the sub-directory boost.</P> | |
| <PRE>bcp --report regex.hpp boost-regex-report.html</PRE> | |
| <P>Creates a HTML report called <EM>boost-regex-report.html</EM> for the boost | |
| module <EM>regex.hpp</EM>. The report contains license information, | |
| author details, and file dependencies.</P> | |
| <H2>Syntax:</H2> | |
| <PRE>bcp --list [options] module-list</PRE> | |
| <P>Outputs a list of all the files in module-list including dependencies.</P> | |
| <PRE>bcp [options] module-list output-path</PRE> | |
| <P>Copies all the files found in module-list to output-path</P> | |
| <PRE>bcp --report [options] module-list html-file</PRE> | |
| <P>Outputs a html report file containing:</P> | |
| <UL> | |
| <LI> | |
| All the licenses in effect, plus the files using each license, and | |
| the copyright holders using each license. | |
| <LI> | |
| Any files with no recognizable license (please report these to the boost | |
| mailing lists). | |
| <LI> | |
| Any files with no recognizable copyright holders (please report these to the | |
| boost mailing lists). | |
| <LI> | |
| All the copyright holders and the files on which they hold copyright. | |
| <LI> | |
| File dependency information - indicates the reason for the inclusion of any | |
| particular file in the dependencies found.</LI></UL> | |
| <H3>Options:</H3> | |
| <PRE>--boost=path</PRE> | |
| <P>Sets the location of the boost tree to <EM>path. </EM> If this option is | |
| not provided then the current path is assumed to be the root directory of the | |
| Boost tree.</P> | |
| <PRE>--scan</PRE> | |
| <P>Treats the module list as a list of (probably non-boost) files to scan for | |
| boost dependencies, the files listed in the module list are not copied (or | |
| listed), only the boost files upon which they depend.</P> | |
| <PRE>--svn</PRE> | |
| <P>Only copy files under svn version control.</P> | |
| <PRE>--unix-lines</PRE> | |
| <P>Make sure that all copied files use Unix style line endings.</P> | |
| <H4>module-list: </H4> | |
| <P>When the --scan option is not used then a list of boost files or library | |
| names to copy, this can be:</P> | |
| <OL> | |
| <LI> | |
| The name of a tool: for example "build" will find "tools/build". | |
| <LI> | |
| The name of a library: for example "regex". | |
| <LI> | |
| The title of a header: for example "scoped_ptr" will find | |
| "boost/scoped_ptr.hpp". | |
| <LI> | |
| The name of a header: for example "scoped_ptr.hpp" will find | |
| "boost/scoped_ptr.hpp". | |
| <LI> | |
| The name of a file: for example "boost/regex.hpp".</LI></OL> | |
| <P>When the --scan option is used, then a list of (probably non-boost) files to | |
| scan for boost dependencies, the files in the module list are not therefore | |
| copied/listed.</P> | |
| <H4>output-path: | |
| </H4> | |
| <P>The path to which files will be copied (this path must exist).</P> | |
| <H2>Dependencies</H2> | |
| <P>File dependencies are found as follows:</P> | |
| <UL> | |
| <LI> | |
| C++ source files are scanned for #includes, all #includes present in the boost | |
| source tree will then be scanned for their dependencies and so on.</LI> | |
| <LI> | |
| C++ source files are associated with the name of a library, if that library has | |
| source code (and possibly build data), then include that source in the | |
| dependencies.</LI> | |
| <LI> | |
| C++ source files are checked for dependencies on Boost.test (for example to see | |
| if they use cpp_main as an entry point).</LI> | |
| <LI> | |
| HTML files are scanned for immediate dependencies (images and style sheets, but | |
| not links).</LI></UL> | |
| <P>It should be noted that in practice bcp can produce a rather "fat" list of | |
| dependencies, reasons for this include:</P> | |
| <UL> | |
| <LI> | |
| It searches for library names first, so using "regex" as a name will give you | |
| everything in the libs/regex directory and everything that depends on. | |
| This can be a long list as all the regex test and example programs will get | |
| scanned for their dependencies. If you want a more minimal list, then try | |
| using the names of the headers you are actually including, or use the --scan | |
| option to scan your source code.</LI> | |
| <LI> | |
| If you include the header of a library with separate source, then you get that | |
| libraries source and all it's dependencies. This is deliberate and in | |
| general those extra dependencies are needed.</LI> | |
| <LI> | |
| When you include a header, bcp doesn't know what compiler you're using, so it | |
| follows all possible preprocessor paths. If you're distributing a subset of | |
| Boost with you're application then that is what you want to have happen in | |
| general.</LI></UL> | |
| <P>The last point above can result in a substantial increase in the number of | |
| headers found compared to most peoples expectations. For example bcp | |
| finds 274 header dependencies for boost/shared_ptr.hpp: by running bcp in | |
| report mode we can see why all these headers have been found as dependencies:</P> | |
| <UL> | |
| <LI> | |
| All of the Config library headers get included (52 headers, would be | |
| about 6 for one compiler only).</LI> | |
| <LI> | |
| A lot of MPL and type traits code that includes workarounds for broken | |
| compilers that you may or may not need. Tracing back through the code | |
| shows that most of these aren't needed unless the user has | |
| defined BOOST_SP_USE_QUICK_ALLOCATOR, however bcp isn't aware of whether | |
| that preprocessor path will be taken or not, so the headers get included just | |
| in case. This adds about 48 headers (type traits), plus another 49 from | |
| MPL.</LI> | |
| <LI> | |
| The Preprocessor library gets used heavily by MPL: this adds another 96 | |
| headers.</LI> | |
| <LI> | |
| The Shared Pointer library contains a lot of platform specific code, split up | |
| into around 22 headers: normally your compiler would need only a couple of | |
| these files.</LI></UL> | |
| <P>As you can see the number of dependencies found are much larger than those used | |
| by any single compiler, however if you want to distribute a subset of Boost | |
| that's usable in any configuration, by any compiler, on any platform then | |
| that's exactly what you need. If you want to figure out which Boost | |
| headers are being used by your <EM>specific </EM>compiler then the best way to | |
| find out is to prepocess the code and scan the output for boost header | |
| includes. You should be aware that the result will be very platform and | |
| compiler specific, and may not contain all the headers needed if you so much as | |
| change a compiler switch (for example turn on threading support).</P> | |
| <P> | |
| <P> | |
| <HR> | |
| <P></P> | |
| <P></P> | |
| <p>Last revised $Date: 2007-11-15 11:31:06 -0500 (Thu, 15 Nov 2007) $</p> | |
| <P><I>© Copyright John Maddock 2003-7</I></P> | |
| <P align="left"><I>Distributed under the Boost Software License, Version 1.0. | |
| (See accompanying file LICENSE_1_0.txt or <a href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>) | |
| </I></P> | |
| </body> | |
| </html> | |