mirror of
https://github.com/boostorg/build.git
synced 2026-02-11 11:42:14 +00:00
1071 lines
41 KiB
XML
1071 lines
41 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE chapter PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
|
|
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
|
|
|
|
<chapter id="bbv2.reference">
|
|
<title>Detailed reference</title>
|
|
|
|
<section id="bbv2.reference.general">
|
|
<title>General information</title>
|
|
|
|
<section id="bbv2.reference.init">
|
|
<title>Initialization</title>
|
|
|
|
<para>bjam's first job upon startup is to load the Jam code that
|
|
implements the build system. To do this, it searches for a file
|
|
called <filename>boost-build.jam</filename>, 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:</para>
|
|
|
|
<programlisting>
|
|
rule boost-build ( location ? )
|
|
</programlisting>
|
|
|
|
<para>
|
|
If location is a relative path, it is treated as relative to
|
|
the directory of <filename>boost-build.jam</filename>. The directory specified by
|
|
that location and the directories in BOOST_BUILD_PATH are then searched for
|
|
a file called <filename>bootstrap.jam</filename>, which 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
|
|
<filename>boost-build.jam</filename> at the project root containing:
|
|
|
|
<programlisting>
|
|
boost-build build-system ;
|
|
</programlisting>
|
|
|
|
In this case, running bjam anywhere in the project tree will
|
|
automatically find the build system.</para>
|
|
|
|
<para>The default <filename>bootstrap.jam</filename>, after loading some standard
|
|
definitions, loads two files, which can be provided/customised by
|
|
user: <filename>site-config.jam</filename> and <filename>user-config.jam</filename>.</para>
|
|
|
|
<para>Locations where those files a search are summarized below:</para>
|
|
|
|
<table id="bbv2.reference.init.config">
|
|
<title>Search paths for configuration files</title>
|
|
|
|
<tgroup cols="3">
|
|
<thead>
|
|
|
|
<row>
|
|
<entry></entry>
|
|
|
|
<entry>site-config.jam</entry>
|
|
|
|
<entry>user-config.jam</entry>
|
|
</row>
|
|
|
|
</thead>
|
|
<tbody>
|
|
|
|
<row>
|
|
<entry>Linux</entry>
|
|
|
|
<entry>
|
|
<simpara><code>/etc</code></simpara>
|
|
<simpara><code>$HOME</code></simpara>
|
|
<simpara><code>$BOOST_BUILD_PATH</code></simpara>
|
|
</entry>
|
|
|
|
<entry>
|
|
<simpara><code>$HOME</code></simpara>
|
|
<simpara><code>$BOOST_BUILD_PATH</code></simpara>
|
|
</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>Windows</entry>
|
|
|
|
<entry>
|
|
<simpara><code>%SystemRoot%</code></simpara>
|
|
<simpara><code>%HOMEDRIVE%%HOMEPATH%</code></simpara>
|
|
<simpara><code>%HOME%</code></simpara>
|
|
<simpara><code>%BOOST_BUILD_PATH%</code></simpara>
|
|
</entry>
|
|
|
|
<entry>
|
|
<simpara><code>%HOMEDRIVE%%HOMEPATH%</code></simpara>
|
|
<simpara><code>%HOME%</code></simpara>
|
|
<simpara><code>%BOOST_BUILD_PATH%</code></simpara>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
<para>
|
|
Boost.Build comes with default versions of those files,
|
|
<!-- Where are those files installed? The user can't use them as templates unless she can find them -->
|
|
which can serve as templates for customized versions.
|
|
</para>
|
|
|
|
</section>
|
|
<section id="bbv2.reference.commandline">
|
|
<title>Command line</title>
|
|
|
|
<para>The command line may contain:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem><simpara>Jam options,</simpara></listitem>
|
|
|
|
<listitem><simpara>Boost.Build <link linkend=
|
|
"bbv2.reference.init.options">options</link>,</simpara></listitem>
|
|
|
|
<listitem><simpara>Command line arguments</simpara></listitem>
|
|
</itemizedlist>
|
|
|
|
<section id="bbv2.reference.init.args">
|
|
<title>Command line arguments</title>
|
|
|
|
<para>
|
|
Command line arguments specify targets and build
|
|
request using the following rules.
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<simpara>
|
|
An argument that does not contain slashes or the <code>=</code>
|
|
symbol is either a value of an implicit feature or of a target to
|
|
be built. It is taken to be value of a feature if an appropriate
|
|
feature exists. Otherwise, it is considered a <link linkend=
|
|
"bbv2.reference.ids">target id</link>. Building the
|
|
special target name “clean” has the same effect as
|
|
using the <code>--clean</code> option.
|
|
</simpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
An argument containing either slashes or
|
|
the <code>=</code> symbol specifies a number of build
|
|
request elements (see <xref
|
|
linkend="bbv2.reference.buildreq"/>). In its simplest
|
|
form, it's just a set of properties, separated by
|
|
slashes, which become a single build request element,
|
|
for example:
|
|
|
|
<programlisting>
|
|
borland/<runtime-link>static
|
|
</programlisting>
|
|
|
|
A more complex form can be used to save typing. For example,
|
|
instead of
|
|
|
|
<programlisting>
|
|
borland/runtime-link=static borland/runtime-link=dynamic
|
|
</programlisting>
|
|
|
|
one can use
|
|
|
|
<programlisting>
|
|
borland/runtime-link=static,dynamic
|
|
</programlisting>
|
|
|
|
Exactly, the conversion 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 combinations
|
|
<!-- Be specific. Do you mean the cross-product? -->
|
|
of the property sets. Each split
|
|
part should have the either the form
|
|
|
|
<programlisting>
|
|
<emphasis>feature-name</emphasis>=<emphasis>feature-value1</emphasis>[","<emphasis>feature-valueN</emphasis>]*
|
|
</programlisting>
|
|
|
|
or, in case of implicit features
|
|
|
|
<programlisting>
|
|
<emphasis>feature-value1</emphasis>[","<emphasis>feature-valueN</emphasis>;]*
|
|
</programlisting>
|
|
|
|
will be converted into the property set
|
|
|
|
<programlisting>
|
|
<feature-name>feature-value1 .... <feature-name>feature-valueN
|
|
</programlisting>
|
|
|
|
<!-- There's absolutely no explanation of how arguments are combined. Fix that. -->
|
|
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
For example, the command line
|
|
|
|
<programlisting>
|
|
target1 debug gcc/runtime-link=dynamic,static
|
|
</programlisting>
|
|
|
|
would cause target called <literal>target1</literal> to be rebuilt in
|
|
debug mode, except that for gcc, both dynamically and statically
|
|
linked binaries would be created.
|
|
</para>
|
|
|
|
</section>
|
|
<section id="bbv2.reference.init.options">
|
|
<title>Command line options</title>
|
|
|
|
<para>All of the Boost.Build options start with the "--" prefix.
|
|
They are described in the following table.</para>
|
|
|
|
<table>
|
|
<title>Command line options</title>
|
|
<tgroup cols="2">
|
|
|
|
<thead>
|
|
<row>
|
|
<entry>Option</entry>
|
|
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>--version</literal></entry>
|
|
|
|
<entry>Prints information on Boost.Build and Boost.Jam
|
|
versions.</entry>
|
|
</row>
|
|
|
|
<row id="bbv2.reference.init.options.help">
|
|
<entry><literal>--help</literal></entry>
|
|
|
|
<entry>Access to the online help system. This prints general
|
|
information on how to use the help system with additional
|
|
--help* options.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><literal>--clean</literal></entry>
|
|
|
|
<entry>Removes everything instead of building. Unlike
|
|
<literal>clean</literal> target in make, it is possible to clean only
|
|
some targets.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><literal>--debug</literal></entry>
|
|
|
|
<entry>Enables internal checks.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><literal>--dump-projects</literal></entry>
|
|
|
|
<entry>Cause the project structure to be output.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><literal>--no-error-backtrace</literal></entry>
|
|
|
|
<entry>Don't print backtrace on errors. Primary useful for
|
|
testing.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><literal>--ignore-config</literal></entry>
|
|
|
|
<entry>Do not load <literal>site-config.jam</literal> and
|
|
<literal>user-config.jam</literal></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
</section>
|
|
</section>
|
|
|
|
|
|
</section>
|
|
|
|
<section id="bbv2.reference.jamfiles">
|
|
<title>Writing Jamfiles</title>
|
|
|
|
<para>This section describes specific information about writing Jamfiles.</para>
|
|
|
|
<section id="bbv2.reference.headers">
|
|
<title>Generated headers</title>
|
|
|
|
<para>Usually, Boost.Build handles implicit dependendies completely
|
|
automatically. For example, for C++ files, all <literal>#include</literal>
|
|
statements are found and handled. The only aspect where user help
|
|
might be needed is implicit dependency on generated files.</para>
|
|
|
|
<para>By default, Boost.Build handles such dependencies within one
|
|
main target. For example, assume that main target "app" has two
|
|
sources, "app.cpp" and "parser.y". The latter source is converted
|
|
into "parser.c" and "parser.h". Then, if "app.cpp" includes
|
|
"parser.h", Boost.Build will detect this dependency. Moreover,
|
|
since "parser.h" will be generated into a build directory, the
|
|
path to that directory will automatically added to include
|
|
path.</para>
|
|
|
|
<para>Making this mechanism work across main target boundaries is
|
|
possible, but imposes certain overhead. For that reason, if
|
|
there's implicit dependency on files from other main targets, the
|
|
<literal><implicit-dependency></literal> [ link ] feature must
|
|
be used, for example:</para>
|
|
|
|
<programlisting>
|
|
lib parser : parser.y ;
|
|
exe app : app.cpp : <implicit-dependency>parser ;
|
|
</programlisting>
|
|
|
|
<para>
|
|
The above example tells the build system that when scanning
|
|
all sources of "app" for implicit-dependencies, it should consider
|
|
targets from "parser" as potential dependencies.
|
|
</para>
|
|
</section>
|
|
|
|
|
|
</section>
|
|
|
|
<section id="bbv2.reference.buildprocess">
|
|
<title>Build process</title>
|
|
|
|
<para>The general overview of the build process was given in the
|
|
<link linkend="bbv2.advanced.build_process">user documentation</link>.
|
|
This section provides additional details, and some specific rules.
|
|
</para>
|
|
|
|
<para>To recap, building a target with specific properties includes the
|
|
following steps:
|
|
<orderedlist>
|
|
|
|
<listitem><para>applying default build,</para></listitem>
|
|
|
|
<listitem><para>selecting the main target alternative to use,
|
|
</para></listitem>
|
|
|
|
<listitem><para>determining "common" properties</para></listitem>
|
|
|
|
<listitem><para>building targets referred by the sources list and
|
|
dependency properties</para></listitem>
|
|
|
|
<listitem><para>adding the usage requirements produces when building
|
|
dependencies to the "common" properties</para></listitem>
|
|
|
|
<listitem><para>building the target using generators</para></listitem>
|
|
|
|
<listitem><para>computing the usage requirements to be returned</para></listitem>
|
|
|
|
</orderedlist>
|
|
</para>
|
|
|
|
<section id="bbv2.reference.buildprocess.alternatives">
|
|
<title>Alternative selection</title>
|
|
|
|
<para>When there are several alternatives, one of them must be
|
|
selected. The process is as follows:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<simpara>
|
|
For each alternative <emphasis>condition</emphasis> is defined
|
|
as the set of base properies in requirements. [Note: it might be
|
|
better to specify the condition explicitly, as in
|
|
conditional requirements].
|
|
</simpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
An alternative is viable only if all properties in condition
|
|
are present in build request.
|
|
</simpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
If there's one viable alternative, it's choosen. Otherwise,
|
|
an attempt is made to find one best alternative. An alternative
|
|
a is better than another alternative b, iff set of properties
|
|
in b's condition is strict subset of the set of properities of
|
|
'a's condition. If there's one viable alternative, which is
|
|
better than all other, it's selected. Otherwise, an error is
|
|
reported.
|
|
</simpara>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
</section>
|
|
|
|
<section id="bbv2.reference.buildprocess.common">
|
|
<title>Determining common properties</title>
|
|
|
|
<para>The "common" properties is a somewhat artificial term. Those are
|
|
the intermediate property set from which both the build request for
|
|
dependencies and properties for building the target are derived.
|
|
</para>
|
|
|
|
<para>Since default build and alternatives are already handled, we have
|
|
only two inputs: build requests and requirements. Here are the rules
|
|
about common properties.
|
|
</para>
|
|
|
|
<orderedlist>
|
|
<listitem><para>Non-free feature can have only one
|
|
value</para></listitem>
|
|
|
|
<listitem><para>A non-conditional property in requirement in always
|
|
present in common properties.</para></listitem>
|
|
|
|
<listitem><para>A property in build request is present in
|
|
common properties, unless (2) tells otherwise.</para></listitem>
|
|
|
|
<listitem><para>If either build request, or requirements (non-conditional
|
|
or conditional) include an expandable property (either composite,
|
|
or property with specified subfeature value), the behaviour is
|
|
equivalent to explicitly adding all expanded properties to build
|
|
request or requirements.</para></listitem>
|
|
|
|
<listitem><para>If requirements include a conditional property, and
|
|
condiiton of this property is true in context of common
|
|
properties, then the conditional property should be in common
|
|
properties as well.</para></listitem>
|
|
|
|
<listitem><para>If no value for a feature is given by other rules
|
|
here, it has default value in common properties.</para></listitem>
|
|
</orderedlist>
|
|
|
|
<para>Those rules are declarative, they don't specify how to compute the
|
|
common properties. However, they provide enough information for the
|
|
user. The important point is the handling of conditional
|
|
requirements. The condition can be satisfied either by property in
|
|
build request, by non-conditional requirements, or even by another
|
|
conditional property. For example, the following example works as
|
|
expected:
|
|
<programlisting>
|
|
exe a : a.cpp
|
|
: <toolset>gcc:<variant>release
|
|
<variant>release:<define>FOO ;
|
|
</programlisting>
|
|
</para>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id="bbv2.reference.definitions">
|
|
|
|
<title>Definitions</title>
|
|
|
|
<section id="bbv2.reference.features">
|
|
<title>Features and properties</title>
|
|
|
|
<para>A <emphasis>feature</emphasis> is a normalized (toolset-independent)
|
|
aspect of a build configuration, such as whether inlining is
|
|
enabled. Feature names may not contain the '<literal>></literal>'
|
|
character.</para>
|
|
|
|
<!--
|
|
And what about dash?
|
|
-->
|
|
|
|
<para>Each feature in a build configuration has one or more
|
|
associated <emphasis>value</emphasis>s. Feature values for non-free features
|
|
may not contain the '<literal><</literal>', '<literal>:</literal>', or
|
|
'<literal>=</literal>' characters. Feature values for free features may not
|
|
contain the '<literal><</literal>' character.</para>
|
|
|
|
<para>A <emphasis>property</emphasis> is a (feature,value) pair, expressed as
|
|
<feature>value.</para>
|
|
|
|
<para>A <emphasis>subfeature</emphasis> is a feature that only exists in the
|
|
presence of its parent feature, and whose identity can be derived
|
|
(in the context of its parent) from its value. A subfeature's
|
|
parent can never be another subfeature. Thus, features and their
|
|
subfeatures form a two-level hierarchy.</para>
|
|
|
|
<para>A <emphasis>value-string</emphasis> for a feature <emphasis role="bold">F</emphasis> is a string of
|
|
the form
|
|
<literal>value-subvalue1-subvalue2</literal>...<literal>-subvalueN</literal>, where
|
|
<literal>value</literal> is a legal value for <emphasis role="bold">F</emphasis> and
|
|
<literal>subvalue1</literal>...<literal>subvalueN</literal> are legal values of some
|
|
of <emphasis role="bold">F</emphasis>'s subfeatures. For example, the properties
|
|
<literal><toolset>gcc <toolset-version>3.0.1</literal> can be
|
|
expressed more conscisely using a value-string, as
|
|
<literal><toolset>gcc-3.0.1</literal>.</para>
|
|
|
|
<para>A <emphasis>property set</emphasis> is a set of properties (i.e. a
|
|
collection without duplicates), for instance:
|
|
<literal><toolset>gcc <runtime-link>static</literal>.</para>
|
|
|
|
<para>A <emphasis>property path</emphasis> 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
|
|
<literal><toolset>gcc/<runtime-link>static</literal>.</para>
|
|
|
|
<para>A <emphasis>build specification</emphasis> is a property set that fully
|
|
describes the set of features used to build a target.</para>
|
|
|
|
<section id="bbv2.reference.features.validity">
|
|
<title>Property Validity</title>
|
|
|
|
<para>
|
|
For <link linkend=
|
|
"bbv2.reference.features.attributes.free">free</link>
|
|
features, all values are valid. For all other features,
|
|
the valid values are explicitly specified, and the build
|
|
system will report an error for the use of an invalid
|
|
feature-value. Subproperty validity may be restricted so
|
|
that certain values are valid only in the presence of
|
|
certain other subproperties. For example, it is possible
|
|
to specify that the <code><gcc-target>mingw</code>
|
|
property is only valid in the presence of
|
|
<code><gcc-version>2.95.2</code>.
|
|
</para>
|
|
|
|
</section>
|
|
<section id="bbv2.reference.features.attributes">
|
|
<title>Feature Attributes</title>
|
|
|
|
<para>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 an <emphasis>incidental</emphasis> property, for example, is
|
|
one whose feature has the <emphasis>incidental</emphasis>
|
|
attribute.</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>incidental</emphasis></para>
|
|
|
|
<para>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 that controls a
|
|
compiler's warning level is one example of a likely
|
|
incidental feature.</para>
|
|
|
|
<para>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 "target paths" below. [ where? ]
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<anchor id="bbv2.reference.features.attributes.propagated"/>
|
|
<emphasis>propagated</emphasis>
|
|
</para>
|
|
|
|
<para>Features of this kind are
|
|
propagated to dependencies. That is, if a <link linkend=
|
|
"bbv2.advanced.targets.main">main target</link> 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 <literal><optimization></literal> feature is
|
|
propagated.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<anchor id="bbv2.reference.features.attributes.free"/>
|
|
<emphasis>free</emphasis>
|
|
</para>
|
|
|
|
<para>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:</para>
|
|
|
|
<programlisting>
|
|
<define>NDEBUG=1 <define>HAS_CONFIG_H=1
|
|
</programlisting>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>optional</emphasis></para>
|
|
|
|
<para>An optional feature is a feature that is not required to
|
|
appear in a build specification. Every non-optional non-free
|
|
feature has a default value that 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]</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>symmetric</emphasis></para>
|
|
|
|
<para>A symmetric feature's default value is not automatically
|
|
included in <link linkend=
|
|
"bbv2.reference.variants">build variants</link>. 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.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>path</emphasis></para>
|
|
|
|
<para>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</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>implicit</emphasis></para>
|
|
|
|
<para>Values of implicit features alone identify the feature.
|
|
For example, a user is not required to write
|
|
"<toolset>gcc", 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.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>composite</emphasis></para>
|
|
|
|
<para>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
|
|
<emphasis>added</emphasis> to the build property set, so rules can find
|
|
them if necessary. Non-composite non-free features override
|
|
components of composite features in a build property set.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>dependency</emphasis></para>
|
|
|
|
<para>The value of dependency feature if a target reference.
|
|
When used for building of a main target, the value of
|
|
dependency feature is treated as additional dependency.</para>
|
|
|
|
<para>For example, dependency features allow to state that
|
|
library A depends on library B. As the result, whenever an
|
|
application will link to A, it will also link to B.
|
|
Specifying B as dependency of A is different from adding B to
|
|
the sources of A. <!-- Need to clarify this. --></para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Features that are neither free nor incidental are called
|
|
<emphasis>base</emphasis> features.</para>
|
|
|
|
|
|
</section>
|
|
<section id="bbv2.reference.features.declaration">
|
|
<title>Feature Declaration</title>
|
|
|
|
<para>The low-level feature declaration interface is the
|
|
<literal>feature</literal> rule from the
|
|
<literal>feature</literal> module:
|
|
|
|
<programlisting>
|
|
rule feature ( name : allowed-values * : attributes * )
|
|
</programlisting>
|
|
|
|
A feature's allowed-values may be extended with the
|
|
<code>feature.extend</code> rule.
|
|
</para>
|
|
|
|
</section>
|
|
</section>
|
|
|
|
<section id="bbv2.reference.variants">
|
|
<title>Build Variants</title>
|
|
|
|
<para>
|
|
A build variant, or (simply variant) is a special kind of composite
|
|
feature that 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 ]
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section id="bbv2.reference.variants.proprefine">
|
|
<title>Property refinement</title>
|
|
|
|
<para>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
|
|
<emphasis>property refinement</emphasis> and is performed by these rules</para>
|
|
|
|
<orderedlist>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
Each property in the required set is added to the original
|
|
property set
|
|
</simpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
If the original property set includes property with a different
|
|
value of non free feature, that property is removed.
|
|
</simpara>
|
|
</listitem>
|
|
</orderedlist>
|
|
</section>
|
|
|
|
<section id="bbv2.reference.variants.propcond">
|
|
<title>Conditional properties</title>
|
|
|
|
<para>Sometime it's desirable to apply certain requirements only for
|
|
a specific combination of other properties. For example, one of
|
|
compilers that you use issues a pointless warning that you want to
|
|
suppress by passing a command line option to it. You would not
|
|
want to pass that option to other compilers. Conditional
|
|
properties allow you to do just that. Their syntax is:</para>
|
|
|
|
<programlisting>
|
|
property ( "," property ) * ":" property
|
|
</programlisting>
|
|
|
|
<para>
|
|
For example, the problem above would be solved by:
|
|
|
|
<programlisting>
|
|
exe hello : hello.cpp : <toolset>yfc:<cxxflags>-disable-pointless-warning ;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>The syntax also allows several properties in the condition, for
|
|
example:
|
|
<programlisting>
|
|
exe hello : hello.cpp : <os>NT,<toolset>gcc:<link>static ;
|
|
</programlisting>
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section id="bbv2.reference.ids">
|
|
<title>Target identifiers and references</title>
|
|
|
|
<para><emphasis>Target identifier</emphasis> is used to denote a
|
|
target. The syntax is:</para>
|
|
|
|
<programlisting>
|
|
target-id -> (project-id | target-name | file-name )
|
|
| (project-id | directory-name) "//" target-name
|
|
project-id -> path
|
|
target-name -> path
|
|
file-name -> path
|
|
directory-name -> path
|
|
</programlisting>
|
|
|
|
<para>
|
|
This grammar allows some elements to be recognized as either
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<simpara>
|
|
project id (at this point, all project ids start with slash).
|
|
</simpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
name of target declared in current Jamfile (note that target
|
|
names may include slash).
|
|
</simpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
a regular file, denoted by absolute name or name relative to
|
|
project's sources location.
|
|
</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
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:
|
|
|
|
<screen>
|
|
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
|
|
</screen>
|
|
|
|
</para>
|
|
|
|
<para><emphasis role="bold">Rationale:</emphasis>Target is separated from project by special
|
|
separator (not just slash), because:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<simpara>
|
|
It emphasises that projects and targets are different things.
|
|
</simpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
It allows to have main target names with slashes.
|
|
|
|
<!-- The motivation for which is:
|
|
|
|
So, to summarize:
|
|
|
|
1. The project that extract tarfile may extract all possible kinds
|
|
of targets, and it's reasonable to use them directly from other
|
|
project.
|
|
|
|
2. The rule for unpacking tar is inplemented in terms of
|
|
"patch-file", for maintainability, and therefore, must use main
|
|
target name that contains slashes?
|
|
|
|
3. Using sub-Jamfile in "foo" to declare extracted file "foo/b" is
|
|
not an option, because you should not change existing tree
|
|
|
|
That makes good rationale for why main target must contain names.
|
|
-->
|
|
</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para id="bbv2.reference.targets.references">
|
|
<emphasis>Target reference</emphasis> is used to
|
|
specify a source target, and may additionally specify desired
|
|
properties for that target. It has this syntax:</para>
|
|
|
|
<programlisting>
|
|
target-reference -> target-id [ "/" requested-properties ]
|
|
requested-properties -> property-path
|
|
</programlisting>
|
|
|
|
<para>
|
|
For example,
|
|
|
|
<programlisting>
|
|
exe compiler : compiler.cpp libs/cmdline/<optimization>space ;
|
|
</programlisting>
|
|
|
|
would cause the version of <literal>cmdline</literal> library,
|
|
optimized for space, to be linked in even if the
|
|
<literal>compiler</literal> executable is build with optimization for
|
|
speed.
|
|
</para>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section id="bbv2.reference.generators">
|
|
<title>Generators</title>
|
|
|
|
<warning><para>The information is this section is likely to be outdated
|
|
and misleading.
|
|
</para></warning>
|
|
|
|
<para>To construct a main target with given properties from sources,
|
|
it is required to create a dependency graph for that main target,
|
|
which will also include actions to be run. The algorithm for
|
|
creating the dependency graph is described here.</para>
|
|
|
|
<para>The fundamental concept is <emphasis>generator</emphasis>. If encapsulates
|
|
the notion of build tool and is capable to converting a set of
|
|
input targets into a set of output targets, with some properties.
|
|
Generator matches a build tool as closely as possible: it works
|
|
only when the tool can work with requested properties (for
|
|
example, msvc compiler can't work when requested toolset is gcc),
|
|
and should produce exactly the same targets as the tool (for
|
|
example, if Borland's linker produces additional files with debug
|
|
information, generator should also).</para>
|
|
|
|
<para>Given a set of generators, the fundamental operation is to
|
|
construct a target of a given type, with given properties, from a
|
|
set of targets. That operation is performed by rule
|
|
<literal>generators.construct</literal> and the used algorithm is described
|
|
below.</para>
|
|
|
|
<section>
|
|
<title>Selecting and ranking viable generators</title>
|
|
|
|
<para>Each generator, in addition to target types that it can
|
|
produce, have attribute that affects its applicability in
|
|
particular sitiation. Those attributes are:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<simpara>
|
|
Required properties, which are properties absolutely
|
|
necessary for the generator to work. For example, generator
|
|
encapsulating the gcc compiler would have <toolset>gcc as
|
|
required property.
|
|
</simpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
Optional properties, which increase the generators
|
|
suitability for a particual build.
|
|
</simpara>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>
|
|
Generator's required and optional properties may not include
|
|
either free or incidental properties. (Allowing this would
|
|
greatly complicate caching targets).
|
|
</para>
|
|
|
|
<para>When trying to construct a target, the first step is to select
|
|
all possible generators for the requested target type, which
|
|
required properties are a subset of requested properties.
|
|
Generators that were already selected up the call stack are
|
|
excluded. In addition, if any composing generators were selected
|
|
up the call stack, all other composing generators are ignored
|
|
(TODO: define composing generators). The found generators
|
|
are assigned a rank, which is the number of optional properties
|
|
present in requested properties. Finally, generators with highest
|
|
rank are selected for futher processing.</para>
|
|
|
|
</section>
|
|
<section>
|
|
<title>Running generators</title>
|
|
|
|
<para>When generators are selected, each is run to produce a list of
|
|
created targets. This list might include targets that are not of
|
|
requested types, because generators create the same targets as
|
|
some tool, and tool's behaviour is fixed. (Note: should specify
|
|
that in some cases we actually want extra targets). If generator
|
|
fails, it returns an empty list. Generator is free to call
|
|
'construct' again, to convert sources to the types it can handle.
|
|
It also can pass modified properties to 'construct'. However, a
|
|
generator is not allowed to modify any propagated properties,
|
|
otherwise when actually consuming properties we might discover
|
|
that the set of propagated properties is different from what was
|
|
used for building sources.</para>
|
|
|
|
<para>For all targets that are not of requested types, we try to
|
|
convert them to requested type, using a second call to
|
|
<literal>construct</literal>. This is done in order to support
|
|
transformation sequences where single source file expands to
|
|
several later. See <ulink url=
|
|
"http://groups.yahoo.com/group/jamboost/message/1667">this
|
|
message</ulink> for details.</para>
|
|
|
|
</section>
|
|
|
|
<section>
|
|
<title>Selecting dependency graph</title>
|
|
|
|
<para>
|
|
After all generators are run,
|
|
it is necessary to decide which of successfull invocation will be
|
|
taken as final result. At the moment, this is not done. Instead,
|
|
it is checked whether all successfull generator invocation
|
|
returned the same target list. Error is issued otherwise.
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section>
|
|
<title>Property adjustment</title>
|
|
|
|
<para>Because target location is determined by the build system, it
|
|
is sometimes necessary to adjust properties, in order to not
|
|
break actions. For example, if there's an action that generates
|
|
a header, say "a_parser.h", and a source file "a.cpp" which
|
|
includes that file, we must make everything work as if a_parser.h
|
|
is generated in the same directory where it would be generated
|
|
without any subvariants.</para>
|
|
|
|
<para>Correct property adjustment can be done only after all targets
|
|
are created, so the approach taken is:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>
|
|
When dependency graph is constructed, each action can be
|
|
assigned a rule for property adjustment.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
When virtual target is actualized, that rule is run and
|
|
return the final set of properties. At this stage it can use
|
|
information of all created virtual targets.
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>In case of quoted includes, no adjustment can give 100% correct
|
|
results. If target dirs are not changed by build system, quoted
|
|
includes are searched in "." and then in include path, while angle
|
|
includes are searched only in include path. When target dirs are
|
|
changed, we'd want to make quoted includes to be search in "." then in
|
|
additional dirs and then in the include path and make angle includes
|
|
be searched in include path, probably with additional paths added at
|
|
some position. Unless, include path already has "." as the first
|
|
element, this is not possible. So, either generated headers should not
|
|
be included with quotes, or first element of include path should be
|
|
".", which essentially erases the difference between quoted and angle
|
|
includes. <emphasis role="bold">Note:</emphasis> the only way to get
|
|
"." as include path into compiler command line is via verbatim
|
|
compiler option. In all other case, Boost.Build will convert "." into
|
|
directory where it occurs.</para>
|
|
|
|
</section>
|
|
|
|
<section>
|
|
<title>Transformations cache</title>
|
|
|
|
<para>
|
|
Under certain conditions, an
|
|
attempt is made to cache results of transformation search. First,
|
|
the sources are replaced with targets with special name and the
|
|
found target list is stored. Later, when properties, requested
|
|
type, and source type are the same, the store target list is
|
|
retrieved and cloned, with appropriate change in names.
|
|
</para>
|
|
|
|
</section>
|
|
</section>
|
|
|
|
</chapter>
|
|
|
|
<!--
|
|
Local Variables:
|
|
mode: xml
|
|
sgml-indent-data: t
|
|
sgml-parent-document: ("userman.xml" "chapter")
|
|
sgml-set-face: t
|
|
End:
|
|
-->
|