ceph/src/boost/tools/bcp/doc/bcp.qbk

   1
   2 [article BCP
   3     [quickbook 1.4]
   4     [copyright 2009 John Maddock]
   5     [purpose Regular Expressions]
   6     [license
   7         Distributed under the Boost Software License, Version 1.0.
   8         (See accompanying file LICENSE_1_0.txt or copy at
   9         [@http://www.boost.org/LICENSE_1_0.txt])
  10     ]
  11     [authors [Maddock, John]]
  12     [category text]
  13     [/last-revision $Date: 2008-02-21 12:58:15 +0000 (Thu, 21 Feb 2008) $]
  14 ]
  15
  16 [section:overview Overview]
  17
  18 The bcp utility is a tool for extracting subsets of Boost, it's useful for Boost authors who want to distribute
  19 their library separately from Boost, and for Boost users who want to distribute a subset of Boost with their application.
  20
  21 bcp can also report on which parts of Boost your code is dependent on, and what licences are used by those dependencies.
  22
  23 [endsect]
  24
  25 [section:examples Examples]
  26
  27 [pre
  28 bcp scoped_ptr /foo
  29 ]
  30
  31 Copies boost/scoped_ptr.hpp and dependencies to /foo.
  32
  33 [pre
  34 bcp boost/regex.hpp /foo
  35 ]
  36
  37 Copies boost/regex.hpp and all dependencies including the regex source code (in libs/regex/src) and
  38 build files (in libs/regex/build) to /foo.  Does not copy the regex documentation, test, or example code.
  39 Also does not copy the Boost.Build system.
  40
  41 [pre
  42 bcp regex /foo
  43 ]
  44
  45 Copies the full regex lib (in libs/regex) including dependencies (such as the boost.test source required
  46 by the regex test programs) to /foo.  Does not copy the Boost.Build system.
  47
  48 [pre
  49 bcp --namespace=myboost --namespace-alias regex config build /foo
  50 ]
  51
  52 Copies the full regex lib (in libs\/regex) plus the config lib (libs\/config) and the build system (tools\/build)
  53 to \/foo including all the dependencies.  Also renames the boost namespace to /myboost/ and changes the filenames
  54 of binary libraries to begin with the prefix "myboost" rather than "boost".  The --namespace-alias option makes
  55 `namespace boost` an alias of the new name.
  56
  57 [pre
  58 bcp --scan --boost=/boost foo.cpp bar.cpp boost
  59 ]
  60
  61 Scans the [non-boost] files foo.cpp and bar.cpp for boost dependencies and copies those dependencies to the sub-directory boost.
  62
  63 [pre
  64 bcp --report regex.hpp boost-regex-report.html
  65 ]
  66
  67 Creates a HTML report called boost-regex-report.html for the boost module regex.hpp.  The report contains license information, author details, and file dependencies.
  68
  69 [endsect]
  70
  71 [section:syntax Syntax]
  72
  73 [section:main Behaviour Selection]
  74
  75 [pre
  76 bcp --list \[options\] module-list
  77 ]
  78
  79 Outputs a list of all the files in module-list including dependencies.
  80
  81 [pre
  82 bcp \[options\] module-list output-path
  83 ]
  84
  85 Copies all the files found in module-list to output-path
  86
  87 [pre
  88 bcp --report \[options\] module-list html-file
  89 ]
  90
  91 Outputs a html report file containing:
  92
  93 * All the licenses in effect, plus the files using each license, and the copyright holders using each license.
  94 * Any files with no recognizable license (please report these to the boost mailing lists).
  95 * Any files with no recognizable copyright holders (please report these to the boost mailing lists).
  96 * All the copyright holders and the files on which they hold copyright.
  97 * File dependency information - indicates the reason for the inclusion of any particular file in the dependencies found.
  98
  99 [endsect]
 100
 101 [section:options Options]
 102
 103 [pre
 104 --boost=path
 105 ]
 106
 107 Sets the location of the boost tree to path.  If this option is not provided then the current path is assumed to be
 108 the root directory of the Boost tree.
 109
 110 [pre --namespace=newname ]
 111
 112 When copying files, all occurances of the boost namespace will get renamed to "newname".  Also
 113 renames Boost binaries to use "newname" rather than "boost" as a prefix.
 114
 115 Often used in conjunction with the --namespace-alias option, this allows two different Boost versions to be
 116 used in the same program, but not in the same translation unit.
 117
 118 [pre --namespace-alias]
 119
 120 When used in conjunction with the --namespace option, then `namespace boost` will be declared as an alias
 121 of the new namespace name.  This allows existing code that relies on Boost code being in `namespace boost`
 122 to compile unchanged, while retaining the "strong versioning" that can be achieved with a namespace change.
 123
 124 [pre
 125 --scan
 126 ]
 127
 128 Treats the module list as a list of (probably non-boost) files to scan for boost dependencies,
 129 the files listed in the module list are not copied (or listed), only the boost files upon which they depend.
 130
 131 [pre
 132 --svn
 133 ]
 134
 135 Only copy files under svn version control.
 136
 137 [pre
 138 --unix-lines
 139 ]
 140
 141 Make sure that all copied files use Unix style line endings.
 142
 143 [endsect]
 144
 145 [section:module module-list]
 146
 147 When the --scan option is not used then a list of boost files or library names to copy, this can be:
 148
 149 # The name of a tool: for example "build" will find "tools/build".
 150 # The name of a library: for example "regex".
 151 # The title of a header: for example "scoped_ptr" will find "boost/scoped_ptr.hpp".
 152 # The name of a header: for example "scoped_ptr.hpp" will find "boost/scoped_ptr.hpp".
 153 # The name of a file: for example "boost/regex.hpp".
 154
 155 When the --scan option is used, then a list of (probably non-boost) files to scan for boost dependencies,
 156 the files in the module list are not therefore copied/listed.
 157
 158 [endsect]
 159
 160 [section:output output-path]
 161
 162 The path to which files will be copied (this path must exist).
 163
 164 [endsect]
 165
 166 [section Dependencies]
 167
 168 File dependencies are found as follows:
 169
 170 * C++ source files are scanned for #includes, all #includes present in the boost source tree will then be scanned for
 171 their dependencies and so on.
 172 * C++ source files are associated with the name of a library, if that library has source code
 173 (and possibly build data), then include that source in the dependencies.
 174 * C++ source files are checked for dependencies on Boost.test (for example to see if they use cpp_main as an entry point).
 175 * HTML files are scanned for immediate dependencies (images and style sheets, but not links).
 176
 177 It should be noted that in practice bcp can produce a rather "fat" list of dependencies, reasons for this include:
 178
 179 * It searches for library names first, so using "regex" as a name will give you everything in the
 180 libs/regex directory and everything that depends on.  This can be a long list as all the regex test and example
 181 programs will get scanned for their dependencies.  If you want a more minimal list, then try using the
 182 names of the headers you are actually including, or use the --scan option to scan your source code.
 183 * If you include the header of a library with separate source, then you get that libraries source and all
 184 it's dependencies.  This is deliberate and in general those extra dependencies are needed.
 185 * When you include a header, bcp doesn't know what compiler you're using, so it follows all
 186 possible preprocessor paths. If you're distributing a subset of Boost with you're application then that
 187 is what you want to have happen in general.
 188
 189 The last point above can result in a substantial increase in the number of headers found compared to most
 190 peoples expectations.  For example bcp finds 274 header dependencies for boost/shared_ptr.hpp: by
 191 running bcp in report mode we can see why all these headers have been found as dependencies:
 192
 193 * All of the Config library headers get included (52 headers, would be about 6 for one compiler only).
 194 * A lot of MPL and type traits code that includes workarounds for broken compilers that you may or may not need.
 195 Tracing back through the code shows that most of these aren't needed unless the user has
 196 defined BOOST_SP_USE_QUICK_ALLOCATOR, however bcp isn't aware of whether that preprocessor path will be
 197 taken or not, so the headers get included just in case.  This adds about 48 headers (type traits), plus another 49 from MPL.
 198 * The Preprocessor library gets used heavily by MPL: this adds another 96 headers.
 199 * The Shared Pointer library contains a lot of platform specific code, split up into around 22 headers:
 200 normally your compiler would need only a couple of these files.
 201
 202 As you can see the number of dependencies found are much larger than those used by any single compiler,
 203 however if you want to distribute a subset of Boost that's usable in any configuration, by any compiler,
 204 on any platform then that's exactly what you need.  If you want to figure out which Boost headers are
 205 being used by your specific compiler then the best way to find out is to prepocess the code and scan
 206 the output for boost header includes.  You should be aware that the result will be very platform and compiler
 207 specific, and may not contain all the headers needed if you so much as change a compiler switch
 208 (for example turn on threading support).
 209
 210 [endsect]
 211 [endsect]
 212