mirror of
https://github.com/boostorg/build.git
synced 2026-02-10 11:22:12 +00:00
2134 lines
84 KiB
XML
2134 lines
84 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"
|
|
[
|
|
<!ENTITY toolset_ops "<optional><replaceable>version</replaceable></optional> : <optional><replaceable>c++-compile-command</replaceable></optional> : <optional><replaceable>compiler options</replaceable></optional>">
|
|
<!ENTITY option_list_intro "<para>The following options can be provided, using <literal><<replaceable>option-name</replaceable>><replaceable>option-value</replaceable></literal> syntax:</para>">
|
|
<!ENTITY using_repeation "<para>This statement may be repeated several times, if you want to configure several versions of the compiler.</para>">
|
|
]>
|
|
|
|
<chapter id="bbv2.reference"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
<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 are searched 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.advanced.build_request"/>). 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 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>
|
|
|
|
<para>FIXME: That table has moved into "User documentation" section
|
|
and there's nothing we can add here. Remove this part?</para>
|
|
|
|
|
|
</section>
|
|
</section>
|
|
|
|
|
|
</section>
|
|
|
|
<section id="bbv2.reference.rules">
|
|
<title>Builtin rules</title>
|
|
|
|
<para>This section contains the list of all rules that
|
|
can be used in Jamfile—both rules that define new
|
|
targets and auxiliary rules.</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><literal>exe</literal></term>
|
|
|
|
<listitem><para>Creates an executable file. See
|
|
<xref linkend="bbv2.tasks.programs"/>.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>lib</literal></term>
|
|
|
|
<listitem><para>Creates an library file. See
|
|
<xref linkend="bbv2.tasks.libraries"/>.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>install</literal></term>
|
|
|
|
<listitem><para>Installs built targets and other files. See
|
|
<xref linkend="bbv2.tasks.installing"/>.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>alias</literal></term>
|
|
|
|
<listitem><para>Creates an alias for other targets. See
|
|
<xref linkend="bbv2.tasks.alias"/>.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>unit-test</literal></term>
|
|
|
|
<listitem><para>Creates an executable that will be automatically run. See
|
|
<xref linkend="bbv2.tutorial.testing"/>.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>compile</literal></term>
|
|
<term><literal>compile-fail</literal></term>
|
|
<term><literal>link</literal></term>
|
|
<term><literal>link-fail</literal></term>
|
|
<term><literal>run</literal></term>
|
|
<term><literal>run-fail</literal></term>
|
|
|
|
<listitem><para>Specialized rules for testing. See
|
|
<xref linkend="bbv2.tutorial.testing"/>.</para></listitem>
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry>
|
|
<term><literal>obj</literal></term>
|
|
|
|
<listitem><para>Creates an object file. Useful when a single source
|
|
file must be compiled with special properties.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>glob</literal></term>
|
|
|
|
<listitem><para>The <code>glob</code> rule takes a list shell pattern
|
|
and returns the list of files in the project's source directory that
|
|
match the pattern. For example:
|
|
<programlisting>
|
|
lib tools : [ glob *.cpp ] ;
|
|
</programlisting>
|
|
It is possible to also pass a second argument—the list of
|
|
exclude patterns. The result will then include the list of
|
|
files patching any of include patterns, and not matching any
|
|
of the exclude patterns. For example:
|
|
<programlisting>
|
|
lib tools : [ glob *.cpp : file_to_exclude.cpp bad*.cpp ] ;
|
|
</programlisting>
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="bbv2.reference.glob-tree">
|
|
<indexterm><primary>glob-tree</primary></indexterm>
|
|
<term><literal>glob-tree</literal></term>
|
|
|
|
<listitem><para>The <code>glob-tree</code> is similar to the
|
|
<code>glob</code> except that it operates recursively from
|
|
the directory of the containing Jamfile. For example:
|
|
<programlisting>
|
|
ECHO [ glob-tree *.cpp : .svn ] ;
|
|
</programlisting>
|
|
will print the names of all C++ files in your project. The
|
|
<literal>.svn</literal> exclude pattern prevents the
|
|
<code>glob-tree</code> rule from entering administrative
|
|
directories of the Subversion version control system.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>project</literal></term>
|
|
|
|
<listitem><para>Declares project id and attributes, including
|
|
project requirements. See <xref linkend="bbv2.advanced.projects"/>.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>use-project</literal></term>
|
|
|
|
<listitem><para>Assigns a symbolic project ID to a project at
|
|
a given path. This rule must be better documented!
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>explicit</literal></term>
|
|
|
|
<listitem><para>The <literal>explicit</literal> rule takes a single
|
|
parameter—a list of target names. The named targets will
|
|
be marked explicit, and will be built only if they are explicitly
|
|
requested on the command line, or if their dependents are built.
|
|
Compare this to ordinary targets, that are built implicitly when
|
|
their containing project is built.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>constant</literal></term>
|
|
|
|
<listitem><para>Sets project-wide constant. Takes two
|
|
parameters: variable name and a value and makes the specified
|
|
variable name accessible in this Jamfile and any child Jamfiles.
|
|
For example:
|
|
<programlisting>
|
|
constant VERSION : 1.34.0 ;
|
|
</programlisting>
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>path-constant</literal></term>
|
|
|
|
<listitem><para>Same as <literal>constant</literal> except that
|
|
the value is treated as path relative to Jamfile location. For example,
|
|
if <command>bjam</command> is invoked in the current directory,
|
|
and Jamfile in <filename>helper</filename> subdirectory has:
|
|
<programlisting>
|
|
path-constant DATA : data/a.txt ;
|
|
</programlisting>
|
|
then the variable <varname>DATA</varname> will be set to
|
|
<literal>helper/data/a.txt</literal>, and if <command>bjam</command>
|
|
is invoked from the <filename>helper</filename> directory, then
|
|
the variable <varname>DATA</varname> will be set to
|
|
<literal>data/a.txt</literal>.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>build-project</literal></term>
|
|
|
|
<listitem><para>Cause some other project to be built. This rule
|
|
takes a single parameter—a directory name relative to
|
|
the containing Jamfile. When the containing Jamfile is built,
|
|
the project located at that directory will be built as well.
|
|
At the moment, the parameter to this rule should be a directory
|
|
name. Project ID or general target references are not allowed.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>test-suite</literal></term>
|
|
|
|
<listitem><para>This rule is deprecated and equivalent to
|
|
<code>alias</code>.</para></listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</section>
|
|
|
|
<section id="bbv2.advanced.builtins.features">
|
|
<title>Builtin features</title>
|
|
|
|
<variablelist>
|
|
<varlistentry><term><literal>variant</literal></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
A feature that combines several low-level features, making
|
|
it easy to request common build configurations.
|
|
</para>
|
|
|
|
<para><emphasis role="bold">Allowed values:</emphasis> <literal>debug</literal>, <literal>release</literal>,
|
|
<literal>profile</literal>.</para>
|
|
|
|
<para>The value <literal>debug</literal> expands to</para>
|
|
|
|
<programlisting>
|
|
<optimization>off <debug-symbols>on <inlining>off <runtime-debugging>on
|
|
</programlisting>
|
|
|
|
<para>The value <literal>release</literal> expands to</para>
|
|
|
|
<programlisting>
|
|
<optimization>speed <debug-symbols>off <inlining>full <runtime-debugging>off
|
|
</programlisting>
|
|
|
|
<para>The value <literal>profile</literal> expands to the same as
|
|
<literal>release</literal>, plus:</para>
|
|
|
|
<programlisting>
|
|
<profiling>on <debug-symbols>on
|
|
</programlisting>
|
|
|
|
<para>User can define his own build variants using the <code>variant</code> rule from the <code>common</code>
|
|
module.</para>
|
|
|
|
<para><emphasis role="bold">Notee:</emphasis> Runtime
|
|
debugging is on in debug builds to suit the expectations of
|
|
people used to various IDEs.
|
|
<!-- Define "runtime debugging." Why will those people expect it to be on in debug builds? -->
|
|
</para>
|
|
</listitem></varlistentry>
|
|
|
|
<varlistentry id="bbv2.advanced.builtins.features.link">
|
|
<term><literal>link</literal></term>
|
|
|
|
<listitem>
|
|
|
|
<para><emphasis role="bold">Allowed values:</emphasis> <literal>shared</literal>,
|
|
<literal>static</literal></para>
|
|
|
|
<simpara>
|
|
A feature that controls how libraries are built.
|
|
</simpara>
|
|
|
|
</listitem></varlistentry>
|
|
|
|
<varlistentry id="bbv2.advanced.builtins.features.runtime-link">
|
|
<indexterm><primary>runtime linking</primary></indexterm>
|
|
<term><literal>runtime-link</literal></term>
|
|
|
|
<listitem>
|
|
<para><emphasis role="bold">Allowed values:</emphasis> <literal>shared</literal>,
|
|
<literal>static</literal></para>
|
|
|
|
<simpara>
|
|
Controls if a static or shared C/C++ runtime should be used. There
|
|
are some restrictions how this feature can be used, for example
|
|
on some compilers an application using static runtime should
|
|
not use shared libraries at all, and on some compilers,
|
|
mixing static and shared runtime requires extreme care. Check
|
|
your compiler documentation for more details.
|
|
</simpara>
|
|
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry><term><literal>source</literal></term>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
The <code><source>X</code> feature has the same effect on
|
|
building a target as putting X in the list of sources.
|
|
It's useful when you want to add
|
|
the same source to all targets in the project
|
|
(you can put <source> in requirements) or to conditionally
|
|
include a source (using conditional requirements, see <xref linkend="bbv2.tutorial.conditions"/>)
|
|
See also the <code><library></code> feature.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry><term><literal>library</literal></term>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
This feature is almost equivalent to the <code><source></code> feature,
|
|
except that it takes effect only for linking. When you want to
|
|
link all targets in a Jamfile to certain library, the
|
|
<code><library></code> feature is preferred over
|
|
<code><source>X</code> -- the latter will add the library to
|
|
all targets, even those that have nothing to do with libraries.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry><term><anchor id="bbv2.builtin.features.dependency"/>
|
|
<literal>dependency</literal></term>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
Introduces a dependency on the target named by the
|
|
value of this feature (so it will be brought
|
|
up-to-date whenever the target being declared is).
|
|
The dependency is not used in any other way. For example, in
|
|
application with plugins, the plugins are not used when linking
|
|
the application,
|
|
application might have dependency on its plugins, even though
|
|
|
|
|
|
, and
|
|
adds its usage requirements to the build properties
|
|
of the target being declared.
|
|
|
|
The primary use case is when you want
|
|
the usage requirements (such as <code>#include</code> paths) of some
|
|
library to be applied, but don't want to link to it.
|
|
<!-- It's hard to picture why anyone would want to do
|
|
that. Please flesh out this motivation -->
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry><term><anchor id="bbv2.builtin.features.use"/>
|
|
<literal>use</literal></term>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
Introduces a dependency on the target named by the
|
|
value of this feature (so it will be brought
|
|
up-to-date whenever the target being declared is), and
|
|
adds its usage requirements to the build properties
|
|
<!-- Do you really mean "to the requirements?" -->
|
|
of the target being declared. The dependency is not used
|
|
in any other way. The primary use case is when you want
|
|
the usage requirements (such as <code>#include</code> paths) of some
|
|
library to be applied, but don't want to link to it.
|
|
<!-- It's hard to picture why anyone would want to do
|
|
that. Please flesh out this motivation -->
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry><term><anchor id="bbv2.reference.features.dll-path"/>
|
|
<literal>dll-path</literal></term>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
Specify an additional directory where the system should
|
|
look for shared libraries when the executable or shared
|
|
library is run. This feature only affects Unix
|
|
compilers. Plase see <xref linkend="bbv2.faq.dll-path"/>
|
|
in <xref linkend="bbv2.faq"/> for details.
|
|
</simpara>
|
|
</listitem></varlistentry>
|
|
|
|
<varlistentry><term><literal>hardcode-dll-paths</literal></term>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
Controls automatic generation of dll-path properties.
|
|
</simpara>
|
|
|
|
<para><emphasis role="bold">Allowed values:</emphasis>
|
|
<literal>true</literal>, <literal>false</literal>. This property
|
|
is specific to Unix systems. If an executable is built with
|
|
<code><hardcode-dll-paths>true</code>, the generated binary
|
|
will contain the list of all the paths to the used shared
|
|
libraries. As the result, the executable can be run without
|
|
changing system paths to shared libraries or installing the
|
|
libraries to system paths. This
|
|
<!-- you need an antecedent. This _what_? -->
|
|
is very convenient during
|
|
development. Plase see the <link
|
|
linkend="bbv2.faq.dll-path">FAQ entry</link> for details.
|
|
Note that on Mac OSX, the paths are unconditionally hardcoded by
|
|
the linker, and it's not possible to disable that behaviour.
|
|
</para>
|
|
</listitem></varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>cflags</literal></term>
|
|
<term><literal>cxxflags</literal></term>
|
|
<term><literal>linkflags</literal></term>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
The value of those features is passed without modification to the
|
|
corresponding tools. For <code>cflags</code> that's both the C and C++
|
|
compilers, for <code>cxxflags</code> that's the C++ compiler and for
|
|
<code>linkflags</code> that's the linker. The features are handy when
|
|
you're trying to do something special that cannot be achieved by
|
|
higher-level feature in Boost.Build.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry><term><literal>warnings</literal></term>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
The <code><warnings></code> feature controls the warning level of compilers. It has the following values:
|
|
<itemizedlist>
|
|
<listitem><para><code>off</code> - disables all warnings.</para></listitem>
|
|
<listitem><para><code>on</code> - enables default warning level for the tool.</para></listitem>
|
|
<listitem><para><code>all</code> - enables all warnings.</para></listitem>
|
|
</itemizedlist>
|
|
Default value is <code>all</code>.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry><term><literal>warnings-as-errors</literal></term>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
The <code><warnings-as-errors></code> makes it possible to treat warnings as errors and abort
|
|
compilation on a warning. The value <code>on</code> enables this behaviour. The default value is
|
|
<code>off</code>.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry><term><literal>build</literal></term>
|
|
|
|
<listitem>
|
|
<para><emphasis role="bold">Allowed values:</emphasis> <literal>no</literal></para>
|
|
|
|
<para>
|
|
The <code>build</code> feature is used to conditionally disable build of a target. If <code><build>no</code>
|
|
is in properties when building a target, build of that target is skipped. Combined with conditional requirements this
|
|
allows to skip building some target in configurations where the build is known to fail.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry><term><literal>tag</literal></term>
|
|
|
|
<listitem><para>The <literal>tag</literal> feature is used to customize
|
|
the name of the generated files. The value should have the form:
|
|
<programlisting>@<replaceable>rulename</replaceable></programlisting> where
|
|
<replaceable>rulename</replaceable> should be a name of a rule with
|
|
the following signature:
|
|
<programlisting>rule tag ( name : type ? : property-set )</programlisting>
|
|
The rule will be called for each target with the default name computed
|
|
by Boost.Build, the type of the target, and property set. The rule
|
|
can either return a string that must be used as the name of the
|
|
target, or empty string, in which case the default name will be used.
|
|
</para>
|
|
|
|
<para>Most typical use of the <literal>tag</literal> feature is
|
|
to encode build properties, or library version in library target names.
|
|
You should take care to return non-empty string from the tag rule
|
|
only for types you care about — otherwise, you might
|
|
end up modifying names of object files, generated header file and
|
|
other targets for which changing names does not make sense.</para>
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
<varlistentry><term><literal>debug-symbols</literal></term>
|
|
|
|
<listitem>
|
|
<para><emphasis role="bold">Allowed values:</emphasis> <literal>on</literal>, <literal>off</literal>.</para>
|
|
|
|
<para>The <literal>debug-symbols</literal> feature specifies if
|
|
produced object files, executables and libraries should include
|
|
debug information.
|
|
Typically, the value of this feature is implicitly set by the
|
|
<literal>variant</literal> feature, but it can be explicitly
|
|
specified by the user. The most common usage is to build
|
|
release variant with debugging information.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry><term><literal>architecture</literal></term>
|
|
<listitem>
|
|
|
|
<para>The <literal>architecture</literal> features specifies
|
|
the general processor familty to generate code for.</para>
|
|
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry><term><literal>instruction-set</literal></term>
|
|
<indexterm><primary>instruction-set</primary></indexterm>
|
|
<listitem>
|
|
<para>Allowed values for this feature depend on used toolset.</para>
|
|
|
|
<para>The <literal>instruction-set</literal> specifies for which
|
|
specific instruction set the code should be generated. The
|
|
code in general might not run on processors with older/different
|
|
instruction sets.</para>
|
|
|
|
<para>While Boost.Build allows a large set of possible values
|
|
for this features, whether a given value works depends on which
|
|
compiler you use. Please see
|
|
<xref linkend="bbv2.reference.tools.compilers"/> for details.
|
|
</para>
|
|
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry><term><literal>address-model</literal></term>
|
|
<indexterm><primary>64-bit compilation</primary></indexterm>
|
|
<listitem>
|
|
<para><emphasis role="bold">Allowed values:</emphasis> <literal>32</literal>, <literal>64</literal>.</para>
|
|
|
|
<para>The <literal>address-model</literal> specifies if 32-bit or
|
|
64-bit code should be generated by the compiler. Whether this feature
|
|
works depends on the used compiler, it's version, how the compiler
|
|
is configured, and the values of the <literal>architecture</literal>
|
|
<literal>instruction-set</literal>
|
|
features. Please see <xref linkend="bbv2.reference.tools.compilers"/>
|
|
for details.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</section>
|
|
|
|
<section id="bbv2.reference.tools">
|
|
<title>Builtin tools</title>
|
|
|
|
<para>Boost.Build comes with support for a large number of C++ compilers,
|
|
and other tools. This section documents how to use those tools.</para>
|
|
|
|
<para>Before using any tool, you must declare your intention, and possibly
|
|
specify additional information about tool's configuration. This is done
|
|
with the <code>using</code> rule, for example:
|
|
<programlisting>
|
|
using gcc ;
|
|
</programlisting>
|
|
additional parameters can be passed just like for other rules, for example:
|
|
<programlisting>
|
|
using gcc : 4.0 : g++-4.0 ;
|
|
</programlisting>
|
|
The options that can be passed to each tool will be documented in the
|
|
subsequent sections.</para>
|
|
|
|
<section id="bbv2.reference.tools.compilers">
|
|
|
|
<title>C++ Compilers</title>
|
|
|
|
<para>This section lists all Boost.Build modules that support C++
|
|
compilers and documents how each one can be initialized.</para>
|
|
|
|
<section id="bbv2.reference.tools.compiler.gcc">
|
|
|
|
<title>GNU C++</title>
|
|
|
|
<para>The <code>gcc</code> module supports the
|
|
<ulink url="http://gcc.gnu.org">GNU C++ compiler</ulink>
|
|
on Linux, a number of Unix-like system including MacOS X, SunOS and
|
|
BeOS, and on Windows (either <ulink url="http://www.cygwin.com">Cygwin</ulink>
|
|
or <ulink url="http://www.mingw.org">MinGW</ulink>).
|
|
</para>
|
|
|
|
<para>The <code>gcc</code> module is initialized using the following
|
|
syntax:</para>
|
|
<programlisting>
|
|
using gcc : &toolset_ops; ;</programlisting>
|
|
|
|
&using_repeation;
|
|
|
|
<!-- FIXME: mention everywhere what is the semantic
|
|
of version is -->
|
|
|
|
<para>
|
|
If the version is not explicitly specified, it will be
|
|
automatically detected by running the compiler with the <code>-v</code>
|
|
option. If the command is not specified, the <command>g++</command>
|
|
binary will be searched in <envar>PATH</envar>.</para>
|
|
|
|
&option_list_intro;
|
|
<variablelist>
|
|
|
|
<xi:include href="fragments.xml#xpointer(id('common_options')/*)"
|
|
parse="xml"/>
|
|
|
|
<xi:include href="fragments.xml#xpointer(id('root_option')/*)"
|
|
parse="xml"/>
|
|
|
|
<varlistentry>
|
|
<term><literal>rc</literal></term>
|
|
|
|
<listitem>
|
|
<para>Specifies the resource compiler command
|
|
that will be used with the version of gcc that is being
|
|
configured. This setting makes sense only for Windows and only
|
|
if you plan to use resource files. By
|
|
default <command>windres</command> will be used.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>rc-type</literal></term>
|
|
|
|
<listitem>
|
|
<para>Specifies the type of resource compiler. The value can
|
|
be either <code>windres</code> for msvc resource compiler,
|
|
or <code>rc</code> for borland's resource compiler.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
<indexterm><primary>64-bit compilation</primary>
|
|
<secondary>gcc</secondary></indexterm>
|
|
|
|
In order to compile 64-bit applications, you have to specify
|
|
<code>address-model=64</code>, and the <code>instruction-set</code>
|
|
feature should refer to a 64 bit processor. Currently, those
|
|
include <literal>nocona</literal>, <literal>opteron</literal>,
|
|
<literal>athlon64</literal> and <literal>athlon-fx</literal>.
|
|
|
|
</section>
|
|
|
|
|
|
<section id="bbv2.reference.tools.compiler.msvc">
|
|
|
|
<title>Microsoft Visual C++</title>
|
|
|
|
<para>The <code>msvc</code> module supports the
|
|
<ulink url="http://msdn.microsoft.com/visualc/">Microsoft Visual
|
|
C++</ulink> command-line tools on Microsoft Windows. The supported
|
|
products and versions of command line tools are listed below:</para>
|
|
<itemizedlist>
|
|
<listitem><para>Visual Studio 2005—8.0</para></listitem>
|
|
<listitem><para>Visual Studio .NET 2003—7.1</para></listitem>
|
|
<listitem><para>Visual Studio .NET—7.0</para></listitem>
|
|
<listitem><para>Visual Studio 6.0, Service Pack 5—6.5</para></listitem>
|
|
</itemizedlist>
|
|
|
|
<para>The <code>msvc</code> module is initialized using the following
|
|
syntax:</para>
|
|
<programlisting>
|
|
using msvc : &toolset_ops; ;
|
|
</programlisting>
|
|
&using_repeation;
|
|
<para>If the version is not explicitly specified, the most recent
|
|
version found in the registry will be used instead. If the
|
|
special value <code>all</code> is passed as the version, all
|
|
versions found in the registry will be configured. If a version is
|
|
specified, but the command is not, the compiler binary will be
|
|
searched in standard installation paths for that version, followed
|
|
by <envar>PATH</envar>.
|
|
</para>
|
|
|
|
<para>The compiler command should be specified using forward slashes,
|
|
and quoted.</para>
|
|
|
|
&option_list_intro;
|
|
<variablelist>
|
|
|
|
<xi:include href="fragments.xml#xpointer(id('common_options')/*)"
|
|
parse="xml"/>
|
|
|
|
<varlistentry>
|
|
<term><literal>setup</literal></term>
|
|
|
|
<listitem><para>The filename of the environment setup scripts
|
|
to run before invoking the compiler. If not specified,
|
|
<command>vcvars32.bat</command> alongside the compiler binary
|
|
will be used.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>compiler</literal></term>
|
|
|
|
<listitem><para>The command that compiles C and C++ sources.
|
|
If not specified, <command>cl</command> will be used. The
|
|
command will be invoked after the setup script was
|
|
executed and adjusted the <envar>PATH</envar> variable.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>linker</literal></term>
|
|
|
|
<listitem><para>The command that links executables and dynamic
|
|
libraries.
|
|
If not specified, <command>link</command> will be used. The
|
|
command will be invoked after the setup script was
|
|
executed and adjusted the <envar>PATH</envar> variable.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>assembler</literal></term>
|
|
|
|
<listitem><para>The command that compiles assember files.
|
|
If not specified, <command>cl</command> will be used. The
|
|
command will be invoked after the setup script was
|
|
executed and adjusted the <envar>PATH</envar> variable.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>resource-compiler</literal></term>
|
|
|
|
<listitem><para>The command that compiles resource files.
|
|
If not specified, <command>rc</command> will be used. The
|
|
command will be invoked after the setup script was
|
|
executed and adjusted the <envar>PATH</envar> variable.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>idl-compiler</literal></term>
|
|
|
|
<listitem><para>The command that compiles Microsoft COM
|
|
interface definition files.
|
|
If not specified, <command>midl</command> will be used. The
|
|
command will be invoked after the setup script was
|
|
executed and adjusted the <envar>PATH</envar> variable.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>mc-compiler</literal></term>
|
|
|
|
<listitem><para>The command that compiles Microsoft message
|
|
catalog files.
|
|
If not specified, <command>mt</command> will be used. The
|
|
command will be invoked after the setup script was
|
|
executed and adjusted the <envar>PATH</envar> variable.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
|
|
</variablelist>
|
|
|
|
<section>
|
|
<title>64-bit support</title>
|
|
|
|
<indexterm><primary>64-bit compilation</primary>
|
|
<secondary>Microsoft Visual Studio</secondary></indexterm>
|
|
|
|
<para>Starting with version 8.0, Microsoft Visual Studio
|
|
can generate binaries for 64-bit processor, both 64-bit
|
|
flavours of x86 (codenamed AMD64/EM64T), and
|
|
Itanium (codenamed IA64). In addition, compilers that are
|
|
itself run in 64-bit mode, for better performance, are provided.
|
|
The complete list of compiler configurations are as follows
|
|
(we abbreviate AMD64/EM64T to just AMD64):</para>
|
|
<itemizedlist>
|
|
<listitem><para>32-bit x86 host, 32-bit x86 target</para>
|
|
</listitem>
|
|
<listitem><para>32-bit x86 host, 64-bit AMD64 target</para>
|
|
</listitem>
|
|
<listitem><para>32-bit x86 host, 64-bit IA64 target</para>
|
|
</listitem>
|
|
<listitem><para>64-bit AMD64 host, 64-bit AMD64 target</para>
|
|
</listitem>
|
|
<listitem><para>64-bit IA64 host, 64-bit IA64 target</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
The 32-bit host compilers can be always used, even on 64-bit Windows.
|
|
On the contrary, 64-bit host compilers require both 64-bit
|
|
host processor and 64-bit Windows, but can be faster. By default,
|
|
only 32-bit host, 32-bit target compiler is installed, and additional
|
|
compilers should be installed explicitly.
|
|
</para>
|
|
|
|
<para>To use 64-bit compilation you should:</para>
|
|
<orderedlist>
|
|
<listitem><para>Configure you compiler as usual. If you provide
|
|
a path to the compiler explicitly, provide the path to the
|
|
32-bit compiler. If you try to specify the path to any of 64-bit
|
|
compilers, configuration won't work.</para>
|
|
</listitem>
|
|
|
|
<listitem><para>When compiling, use <code>address-model=64</code>,
|
|
to generate AMD64 code.</para></listitem>
|
|
|
|
<listitem><para>To generate IA64 code, use
|
|
<code>architecture=ia64</code></para></listitem>
|
|
</orderedlist>
|
|
|
|
<para>The (AMD64 host, AMD64 target) compiler will be used
|
|
automatically when you're generating AMD64 code and are
|
|
running 64-bit Windows on AMD64. The (IA64 host, IA64 target)
|
|
compiler won't be ever used, since nobody has an IA64 machine
|
|
to test.</para>
|
|
|
|
<para>It is believed that AMD64 and EM64T targets are essentially
|
|
compatible. The compiler options <code>/favor:AMD64</code>
|
|
and <code>/favor:EM64T</code>, which are accepted only by
|
|
AMD64 targeting compilers, cause the generated code to be
|
|
tuned to a specific flavor of 64-bit x86. Boost.Build will
|
|
make use of those options depending on the value
|
|
of the<code>instruction-set</code> feature.</para>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section id="bbv2.reference.tools.compiler.intel">
|
|
|
|
<title>Intel C++</title>
|
|
|
|
<para>The <code>intel-linux</code> and <code>intel-win</code> modules
|
|
support the Intel C++ command-line compiler—the <ulink url=
|
|
"http://www.intel.com/software/products/compilers/clin/index.htm">Linux</ulink>
|
|
and <ulink url=
|
|
"http://www.intel.com/cd/software/products/asmo-na/eng/compilers/284527.htm">
|
|
Windows</ulink> versions respectively.</para>
|
|
|
|
<para>The module is initialized using the following syntax:</para>
|
|
<programlisting>
|
|
using intel-linux : &toolset_ops; ;</programlisting>
|
|
<para>or</para>
|
|
<programlisting>
|
|
using intel-win : &toolset_ops; ;</programlisting>
|
|
<para>respectively.</para>
|
|
|
|
&using_repeation;
|
|
|
|
<para>
|
|
If compiler command is not specified, then Boost.Build will
|
|
look in <envar>PATH</envar> for an executable <command>icpc</command>
|
|
(on Linux), or <command>icc.exe</command> (on Windows).
|
|
</para>
|
|
|
|
&option_list_intro;
|
|
<variablelist>
|
|
|
|
<xi:include href="fragments.xml#xpointer(id('common_options')/*)"
|
|
parse="xml"/>
|
|
|
|
</variablelist>
|
|
|
|
<para>The Linux version supports the following additional options:</para>
|
|
<variablelist>
|
|
|
|
<xi:include href="fragments.xml#xpointer(id('root_option')/*)"
|
|
parse="xml"/>
|
|
|
|
</variablelist>
|
|
|
|
<!-- the compatibility option appears to be messed up -->
|
|
|
|
</section>
|
|
|
|
<section id="bbv2.reference.tools.compiler.acc">
|
|
|
|
<title>HP aC++ compiler</title>
|
|
|
|
<para>The <code>acc</code> module supports the
|
|
<ulink url="http://h21007.www2.hp.com/dspp/tech/tech_TechSoftwareDetailPage_IDX/1,1703,1740,00.html">HP aC++ compiler</ulink>
|
|
for the HP-UX operating system.</para>
|
|
|
|
<para>The module is initialized using the following
|
|
syntax:</para>
|
|
<programlisting>
|
|
using acc : &toolset_ops; ;</programlisting>
|
|
|
|
&using_repeation;
|
|
|
|
|
|
<para>
|
|
If the command is not specified, the <command>aCC</command>
|
|
binary will be searched in <envar>PATH</envar>.</para>
|
|
|
|
&option_list_intro;
|
|
<variablelist>
|
|
<xi:include href="fragments.xml#xpointer(id('common_options')/*)"
|
|
parse="xml"/>
|
|
</variablelist>
|
|
|
|
</section>
|
|
|
|
<section id="bbv2.reference.tools.compiler.borland">
|
|
|
|
<title>Borland C++ Compiler</title>
|
|
|
|
<para>The <code>borland</code> module supports the command line
|
|
C++ compiler included in
|
|
<ulink url="http://www.borland.com/us/products/cbuilder/index.html">C++ Builder 2006</ulink>
|
|
product and earlier version of it, running on Microsoft Windows.</para>
|
|
|
|
<para>The supported products are listed below. The version reported
|
|
by the command lines tools is also listed for reference.:</para>
|
|
<itemizedlist>
|
|
<listitem><para>C++ Builder 2006—5.8.2</para></listitem>
|
|
<listitem><para>CBuilderX—5.6.5, 5.6.4 (depending on release)</para></listitem>
|
|
<listitem><para>CBuilder6—5.6.4</para></listitem>
|
|
<listitem><para>Free command line tools—5.5.1</para></listitem>
|
|
</itemizedlist>
|
|
|
|
<para>The module is initialized using the following syntax:</para>
|
|
<programlisting>
|
|
using borland : &toolset_ops; ;</programlisting>
|
|
|
|
&using_repeation;
|
|
|
|
<para>If the command is not specified, Boost.Build will search for
|
|
a binary named <command>bcc32</command> in <envar>PATH</envar>.</para>
|
|
|
|
&option_list_intro;
|
|
<variablelist>
|
|
<xi:include href="fragments.xml#xpointer(id('common_options')/*)"
|
|
parse="xml"/>
|
|
</variablelist>
|
|
|
|
</section>
|
|
|
|
<section id="bbv2.reference.tools.compiler.como">
|
|
|
|
<title>Comeau C/C++ Compiler</title>
|
|
|
|
<para>The <code>como-linux</code> and the <code>como-win</code>
|
|
modules supports the
|
|
<ulink url="http://www.comeaucomputing.com/">Comeau C/C++ Compiler</ulink>
|
|
on Linux and Windows respectively.</para>
|
|
|
|
<para>The module is initialized using the following syntax:</para>
|
|
<programlisting>
|
|
using como-linux : &toolset_ops; ;</programlisting>
|
|
|
|
&using_repeation;
|
|
|
|
<para>If the command is not specified, Boost.Build will search for
|
|
a binary named <command>como</command> in
|
|
<envar>PATH</envar>.</para>
|
|
|
|
&option_list_intro;
|
|
<variablelist>
|
|
<xi:include href="fragments.xml#xpointer(id('common_options')/*)"
|
|
parse="xml"/>
|
|
</variablelist>
|
|
|
|
<para>Before using the windows version of the compiler,
|
|
you need to setup necessary environment variables per compiler's
|
|
documentation. In particular, the <envar>COMO_XXX_INCLUDE</envar>
|
|
variable should be set, where <envar>XXX</envar> corresponds to the
|
|
used backend C compiler.</para>
|
|
|
|
</section>
|
|
|
|
<section id="bbv2.reference.tools.compiler.cw">
|
|
|
|
<title>Code Warrior</title>
|
|
|
|
<para>The <code>cw</code> module support CodeWarrior compiler,
|
|
originally produced by Metrowerks and presently developed
|
|
by Freescale. Boost.Build supports only the versions of the compiler
|
|
that target x86 processors. All such versions were released by
|
|
Metrowerks before aquisition and are not sold any longer.
|
|
The last version known to work is 9.4</para>
|
|
|
|
<para>The module is initialized using the following syntax:</para>
|
|
<programlisting>
|
|
using cw : &toolset_ops; ;</programlisting>
|
|
|
|
&using_repeation;
|
|
|
|
<para>If the command is not specified, Boost.Build will search for
|
|
a binary named <command>mwcc</command> in default installation
|
|
paths and in <envar>PATH</envar>.</para>
|
|
|
|
&option_list_intro;
|
|
<variablelist>
|
|
|
|
<xi:include href="fragments.xml#xpointer(id('common_options')/*)"
|
|
parse="xml"/>
|
|
|
|
<xi:include href="fragments.xml#xpointer(id('root_option')/*)"
|
|
parse="xml"/>
|
|
|
|
<varlistentry>
|
|
<term><literal>setup</literal></term>
|
|
|
|
<listitem><para>The command that sets up environment variables
|
|
prior to invoking the compiler. If not specified,
|
|
<command>cwenv.bat</command> alongside the compiler binary
|
|
will be used.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry>
|
|
<term><literal>compiler</literal></term>
|
|
|
|
<listitem><para>The command that compiles C and C++ sources.
|
|
If not specified, <command>mwcc</command> will be used. The
|
|
command will be invoked after the setup script was
|
|
executed and adjusted the <envar>PATH</envar> variable.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>linker</literal></term>
|
|
|
|
<listitem><para>The command that links executables and dynamic
|
|
libraries.
|
|
If not specified, <command>mwld</command> will be used. The
|
|
command will be invoked after the setup script was
|
|
executed and adjusted the <envar>PATH</envar> variable.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</section>
|
|
|
|
<section id="bbv2.reference.tools.compiler.dmc">
|
|
|
|
<title>Digital Mars C/C++ Compiler</title>
|
|
|
|
<para>The <code>dmc</code> module supports the
|
|
<ulink url="http://www.digitalmars.com/">Digital Mars C++ compiler.</ulink>
|
|
</para>
|
|
|
|
<para>The module is initialized using the following syntax:</para>
|
|
<programlisting>
|
|
using dmc : &toolset_ops; ;</programlisting>
|
|
|
|
&using_repeation;
|
|
|
|
<para>If the command is not specified, Boost.Build will search for
|
|
a binary named <command>como</command> in
|
|
<envar>PATH</envar>.</para>
|
|
|
|
&option_list_intro;
|
|
<variablelist>
|
|
<xi:include href="fragments.xml#xpointer(id('common_options')/*)"
|
|
parse="xml"/>
|
|
</variablelist>
|
|
|
|
</section>
|
|
|
|
<section id="bbv2.reference.tools.compiler.hp_cxx">
|
|
|
|
<title>HP C++ Compiler for Tru64 Unix</title>
|
|
|
|
<para>The <code>hp_cxx</code> modules supports the
|
|
<ulink url="http://h30097.www3.hp.com/cplus/?jumpid=reg_R1002_USEN">
|
|
HP C++ Compiler</ulink> for Tru64 Unix.</para>
|
|
|
|
<para>The module is initialized using the following syntax:</para>
|
|
<programlisting>
|
|
using hp_cxx : &toolset_ops; ;</programlisting>
|
|
|
|
&using_repeation;
|
|
|
|
<para>If the command is not specified, Boost.Build will search for
|
|
a binary named <command>hp_cxx</command> in <envar>PATH</envar>.</para>
|
|
|
|
&option_list_intro;
|
|
<variablelist>
|
|
<xi:include href="fragments.xml#xpointer(id('common_options')/*)"
|
|
parse="xml"/>
|
|
</variablelist>
|
|
|
|
</section>
|
|
|
|
<section id="bbv2.reference.tools.compiler.sun">
|
|
|
|
<title>Sun Studio</title>
|
|
|
|
<para>The <code>sun</code> module supports the
|
|
<ulink url="http://developers.sun.com/sunstudio/index.jsp">
|
|
Sun Studio</ulink> C++ compilers for the Solaris OS.</para>
|
|
|
|
<para>The module is initialized using the following syntax:</para>
|
|
<programlisting>
|
|
using sun : &toolset_ops; ;</programlisting>
|
|
|
|
&using_repeation;
|
|
|
|
<para>If the command is not specified, Boost.Build will search for
|
|
a binary named <command>CC</command>
|
|
in <filename>/opt/SUNWspro/bin</filename> and in
|
|
<envar>PATH</envar>.</para>
|
|
|
|
<para>When using this compiler on complex C++ code, such as the
|
|
<ulink url="http://boost.org">Boost C++ library</ulink>, it is
|
|
recommended to specify the following options when intializing the
|
|
<code>sun</code> module:
|
|
<screen>
|
|
-library=stlport4 -features=tmplife -features=tmplrefstatic
|
|
</screen> See the <ulink url="http://blogs.sun.com/sga/entry/command_line_options">
|
|
Sun C++ Frontend Tales</ulink> for details.</para>
|
|
|
|
&option_list_intro;
|
|
<variablelist>
|
|
<xi:include href="fragments.xml#xpointer(id('common_options')/*)"
|
|
parse="xml"/>
|
|
</variablelist>
|
|
|
|
<indexterm><primary>64-bit compilation</primary>
|
|
<secondary>Sun Studio</secondary></indexterm>
|
|
Starting with Sun Studio 12, you can create 64-bit applications
|
|
by using the <code>address-model=64</code> property.
|
|
|
|
</section>
|
|
|
|
<section id="bbv2.reference.tools.compiler.vacpp">
|
|
|
|
<title>IBM Visual Age</title>
|
|
<para>The <code>vacpp</code> module supports the
|
|
<ulink url="http://www.ibm.com/software/ad/vacpp">IBM Visual
|
|
Age</ulink> C++ Compiler, for the AIX operating system. Versions
|
|
7.1 and 8.0 are known to work.</para>
|
|
|
|
<para>The module is initialized using the following
|
|
syntax:</para>
|
|
<programlisting>
|
|
using vacpp ;</programlisting>
|
|
|
|
<para>The module does not accept any initialization options. The
|
|
compiler should be installed in the <filename>/usr/vacpp/bin</filename>
|
|
directory.</para>
|
|
|
|
<para>Later versions of Visual Age are known as XL C/C++. They
|
|
were not tested with the the <code>vacpp</code> module.</para>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section>
|
|
<title>Third-party libraries</title>
|
|
|
|
<para>Boost.Build provides special support for some
|
|
third-party C++ libraries, documented below.</para>
|
|
|
|
<section id="bbv2.reference.tools.libraries.stlport">
|
|
<title>STLport library</title>
|
|
<indexterm><primary>STLport</primary></indexterm>
|
|
|
|
<para>The <ulink url="http://stlport.org">STLport</ulink> library
|
|
is an alternative implementation of C++ runtime library. Boost.Build
|
|
supports using that library on Windows platfrom. Linux is
|
|
hampered by different naming of libraries in each STLport
|
|
version and is not officially supported.</para>
|
|
|
|
<para>Before using STLport, you need to configure it in
|
|
<filename>user-config.jam</filename> using the following syntax:
|
|
</para>
|
|
<programlisting>
|
|
using stlport : <optional><replaceable>version</replaceable></optional> : <replaceable>header-path</replaceable> : <optional><replaceable>library-path</replaceable></optional> ;
|
|
</programlisting>
|
|
<para>
|
|
Where <replaceable>version</replaceable> is the version of
|
|
STLport, for example <literal>5.1.4</literal>,
|
|
<replaceable>headers</replaceable> is the location where
|
|
STLport headers can be found, and <replaceable>libraries</replaceable>
|
|
is the location where STLport libraries can be found.
|
|
The version should always be provided, and the library path should
|
|
be provided if you're using STLport's implementation of
|
|
iostreams. Note that STLport 5.* always uses its own iostream
|
|
implementation, so the library path is required.
|
|
</para>
|
|
|
|
<para>When STLport is configured, you can build with STLport by
|
|
requesting <literal>stdlib=stlport</literal> on the command line.
|
|
</para>
|
|
|
|
</section>
|
|
|
|
</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 properties 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 the set of properties
|
|
in b's condition is a strict subset of the set of properities of
|
|
'a's condition. If there's one viable alternative, which is
|
|
better than all others, 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:
|
|
-->
|