mirror of
https://github.com/boostorg/build.git
synced 2026-02-10 11:22:12 +00:00
1953 lines
79 KiB
XML
1953 lines
79 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>User documentation</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
|
|
three things:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><link linkend="bbv2.advanced.configuration">
|
|
How to configure Boost.Build</link></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><link linkend="bbv2.advanced.jamfiles">
|
|
How to write 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 the
|
|
<ulink
|
|
url="http://www.boost.org/tools/jam/index.html">Boost.Jam</ulink>
|
|
documentation.
|
|
<!-- Something better than this is desperately needed; the
|
|
tutorial at least should clarify that whitespace is
|
|
significant and we shouldn't get any further than the
|
|
beginning of this document before briefly explaining
|
|
Jam's data and procedural model, rule
|
|
signatures, and Boost.Build modules -->
|
|
</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 <ulink
|
|
url="http://www.boost.org/tools/jam/index.html">Boost.Jam</ulink>
|
|
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 statement ]</programlisting>
|
|
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 "resonable" ;
|
|
}
|
|
return "strange" ;
|
|
}</programlisting> will return <literal>strange</literal>, not
|
|
<literal>resonable</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>
|
|
</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 top-level
|
|
directory of Boost.Build installation 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 contanating
|
|
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.advanced.builtins.targets"/>. 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 propogation 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, their
|
|
documentation explicitly says so.
|
|
</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>
|
|
|
|
<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>Name of main target can contain alphanumeral characters, dash, undescore and dot. 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:
|
|
<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>
|
|
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 double slash. There's no special syntax to
|
|
distinguish directory name from project name—the part before
|
|
double slash is first looked up as project name, and then as directory
|
|
name. For example:
|
|
<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>
|
|
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>
|
|
<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">
|
|
More powerfull variant of conditional requirements is <firstterm>indirect conditional requiremens</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>
|
|
|
|
</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 in unless the user
|
|
explicitly requests a single-threaded version. The difference between
|
|
requirements and default-build is that requirements cannot be
|
|
overriden 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 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
|
|
commonly invoke utility rules such as
|
|
<functionname>constant</functionname> and
|
|
<functionname>path-constant</functionname>, which inject a
|
|
specified Boost.Jam variable setting into this project's Jamfile
|
|
module and those of all its subprojects. See <xref
|
|
linkend="bbv2.advanced.other-rules"/> for a complete description
|
|
of these utility rules. Jamfiles are regular Boost.Jam source
|
|
files and Boost.Build modules, so naturally they can contain any kind of Boost.Jam code,
|
|
including rule definitions.
|
|
<!-- I improved that sentence, but I don't think it belongs
|
|
here. I suggest you strike it. -->
|
|
</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 indentically, 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 <xref
|
|
linkend="bbv2.advanced.projects.relationships.useprojectrule"><functionname>use-project</functionname></xref>,
|
|
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.other-rules">
|
|
<title>Jamfile Utility Rules</title>
|
|
|
|
<para>The following table describes utility rules that can be
|
|
used in Jamfiles. Detailed information for any of these rules can
|
|
be obtained by running:
|
|
<screen>
|
|
bjam --help project.<replaceable>rulename</replaceable>
|
|
</screen>
|
|
</para>
|
|
|
|
<table>
|
|
<title/>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Rule</entry>
|
|
|
|
<entry>Semantics</entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<row>
|
|
<entry><link linkend=
|
|
"bbv2.advanced.projects.attributes.projectrule">project</link>
|
|
</entry>
|
|
|
|
<entry>Define this project's symbolic ID or attributes.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><xref linkend=
|
|
"bbv2.advanced.projects.relationships.useprojectrule">use-project</xref></entry>
|
|
|
|
<entry>Make another project known so that it can be referred to by symbolic ID.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><xref linkend=
|
|
"bbv2.advanced.projects.relationships.buildprojectrule">build-project</xref></entry>
|
|
|
|
<entry>Cause another project to be built when this one is built.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><xref linkend=
|
|
"bbv2.reference.buildprocess.explict">explicit</xref></entry>
|
|
|
|
<entry>State that a target should be built only by explicit
|
|
request.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>glob</entry>
|
|
|
|
<entry>Translate a list of shell-style wildcards into a
|
|
corresponding list of files.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>constant</entry>
|
|
|
|
<entry>Injects a variable setting into this project's
|
|
Jamfile module and those of all its subprojects.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>path-constant</entry>
|
|
|
|
<entry>Injects a variable set to a path value into
|
|
this project's Jamfile module and those of all its subprojects.
|
|
If the value is a relative path it will be adjusted for
|
|
each subproject so that it refers to the same
|
|
directory.</entry>
|
|
</row>
|
|
|
|
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</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>
|
|
<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 made. 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>
|
|
|
|
<section id="bbv2.advanced.builtins.targets">
|
|
<title>Builtin target types</title>
|
|
|
|
<para>This section describes main targets types that Boost.Build supports
|
|
of-of-the-box. Unless otherwise noted, all mentioned main target rules
|
|
have the common signature, described in <xref
|
|
linkend="bbv2.main-target-rule-syntax"/>.
|
|
</para>
|
|
|
|
<section>
|
|
<title>Programs</title>
|
|
|
|
<indexterm><primary>Builtin
|
|
rules</primary><secondary>exe</secondary></indexterm>
|
|
<para>Programs are created using the <code>exe</code> rule, which
|
|
follows the <link linkend="bbv2.main-target-rule-syntax">common
|
|
syntax</link>. For example:
|
|
<programlisting>
|
|
exe hello : hello.cpp some_library.lib /some_project//library
|
|
: <threading>multi
|
|
;
|
|
</programlisting>
|
|
This will create an executable file from the sources -- in this case,
|
|
one C++ file, one library file present in the same directory, and
|
|
another library that is created by Boost.Build. Generally, sources
|
|
can include C and C++ files, object files and libraries. Boost.Build
|
|
will automatically try to convert targets of other types.
|
|
</para>
|
|
|
|
<tip>
|
|
<para>
|
|
On Windows, if an application uses dynamic libraries, and both
|
|
the application and the libraries are built by Boost.Build, its not
|
|
possible to immediately run the application, because the
|
|
<literal>PATH</literal> environment variable should include the path
|
|
to the libraries. It means you have to either add the paths
|
|
manually, or place the application and the libraries to the same
|
|
directory, for example using the <link linkend="bbv2.builtins.stage">
|
|
stage</link> rule.
|
|
</para>
|
|
<!-- We should be emphasizing the use of the built-in testing
|
|
rules rather than continually discussing these quirks of
|
|
running programs with dynamic libraries. -->
|
|
</tip>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Libraries</title>
|
|
|
|
<para>Libraries are created using the <code>lib</code> rule, which
|
|
follows the <link linkend="bbv2.main-target-rule-syntax">common
|
|
syntax</link>. For example:
|
|
<programlisting>
|
|
lib helpers : helpers.cpp : <include>boost : : <include>. ;
|
|
</programlisting>
|
|
</para>
|
|
<!-- Add one sentence that says what the above does. -->
|
|
<para>In the most common case, the <code>lib</code> creates a library
|
|
from the specified sources. Depending on the value of
|
|
<link> feature the library will be either static or
|
|
shared. There are two other cases. First is when the library is
|
|
installed somewhere in compiler's search paths, and should be
|
|
searched by the compiler (typically, using the <option>-l</option>
|
|
option). The second case is where the library is available as a
|
|
prebuilt file and the full path is known.
|
|
<!-- But the first case is also prebuilt. This is confusingly phrased. -->
|
|
</para>
|
|
|
|
<para>
|
|
The syntax for these case is given below:
|
|
<programlisting>
|
|
lib z : : <name>z <search>/home/ghost ;
|
|
lib compress : : <file>/opt/libs/compress.a ;
|
|
</programlisting>
|
|
The <code>name</code> property specifies the name that should be
|
|
passed to the <option>-l</option> option, and the <code>file</code>
|
|
property specifies the file location. The <varname>search</varname> feature
|
|
specifies paths in which to search for the library. That feature can
|
|
be specified several times, or it can be omitted, in which case only
|
|
default compiler paths will be searched.
|
|
</para>
|
|
|
|
<para>The difference between using the <varname>file</varname> feature as
|
|
opposed to the <varname>name</varname> feature together with the
|
|
<varname>search</varname> feature is that <varname>file</varname> is more
|
|
precise. A specific file will be used. On the other hand, the
|
|
<varname>search</varname> feature only adds a library path, and the
|
|
<varname>name</varname> feature gives the basic name of the library. The
|
|
search rules are specific to the linker. For example, given these
|
|
definition:
|
|
<programlisting>
|
|
lib a : : <variant>release <file>/pool/release/a.so ;
|
|
lib a : : <variant>debug <file>/pool/debug/a.so ;
|
|
lib b : : <variant>release <file>/pool/release/b.so ;
|
|
lib b : : <variant>debug <file>/pool/debug/b.so ;
|
|
</programlisting>
|
|
It's possible to use release version of <code>a</code> and debug
|
|
version of <code>b</code>. Had we used the <varname>name</varname> and
|
|
<varname>search</varname> features, the linker would always pick either
|
|
release or debug versions.
|
|
<!-- explain -->
|
|
</para>
|
|
|
|
<para>
|
|
For convenience, the following syntax is allowed:
|
|
<programlisting>
|
|
lib z ;
|
|
lib gui db aux ;
|
|
</programlisting>
|
|
and is does exactly the same as:
|
|
<programlisting>
|
|
lib z : : <name>z ;
|
|
lib gui : : <name>gui ;
|
|
lib db : : <name>db ;
|
|
lib aux : : <name>aux ;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>When a library uses another library you should put that another
|
|
library in the list of sources. This will do the right thing in all
|
|
cases. For portability, you should specify library dependencies even
|
|
for searched and prebuilt libraries, othewise, static linking on
|
|
Unix won't work. For example:
|
|
<programlisting>
|
|
lib z ;
|
|
lib png : z : <name>png ;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<note>
|
|
<para>When a library (say, <code>a</code>), that has another
|
|
library, (say, <code>b</code>)
|
|
<!-- how can a library "have" a library? -->
|
|
is linked dynamically, the <code>b</code>
|
|
library will be incorporated
|
|
<!-- Incorporated? Be precise. -->
|
|
in <code>a</code>. (If <code>b</code>
|
|
is dynamic library as well, then <code>a</code> will only refer to
|
|
it, and not include any extra code.)
|
|
<!-- Don't parenthesize a whole sentence. -->
|
|
When the <code>a</code>
|
|
library is linked statically, Boost.Build will assure that all
|
|
executables that link to <code>a</code> will also link to
|
|
<code>b</code>.
|
|
</para>
|
|
</note>
|
|
|
|
<para>One feature of Boost.Build that is very important for libraries
|
|
is usage requirements.
|
|
<!-- Rephrase that. But then, it's much too late for an
|
|
introduction of usage requirements - you've already
|
|
discussed them many times. -->
|
|
For example, if you write:
|
|
<programlisting>
|
|
lib helpers : helpers.cpp : : : <include>. ;
|
|
</programlisting>
|
|
then the compiler include path for all targets that use
|
|
<code>helpers</code> will contain the directory
|
|
<!-- The rest of this sentence is unintelligible -->
|
|
where the target is defined.path to "helpers.cpp". The user
|
|
only needs to add <code>helpers</code> to the list of sources,
|
|
and needn't consider the requirements its use imposes on a
|
|
dependent target. This feature greatly simplifies Jamfiles.
|
|
<!-- You can't say “allows to”—you need a noun. This error is
|
|
repeated throughout. -->
|
|
</para>
|
|
|
|
<note>
|
|
<para>If you don't want shared libraries to include all libraries
|
|
that are specified in sources (especially statically linked ones),
|
|
you'd need to use the following:
|
|
<programlisting>
|
|
lib b : a.cpp ;
|
|
lib a : a.cpp : <use>b : : <library>b ;
|
|
</programlisting>
|
|
This specifies that <code>a</code> uses <code>b</code>, and causes
|
|
all executables that link to <code>a</code> also link to
|
|
<code>b</code>. In this case, even for shared linking, the
|
|
<code>a</code> library won't even refer to <code>b</code>.
|
|
</para>
|
|
</note>
|
|
|
|
</section>
|
|
|
|
<section id="bbv2.builtins.alias">
|
|
<title>Alias</title>
|
|
|
|
<para>
|
|
The <functionname>alias</functionname> rule gives alternative name to
|
|
a group of targets. For example, to give name
|
|
<filename>core</filename> to a group of three other targets with the
|
|
following code:
|
|
<programlisting>
|
|
alias core : im reader writer ;</programlisting>
|
|
Using <filename>core</filename> on the command line, or in source list
|
|
of any other target is the same as explicitly using
|
|
<filename>im</filename>, <filename>reader</filename>, and
|
|
<filename>writer</filename>, just more convenient.
|
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
Another use of the <code>alias</code> rule is to change build
|
|
properties. For example, if you always want static linking for a
|
|
specific C++ Boost library, you can write the following:
|
|
<programlisting>
|
|
alias threads : /boost/thread//boost_thread : <link>static ;
|
|
</programlisting>
|
|
and use only the <code>threads</code> alias in your Jamfiles.
|
|
<!-- changed name for clarity -->
|
|
</para>
|
|
|
|
<para>
|
|
You can also specify usage requirements for the
|
|
<code>alias</code> target. If you write the following:
|
|
<programlisting>
|
|
alias header_only_library : : : : <include>/usr/include/header_only_library ;
|
|
</programlisting>
|
|
then using <code>header_only_library</code> in sources will only add an
|
|
include path. Also note that when there are some sources, their usage
|
|
requirements are propagated, too. For example:
|
|
<programlisting>
|
|
lib lib : lib.cpp : : : <include>. ;
|
|
alias lib_alias ; <!-- This line can't possibly be correct!?? -->
|
|
exe main : main.cpp lib_alias ;
|
|
</programlisting>
|
|
will compile <filename>main.cpp</filename> with the additional include.
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section id="bbv2.builtins.stage">
|
|
<title>Installing</title>
|
|
|
|
<para>For installing a built target you should use the
|
|
<code>install</code> rule, which follows the <link
|
|
linkend="bbv2.main-target-rule-syntax">common syntax</link>. For
|
|
example:
|
|
<programlisting>
|
|
install dist : hello helpers ;
|
|
</programlisting>
|
|
will cause the targets <code>hello</code> and <code>helpers</code> to
|
|
be moved to the <filename>dist</filename> directory, relative to
|
|
Jamfile's directory. The directory can
|
|
be changed with the <code>location</code> property:
|
|
<programlisting>
|
|
install dist : hello helpers : <location>/usr/bin ;
|
|
</programlisting>
|
|
While you can achieve the same effect by changing the target name to
|
|
<filename>/usr/bin</filename>, using the <code>location</code>
|
|
property is better, because it allows you to use a memnonic target
|
|
name.
|
|
</para>
|
|
|
|
<para>The <code>location</code> property is especially handy when the location
|
|
is not fixed, but depends on build variant or environment variables:
|
|
<programlisting>
|
|
install dist : hello helpers : <variant>release:<location>dist/release
|
|
<variant>debug:<location>dist/debug ;
|
|
install dist2 : hello helpers : <location>$(DIST) ;
|
|
</programlisting>
|
|
See also <link linkend="bbv2.reference.variants.propcond">conditional
|
|
properties</link> and <link linkend="bbv2.faq.envar">environment variables</link>
|
|
</para>
|
|
|
|
<para>
|
|
Specifying the names of all libraries to install can be boring. The
|
|
<code>install</code> allows you to specify only the top-level executable
|
|
targets to install, and automatically install all dependencies:
|
|
<programlisting>
|
|
install dist : hello
|
|
: <install-dependencies>on <install-type>EXE
|
|
<install-type>LIB
|
|
;
|
|
</programlisting>
|
|
will find all targets that <code>hello</code> depends on, and install
|
|
all of the which are either executables or libraries. More
|
|
specifically, for each target, other targets that were specified as
|
|
sources or as dependency properties, will be recursively found. One
|
|
exception is that targets referred with the <link
|
|
linkend="bbv2.builtin.features.use"><code>use</code></link> feature
|
|
are not considered, because that feature is typically used to refer to
|
|
header-only libraries.
|
|
If the set of target types is specified, only targets of that type
|
|
will be installed, otherwise, all found target will be installed.
|
|
</para>
|
|
|
|
<para>The <link linkend="bbv2.builtins.alias"><code>alias</code></link>
|
|
rule can be used when targets must be installed into several
|
|
directories:
|
|
<programlisting>
|
|
install install : install-bin install-lib ;
|
|
install install-bin : applications : /usr/bin ;
|
|
install install-lib : helper : /usr/lib ;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>Because the <code>install</code> rule just copies targets, most
|
|
free features <footnote><para>see the definition of "free" in <xref
|
|
linkend="bbv2.reference.features.attributes"/>.</para></footnote>
|
|
have no effect when used in requirements of the <code>install</code>.
|
|
The only two which matter are
|
|
<link linkend="bbv2.builtin.features.dependency">
|
|
<varname>dependency</varname></link> and, on Unix,
|
|
<link linkend="bbv2.builtin.feature.dll-path"><varname>dll-path</varname></link>.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
(Unix specific). On Unix, executables built with Boost.Build typically
|
|
contain the list of paths to all used dynamic libraries. For
|
|
installing, this is not desired, so Boost.Build relinks the executable
|
|
with an empty list of paths. You can also specify additional paths for
|
|
installed executables with the <varname>dll-path</varname> feature.
|
|
</para>
|
|
</note>
|
|
|
|
|
|
</section>
|
|
|
|
<section id="bbv2.builtins.testing">
|
|
|
|
<title>Testing</title>
|
|
|
|
<para>Boost.Build has convenient support for running unit tests. The
|
|
simplest way is the <code>unit-test</code> rule, which follows the
|
|
<link linkend="bbv2.main-target-rule-syntax">common syntax</link>. For
|
|
example:
|
|
<programlisting>
|
|
unit-test helpers_test : helpers_test.cpp helpers ;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>The <functionname>unit-test</functionname> rule behaves like the
|
|
<functionname>exe</functionname> rule, but after the executable is created it is
|
|
run. If the executable returns an error code, the build system will also
|
|
return an error and will try running the executable on the next
|
|
invocation until it runs successfully. This behaviour ensures that you
|
|
can't miss a unit test failure.
|
|
</para>
|
|
|
|
<para>By default, the executable is run directly. Sometimes, it's
|
|
desirable to run the executable using some helper command. You should use the
|
|
<literal>testing.launcher</literal> property to specify the name of the
|
|
helper command. For example, if you write:
|
|
</para>
|
|
<programlisting>
|
|
unit-test helpers_test
|
|
: helpers_test.cpp helpers
|
|
: <emphasis role="bold"><testing.launcher>valgrind</emphasis>
|
|
;
|
|
</programlisting>
|
|
<para>The command used to run the executable will be:</para>
|
|
<screen>
|
|
<emphasis role="bold">valgrind</emphasis> bin/$toolset/debug/helpers_test
|
|
</screen>
|
|
|
|
|
|
|
|
<para>There are rules for more elaborate testing: <code>compile</code>,
|
|
<code>compile-fail</code>, <code>run</code> and
|
|
<code>run-fail</code>. They are more suitable for automated testing, and
|
|
are not covered here.
|
|
</para>
|
|
</section>
|
|
|
|
</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>
|
|
<simpara>
|
|
A feature that controls how libraries are built.
|
|
</simpara>
|
|
|
|
<para><emphasis role="bold">Allowed values:</emphasis> <literal>shared</literal>,
|
|
<literal>static</literal></para>
|
|
</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.builtin.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 C and C++
|
|
compilers, for <code>cxxflags</code> that's C++ compiler and for
|
|
<code>linkflags</code> that's 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 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 treat warnings as errors and abort
|
|
compilation on 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>
|
|
|
|
|
|
|
|
|
|
|
|
</variablelist>
|
|
</section>
|
|
|
|
<section id="bbv2.advanced.differences_to_v1">
|
|
<title>Differences to Boost.Build V1</title>
|
|
<!-- "Differences to" is the British English usage. American
|
|
English is "differences from." You can use the former but be
|
|
sure you know what you're doing -->
|
|
|
|
<para>While Boost.Build V2 is based on the same ideas as Boost.Build V1,
|
|
some of the syntax was changed, and some new important features were
|
|
added. This chapter describes most of the changes.</para>
|
|
|
|
<section id="bbv2.advanced.differences_to_v1.configuration">
|
|
<title>Configuration</title>
|
|
|
|
<para>In V1, toolsets were configured by environment variables. If you
|
|
wanted to use two versions of the same toolset, you had to create a new
|
|
toolset module that would set the variables and then invoke the base
|
|
toolset. In V2, toolsets are configured by the
|
|
<functionname>using</functionname>, and you can easily configure several
|
|
versions of a toolset. See <xref
|
|
linkend="bbv2.advanced.configuration"/> for details.
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section id="bbv2.advanced.differences_to_v1.jamfiles">
|
|
<title>Writing Jamfiles</title>
|
|
|
|
<para>Probably one of the most important differences in V2 Jamfiles is
|
|
the use of project requirements. In V1, if several targets had the same
|
|
requirements (for example, a common <code>#include</code> path), it was necessary to
|
|
manually write the requirements or use a helper rule or template target. In V2, the
|
|
common properties can be specified with the <code>requirements</code> project
|
|
attribute, as documented in <xref linkend="bbv2.advanced.projects"/>.
|
|
</para>
|
|
|
|
<para><link linkend="bbv2.tutorial.libs">Usage requirements</link>
|
|
also help to simplify Jamfiles.
|
|
<!-- Simplify, simplify, simplify! You could go through the
|
|
entire document several times and make changes like that
|
|
one -->
|
|
If a library requires
|
|
all clients to use specific <code>#include</code> paths or macros when compiling
|
|
code that depends on the library, that information can be cleanly
|
|
represented.</para>
|
|
|
|
<para>The difference between <code>lib</code> and <code>dll</code> targets in V1 is completely
|
|
eliminated in V2. There's only one library target type, <code>lib</code>, which can create
|
|
either static or shared libraries depending on the value of the
|
|
<link linkend="bbv2.advanced.builtins.features.link"><varname><link></varname>
|
|
feature</link>. If your target should be only built in one way<!--"variant" has a different meaning here-->, you
|
|
can add <code><link>shared</code> or <code><link>static</code> to its requirements.
|
|
</para>
|
|
|
|
<para>The syntax for referring to other targets was changed a bit. While
|
|
in V1 one would use:
|
|
<programlisting>
|
|
exe a : a.cpp <lib>../foo/bar ;
|
|
</programlisting>
|
|
the V2 syntax is:
|
|
<programlisting>
|
|
exe a : a.cpp ../foo//bar ;
|
|
</programlisting>
|
|
Note that you don't need to specify the type of other target, but the
|
|
last element should be separated from the others by a double slash to indicate that
|
|
you're referring to target <filename>bar</filename> in project <filename>../foo</filename>, and not to
|
|
project <filename>../foo/bar</filename>.
|
|
</para>
|
|
|
|
|
|
</section>
|
|
|
|
<section id="bbv2.advanced.differences_to_v1.build_process">
|
|
<title>Build process</title>
|
|
|
|
<para>The command line syntax in V2 is completely different. For example
|
|
<programlisting>
|
|
bjam -sTOOLS=msvc -sBUILD=release some_target
|
|
</programlisting>
|
|
now becomes:
|
|
<programlisting>
|
|
bjam toolset=msvc variant=release some_target
|
|
</programlisting>
|
|
or, using implicit features, just:
|
|
<programlisting>
|
|
bjam msvc release some_target
|
|
</programlisting>
|
|
See <link linkend="bbv2.reference.commandline">the reference</link> for a
|
|
complete description of the syntax.
|
|
</para>
|
|
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
</chapter>
|
|
|
|
<!--
|
|
Local Variables:
|
|
mode: nxml
|
|
sgml-indent-data: t
|
|
sgml-parent-document: ("userman.xml" "chapter")
|
|
sgml-set-face: t
|
|
End:
|
|
-->
|