boost_1_45_0/tools/bcp/doc/bcp.qbk - nest-learning-thermostat/5.0/boost - Git at Google


 [article BCP
     [quickbook 1.4]
     [copyright 2209 John Maddock]
     [purpose Regular Expressions]
     [license
         Distributed under the Boost Software License, Version 1.0.
         (See accompanying file LICENSE_1_0.txt or copy at
         [@http://www.boost.org/LICENSE_1_0.txt])
     ]
     [authors [Maddock, John]]
     [category text]
     [/last-revision $Date: 2008-02-21 12:58:15 +0000 (Thu, 21 Feb 2008) $]
 ]

 [section:overview Overview]

 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.

 bcp can also report on which parts of Boost your code is dependent on, and what licences are used by those dependencies.

 [endsect]

 [section:examples Examples]

 [pre
 bcp scoped_ptr /foo
 ]

 Copies boost/scoped_ptr.hpp and dependencies to /foo.

 [pre
 bcp boost/regex.hpp /foo
 ]

 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.

 [pre
 bcp regex /foo
 ]

 Copies the full regex lib (in libs/regex) including dependencies (such as the boost.test source required
 by the regex test programs) to /foo.

 [pre
 bcp --namespace=myboost --namespace-alias regex config build /foo
 ]

 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.  Also renames the boost namespace to /myboost/ and changes the filenames
 of binary libraries to begin with the prefix "myboost" rather than "boost".  The --namespace-alias option makes
 `namespace boost` an alias of the new name.

 [pre
 bcp --scan --boost=/boost foo.cpp bar.cpp boost
 ]

 Scans the [non-boost] files foo.cpp and bar.cpp for boost dependencies and copies those dependencies to the sub-directory boost.

 [pre
 bcp --report regex.hpp boost-regex-report.html
 ]

 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.

 [endsect]

 [section:syntax Syntax]

 [section:main Behaviour Selection]

 [pre
 bcp --list \[options\] module-list
 ]

 Outputs a list of all the files in module-list including dependencies.

 [pre
 bcp \[options\] module-list output-path
 ]

 Copies all the files found in module-list to output-path

 [pre
 bcp --report \[options\] module-list html-file
 ]

 Outputs a html report file containing:

 * All the licenses in effect, plus the files using each license, and the copyright holders using each license.
 * Any files with no recognizable license (please report these to the boost mailing lists).
 * Any files with no recognizable copyright holders (please report these to the boost mailing lists).
 * All the copyright holders and the files on which they hold copyright.
 * File dependency information - indicates the reason for the inclusion of any particular file in the dependencies found.

 [endsect]

 [section:options Options]

 [pre
 --boost=path
 ]

 Sets the location of the boost tree to path.  If this option is not provided then the current path is assumed to be
 the root directory of the Boost tree.

 [pre --namespace=newname ]

 When copying files, all occurances of the boost namespace will get renamed to "newname".  Also
 renames Boost binaries to use "newname" rather than "boost" as a prefix.

 Often used in conjunction with the --namespace-alias option, this allows two different Boost versions to be
 used in the same program, but not in the same translation unit.

 [pre --namespace-alias]

 When used in conjunction with the --namespace option, then `namespace boost` will be declared as an alias
 of the new namespace name.  This allows existing code that relies on Boost code being in `namespace boost`
 to compile unchanged, while retaining the "strong versioning" that can be achieved with a namespace change.

 [pre
 --scan
 ]

 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.

 [pre
 --svn
 ]

 Only copy files under svn version control.

 [pre
 --unix-lines
 ]

 Make sure that all copied files use Unix style line endings.

 [endsect]

 [section:module module-list]

 When the --scan option is not used then a list of boost files or library names to copy, this can be:

 # The name of a tool: for example "build" will find "tools/build".
 # The name of a library: for example "regex".
 # The title of a header: for example "scoped_ptr" will find "boost/scoped_ptr.hpp".
 # The name of a header: for example "scoped_ptr.hpp" will find "boost/scoped_ptr.hpp".
 # The name of a file: for example "boost/regex.hpp".

 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.

 [endsect]

 [section:output output-path]

 The path to which files will be copied (this path must exist).

 [endsect]

 [section Dependencies]

 File dependencies are found as follows:

 * 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.
 * 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.
 * C++ source files are checked for dependencies on Boost.test (for example to see if they use cpp_main as an entry point).
 * HTML files are scanned for immediate dependencies (images and style sheets, but not links).

 It should be noted that in practice bcp can produce a rather "fat" list of dependencies, reasons for this include:
 * 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.
 * 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.
 * 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.

 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:

 * All of the Config library headers get included (52 headers, would be about 6 for one compiler only).
 * 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.
 * The Preprocessor library gets used heavily by MPL: this adds another 96 headers.
 * 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.

 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 specific 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).

 [endsect]
 [endsect]

	[article BCP
	[quickbook 1.4]
	[copyright 2209 John Maddock]
	[purpose Regular Expressions]
	[license
	Distributed under the Boost Software License, Version 1.0.
	(See accompanying file LICENSE_1_0.txt or copy at
	[@http://www.boost.org/LICENSE_1_0.txt])
	]
	[authors [Maddock, John]]
	[category text]
	[/last-revision $Date: 2008-02-21 12:58:15 +0000 (Thu, 21 Feb 2008) $]
	]

	[section:overview Overview]

	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.

	bcp can also report on which parts of Boost your code is dependent on, and what licences are used by those dependencies.

	[endsect]

	[section:examples Examples]

	[pre
	bcp scoped_ptr /foo
	]

	Copies boost/scoped_ptr.hpp and dependencies to /foo.

	[pre
	bcp boost/regex.hpp /foo
	]

	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.

	[pre
	bcp regex /foo
	]

	Copies the full regex lib (in libs/regex) including dependencies (such as the boost.test source required
	by the regex test programs) to /foo.

	[pre
	bcp --namespace=myboost --namespace-alias regex config build /foo
	]

	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. Also renames the boost namespace to /myboost/ and changes the filenames
	of binary libraries to begin with the prefix "myboost" rather than "boost". The --namespace-alias option makes
	`namespace boost` an alias of the new name.

	[pre
	bcp --scan --boost=/boost foo.cpp bar.cpp boost
	]

	Scans the [non-boost] files foo.cpp and bar.cpp for boost dependencies and copies those dependencies to the sub-directory boost.

	[pre
	bcp --report regex.hpp boost-regex-report.html
	]

	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.

	[endsect]

	[section:syntax Syntax]

	[section:main Behaviour Selection]

	[pre
	bcp --list \[options\] module-list
	]

	Outputs a list of all the files in module-list including dependencies.

	[pre
	bcp \[options\] module-list output-path
	]

	Copies all the files found in module-list to output-path

	[pre
	bcp --report \[options\] module-list html-file
	]

	Outputs a html report file containing:

	* All the licenses in effect, plus the files using each license, and the copyright holders using each license.
	* Any files with no recognizable license (please report these to the boost mailing lists).
	* Any files with no recognizable copyright holders (please report these to the boost mailing lists).
	* All the copyright holders and the files on which they hold copyright.
	* File dependency information - indicates the reason for the inclusion of any particular file in the dependencies found.

	[endsect]

	[section:options Options]

	[pre
	--boost=path
	]

	Sets the location of the boost tree to path. If this option is not provided then the current path is assumed to be
	the root directory of the Boost tree.

	[pre --namespace=newname ]

	When copying files, all occurances of the boost namespace will get renamed to "newname". Also
	renames Boost binaries to use "newname" rather than "boost" as a prefix.

	Often used in conjunction with the --namespace-alias option, this allows two different Boost versions to be
	used in the same program, but not in the same translation unit.

	[pre --namespace-alias]

	When used in conjunction with the --namespace option, then `namespace boost` will be declared as an alias
	of the new namespace name. This allows existing code that relies on Boost code being in `namespace boost`
	to compile unchanged, while retaining the "strong versioning" that can be achieved with a namespace change.

	[pre
	--scan
	]

	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.

	[pre
	--svn
	]

	Only copy files under svn version control.

	[pre
	--unix-lines
	]

	Make sure that all copied files use Unix style line endings.

	[endsect]

	[section:module module-list]

	When the --scan option is not used then a list of boost files or library names to copy, this can be:

	# The name of a tool: for example "build" will find "tools/build".
	# The name of a library: for example "regex".
	# The title of a header: for example "scoped_ptr" will find "boost/scoped_ptr.hpp".
	# The name of a header: for example "scoped_ptr.hpp" will find "boost/scoped_ptr.hpp".
	# The name of a file: for example "boost/regex.hpp".

	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.

	[endsect]

	[section:output output-path]

	The path to which files will be copied (this path must exist).

	[endsect]

	[section Dependencies]

	File dependencies are found as follows:

	* 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.
	* 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.
	* C++ source files are checked for dependencies on Boost.test (for example to see if they use cpp_main as an entry point).
	* HTML files are scanned for immediate dependencies (images and style sheets, but not links).

	It should be noted that in practice bcp can produce a rather "fat" list of dependencies, reasons for this include:
	* 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.
	* 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.
	* 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.

	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:

	* All of the Config library headers get included (52 headers, would be about 6 for one compiler only).
	* 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.
	* The Preprocessor library gets used heavily by MPL: this adds another 96 headers.
	* 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.

	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 specific 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).

	[endsect]
	[endsect]