mirror of
https://github.com/boostorg/build.git
synced 2026-02-13 12:22:17 +00:00
760 lines
27 KiB
HTML
760 lines
27 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
|
"http://www.w3.org/TR/html4/strict.dtd">
|
|
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content=
|
|
"HTML Tidy for Linux/x86 (vers 1st March 2002), see www.w3.org">
|
|
<!--tidy options: -i -wrap 78 -->
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link rel="stylesheet" type="text/css" href="../../boost.css">
|
|
|
|
<title>Boost.Build v2 user manual</title>
|
|
<style type="text/css">
|
|
hr { color: black }
|
|
p.revision { text-align: right; font-style: italic }
|
|
pre.code { margin-left: 2em }
|
|
pre.output { margin-left: 2em }
|
|
img.banner { border: 0; float: left }
|
|
h1 { text-align: right }
|
|
br.clear { clear: left }
|
|
div.alert { color: red }
|
|
table { align: center; border: thin; }
|
|
</style>
|
|
</head>
|
|
|
|
<body>
|
|
<p><a href="../../index.htm"><img class="banner" height="86" width="277"
|
|
alt="C++ Boost" src="../../c++boost.gif"></a></p>
|
|
|
|
<h1>Boost.Build v2 user manual<br class="clear">
|
|
</h1>
|
|
<hr>
|
|
|
|
<div class="alert">
|
|
This preliminary reference is intended to document everything
|
|
currently implemeneted, but is not yet ready for any practical
|
|
use.
|
|
</div>
|
|
<br>
|
|
<br>
|
|
|
|
<hr>
|
|
|
|
<dl class="page-index">
|
|
<dt><a href="#sec-reference">Reference documentation</a></dt>
|
|
|
|
<dd>
|
|
<dl class="page-index">
|
|
<dt><a href="#features_properties">Features and properties</a></dt>
|
|
|
|
<dd>
|
|
<dl class="page-index">
|
|
<dt><a href="#features_defined">Defintions</a>
|
|
<dt><a href="#feature_attributes">Feature Attributes</a>
|
|
<dt><a href="#feature_declaration">Feature Declaration</a>
|
|
</dl>
|
|
|
|
<dt><a href="#variants">Build Variants</a></dt>
|
|
|
|
<dt><a href="#subfeatures">Subfeatures</a></dt>
|
|
|
|
<dt><a href="#initialization">Initialization</a></dt>
|
|
|
|
<dt><a href="#command_line">Command line</a></dt>
|
|
|
|
<dt><a href="#projects">Projects</a></dt>
|
|
|
|
<dt><a href="#targets">Targets</a></dt>
|
|
|
|
<dt><a href="#build_process">Build process</a></dt>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
<hr>
|
|
|
|
<h2><a name="sec-reference">Reference</a></h2>
|
|
|
|
<h3><a name="features_properties">Features and properties</a></h3>
|
|
|
|
<h4><a name="features_defined">Definitions</a></h4>
|
|
|
|
<p>A <em>feature</em> is a normalized (toolset-independent) aspect
|
|
of a build configuration, such as whether inlining is
|
|
enabled. Feature names may not contain the '<tt>></tt>'
|
|
character.</p>
|
|
|
|
<p>Each feature in a build configuration has one or more
|
|
associated <em>value</em>s. Feature values may not contain the
|
|
'<tt><</tt>', '<tt>:</tt>', or '<tt>=</tt>' characters.</p>
|
|
|
|
<p>A <em>property</em> is a (feature,value) pair, expressed as
|
|
<feature>value.</p>
|
|
|
|
<p>A <em>subfeature</em> is a feature which only exists in the
|
|
presence of its parent feature, and whose identity can be derived
|
|
(in the context of its parent) from its value.</p>
|
|
|
|
<p>A <em>value-string</em> is a string of the form
|
|
<tt>value-subvalue1-subvalue2</tt>...<tt>-subvalueN</tt>, where <tt>value</tt> is
|
|
a feature value and <tt>subvalue1</tt>...<tt>subvalueN</tt> are values of related
|
|
subfeatures. For example, the properties
|
|
<tt><toolset>gcc <toolset-version>3.0.1</tt> can be
|
|
expressed more conscisely using a value-string, as
|
|
<tt><toolset>gcc-3.0.1</tt>.</p>
|
|
|
|
<p>A <em>property set</em> is a set of properties where no property appears twice, for
|
|
instance: <tt><toolset>gcc <runtime-link>static</tt>.
|
|
|
|
<p>
|
|
|
|
A <em>property path</em> is a property set whose elements have
|
|
been joined into a single string separated by slashes. A property
|
|
path representation of the previous example would be
|
|
<tt><toolset>gcc/<runtime-link>static</tt>.
|
|
|
|
<p>A <em>build specification</em> is a property set which fully
|
|
describes the set of features used to build a target.
|
|
|
|
<h4><a name="feature_attributes">Feature Attributes</a></h4>
|
|
|
|
<p>Each feature has a collection of zero or more of the following
|
|
attributes. Feature attributes are low-level descriptions of how
|
|
the build system should interpret a feature's values when they
|
|
appear in a build request. We also refer to the attributes of
|
|
properties, so that a <i>incidental</i> property, for example, is
|
|
one whose feature is has the <i>incidental</i> attribute.
|
|
|
|
<ul>
|
|
<li>
|
|
<em>incidental</em>
|
|
|
|
<p>Incidental features are assumed not to affect build
|
|
products at all. As a consequence, the build system may use
|
|
the same file for targets whose build specification differs
|
|
only in incidental features. A feature which controls a
|
|
compiler's warning level is one example of a likely incidental
|
|
feature.</p>
|
|
|
|
<p>Non-incidental features are assumed to affect build
|
|
products, so the files for targets whose build specification
|
|
differs in non-incidental features are placed in different
|
|
directories as described in <a href="#target_paths">target
|
|
paths</a> below.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<em>propagated</em>
|
|
|
|
<p>Features of this kind are propagated to dependencies. That
|
|
is, if a <a href="#main_target">main target</a> is built using
|
|
a propagated property, the build systems attempts to use the
|
|
same property when building any of its dependencies as part of
|
|
that main target. For instance, when an optimized exectuable
|
|
is requested, one usually wants it to be linked with optimized
|
|
libraries. Thus, the <tt><optimization></tt> feature is
|
|
propagated.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<em>free</em>
|
|
|
|
<p>Most features have a finite set of allowed values, and can
|
|
only take on a single value from that set in a given build
|
|
specification. Free features, on the other hand, can have
|
|
several values at a time and each value can be an arbitrary
|
|
string. For example, it is possible to have several
|
|
preprocessor symbols defined simultaneously:</p>
|
|
<pre>
|
|
<define>NDEBUG=1 <define>HAS_CONFIG_H=1
|
|
</pre>
|
|
<br>
|
|
</li>
|
|
|
|
<li>
|
|
<em>optional</em>
|
|
|
|
<p>An optional feature is a feature which is not required to
|
|
appear in a build specification. Every non-optional non-free
|
|
feature has a default value which is used when a value for the
|
|
feature is not otherwise specified, either in a target's
|
|
requirements or in the user's build request. [A feature's
|
|
default value is given by the first value listed in the
|
|
feature's declaration. -- move this elsewhere - dwa]</p>
|
|
</li>
|
|
|
|
<li>
|
|
<em>symmetric</em>
|
|
|
|
<p>A symmetric feature's default value is not automatically
|
|
included in <a href="#variants">build variants</a>. Normally a
|
|
feature only generates a subvariant directory when its value
|
|
differs from the value specified by the build variant, leading
|
|
to an assymmetric subvariant directory structure for certain
|
|
values of the feature. A symmetric feature, when relevant to
|
|
the toolset, always generates a corresponding subvariant
|
|
directory.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<em>path</em>
|
|
|
|
<p>The value of a path feature specifies a path. The path is treated
|
|
as relative to the directory of Jamfile where path feature is used
|
|
and is translated appropriately by the build system when the build is
|
|
invoked from a different directory</p>
|
|
</li>
|
|
|
|
<li>
|
|
<em>implicit</em>
|
|
|
|
<p>Values of implicit features alone identify the feature. For
|
|
example, a user is not required to write "<toolset>", but can
|
|
simply write "gcc". Implicit feature names also don't appear in
|
|
variant paths, although the values do. Thus: bin/gcc/... as opposed
|
|
to bin/toolset-gcc/.... There should typically be only a few such
|
|
features, to avoid possible name clashes.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<em>composite</em>
|
|
|
|
<p>Composite features actually correspond to groups of properties.
|
|
For example, a build variant is a composite feature. When generating
|
|
targets from a set of build properties, composite features are
|
|
recursively expanded and <em>added</em> to the build property set, so
|
|
rules can find them if neccessary. Non-composite non-free features
|
|
override components of composite features in a build property
|
|
set.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<em>link-incompatible</em>
|
|
|
|
<p>See <a href="#link_compatibility">below</a>.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<em>dependency</em>
|
|
|
|
<div class="alert">
|
|
Do we need it?
|
|
</div>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>TODO: document active features..</p>
|
|
|
|
<h4><a name="#feature_declaration">Feature Declaration</a></h4>
|
|
|
|
The low-level feature declaration interface is the
|
|
<tt>feature</tt> rule from the <tt>feature</tt> module:
|
|
|
|
<pre>
|
|
rule feature ( name : allowed-values * : attributes * )
|
|
</pre>
|
|
|
|
A feature's allowed-values may be extended wit
|
|
|
|
The build system will provide high-level rules which define
|
|
features in terms of valid and useful combinations of attributes.
|
|
|
|
<h3><a name="#variants">Build Variants</a></h3>
|
|
|
|
A build variant, or (simply variant) is a special kind of
|
|
composite feature which automatically incorporates the default
|
|
values of features that . Typically you'll want at least two separate variants:
|
|
one for debugging, and one for your release code.
|
|
|
|
[ Volodya says: "Yea, we'd need to mention that it's a composite feature and describe how
|
|
they are declared, in pacticular that default values of non-optional
|
|
features are incorporated into build variant automagically. Also, do we
|
|
wan't some variant inheritance/extension/templates. I don't remember how
|
|
it works in V1, so can't document this for V2.". Will clean up soon -DWA ]
|
|
|
|
|
|
<h4 id="link_compatibility">Link compatible and incompatible
|
|
properties</h4>
|
|
|
|
<p>When the build system tries to generate a target (such as library
|
|
dependency) matching a given build request, it may find that an exact
|
|
match isn't possible — for example, the target may impose additonal
|
|
build requirements. We need to determine whether a buildable version of
|
|
that target can actually be used.</p>
|
|
|
|
<p>The build request can originate in many ways: It may come directly
|
|
from the user's command-line, from a dependency of a main target upon a
|
|
library, or from a dependency of a target upon an executable used to
|
|
build that target, for example. For each way, there are different rules
|
|
whether we can use a given subvariant or not. However we currently only
|
|
assume linking and therefore use a simple approach described in the
|
|
following paragraph.</p>
|
|
|
|
<p>In general, there are many possible situations: a libary which is
|
|
dependency of a main target and should be linked into it, target which is
|
|
directly requested on the command line, or build executable which is used
|
|
in the build process itself. At this moment we use a simple approach.</p>
|
|
|
|
<p>Two property sets are called <em>link-compatible</em> when targets
|
|
with those property sets can be used interchangably. In turn, two
|
|
property sets are link compatible when there's no link-incompatible
|
|
feature which has different values in those property sets. Whenever
|
|
requested and actual properties are link-compatible, it's OK. Otherwise,
|
|
it's an error.</p>
|
|
|
|
<h4>Definition of property refinement</h4>
|
|
|
|
<p>When a target with certain properties is requested, and that target
|
|
requires some set of properties, it is needed to find the set of
|
|
properties to use for building. This process is called <em>property
|
|
refinement</em> and is performed by these rules</p>
|
|
|
|
<ol>
|
|
<li>If original properties and required properties are not
|
|
link-compatible, refinement fails.</li>
|
|
|
|
<li>Each property in the required set is added to the original property
|
|
set</li>
|
|
|
|
<li>If the original property set includes property with a different
|
|
value of non free feature, that property is removed.</li>
|
|
</ol>
|
|
|
|
<h3><a name="initialization">Initialization</a></h3>
|
|
|
|
<p>bjam's first job upon startup is to load the Jam code which implements
|
|
the build system. To do this, it searches for a file called
|
|
"boost-build.jam", first in the invocation directory, then in its parent
|
|
and so forth up to the filesystem root, and finally in the directories
|
|
specified by the environment variable BOOST_BUILD_PATH. When found, the
|
|
file is interpreted, and should specify the build system location by
|
|
calling the boost-build rule:</p>
|
|
<pre>
|
|
rule boost-build ( location ? )
|
|
</pre>
|
|
If location is a relative path, it is treated as relative to the
|
|
directory of boost-build.jam. The directory specified by location and
|
|
directories in BOOST_BUILD_PATH are then searched for a file called
|
|
bootstrap.jam which is interpreted and is expected to bootstrap the build
|
|
system. This arrangement allows the build system to work without any
|
|
command-line or environment variable settings. For example, if the build
|
|
system files were located in a directory "build-system/" at your project
|
|
root, you might place a boost-build.jam at the project root containing:
|
|
<pre>
|
|
boost-build build-system ;
|
|
</pre>
|
|
In this case, running bjam anywhere in the project tree will
|
|
automatically find the build system.
|
|
|
|
<h3><a name="command_line">Command line</a></h3>
|
|
|
|
<p>The comamnd line may contain:</p>
|
|
|
|
<ul>
|
|
<li>Jam options,</li>
|
|
|
|
<li>Boost.Build <a href="#command_line_options">options</a>,</li>
|
|
|
|
<li>Command line arguments</li>
|
|
</ul>
|
|
|
|
<h4 id="command_line_arguments">Command line arguments</h4>
|
|
Command line arguments specify targets and build request using the
|
|
following rules.
|
|
|
|
<ul>
|
|
<li>An argument which does not contain slashes or the "=" 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 <a href="#target_id">target id</a>.</li>
|
|
|
|
<li>
|
|
An argument with either slashes or the "=" symbol specifies a number
|
|
of <a href="#build_request">build request</a> elements. properties.
|
|
In the simplest form, it's just a set of properties, separated by
|
|
slashes, which become a single build request element, for example:
|
|
<pre>
|
|
borland/<runtime-link>static
|
|
</pre>
|
|
More complex form is used to save typing. For example, instead of
|
|
<pre>
|
|
borland/runtime-link=static borland/runtime-link=dynamic
|
|
</pre>
|
|
one can use
|
|
<pre>
|
|
borland/runtime-link=static,dynamic
|
|
</pre>
|
|
Exactly, the convertion from argument to build request elements is
|
|
performed by (1) splitting the argument at each slash, (2) converting
|
|
each split part into a set of properties and (3) taking all possible
|
|
combination of the property sets. Each split part should have the
|
|
either the form
|
|
<pre>
|
|
<em>feature-name</em>=<em>feature-value1</em>[","<em>feature-valueN</em>]*
|
|
</pre>
|
|
or, in case of implict feature
|
|
<pre>
|
|
<em>feature-value1</em>[","<em>feature-valueN</em>;]*
|
|
</pre>
|
|
and will be converted into property set
|
|
<pre>
|
|
<feature-name>feature-value1 .... <feature-name>feature-valueN
|
|
</pre>
|
|
</li>
|
|
</ul>
|
|
For example, the command line
|
|
<pre>
|
|
target1 debug gcc/runtime-link=dynamic,static
|
|
|
|
</pre>
|
|
would cause target called <tt>target1</tt> to be rebuild in debug mode,
|
|
except that for gcc, both dynamically and statically linked binaries
|
|
would be created.
|
|
|
|
<h4 id="command_line_options">Command line options</h4>
|
|
|
|
<p>All of the Boost.Build options start with the "--" prefix. They are
|
|
described in the following table.</p>
|
|
|
|
<table align="center">
|
|
<caption>
|
|
Command line options
|
|
</caption>
|
|
|
|
<thead>
|
|
<tr>
|
|
<th>Option</th>
|
|
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<tr>
|
|
<td><tt>--debug</tt></td>
|
|
|
|
<td>Enables internal checks.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><tt>--dump-projects</tt></td>
|
|
|
|
<td>Cause the project structure to be output.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><tt>--help</tt></td>
|
|
|
|
<td>Access to the online help system. This prints general
|
|
information on how to use the help system with additional --help*
|
|
options.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h3><a name="projects">Projects</a></h3>
|
|
|
|
<p>Boost.Build considers every software it build as organized into
|
|
projects, each of which corresponds to a single Jamfile. Projects are
|
|
organized in a hierarchical structure, so each project may have a single
|
|
parent project and a number of subprojects. (TODO: project root).</p>
|
|
|
|
<h4>Project attributes</h4>
|
|
|
|
<p>For each project, there are several attributes.</p>
|
|
|
|
<p><em>Project id</em> 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". There are two ways to refer to a
|
|
project using project-id:</p>
|
|
|
|
<ul>
|
|
<li>Use absolute proejct-id, which starts with "/", for example
|
|
<tt>/boost/thread</tt>.</li>
|
|
|
|
<li>Use relative project-id, which is appended to the project-id of the
|
|
project where it is used.</li>
|
|
</ul>
|
|
|
|
<p><em>Source location</em> specifies the directory where sources for the
|
|
project are located.</p>
|
|
|
|
<p><em>Project requirements</em> are requirements that apply to all the
|
|
targets in the projects as well as all subprojects.</p>
|
|
|
|
<p><em>Default build</em> is the build request that should be used when
|
|
no build request is specified explicitly.</p>
|
|
|
|
<p>The default values for those attributes are given in the table below.
|
|
In order to affect them, Jamfile may call the <tt>project</tt> rule. The
|
|
rule has this syntax:</p>
|
|
<pre>
|
|
project id : <attributes> ;
|
|
|
|
</pre>
|
|
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:
|
|
<pre>
|
|
project tennis
|
|
: requirements <threading>multi
|
|
: default-build release
|
|
;
|
|
|
|
</pre>
|
|
|
|
<table>
|
|
<tr>
|
|
<th>Attribute</th>
|
|
|
|
<th>Name for the 'project' rule</th>
|
|
|
|
<th>Default value</th>
|
|
|
|
<th>Handling by the 'project' rule</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Project id</td>
|
|
|
|
<td>none</td>
|
|
|
|
<td>none</td>
|
|
|
|
<td>Assigned from the first parameter of the 'project' rule. It is
|
|
assumed to denote absolute project id.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Source location</td>
|
|
|
|
<td><tt>source-location</tt></td>
|
|
|
|
<td>The location of jamfile for the project</td>
|
|
|
|
<td>Sets to the passed value</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Requirements</td>
|
|
|
|
<td><tt>requirements</tt></td>
|
|
|
|
<td>The parent's requirements</td>
|
|
|
|
<td>The parent's requirements are refined with the passed requirement
|
|
and the result is used as the project requirements.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Default build</td>
|
|
|
|
<td><tt>default-build</tt></td>
|
|
|
|
<td>TODO</td>
|
|
|
|
<td>Sets to the passed value</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h4>Project relationship</h4>
|
|
|
|
<p>There are three kinds of project relationships.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>Second is build relationship. Some project may request to recursively
|
|
build other projects. Those project need not be child projects. The
|
|
<tt>build-project</tt> rule is used for that:</p>
|
|
<pre>
|
|
build-project src ;
|
|
</pre>
|
|
|
|
<p>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 <tt>use-project</tt> rule
|
|
is employed to guarantee that.</p>
|
|
<pre>
|
|
use-project ( id : location )
|
|
|
|
</pre>
|
|
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 <tt>id</tt> parameter passed to the <tt>use-project</tt> rule be
|
|
equal to the id that the loaded project declared. At this moment, the
|
|
<tt>id</tt> paremeter should be absolute project id.
|
|
|
|
<h3><a name="targets">Targets</a></h3>
|
|
|
|
<h4>Main targets and main target alternatives</h4>
|
|
|
|
<p id="main_target"><em>Main target</em> is a named entity which can be
|
|
build, for example a named executable file. To declare a main target,
|
|
user invokes some of the <a href="#main_target_rules">main target
|
|
rules</a>, passing it things like list of source and requirement.</p>
|
|
|
|
<p>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:</p>
|
|
<pre>
|
|
exe a : a_gcc.cpp : <toolset> ;
|
|
exe a : a.cpp ;
|
|
</pre>
|
|
Each call to the 'exe' rule defines a new <em>main target
|
|
alternative</em> for the main target <tt>a.exe</tt>. In this case, the
|
|
first alternative will be used for the <tt>gcc</tt> toolset, while the
|
|
second alternative will be used in other cases. TODO: document the exact
|
|
selection method under "Build process" below.
|
|
|
|
<h4 id="target_id">Target identifiers and references</h4>
|
|
|
|
<p><em>Target identifier</em> is used to denote a target. It is described
|
|
by the following grammar:</p>
|
|
<pre>
|
|
target-id -> project-reference local-target-name
|
|
project-reference -> [jamfile-location] [ "@" [project-id] ]
|
|
jamfile-location -> pathname
|
|
project-id -> pathname
|
|
local-target-name -> identifier
|
|
</pre>
|
|
For example, valid target ids might be:
|
|
<pre>
|
|
a
|
|
lib/b
|
|
@/boost/thread
|
|
/home/ghost/build/lr_library@parser/lalr1
|
|
</pre>
|
|
To map the target id into target, the project where that target is
|
|
contained is first found:
|
|
|
|
<ol>
|
|
<li>If <tt>project-reference</tt> is empty, then the current project is
|
|
used — i.e. the project there the target id occurs.</li>
|
|
|
|
<li>If the project id is absolute, the project with that id is
|
|
used.</li>
|
|
|
|
<li>If the project id is relative, it is treated relatively to
|
|
project-id of the project at <tt>jamfile-location</tt>. If that project
|
|
does not declare project id, it is an error.</li>
|
|
</ol>
|
|
After that, the target given by <tt>local-target-name</tt> in the found
|
|
project is used.
|
|
|
|
<p><em>Target reference</em> is used to specify a source target, and may
|
|
additionally specify desired properties for that target. It has this
|
|
syntax:</p>
|
|
<pre>
|
|
target-reference -> target-id [ "/" requested-properties ]
|
|
requested-properties -> property-path
|
|
</pre>
|
|
For example,
|
|
<pre>
|
|
exe compiler : compiler.cpp libs/cmdline/<optimization>space ;
|
|
</pre>
|
|
would cause the version of <tt>cmdline</tt> library, optimized for space,
|
|
to be linked in even if the <tt>compile</tt> executable is build with
|
|
optimization for speed.
|
|
|
|
<h5>Ambiguity resolution</h5>
|
|
|
|
<p>Target reference may have the same form as a pathname, for example
|
|
<tt>lib/a</tt>. 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
|
|
a file name.</p>
|
|
|
|
<h4>Target paths</h4>
|
|
|
|
<p>To distinguish targets build with different properties, they are put
|
|
in different directories. Rules for determining target paths are given
|
|
below:</p>
|
|
|
|
<ol>
|
|
<li>All targets are placed under directory corresponding to the project
|
|
where they are defined.</li>
|
|
|
|
<li>Each non free, non incidental property cause an additional element
|
|
to be added to the target path. That element has the form
|
|
<tt><feature-name>-<feature-value></tt> for ordinary
|
|
features and <tt><feature-value></tt> for implicit ones. [Note
|
|
about composite features].</li>
|
|
|
|
<li>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
|
|
<tt>main_target-<name></tt> is added to the target path.
|
|
<b>Note:</b>It would be nice to completely track free features also,
|
|
but this appears to be complex and not extremely needed.</li>
|
|
</ol>
|
|
|
|
<p>For example, we might have these paths:</p>
|
|
<pre>
|
|
debug/optimization-off
|
|
debug/main-target-a
|
|
|
|
</pre>
|
|
|
|
<h3><a name="build_process">Build process</a></h3>
|
|
|
|
<p>The build works in this way. On startup, the project in the current
|
|
directory is read. In turn, it may request building of other projects,
|
|
which will be loaded recursively. Parent projects are also loaded to
|
|
inherit some of their properties. As the result, a tree of projects is
|
|
constructed. After that, the build request is constructed from the
|
|
command line. Then, the steps are:</p>
|
|
|
|
<ol>
|
|
<li>All of the projects to be build are 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. Projects
|
|
mentioned in <tt>build-project</tt> rule will still be build.</li>
|
|
|
|
<li>
|
|
An attempts to make all the main targets in the project is performed.
|
|
For each main target:
|
|
|
|
<ol>
|
|
<li>All main target alternatives which requirements are satisfied
|
|
by the build request are enumerated.</li>
|
|
|
|
<li>If there are several such alternatives, the one which longer
|
|
requirements list is selected.</li>
|
|
</ol>
|
|
</li>
|
|
|
|
<li>
|
|
For each selected alternative
|
|
|
|
<ol>
|
|
<li>Each target reference in the source list are recursively
|
|
constructed.</li>
|
|
|
|
<li>The dependency graph for the target is constructed by running
|
|
so called matching process, using generated source targets and
|
|
ordinary sources.</li>
|
|
</ol>
|
|
</li>
|
|
</ol>
|
|
|
|
<p>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.</p>
|
|
<hr>
|
|
|
|
<p class="revision">Last modified: Aug 15, 2002</p>
|
|
|
|
<p>© 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.</p>
|
|
</body>
|
|
</html>
|
|
|