diff --git a/v2/doc/src/advanced.xml b/v2/doc/src/advanced.xml
index 68633d213..f163c62a8 100644
--- a/v2/doc/src/advanced.xml
+++ b/v2/doc/src/advanced.xml
@@ -3,36 +3,190 @@
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
- Advanced
+ User documentation
- This section will document
- mostly high-level view of Boost.Build, mentioning appropriate
- modules and rules. The on-line help system must be used to obtain
+ This section will provide the information necessary to create your own
+ projects using Boost.Build. The information provided here is relatively
+ high-level, and detailed reference as
+ well as the on-line help system must be used to obtain
low-level documentation (see the help option).
+ The Boost.Build actually consists of two parts - Boost.Jam, which is a
+ build engine with its own interpreted language, and Boost.Build itself,
+ implemented in Boost.Jam's language. The chain of event which happen when
+ you type "bjam" on the command is:
+
+
+ Boost.Jam tries to find Boost.Build and loads the top-level
+ module. The exact process is described in the section on
+ initialization
+
+
+ Boost.Build top-level module loads user-defined configuration
+ files, "user-config.jam" and "site-config.jam", which define
+ available toolsets.
+
+
+ The Jamfile in the current directory is read. That in turn
+ might cause reading of further Jamfiles. As a result, a tree of
+ projects is created, with targets inside projects.
+
+
+ Finally, using build request specified on the command line,
+ Boost.Build decides which targets should be built, and how. That
+ information is passes back to Boost.Jam, which takes care of
+ actually running commands.
+
+
+
+
+ So, to be able to successfully use Boost.Build, you'd need to know only
+ three things:
+
+
+
+ How to configure Boost.Build
+
+
+
+ How to write Jamfiles
+
+
+
+ How the build process works
+
+
+
+
+
+
+ Configuration
+
+ The Boost.Build configuration is specified in the file
+ "user-config.jam". You can edit the one which comes with Boost.Build, or
+ create a copy in your home directory and edit that. The primary function
+ of that file is to declarate which compilers and other tools are
+ available. The simplest syntax to configure a tool is:
+
+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 available
+ the gcc compiler.
+
+
+
+ Since nothing but tool name is specified, Boost.Build will pick some
+ default settings -- for example will use gcc found in path, or look in
+ some known installation locations. For ordinary users, this is quite
+ fine. In case you have several version of a compiler, or it's located in
+ some unusual location, or you need to tweak the configuration, you'd
+ need to pass additional parameters to the "using" rule. Generally,
+ for every tool module, the parameters differ, and you can obtain the documentaiton
+ by running
+
+bjam --help <tool-name>.init
+
+ on the command line. However, for all compilers the meaning of two first
+ parameters is the same: version and invocation command.
+
+
+ The "version" parameter identifies the compiler, in case you have
+ several. It can have any form you like, but it's recommended that you use
+ numeric identifier, like "7.1". The "invocation command"
+ parameter is the command which must be executed to run the compiler. This
+ might be just compiler name, or a name with a path in it. Here are some
+ examples.
+
+
+ To configure a compiler installed in non-standard location and not
+ present in path, you can do the following:
+
+using msvc : : Z:/Programs/Microsoft Visual Studio/vc98/bin/cl.exe ;
+
+
+
+ To configure several versions of a compiler, the following can be used.
+
+using gcc : 3.3 ;
+using gcc : 3.4 : g++-3.4 ;
+using gcc : 3.2 : g++-3.2 ;
+
+ Note that in the first call to "using", the compiler found in path
+ will be used, and there's ne need to explicitly specify the command.
+
+
+ As shown above, both "version" and "invocation command" parameters
+ are optional, but there's important restriction: if you configure the same
+ compiler more then once, you must pass the "version" parameter every
+ time. For example, the following is not allowed:
+
+using gcc ;
+using gcc : 3.4 : g++-3.4 ;
+
+ because the first "using" does not specify the version.
+
+
+
+
+
+ Writing Jamfiles
+
Overview
- The most fundemental entity in Boost.Build is main
- target. This is object that user want to construct from
- sources and keep up to date with regard to those sources. Typical
- examples of main targets are executable files and libraries.
+ Jamfiles are the thing which is most important to the user,
+ bacause they declare the targets which should be build. Jamfiles are
+ also used for organizing targets -- each Jamfile is a separate project,
+ which can be build independently from the other projects.
- Main targets are grouped in projects. Their main
- purpose is organization: related targets placed in one project,
- can then be built together, or share some definitions.
+ Jamfile mostly contain calls to Boost.Build functions, which do
+ all the work, specifically:
+
+
+ declare main
+ targets
+
+
+ define
+ project properties
+
+
+ do various other
+ things
+
+
+
- Main targets and projects are created as the result of reading
- one or several Jamfiles. Each Jamfile is a file written in
- Boost.Jam interpreted language, and typically contains calls to
- functions provided by Boost.Build, which create main targets of
- needed type, declare project attributes and access other
- projects. The full list of functions provided by Boost.Build is
- described below.
- Of course, user can create his own functions, or it can directly
- access Boost.Build internals from Jamfile, if builtin facilities are
- not sufficient.
+ In addition to Jamfiles, Boost.Build has another user-editable
+ file, project-root.jam, which is mostly usefull to declare constants
+ global to all the projects. It is also describe below.
+
+
+
+
Main targetsMain target is a user-defined named
- entity which can be build, for example a named executable file.
- Declaring a main target is usually done using one of main target functions.
+ entity which can be build, for example a named executable file.
+ Declaring a main target is usually done using one of main target functions.
The user can also declare custom main target
- function.
-
- Most main targets rules in Boost.Build use similiar
- syntax:
+ "doc/extending.html#main_target_rules">custom main target
+ function.
+
+ Most main targets rules in Boost.Build use similiar
+ syntax:
function-name main-target-name
@@ -144,83 +300,109 @@ function-name main-target-name
;
-
-
-
- "main-target-name" is the name used to request the target
- on command line and to use it from other main targets. Main
- target name may contain alphanumeric characters and symbols '-'
- and '_';
-
-
-
-
-
- "sources" is the list of source files and other main
- targets that must be combined. If source file is specified
- using relative path, it's considered to be relative to the
- source directory of the project where the path is used. See the
- project rule
- for information how to change source directory.
-
-
-
-
-
- "requirements" is the list of properties that must always
- be present when this main target is built.
-
-
-
-
-
- "default-build" is the list of properties that will be used
- unless some other value of the same feature is already
- specified.
-
-
-
-
-
- "usage-requirements" is the list of properties that will be
- propagated to all main targets that use this one, i.e. to all
- dependedents.
-
-
-
-
- Some main target rules have shorter list of parameters, and
- you should consult their documentation for details.
-
- Building of the same main target can differ greatly from
- platform to platform. For example, you might have different list
- of sources for different compilers. Therefore it is possible to
- invoke main target rules several times for a single main target.
- For example:
+
+
+
+ "main-target-name" is the name used to request the target
+ on command line and to use it from other main targets. Main
+ target name may contain alphanumeric characters and symbols '-'
+ and '_';
+
+
+
+
+
+ "sources" is the list of source files and other main
+ targets that must be combined.
+
+
+
+
+
+ "requirements" is the list of properties that must always
+ be present when this main target is built.
+
+
+
+
+
+ "default-build" is the list of properties that will be used
+ unless some other value of the same feature is already
+ specified.
+
+
+
+
+
+ "usage-requirements" is the list of properties that will be
+ propagated to all main targets that use this one, i.e. to all
+ dependedents.
+
+
+
+ Some main target rules have shorter list of parameters, and
+ you should consult their documentation for details.
+
+ The list of sources specifies what should be processed to get
+ the resulting targets. Most of the time, it's just a list of
+ files. Sometimes, you'd want to use all files with the same
+ extension as sources, in which case you can use the "glob"
+ rule. Here are two examples:
-exe a : a_gcc.cpp : <toolset>gcc ;
exe a : a.cpp ;
+exe b : [ glob *.cpp ] ;
-
+ Unless you specify a files with absolute path, the name is
+ considered relative to the source directory -- which is typically
+ the same as directory when Jamfile is located, but can be changed as
+ described here
+
+
- Each call to the 'exe' rule defines a new main target
- alternative for the main target a.
- In this case, the first alternative will be used for the
- gcc toolset, while the second alternative will
- be used in other cases. See below for
- details.
+ The list of sources can also reference other main targets. The
+ targets in the same project can be referred by using the name, and
+ targets in other project need to specify directory or a symbolic
+ name of the other project. For example:
+
+lib helper : helper.cpp ;
+exe a : a.cpp helper ;
+exe b : b.cpp ..//utils ;
+exe c : c.cpp /boost/program_options//program_opions ;
+
+ 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.
- Sometime a main target is really needed only by some other
- main target. E.g. a rule that declared test-suite uses a main
- target that represent test, but those main targets are rarely
- needed by themself.
+
- It possible to declare target inline, i.e. the "sources"
- parameter may include call to other main rules. For example:
+ Building of the same main target can differ greatly from
+ platform to platform. For example, you might have different list
+ 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. E.g. a rule that declares test-suite uses a main
+ target that represent test, but those main targets are rarely
+ needed by themself.
+
+ It possible to declare target inline, i.e. the "sources"
+ parameter may include call to other main rules. For example:
exe hello : hello.cpp
@@ -228,11 +410,11 @@ 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".
+ 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".
@@ -240,93 +422,193 @@ to build only helpers, one should run "bjam hello..helpers".
Projects
- Boost.Build considers every software it build as organized
- into projects — modules which declare targets.
- Projects are organized in a hierarchical structure, so each
- project may have a single parent project and a number of
- subprojects.
+ As mentioned before, targets are grouped into project, and each
+ Jamfile is a separate project. Projects are usefull 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.
+
- Most often, projects are created as result of loading
- Jamfile — files which are specially meant to
- describe projects. Boost.Build will implicitly load Jamfile in
- the invocation directory, and all Jamfiles referred by the first
- one, creating the hierarchy of projects.
+ The rule has this syntax
+
+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 it
+ possible to write:
+
+project tennis
+ : requirements <threading>multi
+ : default-build release
+ ;
+
+
- The exact name of file that describes project is configurable.
- By default, it's Jamfile, but can be changed by setting
- global variables JAMFILE, for example in
- boost-build.jam file. The value of the variable is a
- list of regex patterns that are used when searching for Jamfile
- in a directory.
+ The possible attributes are listed below.
- Every Boost.Build modules can decide to act as project and be
- able to declare targets. For example, the
- site-config.jam module can declare libraries
- available on a given host, as described here.
+ Project id is a short way to denote a project, as
+ opposed to the Jamfile's pathname. It is a hierarchical path,
+ unrelated to filesystem, such as "boost/thread". Target references make use of project ids to
+ specify a target.
- There are three things that can be put in Jamfile:
- declarations of main targets, calls to a number of predefined
- rules, and arbitrary user code. The predefined rules are listed
- below:
+ Source location specifies the directory where sources
+ for the project are located.
-
-
-
-
-
- Rule
+ Project requirements are requirements that apply to
+ all the targets in the projects as well as all subprojects.
- Semantic
-
-
+ Default build is the build request that should be
+ used when no build request is specified explicitly.
-
-
- project
-
+
+ The default values for those attributes are
+ given in the table below.
- Define project attributes.
-
+
+
+
+
+
+ Attribute
+
+ Name for the 'project' rule
+
+ Default value
+
+ Handling by the 'project' rule
+
+
+
+
+
+
+ Project id
+
+ none
+
+ none
+
+ Assigned from the first parameter of the 'project' rule.
+ It is assumed to denote absolute project id.
+
+
+
+ Source location
+
+ source-location
+
+ The location of jamfile for the project
+
+ Sets to the passed value
+
+
+
+ Requirements
+
+ requirements
+
+ The parent's requirements
+
+ The parent's requirements are refined with the passed
+ requirement and the result is used as the project
+ requirements.
+
+
+
+ Default build
+
+ default-build
+
+ none
+
+ Sets to the passed value
+
+
+
+ Build directory
+
+ 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
+
+ Sets to the passed value, interpreted as relative to the
+ project's location.
+
+
+
+
+
+
-
- use-project
+
+ Additional Jamfile rules
- Make another project known.
-
+ There's a number of other helper rules which can be used in
+ Jamfile, described in the following table.
-
- build-project
-
- Build another project when this one is built.
-
-
-
- explicit
-
- States that the target should be built only by explicit
- request.
-
-
-
- glob
-
- Takes a list of wildcards, and returns the list of files
- which match any of the wildcards.
-
-
-
-
-
- Each project is also associated with project root.
- That's a root for a tree of projects, which specifies some global
- properties.
-
-
+
+
+
+
+
+ Rule
+
+ Semantic
+
+
+
+
+
+ project
+
+
+ Define project attributes.
+
+
+
+ use-project
+
+ Make another project known.
+
+
+
+ build-project
+
+ Build another project when this one is built.
+
+
+
+ explicit
+
+ States that the target should be built only by explicit
+ request.
+
+
+
+ glob
+
+ Takes a list of wildcards, and returns the list of files
+ which match any of the wildcards.
+
+
+
+
+
+
+
+ Each project is also associated with project root.
+ That's a root for a tree of projects, which specifies some global
+ properties.
+
Project root
@@ -336,162 +618,42 @@ to build only helpers, one should run "bjam hello..helpers".
certain properties which apply to all projects under project
root. It can:
-
-
-
- configure toolsets, via call to toolset.using
-
-
-
-
-
- refer to other projects, via the use-project
- rule
-
-
-
-
-
- declare constants, via the constant and
- path-constant rules.
-
-
-
+
+
+
+ configure toolsets, via call to toolset.using
+
+
+
+
+
+ refer to other projects, via the use-project
+ rule
+
+
+
+
+
+ declare constants, via the constant and
+ path-constant rules.
+
+
+
- To facilitate declaration of simple projects, Jamfile and
- project-root can be merged together. To achieve this effect, the
- project root file should call the project rule. The
- semantic is precisely the same as if the call was made in
- Jamfile, except that project-root.jam will start serve as
- Jamfile. The Jamfile in the directory of project-root.jam will be
- ignored, and project-root.jam will be able to declare main
- targets as usual.
-
-
-
-
- Project attributes
-
- For each project, there are several attributes.
-
- Project id is a short way to denote a project, as
- opposed to the Jamfile's pathname. It is a hierarchical path,
- unrelated to filesystem, such as "boost/thread". Target references make use of project ids to
- specify a target.
-
- Source location specifies the directory where sources
- for the project are located.
-
- Project requirements are requirements that apply to
- all the targets in the projects as well as all subprojects.
-
- Default build is the build request that should be
- used when no build request is specified explicitly.
-
-
- The default values for those attributes are
- given in the table below. In order to affect them, Jamfile may
- call the project rule. The rule has this
- syntax:
-
-
-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 it
-possible to write:
-
-
-
-project tennis
- : requirements <threading>multi
- : default-build release
- ;
-
-
-
-
-
-
-
- Attribute
-
- Name for the 'project' rule
-
- Default value
-
- Handling by the 'project' rule
-
-
-
-
-
-
- Project id
-
- none
-
- none
-
- Assigned from the first parameter of the 'project' rule.
- It is assumed to denote absolute project id.
-
-
-
- Source location
-
- source-location
-
- The location of jamfile for the project
-
- Sets to the passed value
-
-
-
- Requirements
-
- requirements
-
- The parent's requirements
-
- The parent's requirements are refined with the passed
- requirement and the result is used as the project
- requirements.
-
-
-
- Default build
-
- default-build
-
- none
-
- Sets to the passed value
-
-
-
- Build directory
-
- 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
-
- Sets to the passed value, interpreted as relative to the
- project's location.
-
-
-
-
-
+ To facilitate declaration of simple projects, Jamfile and
+ project-root can be merged together. To achieve this effect, the
+ project root file should call the project rule. The
+ semantic is precisely the same as if the call was made in
+ Jamfile, except that project-root.jam will start serve as
+ Jamfile. The Jamfile in the directory of project-root.jam will be
+ ignored, and project-root.jam will be able to declare main
+ targets as usual.
+
+
+
-
- Target identifiers and references
-
- Target identifier is used to denote a
- target. The syntax is:
-
-
-target-id -> (project-id | target-name | file-name )
- | (project-id | directory-name) "//" target-name
-project-id -> path
-target-name -> path
-file-name -> path
-directory-name -> path
-
-
-
-This grammar allows some elements to be recognized as either
-
-
-
-
- project id (at this point, all project ids start with slash).
-
-
-
-
-
- name of target declared in current Jamfile (note that target
- names may include slash).
-
-
-
-
-
- a regular file, denoted by absolute name or name relative to
- project's sources location.
-
-
-
-
- To determine the real meaning a check is made if project-id
- by the specified name exists, and then if main target of that
- name exists. For example, valid target ids might be:
-
-
-a -- target in current project
-lib/b.cpp -- regular file
-/boost/thread -- project "/boost/thread"
-/home/ghost/build/lr_library//parser -- target in specific project
-
-
-
-
- Rationale:Target is separated from project by special
- separator (not just slash), because:
-
-
-
-
- It emphasises that projects and targets are different things.
-
-
-
-
-
- It allows to have main target names with slashes.
-
-
-
-
-
-
-
- Target reference is used to
- specify a source target, and may additionally specify desired
- properties for that target. It has this syntax:
-
-
-target-reference -> target-id [ "/" requested-properties ]
-requested-properties -> property-path
-
-
-
-For example,
-
-
-exe compiler : compiler.cpp libs/cmdline/<optimization>space ;
-
-
-would cause the version of cmdline library,
-optimized for space, to be linked in even if the
-compiler executable is build with optimization for
-speed.
-
- Builtin facilitiesMain targets
-
- exe
-
-
-
- Creates a regular executable file. Sources must be either
- object files or libraries, and sources of different types
- will be converted to accepted types automatically.
-
-
-
-
- lib
-
-
- Creates a library file. Depending on the value of
- <link> feature the library will be either static or
- shared. Like with "exe", sources will be converted either to
- objects or libraries.
-
- The handling of libraries in sources depends on whether
- linking is static or shared. For shared linking, libraries
- will be linked in. For static linking the library sources
- will not be linked in, since it's not possible, and will be
- passed on. Other main target which depend on this one will
- see those libraries and link to it. Therefore, putting
- library in sources of other library works in all cases.
-
-
-
- alias
-
-
-
- Builds all the source targets and returns them unmodified.
- Please run "bjam --help alias" for more details.
-
-
-
- stage
-
-
-
- Copies a number of targets to a single directory. The
- primary purpose is installing binaries. Please run "bjam --help
- stage" for more details.
-
-
-
- unit-test (from module "testing")
-
-
-
- Creates an executable file and runs it. Build won't succeed
- unless the executable runs successfully. The rule is usefull
- for creating test program which should be rerun whenever any
- dependency changes.
-
-
-
-
+
+ exe
+
+
+
+ Creates a regular executable file. Sources must be either
+ object files or libraries, and sources of different types
+ will be converted to accepted types automatically.
+
+
+
+
+ lib
+
+
+ Creates a library file. Depending on the value of
+ <link> feature the library will be either static or
+ shared. Like with "exe", sources will be converted either to
+ objects or libraries.
+
+ The handling of libraries in sources depends on whether
+ linking is static or shared. For shared linking, libraries
+ will be linked in. For static linking the library sources
+ will not be linked in, since it's not possible, and will be
+ passed on. Other main target which depend on this one will
+ see those libraries and link to it. Therefore, putting
+ library in sources of other library works in all cases.
+
+
+
+ alias
+
+
+
+ Builds all the source targets and returns them unmodified.
+ Please run "bjam --help alias" for more details.
+
+
+
+ stage
+
+
+
+ Copies a number of targets to a single directory. The
+ primary purpose is installing binaries. Please run "bjam --help
+ stage" for more details.
+
+
+
+ unit-test (from module "testing")
+
+
+
+ Creates an executable file and runs it. Build won't succeed
+ unless the executable runs successfully. The rule is usefull
+ for creating test program which should be rerun whenever any
+ dependency changes.
+
+
+
+
-
+
Features
-
-
- variant
-
-
-
- The feature which combines several low-level features in
- order to make building most common variants simple.
-
-
- Allowed values:debug, release,
- profile
-
- The value debug expands to
-
+
+
+ variant
+
+
+
+ The feature which combines several low-level features in
+ order to make building most common variants simple.
+
+
+ Allowed values:debug, release,
+ profile
+
+ The value debug expands to
+
<optimization>off <debug-symbols>on <inlining>off <runtime-debugging>on
-
- The value release expands to
+
+ The value release expands to
<optimization>speed <debug-symbols>off <inlining>full <runtime-debugging>off
- The value profile expands to the same as
- release, plus:
+ The value profile expands to the same as
+ release, plus:
<profiling>on <debug-symbols>on
+
+ Rationale: Runtime debugging is on in debug build
+ so suit expectations of people used various IDEs. It's
+ assumed other folks don't have any specific expectation in
+ this point.
+
+
+
+ link
+
+
+
+ Feature which controls how libraries are built.
+
- Rationale: Runtime debugging is on in debug build
- so suit expectations of people used various IDEs. It's
- assumed other folks don't have any specific expectation in
- this point.
-
-
- link
-
-
-
- Feature which controls how libraries are built.
-
-
- Allowed values:shared,
- static
-
-
- source
-
-
-
- Tthe <source>X feature has the same effect on building a target
- as putting X in the list of sources. The feature
- is sometimes more convenient: you can put <source>X in
- the requirements for a project and it will be linked to all
- executables.
-
-
-
-
- library
-
-
-
- This feature is equivalent to the <source> feature, and exists
- for backward compatibility reasons.
-
-
-
-
-
- use
-
-
-
- Causes the target referenced by the value of this feature
- to be constructed and adds it's usage requirements to build
- properties. The constructed targets are not used in any other
- way. The primary use case is when you use some library and want
- it's usage requirements (such as include paths) to be applied,
- but don't want to link to the library.
-
-
-
-
- dll-path
-
-
-
- Specify a path where dynamic libraries should be found at
- where executable or shared library is run. This feature
- directly affects binaries with the gcc compiler, allowing them
- to pick specific libraries, and ignoring all environment
- settings. On other toolsets, the binary still requires proper
- environment settings to be run. However, Boost.Build tools
- which run executables will notice dll-path settings and create
- this environment automatically.
-
-
-
- hardcode-dll-paths
-
-
-
- Controls automatic generation of dll-path properties.
-
-
- Allowed values:off, on When this
- property is on, usage requirements for each library will
- include additional dll-path propertry, with the path the the
- generated library file. This allows to run executables
- without placing all the dependent libraries to a single
- location.
-
-
-
+ Allowed values:shared,
+ static
+
+
+ source
+
+
+
+ Tthe <source>X feature has the same effect on building a target
+ as putting X in the list of sources. The feature
+ is sometimes more convenient: you can put <source>X in
+ the requirements for a project and it will be linked to all
+ executables.
+
+
+
+
+ library
+
+
+
+ This feature is equivalent to the <source> feature, and exists
+ for backward compatibility reasons.
+
+
+
+
+
+ use
+
+
+
+ Causes the target referenced by the value of this feature
+ to be constructed and adds it's usage requirements to build
+ properties. The constructed targets are not used in any other
+ way. The primary use case is when you use some library and want
+ it's usage requirements (such as include paths) to be applied,
+ but don't want to link to the library.
+
+
+
+
+ dll-path
+
+
+
+ Specify a path where dynamic libraries should be found at
+ where executable or shared library is run. This feature
+ directly affects binaries with the gcc compiler, allowing them
+ to pick specific libraries, and ignoring all environment
+ settings. On other toolsets, the binary still requires proper
+ environment settings to be run. However, Boost.Build tools
+ which run executables will notice dll-path settings and create
+ this environment automatically.
+
+
+
+ hardcode-dll-paths
+
+
+
+ Controls automatic generation of dll-path properties.
+
+
+ Allowed values:off, on When this
+ property is on, usage requirements for each library will
+ include additional dll-path propertry, with the path the the
+ generated library file. This allows to run executables
+ without placing all the dependent libraries to a single
+ location.
+
+
+
+
+
+
+
+ Build process
+
+ This section will describe two things: how you specify what to build,
+ and how the main targets are actually build.
+
+
+
+ The command line specifies which targets to built and which what
+ properties. For example:
+
+bjam app1 lib1//lib1 toolset=gcc variant=debug optimization=full
+
+ would build two targets, "app1" and "lib1//lib1" with the specified
+ properties. You can refer to any targets, using
+ target id and specify arbitrary
+ properties. Some of the properties are very common, and for them the name
+ of the property can be omitted. For example, the above can be written as:
+
+bjam app1 lib1//lib1 gcc debug optimization=full
+
+ The complete syntax which had some additional shortcuts if described here.
+
+
+
+
+
+ Differences to Boost.Build V1
+
+ While Boost.Build V2 is based on the same ideas as Boost.Build V1,
+ some of the syntax was changed, and some new important features were
+ added. This chapter describes most of the changes.
+
+
+ Configuration
+
+ In V1, there were two methods to configure a toolset. One is to
+ set some environment variable, or use "-s" command line option to set
+ variable inside BJam. Another method was creating new toolset module,
+ which would set the variables and then invoke basic toolset. Neither
+ method is necessary now, the "using" rule provides a consistent way to
+ initialize toolset, including several versions. See section on configuraton for
+ details.
+
+
+
+
+
+ Writing Jamfiles
+
+ Probably one of the most important differences in V2 Jamfiles is
+ the project requirements. In V1, if several targets have the same
+ requirements (for example, common include path), it was necessary to
+ manually write that requirements, or use a helper rule. In V2, the
+ common properties can be specified with the "requirements" project
+ attribute, as documented here.
+
+
+ The usage requirements
+ is also important mechanism to simplify Jamfile. If a library requires
+ all clients to use specific includes, or macroses when compiling the
+ code which depends on the library, this information can be cleanly
+ represented.
+
+ The difference between "lib" and "dll" targets in V1 is completely
+ eliminated in V2. There's only one target -- "lib", which can create
+ either static or shared library depending on the value of the
+ <link>
+ feature. If your target should be only build in one variant, you
+ can add <link>shared or <link>static to requirements.
+
+
+ The syntax for referring to other targets was changed a bit. While
+ in V1 one would use:
+
+exe a : a.cpp <lib>../foo/bar ;
+
+ the V2 syntax is:
+
+exe a : a.cpp ../foo//bar ;
+
+ Note that you don't need to specify the type of other target, but the
+ last element should be separated to double slash, to indicate that
+ you're referring to target "bar" in project "../foo", and not to
+ project "../foo/bar".
+
+
+
+
+
+
+ Build process
+
+ The command line syntax in V2 is completely different. For example
+
+bjam -sTOOLS=msvc -sBUILD=release some_target
+
+ now becomes:
+
+bjam toolset=msvc variant=release some_target
+
+ or, using shortcuts, just:
+
+bjam msvc release some_target
+
+ See the reference for
+ complete description of the syntax.
+
+
+
+
+
+
+
+
diff --git a/v2/doc/src/extending.xml b/v2/doc/src/extending.xml
index eff223486..1f9b5d25c 100644
--- a/v2/doc/src/extending.xml
+++ b/v2/doc/src/extending.xml
@@ -105,24 +105,86 @@ and linked it.
"../../example/customization">example/customization
directory.
-
-
- Target types
+
+
+ Target types
+
+
+
+
+ Tools
-
+
+
+
+ Main target rules
+
+ The main target rule is what creates a top-level target, for example "exe" or
+ "lib". It's quite likely that's you'll want to declare your own and
+ there are as much as three way to do that.
+
+
+ The first is the simplest, but is sufficient in a number of
+ case. Just write a wrapper rule, which will redirect to any of existing
+ rules. For example, you have only one library per directory and want all
+ cpp files in the directory to be compiled. You can achieve this effect
+ with:
+
+lib codegen : [ glob *.cpp ] ;
+
+ but what if you want to make it even simple. Then, you add the following
+ definition to the project-root.jam file:
+
+rule glib ( name : extra-sources * : requirements * )
+{
+ lib $(name) : [ glob *.cpp ] $(extra-sources) : $(requirements) ;
+}
+
+which would allow to reduce Jamfile to
+
+glib codegen ;
+
+
-
- Tools
-
-
+ The second approach is suitable when your target rule should just
+ produce a target of specific type. Then, when declaring a type you
+ should tell Boost.Build that a main target rule should be created.
+ For example, if you create a module "obfuscate.jam" containing:
-
- Main target rules
-
-
+
+import type ;
+type.register OBFUSCATED_CPP : ocpp : : main ;
+
+import generators ;
+generators.register-standard obfuscate.file : CPP : OBFUSCATED_CPP ;
+
+ and import that module, you'll be able to use the rule "obfuscated-cpp"
+ in Jamfiles, which will convert source to the OBFUSCATED_CPP type.
+
+
+
+ The remaining method is to declared your own main target class. The
+ simplest example of this can be found in "build/alias.jam" file. The
+ current V2 uses this method when transformations are relatively
+ complex. However, we might deprecate this approach. If you find that you
+ need to use it (that is, the first two approaches are not sufficient),
+ please let us know by posting to the mailing list.
+
+
+
+ Scanners
+
+
diff --git a/v2/doc/src/reference.xml b/v2/doc/src/reference.xml
index 400cdbac5..b9e0fa210 100644
--- a/v2/doc/src/reference.xml
+++ b/v2/doc/src/reference.xml
@@ -484,7 +484,7 @@ Boost.Build comes with default versions of those files,
symbol is either a value of an implicit feature, or target to
be built. It is taken to be value of a feature if appropriate
feature exists. Otherwise, it is considered a target id. Special target name "clean"
+ "bbv2.reference.ids">target id. Special target name "clean"
has the same effect as "--clean" option.
@@ -631,6 +631,118 @@ linked binaries would be created.
Build request
+
+ Target identifiers and references
+
+ Target identifier is used to denote a
+ target. The syntax is:
+
+
+target-id -> (project-id | target-name | file-name )
+ | (project-id | directory-name) "//" target-name
+project-id -> path
+target-name -> path
+file-name -> path
+directory-name -> path
+
+
+
+This grammar allows some elements to be recognized as either
+
+
+
+
+ project id (at this point, all project ids start with slash).
+
+
+
+
+
+ name of target declared in current Jamfile (note that target
+ names may include slash).
+
+
+
+
+
+ a regular file, denoted by absolute name or name relative to
+ project's sources location.
+
+
+
+
+ To determine the real meaning a check is made if project-id
+ by the specified name exists, and then if main target of that
+ name exists. For example, valid target ids might be:
+
+
+a -- target in current project
+lib/b.cpp -- regular file
+/boost/thread -- project "/boost/thread"
+/home/ghost/build/lr_library//parser -- target in specific project
+
+
+
+
+ Rationale:Target is separated from project by special
+ separator (not just slash), because:
+
+
+
+
+ It emphasises that projects and targets are different things.
+
+
+
+
+
+ It allows to have main target names with slashes.
+
+
+
+
+
+
+
+ Target reference is used to
+ specify a source target, and may additionally specify desired
+ properties for that target. It has this syntax:
+
+
+target-reference -> target-id [ "/" requested-properties ]
+requested-properties -> property-path
+
+
+
+For example,
+
+
+exe compiler : compiler.cpp libs/cmdline/<optimization>space ;
+
+
+would cause the version of cmdline library,
+optimized for space, to be linked in even if the
+compiler executable is build with optimization for
+speed.
+
+
+