]>
Commit | Line | Data |
---|---|---|
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 © 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> |