This is preliminary version intended to document + everything implemeneted but not yet ready for any practical use.
+Boost.Build extends Jam's command line in two ways. First, command + line arguments can be used not only to specify targets to build, but also + to specify build variants or arbitrary build request. Second, there are + additional command line options.
+ ++ <feature-name>=<feature-value>[","<feature-value>]* + ++ For each specified value, a propertry with that value and the + specified feature name is added to the set. +
+ target1 debug gcc/runtime-link=dynamic,static + ++ would cause target called target1 to be rebuild in debug mode, + except that for gcc, both dynamically and statically linked binaries + would be created. + +
TODO: should allow
++ target1 debug gcc,borland/runtime-link=static + ++ to work. + +
All of the Boost.Build options start with the "--" prefix. They are + described in the following table.
+ +| Option | + +Description | +
|---|---|
| --debug | + +Enables internal checks. | +
| --dump-projects | + +Cause the project structure to be output. | +
Boost.Build considers every software it build as organized into + projects, which corresponds to a single Jamfile. The project are + organized in a hierarchical structure, so for each project we can talk + about parent project, which is always unique and a number of subprojects. + (TODO: project root).
+ +For each project, there are several attributes.
+ +Project id is used to denote the project from other project. + Each project id is a hierarchical path, such as "boost/thread". When + project-id need to be referred from other projects there are two + alternatives:
+ +Source location specifies 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 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 | + +TODO | + +Sets to the passed value | +
There are two 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 ; + ++ +
Target identifier is used to denote a target.
+ +Target reference is used to refer to a target, and may additionally + specify desired properties for that target.
+ +Simplified target reference has the same form as pathname, for example + lib/a. In order to determine if this is target reference or + pathname, it is checked if there's a jamfile in the specified path. If + there is one, it is loaded and if the specified target is declared by + that project it is used. Otherwise, we just treat the target reference as + file name.
+ +The build works in this way. On startup, the project in the current + directory is read. As the result a tree of projects is constructed. After + that, the build request is constructed from the command line. Then, the + steps are:
+ +The dependency graph constructed for each target is build of so called + "virtual targets", which do not yet correspond to jam's targets. It is + therefore converted to jam's dependency graph which is then build.
+ +The paths for build targets are determined with a method having two + properties. First, non-free features are represented in path. Second, + free features are not represented in path (because that would make them + overly long), but two targets with different free features are never + mixed. Each project has a base directory for all its target.
+ +Path for each target is relative to the base and has two components. + The first component represents all non-free features used to build the + target. If the set of free properties used to build the target is equal + to the set of free properties in the project's requirements, then the + second component is empty. Otherwise, the second part has the form + "main_target-<name>", where "name" is the name of main target which + build required the current target.
+ +For example, we might have these paths:
++ debug/optimization-off + debug/main-target-a + ++
Last modified: July 7, 2002
+ +© Copyright Vladimir Prus 2002. Permission to copy, use, modify, + sell and distribute this document is granted provided this copyright + notice appears in all copies. This document is provided ``as is'' without + express or implied warranty, and with no claim as to its suitability for + any purpose.
+ + +