From e1146755be9e231c1957d8bffbad8ce80eca46ee Mon Sep 17 00:00:00 2001 From: Vladimir Prus Date: Mon, 8 Jul 2002 11:12:32 +0000 Subject: [PATCH] Beginnings of a user manual. [SVN r14346] --- boost_build_v2.html | 380 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 380 insertions(+) create mode 100644 boost_build_v2.html diff --git a/boost_build_v2.html b/boost_build_v2.html new file mode 100644 index 000000000..557045981 --- /dev/null +++ b/boost_build_v2.html @@ -0,0 +1,380 @@ + + + + + + + + + Boost.Build v2 user manual + + + + +

+ +

Boost.Build v2 user manual
+

+
+ +

This is preliminary version intended to document + everything implemeneted but not yet ready for any practical use.

+
+ +
+
Reference documentation
+ +
+
+
Features and properties
+ +
Initialization
+ +
Command line
+ +
Projects
+ +
Targets
+ +
Build process
+
+
+
+
+ +

Reference

+ +

Features and properties

+ +

Definition

+ +

Link compatible and imcompatible properties

+ +

Definition of property refinement

+ +

Initialization

+ +

Command line

+ +

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.

+ +

Command line arguments

+ Command line arguments specify targets and build request using the + following rules. + + + For example, the command line +
+    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. + +

Command line options

+ +

All of the Boost.Build options start with the "--" prefix. They are + described in the following table.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
+ Command line options +
OptionDescription
--debugEnables internal checks.
--dump-projectsCause the project structure to be output.
+ +

Projects

+ +

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).

+ +

Project attributes

+ +

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
+        ;
+   
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeName for the 'project' ruleDefault valueHandling by the 'project' rule
Project idnonenoneAssigned from the first parameter of the 'project' rule. It is + assumed to denote absolute project id.
Source locationsource-locationThe location of jamfile for the projectSets to the passed value
RequirementsrequirementsThe parent's requirementsThe parent's requirements are refined with the passed requirement + and the result is used as the project requirements.
Default builddefault-buildTODOSets to the passed value
+ +

Project relationship

+ +

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 ;
+   
+
+ +

Targets

+ +

Main targets and main target alternatives

+ +

Target identifiers and references

+ +

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.

+ +

Build process

+ +

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:

+ +
    +
  1. The project in the current dir is passed the build request. If the + build request does not satisfy the project's requirements, a warning is + issued and the build of the project is skipped. Otherwise, the process + is repeated recusrively for all subprojects.
    2. + +
  2. + An attempts to make all the main targets in the project is performed. + For each main target: + +
      +
    1. All main target alternatives which requirements are satisfied + by the build request are enumerated.
      2. + +
    2. If there are several such alternatives, the one which longer + requirements list is selected.
      3. +
    +
    3. + +
  3. + For each selected alternative + +
      +
    1. Each target reference in the source list are recursively + constructed.
      2. + +
    2. The dependency graph for the target is constructed by running + so called matching process, using generated source targets and + ordinary sources.
      3. +
    +
    4. +
+ +

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.

+ + +