###

# The bcp utility

###

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.

## Examples:

    bcp scoped_ptr /foo

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

    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.

    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.

    bcp 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.

    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.

    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.

## Syntax:

    bcp --list [options] module-list

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

    bcp [options] module-list output-path

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

    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.

### Options:

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

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

    --cvs

Only copy files under cvs version control.

    --unix-lines

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

#### module-list:

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

1. The name of a tool: for example "build" will find "tools/build".
2. The name of a library: for example "regex".
3. The title of a header: for example "scoped_ptr" will find "boost/scoped_ptr.hpp".
4. The name of a header: for example "scoped_ptr.hpp" will find "boost/scoped_ptr.hpp".
5. 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.

#### output-path:

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

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

Revised 28 June 2004

© Copyright John Maddock 2003-4

Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. Dr John Maddock makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.