diff --git a/v2/doc/src/advanced.xml b/v2/doc/src/advanced.xml
index 4b2dcb756..9c735f0c6 100644
--- a/v2/doc/src/advanced.xml
+++ b/v2/doc/src/advanced.xml
@@ -499,16 +499,19 @@ exe b : [ glob *.cpp ] ; # all .cpp files in this directory are sources
lib helper : helper.cpp ;
exe a : a.cpp helper ;
-exe b : b.cpp ..//utils ;
-exe c : c.cpp /boost/program_options//program_opions ;
+exe b : b.cpp ..//utils ;
+exe c : c.cpp /boost/program_options//program_options ;
- The first exe uses the library defined in the same project. The
- second one uses some target (most likely library) defined by Jamfile
- one level higher. Finally, the third target uses some C++ Boost library, using the
- symbolic name to refer to it. More information about it can be found
- in tutorial and in
- target id reference.
+ The first exe uses the library defined in the same
+ project. The second one uses some target (most likely library)
+ defined by Jamfile one level higher. Finally, the third target
+ uses some C++ Boost
+ library, referring to it by its absolute symbolic name. More
+ information about it can be found in and .
+ other properties can be used, for example if
+ a library can only be built statically, or a file can't be compiled
with optimization due to a compiler bug, one can use
lib util : util.cpp : <link>static ;
@@ -533,61 +538,93 @@ obj main : main.cpp : <optimization>off ;
- Sometimes, requirements are necessary only for a specific
- compiler, or build variant. The
- conditional
- properties can be used in that case:
+ Sometimes requirements are necessary only for a specific
+ compiler or build variant. Conditional
+ properties can be used in that case:
+
lib util : util.cpp : <toolset>msvc:<link>static ;
- In means when whenever <toolset>msvc property is
+
+ Whenever <toolset>msvc property is
in build properties, the <link>static property will
- be included as well. The conditional requirements can be "chained":
+ be included as well. Conditional requirements can be “chained”:
lib util : util.cpp : <toolset>msvc:<link>static
<link>static:<define>STATIC_LINK ;
- will set of static link and the STATIC_LINK define on the
+ will set of static link
+
+ and the STATIC_LINK define on the
msvc toolset.
+
- The default-build attribute is
- a set of properties that should be used if build request does not
- specify a value. For example:
+ The default-build parameter
+
+ is a set of properties to be used if the build request does
+ not otherwise specify a value for features in the set. For example:
exe hello : hello.cpp : : <threading>multi ;
- would build the target in multi-threaded mode, unless the user
- explicitly requests single-threaded version. The difference between
+ would build a multi-threaded target in unless the user
+ explicitly requests a single-threaded version. The difference between
requirements and default-build is that requirements cannot be
- overriden in any way.
+ overriden in any way.
- A target of the same name can be declared several times. In that
- case is declaration is called an
- alternative. When the target is build, one of
- the alternatives will be selected and use. Alternatives need not be
- defined by the same main target rule. The following is OK:
+ A target of the same name can be declared several times, in which
+ case each declaration is called an
+ alternative. When the target is built, one of
+ the alternatives will be selected and used. Alternatives need not be
+ defined by the same main target rule. For example,
-lib helpers : helpers.hpp ;
-alias helpers : helpers.lib : <toolset>msvc ;
+lib helpers : helpers.hpp ; # a header-only library
+alias helpers : helpers.lib : <toolset>msvc ; # except on msvc
+
- Building of the same main target can differ greatly from
- platform to platform. For example, you might have different list
+ The actual commands used to build any given main target can differ greatly from
+ platform to platform. For example, you might have different lists
of sources for different compilers, or different options for those
compilers. Two approaches to this are explained in the
tutorial.
+
Sometimes a main target is really needed only by some other main
target. For example, a rule that declares a test-suite uses a main
- target that represent test, but those main targets are rarely needed
- by themself.
+ target
+
+ that represent test, but those main targets are rarely needed
+ by themselves.
+
+
- It is possible to declare target inline, i.e. the "sources"
- parameter may include call to other main rules. For example:
+ It is possible to declare a target inline, i.e. the "sources"
+ parameter may include calls to other main rules. For example:
exe hello : hello.cpp
@@ -596,10 +633,17 @@ exe hello : hello.cpp
Will cause "helpers.cpp" to be always compiled without
- optimization. It's possible to request main targets declared
- inline, but since they are considered local, they are renamed to
- "parent-main-target_name..main-target-name". In the example above,
- to build only helpers, one should run "bjam hello..helpers".
+ optimization.
+
+ When referring to an inline main target, its declared name
+ must be prefixed by its parent target's name and two dots. In
+ the example above, to build only helpers, one should run
+ bjam hello..helpers.
@@ -607,22 +651,27 @@ exe hello : hello.cpp
Projects
- As mentioned before, targets are grouped into projects, and each
- Jamfile is a separate project. Projects are useful because it allows
- to group related targets together, define properties common to all
- those targets, and assign a symbolic name to the project, allowing to
- easily refer to the targets in the project. Two last goals are
- accompished with the "project" rule.
+ As mentioned before, targets are grouped into projects,
+ and each Jamfile is a separate project. Projects are useful
+ because they allow us to group related targets together, define
+ properties common to all those targets, and assign a symbolic
+ name to the project that can be used in referring to its
+ targets.
- The rule has this syntax
+ Projects are named using the
+ project rule, which has the
+ following syntax:
-project id : <attributes> ;
+project id : attributes ;
- Here, attributes is a sequence of (attribute-name,
- attribute-value) pairs. The list of attribute names along with its
- handling is also shown in the table below. For example, it is
- possible to write:
+ Here, attributes is a sequence of
+ rule arguments, each of which begins with an attribute-name
+ and is followed by any number of build properties.
+ The list
+ of attribute names along with its handling is also shown in
+ the table below. For example, it is possible to write:
project tennis
: requirements <threading>multi
@@ -717,9 +766,11 @@ project tennis
build-dir
- If parent has a build dir set, the value of it, joined
- with the relative path from parent to the current project.
- Otherwise, empty
+ Empty if the parent has no build directory set.
+ Otherwise, the parent's build directory with with the
+ relative path from parent to the current project
+ appended to it.
+ Sets to the passed value, interpreted as relative to the
project's location.
@@ -729,46 +780,53 @@ project tennis
- Besides setting attributes and defining main targets,
- projects can invoke a number of rules,
- in particular the constant and path-constant
- which defines constants for all child projects. Project can also
- contain definitions of custom rules.
+ Besides defining projects and main targets,
+ Jamfiles commonly invoke utility rules such
+ as constant and
+ path-constant, which define
+ Boost.Jam variables that are automatically defined in all child
+ projects. See for a
+ complete description of these utility rules.
+ Jamfiles are regular Boost.Jam source
+ files, so naturally they can contain any kind of Boost.Jam code,
+ including rule definitions.
+
- Each project inherits attributes, constants and rules from the
- parent project -- the project in the nearest parent
- directory. However, the top-level Jamfile should not inherit
- anything. To indicate that, you'd need to use a different name:
- Jamroot. When loading a project, Boost.Build
- looks for both Jamroot and Jamfile,
- and they are handled indentically, except that if file is called
- Jamroot, search for parent project is not performed.
+ Each subproject inherits attributes, constants and rules
+ from its parent project (the project in the nearest parent
+ directory). The top-level project is declared in a file called
+ Jamroot rather than
+ Jamfile. When loading a project,
+ Boost.Build looks for both Jamroot and
+ Jamfile. They are handled indentically, except
+ that if the file is called Jamroot, the
+ search for a parent project is not performed.
- An important note about parent/child Jamfiles is that parents are
- always loaded before children. Consequently, every definitions made in
- parents are always available to children. The loading order of any
- other projects is not defined. Even if one project refers to another
- via use-project,
- or via target reference, no specific order should be assumed.
+ Even when building in a subproject directory, parent
+ project files are always loaded before those of their
+ subprojects, so that every definition made in a parent project
+ is always available to its children. The loading order of any
+ other projects is unspecified. Even if one project refers to
+ another via use-project,
+ or a target reference, no specific order should be assumed.
- The root project must use a different name because Boost.Build
- must decide if parent must be loaded before reading the project. If
- we first loaded a project and then decide if parent should be
- loaded, the definitions made by parent, especially constants, won't
- be available to the child.
+ Giving the root project the special name
+ “Jamroot” ensures that
+ Boost.Build won't misinterpret a directory above it that
+ happens to contain a Jamfile as the project root.
+
-
Additional Jamfile rules
diff --git a/v2/doc/src/tutorial.xml b/v2/doc/src/tutorial.xml
index 09b109b42..4a7dd3295 100644
--- a/v2/doc/src/tutorial.xml
+++ b/v2/doc/src/tutorial.xml
@@ -774,7 +774,7 @@ lib network : network.cpp
it. We can express this situation using target
alternatives:
-lib demangler : dummy_demangler.cpp ; # alternative 1
+lib demangler : dummy_demangler.cpp ; # alternative 1
lib demangler : demangler_gcc.cpp : <toolset>gcc ; # alternative 2
lib demangler : demangler_msvc.cpp : <toolset>msvc ; # alternative 3
diff --git a/v2/doc/src/userman.xml b/v2/doc/src/userman.xml
index f4a9202f1..ef80b7803 100644
--- a/v2/doc/src/userman.xml
+++ b/v2/doc/src/userman.xml
@@ -3,7 +3,7 @@
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
+ id="bbv2" last-revision="$Date$" status="draft">
Boost.Build v2 User Manual