mirror of
https://github.com/boostorg/build.git
synced 2026-02-13 00:12:11 +00:00
1815 lines
75 KiB
XML
1815 lines
75 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/build/jam_src/index.html#jam_fundamentals">Boost.Jam</ulink>
|
|
and <ulink
|
|
url="http://www.boost.org/tools/build/jam_src/jam.html">Classic
|
|
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.configuration">
|
|
<title>Configuration</title>
|
|
|
|
<para>The Boost.Build configuration is specified in the file
|
|
<filename>user-config.jam</filename>. You can edit the one that comes with Boost.Build, or
|
|
<!-- You can't tell people that without telling them where to find it! -->
|
|
create a copy in your home directory and edit that. (See the <link
|
|
linkend="bbv2.reference.init.config">reference</link> 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.
|
|
<!-- Will
|
|
|
|
using msvc : : foo/bar/vcvars32.bat && foo/bar/baz/cl ;
|
|
|
|
work? If not we should clarify what we really mean by "invocation command."
|
|
-->
|
|
</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.jamfiles">
|
|
<title>Writing Jamfiles</title>
|
|
|
|
<section id="bbv2.advanced.overview">
|
|
<title>Overview</title>
|
|
|
|
<para>Jamfiles are the thing that is most important to the user,
|
|
<!-- Semantics-free, and wrong. Many things are more important to the user -->
|
|
bacause they declare the targets that should be built.
|
|
<!-- The reader already knows that -->
|
|
Jamfiles are also used for organizing targets—
|
|
<!-- Practically redundant with "Jamfiles... declare targets" -->
|
|
each Jamfile is a separate project
|
|
<!-- Okay, there's some content! -->
|
|
that can be built independently from the other projects.
|
|
<!-- :( Practically redundant with "each Jamfile is a separate project." -->
|
|
</para>
|
|
|
|
<para>Jamfiles mostly contain calls to Boost.Build functions that do
|
|
all the work, specifically:
|
|
<!-- it's too late to start saying "functions." You have to
|
|
use "rules" everwhere or it will just get confusing. -->
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><link linkend="bbv2.advanced.targets">declare main
|
|
targets</link></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><link
|
|
linkend="bbv2.advanced.projects">define
|
|
project properties</link></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><link linkend="bbv2.advanced.other-rules">do various other
|
|
things</link></para>
|
|
<!-- Semantics-free again. -->
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<!-- Don't expect those links to do anything useful, even for
|
|
someone reading the HTML. A list of items where all of the
|
|
*real* content is only available through links is often
|
|
worse than nothing. Have you ever tried to read NG
|
|
postings by Alexander Terekhov? The whole list is pretty
|
|
useless. Consider scratching or rewriting the entire section. -->
|
|
|
|
<!-- That's a *lot* of flotsam below. If it's not good enough
|
|
to go in the output users see, just delete it. -->
|
|
<!-- ======================================================== -->
|
|
<!--
|
|
<para>The most fundemental entity in Boost.Build is <emphasis>main
|
|
target</emphasis>. This is object that user want to construct from
|
|
sources and keep up to date with regard to those sources. Typical
|
|
examples of main targets are executable files and libraries.</para>
|
|
|
|
<para>Main targets are grouped in <emphasis>projects</emphasis>. Their main
|
|
purpose is organization: related targets placed in one project,
|
|
can then be built together, or share some definitions.</para>
|
|
|
|
<para>Main targets and projects are created as the result of reading
|
|
one or several Jamfiles. Each Jamfile is a file written in
|
|
Boost.Jam interpreted language, and typically contains calls to
|
|
functions provided by Boost.Build, which create main targets of
|
|
needed type, declare project attributes and access other
|
|
projects. The full list of functions provided by Boost.Build is
|
|
described <link linkend="bbv2.advanced.builtins">below</link>.
|
|
Of course, user can create his own functions, or it can directly
|
|
access Boost.Build internals from Jamfile, if builtin facilities are
|
|
not sufficient.</para>
|
|
|
|
<para>Each main target, or project can be built in a number of ways,
|
|
say with optimization or without. We'll call such entities
|
|
"metatargets". To make Boost.Build produce any real targets, user
|
|
issues <link linkend="bbv2.reference.buildreq">build request</link>,
|
|
which specifies metatargets to be built, and properties to be
|
|
used.</para>
|
|
|
|
<para>The <emphasis>properties</emphasis> are just (name,value) pairs that
|
|
describe various aspects of constructed objects, for example:</para>
|
|
<programlisting>
|
|
<optimization>full <inlining>off
|
|
</programlisting>
|
|
|
|
<para>Given the built request, Boost.Build figures out the targets
|
|
needed for requested metatargets with requested properties, how
|
|
they can be created, and whether exising files can be reused. It
|
|
finally issues command to create needed files, automatically
|
|
converting properties into appropricate command line options.</para>
|
|
-->
|
|
<!-- ======================================================== -->
|
|
</section>
|
|
|
|
<!-- Delete this flotsam too! -->
|
|
<!-- ======================================================== -->
|
|
<!--
|
|
<section id="bbv2.advanced.roadmap">
|
|
<title>Your first project and roadmap</title>
|
|
|
|
|
|
<para>Creating your first project requires three steps:</para>
|
|
|
|
<orderedlist>
|
|
<listitem><simpara>Create an empty file called "Jamfile"</simpara></listitem>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
Create an empty file called "project-root.jam"
|
|
</simpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Either set your <envar>BOOST_BUILD_PATH</envar> environment
|
|
variant to Boost.Build root, or create a "boost-build.jam" file
|
|
with the following content:
|
|
|
|
<programlisting>
|
|
boost-build /path/to/boost.build ;
|
|
</programlisting>
|
|
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>After that, you can run the "bjam" command in the directory
|
|
where you've created the files. Surely, it won't do anything, but
|
|
it will run without error, at least. Your next steps might
|
|
be:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<simpara>
|
|
Adding new main targets to the "Jamfile" file. The basic
|
|
syntax for declaring a main target is described <link linkend=
|
|
"bbv2.advanced.targets">below</link>, and all builtin functions for
|
|
declaring main targets are <link linkend=
|
|
"bbv2.advanced.builtins.targets">listed</link>.
|
|
</simpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
Creating subprojects. Create a directory, put new Jamfile
|
|
there, and move some main targets to that Jamfile, or declare
|
|
new ones. The <link linkend="bbv2.advanced.projects">projects
|
|
reference</link> will help with this part.
|
|
</simpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
Customizing Boost.Build for your needs. You might have
|
|
additional tools you want to run, or just want different
|
|
extension for some file. The <link linkend="bbv2.extending">extender manual</ulink> is waiting for
|
|
you.
|
|
</simpara>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
</section>
|
|
-->
|
|
<section id="bbv2.advanced.targets">
|
|
<title>Main 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 <!-- a named --> executable file.
|
|
<!-- We already said it was named in the very same sentence.
|
|
Is there even such a thing as an unnamed executable?? -->
|
|
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>
|
|
|
|
<para>Most main target rules in Boost.Build can be invoked with
|
|
a common syntax:</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.
|
|
-->
|
|
|
|
<anchor id="bbv2.main-target-rule-syntax"/>
|
|
<programlisting>
|
|
<replaceable>rule-name</replaceable> <replaceable>main-target-name</replaceable>
|
|
: <replaceable>sources...</replaceable>
|
|
: <replaceable>requirements...</replaceable>
|
|
: <replaceable>default-build...</replaceable>
|
|
: <replaceable>usage-requirements...</replaceable>
|
|
;
|
|
</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 shorter list of parameters;
|
|
consult their documentation for details.
|
|
</para>
|
|
<para>Note that the actual requirements, default-build and
|
|
usage-requirements attributes for a target are obtained by
|
|
combining the explicitly specified ones with those specified for
|
|
the project where a target is declared.
|
|
<!-- Need an xref here to the place where the combination is
|
|
described in detail -->
|
|
</para>
|
|
|
|
<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 files with 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>
|
|
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 need to <!-- targets don't "specify"
|
|
anything -->be qualified with<!----> a directory or a symbolic
|
|
project name. For example:
|
|
<programlisting>
|
|
lib helper : helper.cpp ;
|
|
exe a : a.cpp helper ;
|
|
exe b : b.cpp ..//utils ;<!-- It's unclear at this point whether that's a directory path or project ID. Clarify -->
|
|
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 its absolute symbolic name. More
|
|
information about it <!-- What is "it?" Used here, "it" must
|
|
refer to "some C++ Boost library" or "its absolute symbolic
|
|
name -->can be found in <xref
|
|
linkend="bbv2.tutorial.libs"/> and <xref
|
|
linkend="bbv2.reference.ids"/>.
|
|
</para>
|
|
|
|
<!--
|
|
<section id="bbv2.advanced.targets.requirements">
|
|
<title>Requirements and usage-requirements</title>
|
|
|
|
<para>The requirements argument specify what properties are absolutely
|
|
necessary for this main target.
|
|
</section>
|
|
-->
|
|
<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>
|
|
In special circumstances,
|
|
<!-- What sort of "special circumstances?" This is vague and unclear -->
|
|
other properties can be used, 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>Sometimes requirements are necessary only for a specific
|
|
compiler or build variant. <link
|
|
linkend="bbv2.reference.variants.propcond">Conditional
|
|
properties</link> can be used in that case:
|
|
<!-- This phrasing is a bit awkward. Hasn't this been covered
|
|
more thoroughly in the tutorial? -->
|
|
<programlisting>
|
|
lib util : util.cpp : <toolset>msvc:<link>static ;
|
|
</programlisting>
|
|
<!-- "In means when whenever" is nonsense -->
|
|
Whenever <code><toolset>msvc</code> property is
|
|
in build properties, the <code><link>static</code> property will
|
|
be included as well. Conditional requirements can be “chained”:
|
|
<programlisting>
|
|
lib util : util.cpp : <toolset>msvc:<link>static
|
|
<link>static:<define>STATIC_LINK ;
|
|
</programlisting>
|
|
will set of static link
|
|
<!-- ??? Even if you remove "of," what does it mean to "set static link?" -->
|
|
and the <code>STATIC_LINK</code> define on the
|
|
<code>msvc</code> toolset.
|
|
<!-- really, on the **toolset** ?? I don't think so!-->
|
|
</para>
|
|
|
|
<para>The <varname>default-build</varname> parameter
|
|
<!-- You can't say "attribute" here because you use it with an
|
|
entirely different meaning in the next section! -->
|
|
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.<!-- Is that still true? I thought
|
|
requirements could be overridden by explicit request as
|
|
propagated from dependents -->
|
|
</para>
|
|
|
|
<para>A target of the same name can be declared several times, in which
|
|
case each declaration is called an
|
|
<firstterm>alternative</firstterm>. When the target is built, one of
|
|
the alternatives will be selected and used. Alternatives need not be
|
|
defined by the same main target rule. For example,
|
|
<programlisting>
|
|
lib helpers : helpers.hpp ; # a header-only library
|
|
alias helpers : helpers.lib : <toolset>msvc ; # except on msvc
|
|
</programlisting>
|
|
<!-- Above, is "helpers.lib" a target reference or a file reference?
|
|
If the former, how does the extension get added? If the latter,
|
|
is it a realistic case? What about:
|
|
|
|
obj helpers : helpers.cpp
|
|
lib helpers : helpers.cpp msvc_helper.cpp : <toolset>msvc ;
|
|
|
|
??
|
|
-->
|
|
</para>
|
|
|
|
<para>The actual commands used to build any given main target can differ greatly from
|
|
platform to platform. For example, you might have different lists
|
|
of sources for different compilers, or different options for those
|
|
compilers. Two approaches to this are explained in the
|
|
<link linkend="bbv2.tutorial.conditions">tutorial</link>.
|
|
<!-- Doing an inferior job of covering this material here is
|
|
bad. This chapter should be merged with the tutorial.
|
|
|
|
Also, AFAICT only one approach is explained in the
|
|
referenced section. Another approach that might have
|
|
been covered would be to combine the <source> property,
|
|
which is covered in a different section of the tutorial,
|
|
with conditional properties. -->
|
|
</para>
|
|
|
|
<para>Sometimes a main target is really needed only by some other main
|
|
target. For example, a rule that declares a test-suite uses a main
|
|
target
|
|
<!-- how can a rule "use a main target??" -->
|
|
that represent test, but those main targets are rarely needed
|
|
by themselves.
|
|
<!-- what does that mean?? This is completely opaque to me.
|
|
IMO this whole paragraph should be dropped -->
|
|
</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.
|
|
<!-- This bit was unintelligible until I reread it about 10 times
|
|
|
|
It's possible to request main targets declared inline, but
|
|
since they are considered local, they are renamed to
|
|
"parent-main-target_name..main-target-name"
|
|
-->
|
|
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>
|
|
|
|
</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 previous description was completely wrong and confusing -->
|
|
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 for the 'project' rule</entry>
|
|
<!-- Incorrectly gives the impression that Project IDs
|
|
(for example) are not called “Project ID” except
|
|
in the context of the 'project' rule. BTW, use
|
|
<function>...</function>, not single quotes -->
|
|
|
|
<entry>Default value</entry>
|
|
|
|
<entry>Handling by the 'project' 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 <link
|
|
linkend="bbv2.advanced.projects.relationships.useprojectrule"><functionname>use-project</functionname></link>,
|
|
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><link linkend=
|
|
"bbv2.advanced.projects.relationships.useprojectrule">use-project</link></entry>
|
|
|
|
<entry>Make another project known so that it can be referred to by symbolic ID.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><link linkend=
|
|
"bbv2.advanced.projects.relationships.buildprojectrule">build-project</link></entry>
|
|
|
|
<entry>Cause another project to be built when this one is built.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><link linkend=
|
|
"bbv2.reference.buildprocess.explict">explicit</link></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>
|
|
|
|
|
|
<!-- STRIKE ALL FLOTSAM!! -->
|
|
<!--
|
|
<section id="bbv2.advanced.projects.relationships">
|
|
<title>Project relationship</title>
|
|
|
|
<para>There are three kinds of project relationships.</para>
|
|
|
|
<para>First is parent-child. This relationship is established
|
|
implicitly: parent directories of a project are searched, and the
|
|
first found Jamfile is assumed to define the parent project. The
|
|
parent-child relationship affects only attribute values for the
|
|
child project.</para>
|
|
|
|
<para id="bbv2.advanced.projects.relationships.buildprojectrule">
|
|
Second is build relationship. Some
|
|
project may request to recursively build other projects. Those
|
|
project need not be child projects. The <literal>build-project</literal>
|
|
rule is used for that:</para>
|
|
<programlisting>
|
|
build-project src ;
|
|
</programlisting>
|
|
|
|
<para id="bbv2.advanced.projects.relationships.useprojectrule">
|
|
The third kind is the 'use'
|
|
relationship. In means that one project uses targets from
|
|
another. It is possible to just refer to target in other projects
|
|
using target id. However, if target id uses project id, it is
|
|
required that the project id is known. The
|
|
<literal>use-project</literal>
|
|
rule is employed to guarantee that.
|
|
</para>
|
|
|
|
<programlisting>
|
|
use-project ( id : location )
|
|
</programlisting>
|
|
|
|
<para>
|
|
It loads the project at the specified location, which makes
|
|
its project id available in the project which invokes the rule. It
|
|
is required that the <literal>id</literal> parameter passed to the
|
|
<literal>use-project</literal> rule be equal to the id that the loaded
|
|
project declared. At this moment, the <literal>id</literal> paremeter
|
|
should be absolute project id.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
-->
|
|
<!-- STRIKE ALL FLOTSAM!! -->
|
|
|
|
</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,
|
|
<!-- Don't say “of course”—it just makes those not already
|
|
familiar with what you're describing feel stupid. -->
|
|
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"/>.
|
|
<!-- The previous text was unintelligible. Did I guess your meaning? -->
|
|
</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>
|
|
|
|
<!-- Every section must have immediate content, even if it's only
|
|
an introductory sentence or two -->
|
|
<section>
|
|
<title>Programs</title>
|
|
|
|
<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 <code>alias</code> rule follows the <link
|
|
linkend="bbv2.main-target-rule-syntax">common syntax</link>. For
|
|
example:
|
|
<programlisting>
|
|
alias core : im reader writer ;
|
|
</programlisting>
|
|
will build the sources
|
|
<!-- it's not immediately obvious that there are sources. Make this more transparent -->
|
|
and return
|
|
<!-- no mental model -->
|
|
the generated source targets
|
|
without modification.
|
|
</para>
|
|
|
|
<para>
|
|
The <functionname>alias</functionname> rule is a convenience tool. If you often build
|
|
the same group of targets at the same time, you can define an alias
|
|
to save typing.
|
|
</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,
|
|
<varname>dll-path</varname>.
|
|
</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>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>
|
|
<simpara>
|
|
A feature that combines several low-level features, making
|
|
it easy to request common build configurations.
|
|
</simpara>
|
|
|
|
<para><emphasis role="bold">Allowed values:</emphasis> <literal>debug</literal>, <literal>release</literal>,
|
|
<literal>profile</literal></para>
|
|
<!-- It should be noted that these are extensible -->
|
|
|
|
<para>The value <literal>debug</literal> expands to</para>
|
|
|
|
<!-- these are badly formatted when printed; they run off the right edge of the page. Fix. -->
|
|
<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><emphasis role="bold">Rationale:</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? -->
|
|
It's assumed other folks don't
|
|
have any specific expectation in this point.
|
|
<!-- What is the value of that sentence? -->
|
|
</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. The feature
|
|
is sometimes more convenient:
|
|
<!-- Than what? You have to say, or don't say "more." -->
|
|
you can put <code><source>X</code> in the
|
|
requirements for a project and <filename>X</filename> will
|
|
be included as a source in all of the project's main
|
|
targets.
|
|
<!-- The previous text was inaccurate -->
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry><term><literal>library</literal></term>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
This feature is equivalent to the <source> feature, and exists
|
|
for backward compatibility reasons.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry><term><anchor id="bbv2.builtin.features.dependency"/>
|
|
<literal>dependency</literal></term>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
<!-- vp: I'm just copy-pasting the description of
|
|
'use', so that I can document 'stage'. I'll clean things up
|
|
when I get to editing this part -->
|
|
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.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><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>
|
|
|
|
|
|
</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, there were two methods to configure a toolset. One was to
|
|
set some environment variable, or use the <option>-s</option> command line option to set
|
|
a variable inside BJam.
|
|
<!-- You can't say "one was ... , or ...." If you say "One
|
|
was," you have to say "and the other was." I suggest "In
|
|
V1 you could configure a toolset by..., or by ... " -->
|
|
Another method was to create a new toolset module that would set
|
|
the variables and then invoke the base toolset. Neither method
|
|
is necessary now: the <functionname>using</functionname> rule provides a consistent way to
|
|
initialize a toolset,
|
|
<!-- Rephrase the following. If you can't tell what doesn't work about it, ask. -->
|
|
including several versions. 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:
|
|
-->
|