@@ -138,12 +178,12 @@
bjam there. A simple application will be built. You can also
play with other projects in examples-v2.
+ it somewhere.
+
+
It is slighly better way is to copy new/user-config.jam
+ into one of the locations where it can be found (given in this table). This prevent you from
+ accidentally overwriting your config when updating.
-->
@@ -638,8 +678,407 @@ boost-build /path/to/boost.build ;
date. At this step, implicit dependencies are also scanned and accounted
for, as described here.
+
Main targets
+
+
Main 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 rules. The user can also declare custom main target rules.
+
+
Most main targets rules in Boost.Build use similiar syntax:
"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.
+
+
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:
+
+ exe a : a_gcc.cpp : <toolset> ;
+ exe a : a.cpp ;
+
+ 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. TODO: document the exact
+ selection method under "Build process" below.
+
+
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:
+ 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".
+
+
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.
+
+
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 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.
+
+
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.
+
+
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:
States that the target should be built only by explicit
+ request.
+
+
+
+
Each project is also associated with project root. That's a
+ root for a tree of projects, which specifies some global properties.
+
+
Project root
+ Project root for a projects is the nearest parent directory which
+ contains a file called project-root.jam. That file defines
+ 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.
+
+
+
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:
+
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.
+
+
+
+
Project relationship
+
+
There are three kinds of project relationships.
+
+
First is parent-child. This relationship is established implicitly:
+ parent directories of a project are searched, and the first found Jamfile
+ is assumed to define the parent project. The parent-child relationship
+ affects only attribute values for the child project.
+
+
Second is build relationship. Some project may
+ request to recursively build other projects. Those project need not be
+ child projects. The build-project rule is used for that:
+
+ build-project src ;
+
+
+
The third kind is the 'use' relationship. In
+ means that one project uses targets from another. It is possible to just
+ refer to target in other projects using target id. However, if target id
+ uses project id, it is required that the project id is known. The
+ use-project rule is employed to guarantee that.
+
+ use-project ( id : location )
+
+
+ It loads the project at the specified location, which makes its project
+ id available in the project which invokes the rule. It is required that
+ the id parameter passed to the use-project rule be
+ equal to the id that the loaded project declared. At this moment, the
+ id paremeter should be absolute project id.
+
+
Target identifiers and references
+
+
Target identifier is used to denote a target. There are two
+ syntaxes for it. First is the preferred one, described below. The second
+ is older syntax, which is retained to backward compatibility reasons, but
+ will be removed in a future release. It is not documented
+ 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:
+ 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 facilities
+
Main targets
+
+
+
exe
+
+
Creates a regular executable file.
+
+
lib
+
+
Creates a library file. Depending on the value of <link>
+ feature the library will be either static or shared.
+
+
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.
+
+
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.
-
-
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 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.
-
-
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.
-
-
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:
States that the target should be built only by explicit
- request.
-
-
-
-
Each project is also associated with project root. That's a
- root for a tree of projects, which specifies some global properties.
-
-
Project root
- Project root for a projects is the nearest parent directory which
- contains a file called project-root.jam. That file defines
- 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.
-
-
-
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:
-
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.
-
-
-
-
Project relationship
-
-
There are three kinds of project relationships.
-
-
First is parent-child. This relationship is established implicitly:
- parent directories of a project are searched, and the first found Jamfile
- is assumed to define the parent project. The parent-child relationship
- affects only attribute values for the child project.
-
-
Second is build relationship. Some project may
- request to recursively build other projects. Those project need not be
- child projects. The build-project rule is used for that:
-
- build-project src ;
-
-
-
The third kind is the 'use' relationship. In
- means that one project uses targets from another. It is possible to just
- refer to target in other projects using target id. However, if target id
- uses project id, it is required that the project id is known. The
- use-project rule is employed to guarantee that.
-
- use-project ( id : location )
-
-
- It loads the project at the specified location, which makes its project
- id available in the project which invokes the rule. It is required that
- the id parameter passed to the use-project rule be
- equal to the id that the loaded project declared. At this moment, the
- id paremeter should be absolute project id.
-
-
There are two user-visible kinds of targets in Boost.Build. First are
- "abstract" — they correspond to things declared by user, for
- example, projects and executable files. The primary thing about abstract
- target is that it's possible to request them to be build with a
- particular values of some properties. Each combination of properties may
- possible yield different set of real file, so abstract target do not have
- a direct correspondence with files.
-
-
File targets, on the contary, are associated with concrete files.
- Dependency graphs for abstract targets with specific properties are
- constructed from file targets. User has no was to create file targets,
- however it can specify rules that detect file type for sources, and also
- rules for transforming between file targets of different types. That
- information is used in constructing dependency graph, as desribed in the
- next section. Note:File targets are not
- the same as targets in Jam sense; the latter are created from file
- targets at the latest possible moment. Note:"File target" is a
- proposed name for what we call virtual targets. It it more understandable
- by users, but has one problem: virtual targets can potentially be
- "phony", and not correspond to any file.
-
-
Main targets and main target alternatives
-
-
Main target is a named entity which can be
- build, for example a named executable file. To declare a main target,
- user invokes some of the main target
- rules, passing it things like list of sources and requirements.
-
-
It is possible to have different list of sources for different
- toolsets, therefore it is possible to invoke main target rules several
- times for a single main target. For example:
-
- exe a : a_gcc.cpp : <toolset> ;
- exe a : a.cpp ;
-
- Each call to the 'exe' rule defines a new main target
- alternative for the main target a.exe. In this case, the
- first alternative will be used for the gcc toolset, while the
- second alternative will be used in other cases. TODO: document the exact
- selection method under "Build process" below.
-
-
Target identifiers and references
-
-
Target identifier is used to denote a target. There are two
- syntaxes for it. First is the preferred one, described below. The second
- is older syntax, which is retained to backward compatibility reasons, but
- will be removed in a future release. It is not documented
- 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:
- 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.
-
-
File targets
- As described above, file targets corresponds to files that Boost.Build
- manages. User's may be concerned about file targets in three ways: when
- declaring file target types, when declaring transformations between
- types, and when determining where file target will be placed. File
- targets can also be connected with actions, that determine how the target
- is created. Both file targets and actions are implemented in the
- virtual-target module.
-
-
Types
- A file target can be given a file, which determines what transformations
- can be applied to the file. The type.register rule declares new
- types. File type can also be assigned a scanner, which is used to find
- implicit dependencies. See dependency
- scanning below.
-
-
Target paths
-
-
To distinguish targets build with different properties, they are put
- in different directories. Rules for determining target paths are given
- below:
-
-
-
All targets are placed under directory corresponding to the project
- where they are defined.
-
-
Each non free, non incidental property cause an additional element
- to be added to the target path. That element has the form
- <feature-name>-<feature-value> for ordinary
- features and <feature-value> for implicit ones. [Note
- about composite features].
-
-
If the set of free, non incidental properties is different from the
- set of free, non incidental properties for the project in which the
- main target that uses the target is defined, a part of the form
- main_target-<name> is added to the target path.
- Note:It would be nice to completely track free features also,
- but this appears to be complex and not extremely needed.
There are two user-visible kinds of targets in Boost.Build. First are
+ "abstract" — they correspond to things declared by user, for
+ example, projects and executable files. The primary thing about abstract
+ target is that it's possible to request them to be build with a
+ particular values of some properties. Each combination of properties may
+ possible yield different set of real file, so abstract target do not have
+ a direct correspondence with files.
+
+
File targets, on the contary, are associated with concrete files.
+ Dependency graphs for abstract targets with specific properties are
+ constructed from file targets. User has no was to create file targets,
+ however it can specify rules that detect file type for sources, and also
+ rules for transforming between file targets of different types. That
+ information is used in constructing dependency graph, as desribed in the
+ next section. Note:File targets are not
+ the same as targets in Jam sense; the latter are created from file
+ targets at the latest possible moment. Note:"File target" is a
+ proposed name for what we call virtual targets. It it more understandable
+ by users, but has one problem: virtual targets can potentially be
+ "phony", and not correspond to any file.
+
Dependency scanning
Dependency scanning is the process of finding implicit dependencies
@@ -208,6 +236,58 @@
bound via LOCATE_TARGET to "build" and we'll call INCLUDE on that found
target, instread of creating a completely unrelated one.
+
+
+ The remainder of this document is not indended to be read at all. This
+ will be rearranged in future.
+
+
+
File targets
+ As described above, file targets corresponds to files that Boost.Build
+ manages. User's may be concerned about file targets in three ways: when
+ declaring file target types, when declaring transformations between
+ types, and when determining where file target will be placed. File
+ targets can also be connected with actions, that determine how the target
+ is created. Both file targets and actions are implemented in the
+ virtual-target module.
+
+
Types
+ A file target can be given a file, which determines what transformations
+ can be applied to the file. The type.register rule declares new
+ types. File type can also be assigned a scanner, which is used to find
+ implicit dependencies. See dependency
+ scanning below.
+
+
Target paths
+
+
To distinguish targets build with different properties, they are put
+ in different directories. Rules for determining target paths are given
+ below:
+
+
+
All targets are placed under directory corresponding to the project
+ where they are defined.
+
+
Each non free, non incidental property cause an additional element
+ to be added to the target path. That element has the form
+ <feature-name>-<feature-value> for ordinary
+ features and <feature-value> for implicit ones. [Note
+ about composite features].
+
+
If the set of free, non incidental properties is different from the
+ set of free, non incidental properties for the project in which the
+ main target that uses the target is defined, a part of the form
+ main_target-<name> is added to the target path.
+ Note:It would be nice to completely track free features also,
+ but this appears to be complex and not extremely needed.
This document explains how to extend Boost.Build to accomodate your
+ local requirements. Let's start with quite simple, but realistic
+ example.
+
+
Say you're writing an application which generates C++ code. If you
+ ever did this, you know that it's not nice. Embedding large portions of
+ C++ code in string literals is very awkward. A much better solution
+ is:
+
+
+
Write the template of the code to be generated, leaving
+ placeholders at the points which will change
+
+
Access the template in your application and replace placeholders
+ with appropriate text.
+
+
Write the result.
+
+
+
It's quite easy to archive. You write special verbatim files, which
+ are just C++, except that the very first line of the file gives a name of
+ variable that should be generated. A simple tool is created which takes
+ verbatim file and creates a cpp file with a single char* variable, which
+ name is taken from the first line of verbatim file, and which value is
+ properly quoted content of the verbatim file.
+
+
Let's see what Boost.Build can do.
+
+
First off, Boost.Build has no idea about "verbatim files". So, you
+ must register a new type. The following code does it:
The first parameter to 'type.register' gives the name of declared
+ type. By convention, it's uppercase. The second parameter is suffix for
+ this type. So, if Boost.Build sees "code.verbatim" in the list of
+ sources, it knows that it's of type VERBATIM.
+
+
Lastly, you need to tool to convert verbatim files to C++. Say you've
+ stetched such a tool in Python. Then, you have to inform Boost.Build
+ about the tool. The Boost.Build concept which represent tool is
+ generator.
+
+
First, you say that generator 'inline-file' is able to convert
+ VERBATIM type into C++:
Now, we're ready to tie it all together. Put all the code above in
+ file "verbatim.jam", add "import verbatim ;" to "project-root.jam", and
+ it's possible to write the following in Jamfile:
@@ -138,12 +178,12 @@
bjam there. A simple application will be built. You can also
play with other projects in examples-v2.
+ it somewhere.
+
+
It is slighly better way is to copy new/user-config.jam
+ into one of the locations where it can be found (given in this table). This prevent you from
+ accidentally overwriting your config when updating.
-->
@@ -638,8 +678,407 @@ boost-build /path/to/boost.build ;
date. At this step, implicit dependencies are also scanned and accounted
for, as described here.
+
Main targets
+
+
Main 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 rules. The user can also declare custom main target rules.
+
+
Most main targets rules in Boost.Build use similiar syntax:
"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.
+
+
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:
+
+ exe a : a_gcc.cpp : <toolset> ;
+ exe a : a.cpp ;
+
+ 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. TODO: document the exact
+ selection method under "Build process" below.
+
+
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:
+ 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".
+
+
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.
+
+
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 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.
+
+
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.
+
+
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:
States that the target should be built only by explicit
+ request.
+
+
+
+
Each project is also associated with project root. That's a
+ root for a tree of projects, which specifies some global properties.
+
+
Project root
+ Project root for a projects is the nearest parent directory which
+ contains a file called project-root.jam. That file defines
+ 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.
+
+
+
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:
+
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.
+
+
+
+
Project relationship
+
+
There are three kinds of project relationships.
+
+
First is parent-child. This relationship is established implicitly:
+ parent directories of a project are searched, and the first found Jamfile
+ is assumed to define the parent project. The parent-child relationship
+ affects only attribute values for the child project.
+
+
Second is build relationship. Some project may
+ request to recursively build other projects. Those project need not be
+ child projects. The build-project rule is used for that:
+
+ build-project src ;
+
+
+
The third kind is the 'use' relationship. In
+ means that one project uses targets from another. It is possible to just
+ refer to target in other projects using target id. However, if target id
+ uses project id, it is required that the project id is known. The
+ use-project rule is employed to guarantee that.
+
+ use-project ( id : location )
+
+
+ It loads the project at the specified location, which makes its project
+ id available in the project which invokes the rule. It is required that
+ the id parameter passed to the use-project rule be
+ equal to the id that the loaded project declared. At this moment, the
+ id paremeter should be absolute project id.
+
+
Target identifiers and references
+
+
Target identifier is used to denote a target. There are two
+ syntaxes for it. First is the preferred one, described below. The second
+ is older syntax, which is retained to backward compatibility reasons, but
+ will be removed in a future release. It is not documented
+ 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:
+ 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 facilities
+
Main targets
+
+
+
exe
+
+
Creates a regular executable file.
+
+
lib
+
+
Creates a library file. Depending on the value of <link>
+ feature the library will be either static or shared.
+
+
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.
+
+
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.
-
-
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 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.
-
-
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.
-
-
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:
States that the target should be built only by explicit
- request.
-
-
-
-
Each project is also associated with project root. That's a
- root for a tree of projects, which specifies some global properties.
-
-
Project root
- Project root for a projects is the nearest parent directory which
- contains a file called project-root.jam. That file defines
- 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.
-
-
-
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:
-
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.
-
-
-
-
Project relationship
-
-
There are three kinds of project relationships.
-
-
First is parent-child. This relationship is established implicitly:
- parent directories of a project are searched, and the first found Jamfile
- is assumed to define the parent project. The parent-child relationship
- affects only attribute values for the child project.
-
-
Second is build relationship. Some project may
- request to recursively build other projects. Those project need not be
- child projects. The build-project rule is used for that:
-
- build-project src ;
-
-
-
The third kind is the 'use' relationship. In
- means that one project uses targets from another. It is possible to just
- refer to target in other projects using target id. However, if target id
- uses project id, it is required that the project id is known. The
- use-project rule is employed to guarantee that.
-
- use-project ( id : location )
-
-
- It loads the project at the specified location, which makes its project
- id available in the project which invokes the rule. It is required that
- the id parameter passed to the use-project rule be
- equal to the id that the loaded project declared. At this moment, the
- id paremeter should be absolute project id.
-
-
There are two user-visible kinds of targets in Boost.Build. First are
- "abstract" — they correspond to things declared by user, for
- example, projects and executable files. The primary thing about abstract
- target is that it's possible to request them to be build with a
- particular values of some properties. Each combination of properties may
- possible yield different set of real file, so abstract target do not have
- a direct correspondence with files.
-
-
File targets, on the contary, are associated with concrete files.
- Dependency graphs for abstract targets with specific properties are
- constructed from file targets. User has no was to create file targets,
- however it can specify rules that detect file type for sources, and also
- rules for transforming between file targets of different types. That
- information is used in constructing dependency graph, as desribed in the
- next section. Note:File targets are not
- the same as targets in Jam sense; the latter are created from file
- targets at the latest possible moment. Note:"File target" is a
- proposed name for what we call virtual targets. It it more understandable
- by users, but has one problem: virtual targets can potentially be
- "phony", and not correspond to any file.
-
-
Main targets and main target alternatives
-
-
Main target is a named entity which can be
- build, for example a named executable file. To declare a main target,
- user invokes some of the main target
- rules, passing it things like list of sources and requirements.
-
-
It is possible to have different list of sources for different
- toolsets, therefore it is possible to invoke main target rules several
- times for a single main target. For example:
-
- exe a : a_gcc.cpp : <toolset> ;
- exe a : a.cpp ;
-
- Each call to the 'exe' rule defines a new main target
- alternative for the main target a.exe. In this case, the
- first alternative will be used for the gcc toolset, while the
- second alternative will be used in other cases. TODO: document the exact
- selection method under "Build process" below.
-
-
Target identifiers and references
-
-
Target identifier is used to denote a target. There are two
- syntaxes for it. First is the preferred one, described below. The second
- is older syntax, which is retained to backward compatibility reasons, but
- will be removed in a future release. It is not documented
- 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:
- 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.
-
-
File targets
- As described above, file targets corresponds to files that Boost.Build
- manages. User's may be concerned about file targets in three ways: when
- declaring file target types, when declaring transformations between
- types, and when determining where file target will be placed. File
- targets can also be connected with actions, that determine how the target
- is created. Both file targets and actions are implemented in the
- virtual-target module.
-
-
Types
- A file target can be given a file, which determines what transformations
- can be applied to the file. The type.register rule declares new
- types. File type can also be assigned a scanner, which is used to find
- implicit dependencies. See dependency
- scanning below.
-
-
Target paths
-
-
To distinguish targets build with different properties, they are put
- in different directories. Rules for determining target paths are given
- below:
-
-
-
All targets are placed under directory corresponding to the project
- where they are defined.
-
-
Each non free, non incidental property cause an additional element
- to be added to the target path. That element has the form
- <feature-name>-<feature-value> for ordinary
- features and <feature-value> for implicit ones. [Note
- about composite features].
-
-
If the set of free, non incidental properties is different from the
- set of free, non incidental properties for the project in which the
- main target that uses the target is defined, a part of the form
- main_target-<name> is added to the target path.
- Note:It would be nice to completely track free features also,
- but this appears to be complex and not extremely needed.
There are two user-visible kinds of targets in Boost.Build. First are
+ "abstract" — they correspond to things declared by user, for
+ example, projects and executable files. The primary thing about abstract
+ target is that it's possible to request them to be build with a
+ particular values of some properties. Each combination of properties may
+ possible yield different set of real file, so abstract target do not have
+ a direct correspondence with files.
+
+
File targets, on the contary, are associated with concrete files.
+ Dependency graphs for abstract targets with specific properties are
+ constructed from file targets. User has no was to create file targets,
+ however it can specify rules that detect file type for sources, and also
+ rules for transforming between file targets of different types. That
+ information is used in constructing dependency graph, as desribed in the
+ next section. Note:File targets are not
+ the same as targets in Jam sense; the latter are created from file
+ targets at the latest possible moment. Note:"File target" is a
+ proposed name for what we call virtual targets. It it more understandable
+ by users, but has one problem: virtual targets can potentially be
+ "phony", and not correspond to any file.
+
Dependency scanning
Dependency scanning is the process of finding implicit dependencies
@@ -208,6 +236,58 @@
bound via LOCATE_TARGET to "build" and we'll call INCLUDE on that found
target, instread of creating a completely unrelated one.
+
+
+ The remainder of this document is not indended to be read at all. This
+ will be rearranged in future.
+
+
+
File targets
+ As described above, file targets corresponds to files that Boost.Build
+ manages. User's may be concerned about file targets in three ways: when
+ declaring file target types, when declaring transformations between
+ types, and when determining where file target will be placed. File
+ targets can also be connected with actions, that determine how the target
+ is created. Both file targets and actions are implemented in the
+ virtual-target module.
+
+
Types
+ A file target can be given a file, which determines what transformations
+ can be applied to the file. The type.register rule declares new
+ types. File type can also be assigned a scanner, which is used to find
+ implicit dependencies. See dependency
+ scanning below.
+
+
Target paths
+
+
To distinguish targets build with different properties, they are put
+ in different directories. Rules for determining target paths are given
+ below:
+
+
+
All targets are placed under directory corresponding to the project
+ where they are defined.
+
+
Each non free, non incidental property cause an additional element
+ to be added to the target path. That element has the form
+ <feature-name>-<feature-value> for ordinary
+ features and <feature-value> for implicit ones. [Note
+ about composite features].
+
+
If the set of free, non incidental properties is different from the
+ set of free, non incidental properties for the project in which the
+ main target that uses the target is defined, a part of the form
+ main_target-<name> is added to the target path.
+ Note:It would be nice to completely track free features also,
+ but this appears to be complex and not extremely needed.
This document explains how to extend Boost.Build to accomodate your
+ local requirements. Let's start with quite simple, but realistic
+ example.
+
+
Say you're writing an application which generates C++ code. If you
+ ever did this, you know that it's not nice. Embedding large portions of
+ C++ code in string literals is very awkward. A much better solution
+ is:
+
+
+
Write the template of the code to be generated, leaving
+ placeholders at the points which will change
+
+
Access the template in your application and replace placeholders
+ with appropriate text.
+
+
Write the result.
+
+
+
It's quite easy to archive. You write special verbatim files, which
+ are just C++, except that the very first line of the file gives a name of
+ variable that should be generated. A simple tool is created which takes
+ verbatim file and creates a cpp file with a single char* variable, which
+ name is taken from the first line of verbatim file, and which value is
+ properly quoted content of the verbatim file.
+
+
Let's see what Boost.Build can do.
+
+
First off, Boost.Build has no idea about "verbatim files". So, you
+ must register a new type. The following code does it:
The first parameter to 'type.register' gives the name of declared
+ type. By convention, it's uppercase. The second parameter is suffix for
+ this type. So, if Boost.Build sees "code.verbatim" in the list of
+ sources, it knows that it's of type VERBATIM.
+
+
Lastly, you need to tool to convert verbatim files to C++. Say you've
+ stetched such a tool in Python. Then, you have to inform Boost.Build
+ about the tool. The Boost.Build concept which represent tool is
+ generator.
+
+
First, you say that generator 'inline-file' is able to convert
+ VERBATIM type into C++:
Now, we're ready to tie it all together. Put all the code above in
+ file "verbatim.jam", add "import verbatim ;" to "project-root.jam", and
+ it's possible to write the following in Jamfile:
-
-