Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/tools/bcp/bcp.html @ 32

Last change on this file since 32 was 29, checked in by landauf, 16 years ago

updated boost from 1_33_1 to 1_34_1
File size: 10.1 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<html>
3   <head>
4      <title>bcp</title>
5      <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
6      <link rel="stylesheet" type="text/css" href="../../boost.css">
7   </head>
8   <body>
9      <P>
10         <TABLE id="Table1" cellSpacing="1" cellPadding="1" width="100%" border="0">
11            <TR>
12               <td valign="top" width="300">
13                  <h3><a href="../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../boost.png" border="0"></a></h3>
14               </td>
15               <TD width="353">
16                  <H1 align="center">The bcp utility</H1>
17               </TD>
18               <td width="50">
19                  <h3><a href="../../index.htm"><img height="45" width="43" alt="Boost.Regex Index" src="../../libs/regex/doc/uarrow.gif"
20                           border="0"></a></h3>
21               </td>
22            </TR>
23         </TABLE>
24      </P>
25      <HR>
26      <p></p>
27      <P>The bcp utility is a tool for extracting subsets of Boost, it's useful for
28         Boost authors who want to distribute their library separately from Boost, and
29         for Boost users who want to distribute a subset of Boost with their
30         application.</P>
31      <P>bcp can also report on which parts of Boost your code is dependent on, and what
32         licences are used by those dependencies.</P>
33      <H2>Examples:</H2>
34      <PRE>bcp scoped_ptr /foo</PRE>
35      <P>Copies boost/scoped_ptr.hpp and dependencies to /foo.</P>
36      <PRE>bcp boost/regex.hpp /foo</PRE>
37      <P>Copies boost/regex.hpp and all dependencies including the regex source code (in
38         libs/regex/src) and build files (in libs/regex/build) to /foo.&nbsp; Does not
39         copy the regex documentation, &nbsp;test, or example code.</P>
40      <PRE>bcp regex /foo</PRE>
41      <P>Copies the full regex lib (in libs/regex) including dependencies (such as the
42         boost.test source required by the regex test programs) to /foo.</P>
43      <PRE>bcp regex config build /foo</PRE>
44      <P>Copies the full regex lib (in libs/regex) plus the config lib (libs/config) and
45         the build system (tools/build) to /foo including all the dependencies.</P>
46      <PRE>bcp --scan --boost=/boost foo.cpp bar.cpp boost</PRE>
47      <P>Scans the [non-boost] files foo.cpp and bar.cpp for boost dependencies and
48         copies those dependencies to the sub-directory boost.</P>
49      <PRE>bcp --report regex.hpp boost-regex-report.html</PRE>
50      <P>Creates a HTML report called <EM>boost-regex-report.html</EM> for the boost
51         module <EM>regex.hpp</EM>.&nbsp; The report contains license information,
52         author details, and file dependencies.</P>
53      <H2>Syntax:</H2>
54      <PRE>bcp --list [options] module-list</PRE>
55      <P>Outputs a list of all the files in module-list including dependencies.</P>
56      <PRE>bcp [options] module-list output-path</PRE>
57      <P>Copies all the files found in module-list to output-path</P>
58      <PRE>bcp --report [options] module-list html-file</PRE>
59      <P>Outputs a html report file containing:</P>
60      <UL>
61         <LI>
62         All the licenses in effect, plus the files using each license, and
63         the&nbsp;copyright holders&nbsp;using each license.
64         <LI>
65         Any files with no recognizable license (please report these to the boost
66         mailing lists).
67         <LI>
68         Any files with no recognizable copyright holders (please report these to the
69         boost mailing lists).
70         <LI>
71         All the copyright holders and the files on which they hold copyright.
72         <LI>
73            File dependency information - indicates the reason for the inclusion of any
74            particular file in the dependencies found.</LI></UL>
75      <H3>Options:</H3>
76      <PRE>--boost=path</PRE>
77      <P>Sets the location of the boost tree to <EM>path.&nbsp;</EM> If this option is
78         not provided then the current path is assumed to be the root directory of the
79         Boost tree.</P>
80      <PRE>--scan</PRE>
81      <P>Treats the module list as a list of (probably non-boost) files to scan for
82         boost dependencies, the files listed in the module list are not copied (or
83         listed), only the boost files upon which they depend.</P>
84      <PRE>--cvs</PRE>
85      <P>Only copy files under cvs version control.</P>
86      <PRE>--unix-lines</PRE>
87      <P>Make sure that all copied files use Unix style line endings.</P>
88      <H4>module-list:&nbsp;</H4>
89      <P>When the --scan option is not used then&nbsp;a list of boost files or library
90         names to copy, this can be:</P>
91      <OL>
92         <LI>
93         The name of a tool: for example "build" will find "tools/build".
94         <LI>
95         The name of a library: for example "regex".
96         <LI>
97         The title of a header: for example "scoped_ptr" will find
98         "boost/scoped_ptr.hpp".
99         <LI>
100         The name of a header: for example "scoped_ptr.hpp" will find
101         "boost/scoped_ptr.hpp".
102         <LI>
103            The name of a file: for example "boost/regex.hpp".</LI></OL>
104      <P>When the --scan option is used, then a list of (probably non-boost) files to
105         scan for boost dependencies, the files in the module list are not therefore
106         copied/listed.</P>
107      <H4>output-path:
108      </H4>
109      <P>The path to which files will be copied (this path must exist).</P>
110      <H2>Dependencies</H2>
111      <P>File dependencies are found as follows:</P>
112      <UL>
113         <LI>
114            C++ source files are scanned for #includes, all #includes present in the boost
115            source tree will then be scanned for their dependencies and so on.</LI>
116         <LI>
117            C++ source files are associated with the name of a library, if that library has
118            source code (and possibly build data), then include that source in the
119            dependencies.</LI>
120         <LI>
121            C++ source files are checked for dependencies on Boost.test (for example to see
122            if they use cpp_main as an entry point).</LI>
123         <LI>
124            HTML files are scanned for immediate dependencies (images and style sheets, but
125            not links).</LI></UL>
126      <P>It should be noted that in practice bcp can produce a rather "fat" list of
127         dependencies, reasons for this include:</P>
128      <UL>
129         <LI>
130            It searches for library names first, so using "regex" as a name will give you
131            everything in the libs/regex directory and everything that depends on.&nbsp; 
132            This can be a long list as all the regex test and example programs will get
133            scanned for their dependencies.&nbsp; If you want a more minimal list, then try
134            using the names of the headers you are actually including, or use the --scan
135            option to scan your source code.</LI>
136         <LI>
137            If you include the header of a library with separate source, then you get that
138            libraries source and all it's dependencies.&nbsp; This is deliberate and in
139            general those extra dependencies are needed.</LI>
140         <LI>
141            When you include a header, bcp doesn't know what compiler you're using, so it
142            follows all possible preprocessor paths. If you're distributing a subset of
143            Boost with you're application then that is what you want to have happen in
144            general.</LI></UL>
145      <P>The last point above can result in a substantial increase in the number of
146         headers found compared to most peoples expectations.&nbsp; For example bcp
147         finds 274 header dependencies for boost/shared_ptr.hpp: by running bcp in
148         report mode we can see why all these headers have been found as dependencies:</P>
149      <UL>
150         <LI>
151            All of the Config&nbsp;library headers get included&nbsp;(52 headers, would be
152            about 6 for one compiler only).</LI>
153         <LI>
154            A lot of MPL and type traits code that includes workarounds for broken
155            compilers that you may or may not need.&nbsp; Tracing back through the code
156            shows that most of these aren't needed unless the user has
157            defined&nbsp;BOOST_SP_USE_QUICK_ALLOCATOR, however bcp isn't aware of whether
158            that preprocessor path will be taken or not, so the headers get included just
159            in case.&nbsp; This adds about 48 headers (type traits), plus another 49 from
160            MPL.</LI>
161         <LI>
162            The Preprocessor library gets used heavily by MPL: this adds another 96
163            headers.</LI>
164         <LI>
165            The Shared Pointer library contains a lot of platform specific code, split up
166            into around 22 headers: normally your compiler would need only a couple of
167            these files.</LI></UL>
168      <P>As you can see the number of dependencies found are much larger than those used
169         by any single compiler, however if you want to distribute a subset of Boost
170         that's usable in any configuration, by any compiler, on any platform then
171         that's exactly what you need.&nbsp; If you want to figure out which Boost
172         headers are being used by your <EM>specific </EM>compiler then the best way to
173         find out is to prepocess the code and scan the output for boost header
174         includes.&nbsp; You should be aware that the result will be very platform and
175         compiler specific, and may not contain all the headers needed if you so much as
176         change a compiler switch (for example turn on threading support).</P>
177      <P>
178      <P>
179         <HR>
180      <P></P>
181      <P></P>
182      <p>Revised&nbsp; 
183         <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> 
184         28 June 2004&nbsp; 
185         <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
186      </p>
187      <P><I>© Copyright <a href="mailto:jm@regex.fsnet.co.uk">John Maddock</a>&nbsp;2003-4</I></P>
188      <P align="left"><I>Distributed under the Boost Software License, Version 1.0.
189       (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>)
190       </I></P>
191   </body>
192</html>
193
Note: See TracBrowser for help on using the repository browser.