diff --git a/doc/src/advanced.xml b/doc/src/advanced.xml
index 76800ae0b..8a046a833 100644
--- a/doc/src/advanced.xml
+++ b/doc/src/advanced.xml
@@ -296,58 +296,109 @@ actions create-file-from-another
Configuration
- The Boost.Build configuration is specified in the file
- user-config.jam. You can edit the one in the top-level
- directory of Boost.Build installation or create a copy in your home
- directory and edit that. (See
- for the exact search paths.) The primary function of that file is to declare
- which compilers and other tools are available. The simplest syntax to
- configure a tool is:
+
+ On startup, Boost.Build searches and reads two configuration files:
+ site-config.jam and user-config.jam.
+ The first one is usually installed and maintained by system administrator, and
+ the second is for user to modify. You can edit the one in the top-level
+ directory of Boost.Build installation or create a copy in your home
+ directory and edit the copy. The following table explains where both files
+ are searched.
+
+
+
+
+
+
+ You can use the --debug-configuration option to
+ find which configuration files are actually loaded.
+
+
+
+
+ Usually, user-config.jam just defines available compilers
+ and other tools (see for more advanced
+ usage). A tool is configured using the following syntax:
+
-using tool-name ;
+using tool-name : ... ;
+
The using rule is given a name of tool, and
will make that tool available to Boost.Build. For example,
- using gcc ; will make the gcc compiler available.
+
+using gcc ;
+ will make the GCC compiler available.
- Since nothing but a tool name is specified, Boost.Build will pick some
- default settings. For example, it will use the gcc
- executable found in the PATH, or look in some known
- installation locations. In most cases, this strategy works automatically.
- In case you have several versions of a compiler, it is installed in some
- unusual location, or you need to tweak its configuration, you'll need to
- pass additional parameters to the using rule.
- The parameters to using can be different for
- each tool. You can obtain specific documentation for any tool's
- configuration parameters by invoking
-
-bjam --help tool-name.init
-
+ All the supported tools are documented in ,
+ including the specific options they take. Some general notes that apply to most
+ C++ compilers are below.
+
- That said, for all the compiler toolsets Boost.Build supports
+ For all the C++ compiler toolsets Boost.Build supports
out-of-the-box, the list of parameters to
using is the same: toolset-name, version, invocation-command, and options.
-
- The version parameter
- identifies the toolset version, in case you have several installed. It can
- have any form you like, but it is recommended that you use a numeric
- identifier like 7.1.
-
-
-
- The invocation-command parameter
- is the command that must be executed to run the compiler. This parameter
- can usually be omitted if the compiler executable
+ If you have a single compiler, and the compiler executable
has its “usual name” and is in the
PATH, or
@@ -356,27 +407,24 @@ bjam --help tool-name.init
can be found using a global system like the Windows
registry.
-
- For example:
+ it can be configured by simply:
-using msvc : 7.1 ;
-using gcc ;
+using tool-name ;
- If the compiler can be found in the PATH but only by a
- nonstandard name, you can just supply that name:
+
+
+ If the compiler is installed in a custom directory, you should provide the
+ command that invokes the compiler, for example:
using gcc : : g++-3.2 ;
-
- Otherwise, it might be necessary to supply the complete path to the
- compiler executable:
-
using msvc : : "Z:/Programs/Microsoft Visual Studio/vc98/bin/cl" ;
+
Some Boost.Build toolsets will use that path to take additional actions
required before invoking the compiler, such as calling vendor-supplied
scripts to set up its required environment variables. When compiler
executables for C and C++ are different, path to the C++ compiler
- executable must be specified. The “invocation command” can
+ executable must be specified. The command can
be any command allowed by the operating system. For example:
using msvc : : echo Compiling && foo/bar/baz/cl ;
@@ -397,6 +445,7 @@ using gcc : 3.2 : g++-3.2 ;
need to explicitly specify the command.
+
- The options
- parameter is used to fine-tune the configuration. All of
- Boost.Build's standard compiler toolsets accept properties of the
- four builtin features cflags,
- cxxflags, compileflags and
- linkflags as options specifying flags that will be
- always passed to the corresponding tools. Values of the
- cflags feature are passed directly to the C
- compiler, values of the cxxflags feature are
- passed directly to the C++ compiler, and values of the
- compileflags feature are passed to both. For
- example, to configure a gcc toolset so that it
- always generates 64-bit code you could write:
+
+ Many of toolsets have an options
+ parameter to fine-tune the configuration. All of
+ Boost.Build's standard compiler toolsets accept four options
+ cflags, cxxflags,
+ compileflags and linkflags as options specifying flags that will be
+ always passed to the corresponding tools. Values of the
+ cflags feature are passed directly to the C
+ compiler, values of the cxxflags feature are
+ passed directly to the C++ compiler, and values of the
+ compileflags feature are passed to both. For
+ example, to configure a gcc toolset so that it
+ always generates 64-bit code you could write:
-using gcc : 3.4 : : <compileflags>-m64 <linkflags>-m64 ;
+ using gcc : 3.4 : : <compileflags>-m64 <linkflags>-m64 ;
+
+
+ Although the syntax used to specify toolset options is very similar
+ to syntax used to specify requirements in Jamfiles, the toolset options
+ are not the same as features. Don't try to specify a feature value
+ in toolset initialization.
+
+
+
Invocation
- This section describes how invoke Boost.Build from the command line
+ To invoke Boost.Build, type bjam on the command line. Three kinds
+ of command-line tokens are accepted, in any order:
+
+
+ options
- To build all targets defined in Jamfile in the current directory with default properties, run:
+ Options start with either dash, or two dashes. The standard options
+ are listed below, and each project may add additional options
+
+
+
+ properties
+
+ Properties specify details of what you want to build (e.g. debug
+ or release variant). Syntactically, all command line tokens with equal sign in them
+ are considered to specify properties. In the simplest form, property looks like
+ feature=value
+
+
+
+
+ target
+
+ All tokens that are neither options nor properties specify
+ what targets to build. The available targets entirely depend on the project
+ you are building.
+
+
+
+
+ Examples
+
+ To build all targets defined in Jamfile in the current directory with default properties, run:
bjam
-
+
+
- To build specific targets, specify them on the command line:
+ To build specific targets, specify them on the command line:
bjam lib1 subproject//lib2
-
+
- To request a certain value for some property, add
- property=value to the command line:
+ To request a certain value for some property, add
+ property=value to the command line:
bjam toolset=gcc variant=debug optimization=space
- For often used features, like toolset and variant you can
- omit the feature name, so the above can be written as:
+
+
+
+
+ Options
+
+ Boost.Build recognizes the following command line options.
+
+
+
+
+
+
+ Invokes the online help system. This prints general
+ information on how to use the help system with additional
+ --help* options.
+
+
+
+
+
+
+
+ Cleans all targets in the current directory and
+ in any subprojects. Note that unlike the clean
+ target in make, you can use --clean
+ together with target names to clean specific targets.
+
+
+
+
+
+
+ Cleans all targets,
+ no matter where they are defined. In particular, it will clean targets
+ in parent Jamfiles, and targets defined under other project roots.
+
+
+
+
+
+
+
+ Changes build directories for all project roots being built. When
+ this option is specified, all Jamroot files should declare project name.
+ The build directory for the project root will be computed by concatanating
+ the value of the option, the project name
+ specified in Jamroot, and the build dir specified in Jamroot
+ (or bin, if none is specified).
+
+
+ The option is primarily useful when building from read-only
+ media, when you can't modify Jamroot.
+
+
+
+
+
+
+
+ Prints information on Boost.Build and Boost.Jam
+ versions.
+
+
+
+
+
+
+
+ Produces debug information about loading of Boost.Build
+ and toolset files.
+
+
+
+
+
+
+ Prints what targets are being built and with what properties.
+
+
+
+
+
+
+
+ Produces debug output from generator search process.
+ Useful for debugging custom generators.
+
+
+
+
+
+
+
+ Do not load site-config.jam and
+ user-config.jam configuration files.
+
+
+
+
+
+
+
+ Properties
+
+ In the simplest case, the build is performed with a single set of properties,
+ that you specify on the command line with elements in the form
+ feature=value.
+ The complete list of features can be found in .
+ The most common features are summarized below.
+
+
+
+
+
+
+ Feature
+
+ Allowed values
+
+ Notes
+
+
+
+
+
+
+ variant
+
+ debug,release
+
+
+
+
+
+ link
+
+ shared,static
+
+ Determines if Boost.Build creates shared or static libraries
+
+
+
+ threading
+
+ single,multi
+
+ Cause the produced binaries to be thread-safe. This requires proper support in the source code itself.
+
+
+
+ toolset
+
+ (Depends on configuration)
+
+ The C++ compiler to use. See for a detailed list.
+
+
+
+ cxxflags
+
+ (Arbitrary string)
+
+ Custom options to pass to the C++ compiler.
+
+
+
+ cflags
+
+ (Arbitrary string)
+
+ Custom options to pass to the C compiler.
+
+
+
+ includes
+
+ (Arbitrary string)
+
+ Additional include paths for C and C++ compilers.
+
+
+
+ define
+
+ (Arbitrary string)
+
+ Additional macro definitions for C and C++ compilers.
+
+
+
+ runtime-link
+
+ shared,static
+
+ Determines if shared or static version of C and C++ runtimes should be used.
+
+
+
+
+
+
+ If you have more than one version of a given C++ toolset (e.g. configured in
+ user-config.jam, or autodetected, as happens with msvc), you can
+ request the specific version by passing
+ toolset-version as
+ the value of the toolset feature, for example toolset=msvc-8.0.
+
+
+
+ If a feature has a fixed set of values it can be specified more than
+ once on the command line.
+ In which case, everything will be built several times --
+ once for each specified value of a feature. For example, if you use
+
-bjam optimization=space
+bjam link=static link=shared threading=single threading=multi
-
+
+ Then a total of 4 builds will be performed. For convenience,
+ instead of specifying all requested values of a feature in separate command line elements,
+ you can separate the values with commands, for example:
+
+
+bjam link=static,shared threading=single,multi
+
+
+ The comma has special meaning only if the feature has a fixed set of values, so
+
+
+bjam include=static,shared
+
+ is not treated specially.
+
+
+
+ Targets
- Boost.Build recognizes the following command line options.
-
-
-
-
-
-
- Cleans all targets in the current directory and
- in any subprojects. Note that unlike the clean
- target in make, you can use --clean
- together with target names to clean specific targets.
-
-
-
-
-
-
- Cleans all targets,
- no matter where they are defined. In particular, it will clean targets
- in parent Jamfiles, and targets defined under other project roots.
-
-
-
-
-
-
-
- Changes build directories for all project roots being built. When
- this option is specified, all Jamroot files should declare project name.
- The build directory for the project root will be computed by concatanating
- the value of the option, the project name
- specified in Jamroot, and the build dir specified in Jamroot
- (or bin, if none is specified).
-
-
- The option is primarily useful when building from read-only
- media, when you can't modify Jamroot.
-
-
-
-
-
-
-
- Prints information on Boost.Build and Boost.Jam
- versions.
-
-
-
-
-
-
-
- Invokes the online help system. This prints general
- information on how to use the help system with additional
- --help* options.
-
-
-
-
-
-
-
- Produces debug information about loading of Boost.Build
- and toolset files.
-
-
-
-
-
-
- Prints what targets are being built and with what properties.
-
-
-
-
-
-
-
- Produces debug output from generator search process.
- Useful for debugging custom generators.
-
-
-
-
-
-
-
- Do not load site-config.jam and
- user-config.jam configuration files.
-
-
-
-
-
-
-
- Enables internal checks.
-
-
-
-
-
-
-
- For complete specification of command line syntax, see
-
-
-
+ All command line elements that are neither options nor properties are the names of the
+ targets to build. See . If no target is specified,
+ the project in the current directory is built.
+
diff --git a/doc/src/reference.xml b/doc/src/reference.xml
index 449f6925c..a351b47b1 100644
--- a/doc/src/reference.xml
+++ b/doc/src/reference.xml
@@ -9,7 +9,7 @@
- Detailed reference
+ ReferenceGeneral information
@@ -49,186 +49,9 @@ boost-build build-system ;
automatically find the build system.
The default bootstrap.jam, after loading some standard
- definitions, loads two files, which can be provided/customised by
- user: site-config.jam and user-config.jam.
-
- Locations where those files are searched are summarized below:
-
-
-
-
- Boost.Build comes with default versions of those files,
-
- which can serve as templates for customized versions.
-
+ definitions, loads two site-config.jam and user-config.jam.
-
- Command line
-
- The command line may contain:
-
-
- Jam options,
-
- Boost.Build options,
-
- Command line arguments
-
-
-
- Command line arguments
-
-
- Command line arguments specify targets and build
- request using the following rules.
-
-
-
-
-
- An argument that does not contain slashes or the =
- symbol is either a value of an implicit feature or of a target to
- be built. It is taken to be value of a feature if an appropriate
- feature exists. Otherwise, it is considered a target id. Building the
- special target name “clean” has the same effect as
- using the --clean option.
-
-
-
-
-
- An argument containing either slashes or the = symbol
- specifies a number of build request elements (see ). In its simplest form, it is just
- a set of properties, separated by slashes, which become a single
- build request element, for example:
-
-
-borland/runtime-link=static
-
-
- A more complex form can be used to save typing. For example,
- instead of
-
-
-borland/runtime-link=static borland/runtime-link=dynamic
-
-
- one can use
-
-
-borland/runtime-link=static,dynamic
-
-
- Exactly, the conversion from argument to build request
- elements is performed by (1) splitting the argument at each slash,
- (2) converting each split part into a set of properties and (3)
- taking all possible combinations
-
- of the property sets. Each split
- part should have either the form
-
-
-feature-name=feature-value1[","feature-valueN]*
-
-
- or, in case of implicit features
-
-
-feature-value1[","feature-valueN;]*
-
-
- will be converted into the property set
-
-
-<feature-name>feature-value1 .... <feature-name>feature-valueN
-
-
-
-
-
-
-
-
-
- For example, the command line
-
-
-target1 debug gcc/runtime-link=dynamic,static
-
-
- would cause target called target1 to be rebuilt in
- debug mode, except that for gcc, both dynamically and statically
- linked binaries would be created.
-
-
-
-
- Command line options
-
- All of the Boost.Build options start with the "--" prefix.
- They are described in the following table.
-
- FIXME: That table has moved into "User documentation" section
- and there is nothing we can add here. Remove this part?
-
-
-
-
-
@@ -805,15 +628,19 @@ path-constant DATA : data/a.txt ;
Before using any tool, you must declare your intention, and possibly
specify additional information about the tool's configuration. This is
- done with the using rule, for example:
+ done by calling the using rule, typically in your
+ user-config.jam, for example:
using gcc ;
- additional parameters can be passed just like for other rules, for example:
+ additional parameters can be passed just like for other rules, for example:
using gcc : 4.0 : g++-4.0 ;
- The options that can be passed to each tool will be documented in the
+
+
+
+ The options that can be passed to each tool are documented in the
subsequent sections.
@@ -821,7 +648,10 @@ using gcc : 4.0 : g++-4.0 ;
C++ CompilersThis section lists all Boost.Build modules that support C++
- compilers and documents how each one can be initialized.
+ compilers and documents how each one can be initialized. The name
+ of support module for compiler is also the value for
+ the toolset feature that can be used to explicitly
+ request that compiler.
@@ -1310,7 +1140,7 @@ using dmc : &toolset_ops; ;
&using_repeation;
If the command is not specified, Boost.Build will search for
- a binary named como in
+ a binary named dmc in
PATH.
&option_list_intro;
diff --git a/doc/src/standalone.xml b/doc/src/standalone.xml
index decde144a..be5743dfd 100644
--- a/doc/src/standalone.xml
+++ b/doc/src/standalone.xml
@@ -13,8 +13,8 @@
-
+
diff --git a/doc/src/tasks.xml b/doc/src/tasks.xml
index 6ae6f4c58..8c35ae133 100644
--- a/doc/src/tasks.xml
+++ b/doc/src/tasks.xml
@@ -712,6 +712,7 @@ exe app : app.cpp : <implicit-dependency>parser ;
as potential dependencies.
+