mirror of
https://github.com/boostorg/build.git
synced 2026-02-10 23:32:20 +00:00
1236 lines
50 KiB
XML
1236 lines
50 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.advanced">
|
|
<title>Overview</title>
|
|
|
|
<para>This section will provide the information necessary to create your own
|
|
projects using Boost.Build. The information provided here is relatively
|
|
high-level, and <xref linkend="bbv2.reference"/> as
|
|
well as the on-line help system must be used to obtain
|
|
low-level documentation (see <xref linkend=
|
|
"bbv2.reference.init.options.help"/>).</para>
|
|
|
|
<para>Boost.Build actually consists of two parts - Boost.Jam, a
|
|
build engine with its own interpreted language, and Boost.Build itself,
|
|
implemented in Boost.Jam's language. The chain of events when
|
|
you type <command>bjam</command> on the command line is:
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Boost.Jam tries to find Boost.Build and loads the top-level
|
|
module. The exact process is described in <xref
|
|
linkend="bbv2.reference.init"/></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>The top-level module loads user-defined configuration
|
|
files, <filename>user-config.jam</filename> and <filename>site-config.jam</filename>, which define
|
|
available toolsets.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>The Jamfile in the current directory is read. That in turn
|
|
might cause reading of further Jamfiles. As a result, a tree of
|
|
projects is created, with targets inside projects.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Finally, using the build request specified on the command line,
|
|
Boost.Build decides which targets should be built, and how. That
|
|
information is passed back to Boost.Jam, which takes care of
|
|
actually running commands.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</para>
|
|
|
|
<para>So, to be able to successfully use Boost.Build, you need to know only
|
|
four things:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><link linkend="bbv2.advanced.configuration">
|
|
How to configure Boost.Build</link></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><link linkend="bbv2.advanced.targets">
|
|
How to write declares targets in Jamfiles</link></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><link linkend="bbv2.advanced.build_process">
|
|
How the build process works</link></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Some Basics about the Boost.Jam language. See
|
|
<xref linkend="bbv2.advanced.jam_language"/>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<section id="bbv2.advanced.jam_language">
|
|
<title>Boost.Jam Language</title>
|
|
|
|
<para>This section will describe the basics of the Boost.Jam
|
|
language—just enough for writing Jamfiles. For more information,
|
|
please see the <link linkend="bbv2.jam">Boost.Jam</link>
|
|
documentation.</para>
|
|
|
|
<para>Boost.Jam has an interpreted, procedural language.
|
|
On the lowest level, a Boost.Jam program consists of variables and
|
|
<indexterm><primary>rule</primary></indexterm>
|
|
<firstterm>rules</firstterm> (the Jam term for function). They are grouped
|
|
in modules—there's one global module and a number of named
|
|
modules. Besides that, a Boost.Jam program contains classes and class
|
|
instances.
|
|
</para>
|
|
|
|
<para>Syntantically, a Boost.Jam program consists of two kind of
|
|
elements—keywords (which have a special meaning to Boost.Jam) and
|
|
literals.
|
|
|
|
Consider this code:
|
|
<programlisting>
|
|
a = b ;</programlisting>
|
|
which assigns the value <literal>b</literal> to the variable
|
|
<literal>a</literal>. Here, <literal>=</literal> and
|
|
<literal>;</literal> are keywords, while <literal>a</literal> and
|
|
<literal>b</literal> are literals.
|
|
<warning>
|
|
<para>All syntax elements, even keywords, must be separated by
|
|
spaces. For example, omitting the space character before
|
|
<literal>;</literal> will lead to a syntax error.
|
|
</para>
|
|
</warning>
|
|
If you want to use a literal value that is the same as some keyword, the
|
|
value can be quoted:
|
|
<programlisting>
|
|
a = "=" ;</programlisting>
|
|
</para>
|
|
|
|
<para>All variables in Boost.Jam have the same type—list of
|
|
strings. To define a variable one assigns a value to it, like in the
|
|
previous example. An undefined variable is the same as a variable with
|
|
an empty value. Variables can be accessed with the
|
|
<code>$(<replaceable>variable</replaceable>)</code> syntax. For example:
|
|
<programlisting>
|
|
a = $(b) $(c) ;</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
Rules are defined by specifying the rule name, the parameter names,
|
|
and the allowed size of the list value for each parameter.
|
|
<programlisting>
|
|
rule <replaceable>example</replaceable>
|
|
(
|
|
<replaceable>parameter1</replaceable> :
|
|
<replaceable>parameter2 ?</replaceable> :
|
|
<replaceable>parameter3 +</replaceable> :
|
|
<replaceable>parameter4 *</replaceable>
|
|
)
|
|
{
|
|
// body
|
|
}</programlisting>
|
|
When this rule is called, the list passed as the first argument must
|
|
have exactly one value. The list passed as the second argument can
|
|
either have one value of be empty. The two remaining arguments can
|
|
be arbitrary long, but the third argument may not be empty.
|
|
</para>
|
|
|
|
<para>The overview of Boost.Jam language statements is given below:
|
|
<programlisting>
|
|
helper 1 : 2 : 3 ;
|
|
x = [ helper 1 : 2 : 3 ] ;</programlisting>
|
|
This code calls the named rule with the specified arguments. When the
|
|
result of the call must be used inside some expression, you need to add
|
|
brackets around the call, like shown on the second line.
|
|
<programlisting>
|
|
if cond { statements } [ else { statements } ]</programlisting>
|
|
This is a regular if-statement. The condition is composed of:
|
|
<itemizedlist>
|
|
<listitem><para>Literals (true if at least one string is not empty)</para></listitem>
|
|
<listitem><para>Comparisons: <code>a
|
|
<replaceable>operator</replaceable> b</code> where
|
|
<replaceable>operator</replaceable> is one of <code>=</code>,
|
|
<code>!=</code>, <code><</code>, <code>></code>,
|
|
<code><=</code>, <code>>=</code>. The comparison is done
|
|
pairwise between each string in the left and the right arguments.
|
|
</para>
|
|
</listitem>
|
|
<listitem><para>Logical operations: <code>! a</code>, <code>a &&
|
|
b</code>, <code>a || b</code></para></listitem>
|
|
<listitem><para>Grouping: <code>( cond )</code></para></listitem>
|
|
</itemizedlist>
|
|
<programlisting>
|
|
for var in list { statements }</programlisting>
|
|
Executes statements for each element in list, setting the variable
|
|
<varname>var</varname> to the element value.
|
|
<programlisting>
|
|
while cond { statements }</programlisting>
|
|
Repeatedly execute statements while cond remains true upon entry.
|
|
<programlisting>
|
|
return values ;
|
|
</programlisting>This statement should be used only inside a
|
|
rule and assigns <code>values</code> to the return value of the
|
|
rule.
|
|
<warning><para>
|
|
The <code>return</code> statement does not exit the rule. For example:
|
|
<programlisting>
|
|
rule test ( )
|
|
{
|
|
if 1 = 1 {
|
|
return "reasonable" ;
|
|
}
|
|
return "strange" ;
|
|
}</programlisting> will return <literal>strange</literal>, not
|
|
<literal>reasonable</literal>.
|
|
</para></warning>
|
|
|
|
<programlisting>
|
|
import <replaceable>module</replaceable> ;
|
|
import <replaceable>module</replaceable> : <replaceable>rule</replaceable> ;</programlisting>
|
|
The first form imports the specified bjam module. All rules from
|
|
that module are made available using the qualified name:
|
|
<code><replaceable>module</replaceable>.<replaceable>rule</replaceable></code>.
|
|
The second form imports the specified rules only, and they can be called
|
|
using unqualified names.
|
|
</para>
|
|
|
|
<para id="bbv2.advanced.jam_language.actions">
|
|
Sometimes, you'd need to specify the actual command lines to be used
|
|
when creating targets. In jam language, you use named actions to do this.
|
|
For example:
|
|
<programlisting>
|
|
actions create-file-from-another
|
|
{
|
|
create-file-from-another $(<) $(>)
|
|
}
|
|
</programlisting>
|
|
This specifies a named action called
|
|
<literal>create-file-from-another</literal>. The text inside braces is the
|
|
command to invoke. The <literal>$(<)</literal> variable will be expanded to list of
|
|
generated files, and the <literal>$(>)</literal> variable will be expanded
|
|
to the list of source files.
|
|
</para>
|
|
|
|
<para>To flexibly adjust command line, you can define a rule with the
|
|
same name as the action, and taking three parameters -- targets, sources
|
|
and properties. For example:
|
|
<programlisting>
|
|
rule create-file-from-another ( targets * : sources * : properties * )
|
|
{
|
|
if <variant>debug in $(properties)
|
|
{
|
|
OPTIONS on $(targets) = --debug ;
|
|
}
|
|
}
|
|
actions create-file-from-another
|
|
{
|
|
create-file-from-another $(OPTIONS) $(<) $(>)
|
|
}
|
|
</programlisting>
|
|
In this example, the rule checks if certain build property is specified.
|
|
If so, it sets variable <varname>OPIONS</varname> that's used inside
|
|
action. Note that the variable is set "on targets" -- the value will
|
|
be only visible inside action, not globally. Were it set globally,
|
|
using variable named <varname>OPTIONS</varname> in two unrelated
|
|
actions would be impossible.
|
|
</para>
|
|
|
|
<para>More details can be found in Jam reference, <xref linkend="jam.language.rules"/>
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section id="bbv2.advanced.configuration">
|
|
<title>Configuration</title>
|
|
|
|
<para>The Boost.Build configuration is specified in the file
|
|
<filename>user-config.jam</filename>. You can edit the one in the top-level
|
|
directory of Boost.Build installation or create a copy in your home directory
|
|
and edit that. (See <xref linkend="bbv2.reference.init.config"/> for the
|
|
exact search paths.) The primary function of that file is to declare which
|
|
compilers and other tools are available. The simplest syntax to configure
|
|
a tool is:
|
|
|
|
<programlisting>
|
|
using <replaceable>tool-name</replaceable> ;
|
|
</programlisting>
|
|
The <functionname>using</functionname> rule is given a name of tool, and will make that tool
|
|
available to Boost.Build. For example, <code>using gcc ;</code> will make the gcc compiler
|
|
available.
|
|
</para>
|
|
|
|
<para>
|
|
Since nothing but a tool name is specified, Boost.Build will
|
|
pick some default settings. For example, it will use the
|
|
<command>gcc</command> executable found in the
|
|
<envar>PATH</envar>, or look in some known installation
|
|
locations. In most cases, this strategy works automatically. In
|
|
case you have several versions of a compiler, it's installed in
|
|
some unusual location, or you need to tweak its configuration,
|
|
you'll need to pass additional parameters to the
|
|
<functionname>using</functionname> rule. The parameters to
|
|
<functionname>using</functionname> can be different for each
|
|
tool. You can obtain specific documentation for any tool's
|
|
configuration parameters by invoking
|
|
<programlisting>
|
|
bjam --help <replaceable>tool-name</replaceable>.init
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
That said, for all the compiler toolsets Boost.Build supports
|
|
out-of-the-box, the list of parameters to
|
|
<functionname>using</functionname> is the same: <parameter
|
|
class="function">toolset-name</parameter>, <parameter
|
|
class="function">version</parameter>, <parameter
|
|
class="function">invocation-command</parameter>, and <parameter
|
|
class="function">options</parameter>.
|
|
<!-- the previous text here was really confusing -->
|
|
</para>
|
|
|
|
<para>The <parameter class="function">version</parameter>
|
|
parameter identifies the toolset version, in case you have
|
|
several installed. It can have any form you like, but
|
|
it's recommended that you use a numeric identifier like
|
|
<literal>7.1</literal>.
|
|
</para>
|
|
|
|
<para>
|
|
The <parameter class="function">invocation-command</parameter>
|
|
parameter is the command that must be executed to run the
|
|
compiler. This parameter can usually be omitted if the compiler
|
|
executable
|
|
<itemizedlist>
|
|
<listitem><para>has its “usual
|
|
name” and is in the <envar>PATH</envar>,
|
|
or</para></listitem>
|
|
<listitem><para>was installed in a standard
|
|
“installation directory”,
|
|
or</para></listitem>
|
|
|
|
<listitem><para>can be found through a global mechanism like the
|
|
Windows registry.</para></listitem>
|
|
</itemizedlist>
|
|
|
|
For example:
|
|
<programlisting>
|
|
using msvc : 7.1 ;
|
|
using gcc ;
|
|
</programlisting>
|
|
If the compiler can be found in the <envar>PATH</envar> but only by a
|
|
nonstandard name, you can just supply that name:
|
|
<programlisting>
|
|
using gcc : : g++-3.2 ;
|
|
</programlisting>
|
|
Otherwise, it might be necessary to supply the complete path to the
|
|
compiler executable:
|
|
<programlisting>
|
|
using msvc : : "Z:/Programs/Microsoft Visual Studio/vc98/bin/cl" ;
|
|
</programlisting>
|
|
Some Boost.Build toolsets will use that path to take additional
|
|
actions required before invoking the compiler, such as calling
|
|
vendor-supplied scripts to set up its required environment variables.
|
|
When compiler executables for C and C++ are different, path to the C++
|
|
compiler executable must be specified. The “invocation command”
|
|
can be any command allowed by the operating system. For example:
|
|
<programlisting>
|
|
using msvc : : echo Compiling && foo/bar/baz/cl ;
|
|
</programlisting>
|
|
will work.
|
|
</para>
|
|
|
|
<para>To configure several versions of a toolset, simply invoke
|
|
the <functionname>using</functionname> rule multiple times:
|
|
<programlisting>
|
|
using gcc : 3.3 ;
|
|
using gcc : 3.4 : g++-3.4 ;
|
|
using gcc : 3.2 : g++-3.2 ;
|
|
</programlisting>
|
|
Note that in the first call to
|
|
<functionname>using</functionname>, the compiler found in the
|
|
<envar>PATH</envar> will be used, and there's no need to
|
|
explicitly specify the command.
|
|
</para>
|
|
|
|
<para>As shown above, both the <parameter
|
|
class="function">version</parameter> and <parameter
|
|
class="function">invocation-command</parameter> parameters are
|
|
optional, but there's an important restriction: if you configure
|
|
the same toolset more than once, you must pass the <parameter
|
|
class="function">version</parameter>
|
|
parameter every time. For example, the following is not allowed:
|
|
<programlisting>
|
|
using gcc ;
|
|
using gcc : 3.4 : g++-3.4 ;
|
|
</programlisting>
|
|
because the first <functionname>using</functionname> call does
|
|
not specify a <parameter class="function">version</parameter>.
|
|
</para>
|
|
|
|
<para>The <parameter class="function">options</parameter>
|
|
parameter is used to fine-tune the configuration. All of
|
|
Boost.Build's standard compiler toolsets accept properties of the
|
|
four builtin features <varname>cflags</varname>,
|
|
<varname>cxxflags</varname>, <varname>compileflags</varname> and
|
|
<varname>linkflags</varname> as <parameter
|
|
class="function">options</parameter> specifying flags that will be
|
|
always passed to the corresponding tools. Values of the
|
|
<varname>cflags</varname> feature are passed directly to the C
|
|
compiler, values of the <varname>cxxflags</varname> feature are
|
|
passed directly to the C++ compiler, and values of the
|
|
<varname>compileflags</varname> feature are passed to both. For
|
|
example, to configure a <command>gcc</command> toolset so that it
|
|
always generates 64-bit code you could write:
|
|
<programlisting>
|
|
using gcc : 3.4 : : <compileflags>-m64 <linkflags>-m64 ;
|
|
</programlisting>
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section id="bbv2.advanced.invocation">
|
|
<title>Invocation</title>
|
|
|
|
<para>This section describes how invoke Boost.Build from the command line</para>
|
|
|
|
<para>To build all targets defined in Jamfile in the current directory with default properties, run:
|
|
<screen>
|
|
bjam
|
|
</screen></para>
|
|
|
|
<para>To build specific targets, specify them on the command line:
|
|
<screen>
|
|
bjam lib1 subproject//lib2
|
|
</screen>
|
|
</para>
|
|
|
|
<para>To request a certain value for some property, add <literal>
|
|
<replaceable>property</replaceable>=<replaceable>value</replaceable></literal> to the command line:
|
|
<screen>
|
|
bjam toolset=gcc variant=debug optimization=space
|
|
</screen>
|
|
For often used features, like <literal>toolset</literal> and <literal>variant</literal> you can
|
|
omit the feature name, so the above can be written as:
|
|
<screen>
|
|
bjam optimization=space
|
|
</screen>
|
|
</para>
|
|
|
|
|
|
<para>Boost.Build recognizes the following command line options.</para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term><option>--clean</option></term>
|
|
<listitem>
|
|
<para>Cleans all targets in the current directory and
|
|
in any subprojects. Note that unlike the <literal>clean</literal>
|
|
target in make, you can use <literal>--clean</literal>
|
|
together with target names to clean specific targets.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--clean-all</option></term>
|
|
<listitem>
|
|
<para>Cleans all targets,
|
|
no matter where they are defined. In particular, it will clean targets
|
|
in parent Jamfiles, and targets defined under other project roots.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--build-dir</option></term>
|
|
<listitem>
|
|
<para>Changes build directories for all project roots being built. When
|
|
this option is specified, all Jamroot files should declare project name.
|
|
The build directory for the project root will be computed by concatanating
|
|
the value of the <option>--build-dir</option> option, the project name
|
|
specified in Jamroot, and the build dir specified in Jamroot
|
|
(or <literal>bin</literal>, if none is specified).
|
|
</para>
|
|
|
|
<para>The option is primarily useful when building from read-only
|
|
media, when you can't modify Jamroot.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--version</option></term>
|
|
<listitem>
|
|
<para>Prints information on Boost.Build and Boost.Jam
|
|
versions.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="bbv2.reference.init.options.help">
|
|
<term><option>--help</option></term>
|
|
<listitem>
|
|
<para>Invokes the online help system. This prints general
|
|
information on how to use the help system with additional
|
|
--help* options.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--debug-configuration</option></term>
|
|
<listitem>
|
|
<para>Produces debug information about loading of Boost.Build
|
|
and toolset files.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--debug-building</option></term>
|
|
<listitem>
|
|
<para>Prints what targets are being built and with what properties.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--debug-generators</option></term>
|
|
<listitem>
|
|
<para>Produces debug output from generator search process.
|
|
Useful for debugging custom generators.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--ignore-config</option></term>
|
|
<listitem>
|
|
<para>Do not load <literal>site-config.jam</literal> and
|
|
<literal>user-config.jam</literal> configuration files.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--debug</option></term>
|
|
<listitem>
|
|
<para>Enables internal checks.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
|
|
<para>For complete specification of command line syntax, see
|
|
<xref linkend="bbv2.reference.init.args"/>
|
|
</para>
|
|
|
|
|
|
</section>
|
|
|
|
<section id="bbv2.advanced.targets">
|
|
<title>Declaring Targets</title>
|
|
|
|
<para id="bbv2.advanced.targets.main">
|
|
A <firstterm>Main target</firstterm> is a user-defined named
|
|
entity that can be built, for example an executable file.
|
|
Declaring a main target is usually done using one of the main
|
|
target rules described in <xref linkend=
|
|
"bbv2.reference.rules"/>. The user can also declare
|
|
custom main target rules as shown in <xref
|
|
linkend="bbv2.extending.rules"/>.
|
|
</para>
|
|
|
|
<indexterm><primary>main target</primary><secondary>declaration
|
|
syntax</secondary></indexterm>
|
|
<para>Most main target rules in Boost.Build have the same common
|
|
signature:</para>
|
|
|
|
<!-- I think we maybe ought to be talking about a common
|
|
_signature_ here, having already explained Boost.Jam function
|
|
signatures at the beginning of this chapter. Then we could show
|
|
( main-target-name : sources * : requirements * : default-build * : usage-requirements * )
|
|
instead. More precise.
|
|
|
|
Also, I suggest replacing "default-build" by "default-properties" everywhere.
|
|
-->
|
|
|
|
<indexterm><primary>common signature</primary></indexterm>
|
|
<anchor id="bbv2.main-target-rule-syntax"/>
|
|
<programlisting>
|
|
rule <replaceable>rule-name</replaceable> (
|
|
main-target-name :
|
|
sources + :
|
|
requirements * :
|
|
default-build * :
|
|
usage-requirements * )
|
|
</programlisting>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>main-target-name</parameter> is the name used
|
|
to request the target on command line and to use it from
|
|
other main targets. A main target name may contain
|
|
alphanumeric characters, dashes
|
|
(‘<code>-</code>’), and underscores
|
|
(‘<code>_</code>’).
|
|
</simpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>sources</parameter> is the list of source files and other main
|
|
targets that must be combined.
|
|
</simpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>requirements</parameter> is the list of properties that must always
|
|
be present when this main target is built.
|
|
</simpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>default-build</parameter> is the list of properties that will be used
|
|
unless some other value of the same feature is already
|
|
specified, e.g. on the command line or by propagation from a dependent target.
|
|
</simpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
<parameter>usage-requirements</parameter> is the list of properties that will be
|
|
propagated to all main targets that use this one, i.e. to all its
|
|
dependents.
|
|
</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
Some main target rules have a different list of parameters as explicitly
|
|
stated in their documentation.
|
|
</para>
|
|
|
|
<para>The actual requirements for a target are obtained by refining
|
|
requirements of the project where a target is declared with the
|
|
explicitly specified requirements. The same is true for
|
|
usage-requirements. More details can be found in
|
|
<xref linkend="bbv2.reference.variants.proprefine"/>
|
|
</para>
|
|
|
|
<section>
|
|
<title>Name</title>
|
|
|
|
<!-- perphaps we should use 'name-target-name' to closer
|
|
bind this description to the rule's signature. Here, and for
|
|
other parameters. -->
|
|
<para>The name of main target has two purposes. First, it's used to refer to this target from
|
|
other targets and from command line. Second, it's used to compute the names of the generated files.
|
|
Typically, filenames are obtained from main target name by appending system-dependent suffixes and
|
|
prefixes.
|
|
</para>
|
|
|
|
<para>The name of a main target can contain alphanumeric characters,
|
|
dashes, undescores and dots. The entire
|
|
name is significant when resolving references from other targets. For determining filenames, only the
|
|
part before the first dot is taken. For example:</para>
|
|
<programlisting>
|
|
obj test.release : test.cpp : <variant>release ;
|
|
obj test.debug : test.cpp : <variant>debug ;
|
|
</programlisting>
|
|
<para>will generate two files named <filename>test.obj</filename> (in two different directories), not
|
|
two files named <filename>test.release.obj</filename> and <filename>test.debug.obj</filename>.
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section>
|
|
<title>Sources</title>
|
|
|
|
<para>The list of sources specifies what should be processed to
|
|
get the resulting targets. Most of the time, it's just a list of
|
|
files. Sometimes, you'll want to automatically construct the
|
|
list of source files rather than having to spell it out
|
|
manually, in which case you can use the
|
|
<functionname>glob</functionname> rule. Here are two examples:</para>
|
|
<programlisting>
|
|
exe a : a.cpp ; # a.cpp is the only source file
|
|
exe b : [ glob *.cpp ] ; # all .cpp files in this directory are sources
|
|
</programlisting>
|
|
<para>
|
|
Unless you specify a file with an absolute path, the name is
|
|
considered relative to the source directory — which is typically
|
|
the directory where the Jamfile is located, but can be changed as
|
|
described in <xref linkend=
|
|
"bbv2.advanced.projects.attributes.projectrule"/>.
|
|
</para>
|
|
|
|
<para>
|
|
<!-- use "project-id" here? -->
|
|
The list of sources can also refer to other main targets.
|
|
Targets in the same project can be referred to by name, while
|
|
targets in other projects must be qualified with a directory or a
|
|
symbolic project name. The directory/project name is separated from
|
|
the target name by a double forward slash. There's no special syntax to
|
|
distinguish the directory name from the project name—the part before
|
|
the double slash is first looked up as project name, and then as directory
|
|
name. For example:
|
|
</para>
|
|
|
|
<programlisting>
|
|
lib helper : helper.cpp ;
|
|
exe a : a.cpp helper ;
|
|
# Since all project ids start with slash, ".." is directory name.
|
|
exe b : b.cpp ..//utils ;
|
|
exe c : c.cpp /boost/program_options//program_options ;
|
|
</programlisting>
|
|
<para>
|
|
The first exe uses the library defined in the same
|
|
project. The second one uses some target (most likely library)
|
|
defined by Jamfile one level higher. Finally, the third target
|
|
uses some <ulink url="http://boost.org">C++ Boost</ulink>
|
|
library, referring to it by absolute symbolic name. More
|
|
information about target references can be found in <xref
|
|
linkend="bbv2.tutorial.libs"/> and <xref
|
|
linkend="bbv2.reference.ids"/>.
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section id="bbv2.advanced.targets.requirements">
|
|
<title>Requirements</title>
|
|
<para>Requirements are the properties that should always be present when
|
|
building a target. Typically, they are includes and defines:
|
|
<programlisting>
|
|
exe hello : hello.cpp : <include>/opt/boost <define>MY_DEBUG ;
|
|
</programlisting>
|
|
There is a number of other features, listed in
|
|
<xref linkend="bbv2.advanced.builtins.features"/>. For example if
|
|
a library can only be built statically, or a file can't be compiled
|
|
with optimization due to a compiler bug, one can use
|
|
<programlisting>
|
|
lib util : util.cpp : <link>static ;
|
|
obj main : main.cpp : <optimization>off ;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para id="bbv2.advanced.targets.requirements.conditional">Sometimes, particular relationships need to be maintained
|
|
among a target's build properties. This can be achieved with
|
|
<firstterm>conditional
|
|
requirements</firstterm>. For example, you might want to set
|
|
specific <code>#defines</code> when a library is built as shared,
|
|
or when a target's <code>release</code> variant is built in
|
|
release mode.
|
|
<programlisting>
|
|
lib network : network.cpp
|
|
: <emphasis role="bold"><link>shared:<define>NEWORK_LIB_SHARED</emphasis>
|
|
<variant>release:<define>EXTRA_FAST
|
|
;
|
|
</programlisting>
|
|
|
|
In the example above, whenever <filename>network</filename> is
|
|
built with <code><link>shared</code>,
|
|
<code><define>NEWORK_LIB_SHARED</code> will be in its
|
|
properties, too.
|
|
</para>
|
|
|
|
<para>You can use several properties in the condition, for example:
|
|
<programlisting>
|
|
lib network : network.cpp
|
|
: <toolset>gcc,<optimization>speed:<define>USE_INLINE_ASSEMBLER
|
|
;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para id="bbv2.advanced.targets.requirements.indirect">
|
|
A more powerful variant of conditional requirements
|
|
is <firstterm>indirect conditional requirements</firstterm>.
|
|
You can provide a rule that will be called with the current build properties and can compute additional properties
|
|
to be added. For example:
|
|
<programlisting>
|
|
lib network : network.cpp
|
|
: <conditional>@my-rule
|
|
;
|
|
rule my-rule ( properties * )
|
|
{
|
|
local result ;
|
|
if <toolset>gcc <optimization>speed in $(properties)
|
|
{
|
|
result += <define>USE_INLINE_ASSEMBLER ;
|
|
}
|
|
return $(result) ;
|
|
}
|
|
</programlisting>
|
|
This example is equivalent to the previous one, but for complex cases, indirect conditional
|
|
requirements can be easier to write and understand.
|
|
</para>
|
|
|
|
<para>Requirements explicitly specified for a target are usually
|
|
combined with the requirements specified for the containing project. You
|
|
can cause a target to completely ignore specific project's requirement
|
|
using the syntax by adding a minus sign before a property, for example:
|
|
<programlisting>
|
|
exe main : main.cpp : <emphasis role="bold">-<define>UNNECESSARY_DEFINE</emphasis> ;
|
|
</programlisting>
|
|
This syntax is the only way to ignore free properties from a parent,
|
|
such as defines. It can be also useful for ordinary properties. Consider
|
|
this example:
|
|
<programlisting>
|
|
project test : requirements <threading>multi ;
|
|
exe test1 : test1.cpp ;
|
|
exe test2 : test2.cpp : <threading>single ;
|
|
exe test3 : test3.cpp : -<threading>multi ;
|
|
</programlisting>
|
|
Here, <code>test1</code> inherits project requirements and will always
|
|
be built in multi-threaded mode. The <code>test2</code> target
|
|
<emphasis>overrides</emphasis> project's requirements and will
|
|
always be built in single-threaded mode. In contrast, the
|
|
<code>test3</code> target <emphasis>removes</emphasis> a property
|
|
from project requirements and will be built either in single-threaded or
|
|
multi-threaded mode depending on which variant is requested by the
|
|
user.</para>
|
|
|
|
<para>Note that the removal of requirements is completely textual:
|
|
you need to specify exactly the same property to remove it.</para>
|
|
|
|
</section>
|
|
|
|
<section>
|
|
<title>Default Build</title>
|
|
|
|
<para>The <varname>default-build</varname> parameter
|
|
is a set of properties to be used if the build request does
|
|
not otherwise specify a value for features in the set. For example:
|
|
<programlisting>
|
|
exe hello : hello.cpp : : <threading>multi ;
|
|
</programlisting>
|
|
would build a multi-threaded target unless the user
|
|
explicitly requests a single-threaded version. The difference between
|
|
requirements and default-build is that requirements cannot be
|
|
overridden in any way.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Additional Information</title>
|
|
|
|
<para>
|
|
The ways a target is built can be so different that
|
|
describing them using conditional requirements would be
|
|
hard. For example, imagine that a library actually uses
|
|
different source files depending on the toolset used to build
|
|
it. We can express this situation using <firstterm>target
|
|
alternatives</firstterm>:
|
|
<programlisting>
|
|
lib demangler : dummy_demangler.cpp ; # alternative 1
|
|
lib demangler : demangler_gcc.cpp : <toolset>gcc ; # alternative 2
|
|
lib demangler : demangler_msvc.cpp : <toolset>msvc ; # alternative 3
|
|
</programlisting>
|
|
In the example above, when built with <literal>gcc</literal>
|
|
or <literal>msvc</literal>, <filename>demangler</filename>
|
|
will use a source file specific to the toolset. Otherwise, it
|
|
will use a generic source file,
|
|
<filename>dummy_demangler.cpp</filename>.
|
|
</para>
|
|
|
|
<para>It is possible to declare a target inline, i.e. the "sources"
|
|
parameter may include calls to other main rules. For example:</para>
|
|
|
|
<programlisting>
|
|
exe hello : hello.cpp
|
|
[ obj helpers : helpers.cpp : <optimization>off ] ;</programlisting>
|
|
|
|
<para>
|
|
Will cause "helpers.cpp" to be always compiled without
|
|
optimization. When referring to an inline main target, its declared
|
|
name must be prefixed by its parent target's name and two dots. In
|
|
the example above, to build only helpers, one should run
|
|
<code>bjam hello..helpers</code>.
|
|
</para>
|
|
|
|
<para>When no target is requested on the command line, all targets in the
|
|
current project will be built. If a target should be built only by
|
|
explicit request, this can be expressed by the
|
|
<functionname>explicit</functionname> rule:
|
|
<programlisting>
|
|
explicit install_programs ;</programlisting>
|
|
</para>
|
|
|
|
</section>
|
|
</section>
|
|
|
|
<section id="bbv2.advanced.projects">
|
|
<title>Projects</title>
|
|
|
|
<para>As mentioned before, targets are grouped into projects,
|
|
and each Jamfile is a separate project. Projects are useful
|
|
because they allow us to group related targets together, define
|
|
properties common to all those targets, and assign a symbolic
|
|
name to the project that can be used in referring to its
|
|
targets.
|
|
</para>
|
|
|
|
<para>Projects are named using the
|
|
<functionname>project</functionname> rule, which has the
|
|
following syntax:
|
|
<programlisting>
|
|
project <replaceable>id</replaceable> : <replaceable>attributes</replaceable> ;
|
|
</programlisting>
|
|
Here, <replaceable>attributes</replaceable> is a sequence of
|
|
rule arguments, each of which begins with an attribute-name
|
|
and is followed by any number of build properties. The list
|
|
of attribute names along with its handling is also shown in
|
|
the table below. For example, it is possible to write:
|
|
<programlisting>
|
|
project tennis
|
|
: requirements <threading>multi
|
|
: default-build release
|
|
;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>The possible attributes are listed below.</para>
|
|
|
|
<para><emphasis>Project id</emphasis> is a short way to denote a project, as
|
|
opposed to the Jamfile's pathname. It is a hierarchical path,
|
|
unrelated to filesystem, such as "boost/thread". <link linkend=
|
|
"bbv2.reference.ids">Target references</link> make use of project ids to
|
|
specify a target.</para>
|
|
<!--
|
|
This is actually spelled "project-id," isn't it? You
|
|
have to fix all of these and use a code font. Also below
|
|
in the table.
|
|
-->
|
|
|
|
<para><emphasis>Source location</emphasis> specifies the directory where sources
|
|
for the project are located.</para>
|
|
|
|
<para><emphasis>Project requirements</emphasis> are requirements that apply to
|
|
all the targets in the projects as well as all subprojects.</para>
|
|
|
|
<para><emphasis>Default build</emphasis> is the build request that should be
|
|
used when no build request is specified explicitly.</para>
|
|
<!--
|
|
This contradicts your earlier description of default
|
|
build and I believe it is incorrect. Specifying a build
|
|
request does not neccessarily render default build
|
|
ineffective, because it may cover different features.
|
|
This description is repeated too many times in the
|
|
documentation; you almost *had* to get it wrong once.
|
|
-->
|
|
|
|
<para id="bbv2.advanced.projects.attributes.projectrule">
|
|
The default values for those attributes are
|
|
given in the table below.
|
|
|
|
<table>
|
|
<title/>
|
|
<tgroup cols="4">
|
|
<thead>
|
|
<row>
|
|
<entry>Attribute</entry>
|
|
|
|
<entry>Name</entry>
|
|
|
|
<entry>Default value</entry>
|
|
|
|
<entry>Handling by the <functionname>project</functionname>
|
|
rule</entry>
|
|
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody>
|
|
|
|
<row>
|
|
<entry>Project id</entry>
|
|
|
|
<entry>none</entry>
|
|
|
|
<entry>none</entry>
|
|
|
|
<entry>Assigned from the first parameter of the 'project' rule.
|
|
It is assumed to denote absolute project id.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>Source location</entry>
|
|
|
|
<entry><literal>source-location</literal></entry>
|
|
|
|
<entry>The location of jamfile for the project</entry>
|
|
|
|
<entry>Sets to the passed value</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>Requirements</entry>
|
|
|
|
<entry><literal>requirements</literal></entry>
|
|
|
|
<entry>The parent's requirements</entry>
|
|
|
|
<entry>The parent's requirements are refined with the passed
|
|
requirement and the result is used as the project
|
|
requirements.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>Default build</entry>
|
|
|
|
<entry><literal>default-build</literal></entry>
|
|
|
|
<entry>none</entry>
|
|
|
|
<entry>Sets to the passed value</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>Build directory</entry>
|
|
|
|
<entry><literal>build-dir</literal></entry>
|
|
|
|
<entry>Empty if the parent has no build directory set.
|
|
Otherwise, the parent's build directory with the
|
|
relative path from parent to the current project
|
|
appended to it.
|
|
</entry>
|
|
|
|
<entry>Sets to the passed value, interpreted as relative to the
|
|
project's location.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</para>
|
|
|
|
<para>Besides defining projects and main targets, Jamfiles
|
|
often invoke various utility rules. For the full list of rules
|
|
that can be directly used in Jamfile see
|
|
<xref linkend="bbv2.reference.rules"/>.
|
|
</para>
|
|
|
|
<para>Each subproject inherits attributes, constants and rules
|
|
from its parent project, which is defined by the nearest
|
|
Jamfile in an ancestor directory above
|
|
the subproject. The top-level project is declared in a file
|
|
called <filename>Jamroot</filename> rather than
|
|
<filename>Jamfile</filename>. When loading a project,
|
|
Boost.Build looks for either <filename>Jamroot</filename> or
|
|
<code>Jamfile</code>. They are handled identically, except
|
|
that if the file is called <filename>Jamroot</filename>, the
|
|
search for a parent project is not performed.
|
|
</para>
|
|
|
|
<para>Even when building in a subproject directory, parent
|
|
project files are always loaded before those of their
|
|
subprojects, so that every definition made in a parent project
|
|
is always available to its children. The loading order of any
|
|
other projects is unspecified. Even if one project refers to
|
|
another via the <code>use-project</code> or a target reference,
|
|
no specific order should be assumed.
|
|
</para>
|
|
|
|
<note>
|
|
<para>Giving the root project the special name
|
|
“<filename>Jamroot</filename>” ensures that
|
|
Boost.Build won't misinterpret a directory above it as the
|
|
project root just because the directory contains a Jamfile.
|
|
<!-- The logic of the previous reasoning didn't hang together -->
|
|
</para>
|
|
</note>
|
|
|
|
<!-- All this redundancy with the tutorial is bad. The tutorial
|
|
should just be made into the introductory sections of this
|
|
document, which should be called the "User Guide." It's
|
|
perfectly appropriate to start a user guide with that kind
|
|
of material. -->
|
|
</section>
|
|
|
|
<section id="bbv2.advanced.build_process">
|
|
<title>The Build Process</title>
|
|
|
|
<para>When you've described your targets, you want Boost.Build to run the
|
|
right tools and create the needed targets.
|
|
<!-- That sentence is awkward and doesn't add much. -->
|
|
This section will describe
|
|
two things: how you specify what to build, and how the main targets are
|
|
actually constructed.
|
|
</para>
|
|
|
|
<para>The most important thing to note is that in Boost.Build, unlike
|
|
other build tools, the targets you declare do not correspond to specific
|
|
files. What you declare in a Jamfile is more like a “metatarget.”
|
|
<!-- Do we need a new word? We already have “main target.” If
|
|
you're going to introduce “metatarget” you should at least
|
|
tie it together with the main target concept. It's too
|
|
strange to have been saying “main target” all along and now
|
|
suddenly start saying “what you declare in a jamfile” -->
|
|
Depending on the properties you specify on the command line,
|
|
each metatarget will produce a set of real targets corresponding
|
|
to the requested properties. It is quite possible that the same
|
|
metatarget is built several times with different properties,
|
|
producing different files.
|
|
</para>
|
|
<tip>
|
|
<para>
|
|
This means that for Boost.Build, you cannot directly obtain a build
|
|
variant from a Jamfile. There could be several variants requested by the
|
|
user, and each target can be built with different properties.
|
|
</para>
|
|
</tip>
|
|
|
|
<section id="bbv2.advanced.build_request">
|
|
<title>Build Request</title>
|
|
|
|
<para>
|
|
The command line specifies which targets to build and with which
|
|
properties. For example:
|
|
<programlisting>
|
|
bjam app1 lib1//lib1 toolset=gcc variant=debug optimization=full
|
|
</programlisting>
|
|
would build two targets, "app1" and "lib1//lib1" with the specified
|
|
properties. You can refer to any targets, using
|
|
<link linkend="bbv2.reference.ids">target id</link> and specify arbitrary
|
|
properties. Some of the properties are very common, and for them the name
|
|
of the property can be omitted. For example, the above can be written as:
|
|
<programlisting>
|
|
bjam app1 lib1//lib1 gcc debug optimization=full
|
|
</programlisting>
|
|
The complete syntax, which has some additional shortcuts, is
|
|
described in <xref linkend="bbv2.reference.commandline"/>.
|
|
</para>
|
|
</section>
|
|
|
|
<section><title>Building a main target</title>
|
|
|
|
<para>When you request, directly or indirectly, a build of a main target
|
|
with specific requirements, the following steps are done. Some brief
|
|
explanation is provided, and more details are given in <xref
|
|
linkend="bbv2.reference.buildprocess"/>.
|
|
<orderedlist>
|
|
|
|
<listitem><para>Applying default build. If the default-build
|
|
property of a target specifies a value of a feature that is not
|
|
present in the build request, that value is added.</para>
|
|
<!--
|
|
Added to what? Don't say “the build request!” The
|
|
request is what was requested; if its meaning changes
|
|
the reader will be confused.
|
|
-->
|
|
</listitem>
|
|
|
|
<listitem><para>Selecting the main target alternative to use. For
|
|
each alternative we look how many properties are present both in
|
|
alternative's requirements, and in build request. The
|
|
alternative with large number of matching properties is selected.
|
|
</para></listitem>
|
|
|
|
<listitem><para>Determining "common" properties.
|
|
<!-- It would be nice to have a better name for this. But
|
|
even more importantly, unless you say something about
|
|
the reason for choosing whatever term you use, the
|
|
reader is going to wonder what it means. -->
|
|
The build request
|
|
is <link linkend="bbv2.reference.variants.proprefine">refined</link>
|
|
with target's requirements.
|
|
<!-- It's good that you have the links here and below,
|
|
but I'm concerned that it doesn't communicate well
|
|
in print and there's not enough information for the
|
|
print reader. Maybe we need separate XSL for PDF
|
|
printing that generates a readable footnote. -->
|
|
The conditional properties in
|
|
requirements are handled as well. Finally, default values of
|
|
features are added.
|
|
</para></listitem>
|
|
|
|
<listitem><para>Building targets referred by the sources list and
|
|
dependency properties. The list of sources and the properties
|
|
can refer to other target using <link
|
|
linkend="bbv2.reference.ids">target references</link>. For each
|
|
reference, we take all <link
|
|
linkend="bbv2.reference.features.attributes.propagated">propagated</link>
|
|
properties, refine them by explicit properties specified in the
|
|
target reference, and pass the resulting properties as build
|
|
request to the other target.
|
|
</para></listitem>
|
|
|
|
<listitem><para>Adding the usage requirements produced when building
|
|
dependencies to the "common" properties. When dependencies are
|
|
built in the previous step, they return
|
|
<!-- don't assume reader has a mental model for BB internals! -->
|
|
both the set of created
|
|
"real" targets, and usage requirements. The usage requirements
|
|
are added to the common properties and the resulting property
|
|
set will be used for building the current target.
|
|
</para></listitem>
|
|
|
|
<listitem><para>Building the target using generators. To convert the
|
|
sources to the desired type, Boost.Build uses "generators" ---
|
|
objects that correspond to tools like compilers and
|
|
linkers. Each generator declares what type of targets it
|
|
<!-- Was "in." Why are these short and unmistakable
|
|
words so commonly misspelled? -->
|
|
can
|
|
produce and what type of sources it requires. Using this
|
|
information, Boost.Build determines which generators must be run
|
|
to produce a specific target from specific sources. When
|
|
generators are run, they return the "real" targets.
|
|
</para></listitem>
|
|
|
|
<listitem><para>Computing the usage requirements to be returned. The
|
|
conditional properties in usage requirements are expanded
|
|
<!-- what does "expanded" mean? -->
|
|
and the
|
|
result is returned.</para></listitem>
|
|
</orderedlist>
|
|
</para>
|
|
</section>
|
|
|
|
<section><title>Building a Project</title>
|
|
|
|
<para>Often, a user builds a complete project, not just one main
|
|
target. In fact, invoking <command>bjam</command> without
|
|
arguments
|
|
<!-- do you know the difference between parameters and
|
|
arguments? I only learned this year -->
|
|
builds the project defined in the current
|
|
directory.</para>
|
|
|
|
<para>When a project is built, the build request is passed without
|
|
modification to all main targets in that project.
|
|
<!-- What does it mean to pass a build request to a target?
|
|
-->
|
|
It's is possible to
|
|
prevent implicit building of a target in a project with the
|
|
<code>explicit</code> rule:
|
|
<programlisting>
|
|
explicit hello_test ;
|
|
</programlisting>
|
|
would cause the <code>hello_test</code> target to be built only if
|
|
explicitly requested by the user or by some other target.
|
|
</para>
|
|
|
|
<para>The Jamfile for a project can include a number of
|
|
<code>build-project</code> rule calls
|
|
<!-- A comma would only be correct here in German -->
|
|
that specify additional projects
|
|
to be built.
|
|
</para>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
</chapter>
|
|
|
|
<!--
|
|
Local Variables:
|
|
mode: nxml
|
|
sgml-indent-data: t
|
|
sgml-parent-document: ("userman.xml" "chapter")
|
|
sgml-set-face: t
|
|
End:
|
|
-->
|