mirror of
https://github.com/boostorg/build.git
synced 2026-02-15 13:02:11 +00:00
1567 lines
58 KiB
HTML
1567 lines
58 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content=
|
|
"HTML Tidy for Linux/x86 (vers 1st September 2003), see www.w3.org">
|
|
<meta name="generator" content="Microsoft FrontPage 5.0">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
|
|
<link rel="stylesheet" type="text/css" href="../../../boost.css">
|
|
<!-- tidy options: ‐‐tidy-mark false -i -wrap 78 !-->
|
|
|
|
<title>Boost Build System</title>
|
|
</head>
|
|
|
|
<body bgcolor="#FFFFFF" text="#000000">
|
|
<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
|
|
"header">
|
|
<tbody>
|
|
<tr>
|
|
<td valign="top" width="300">
|
|
<h3><a href="http://www.boost.org/"><img height="86" width="277"
|
|
alt="C++ Boost" src="../../../boost.png" border="0"></a></h3>
|
|
</td>
|
|
|
|
<td valign="top">
|
|
<h1 align="center">Boost Build System</h1>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h2><a name="synopsis" id="synopsis">Synopsis</a></h2>
|
|
|
|
<p>Boost.Build is a system for large project software construction built on
|
|
<a href="../jam_src/index.html">Boost.Jam</a>, a descendant of "<a href=
|
|
"http://www.perforce.com/jam/jam.html">Perforce Jam</a>", an open-source
|
|
make replacement<a href="#one">[1]</a>. Key features are:</p>
|
|
|
|
<ul>
|
|
<li>A simple target description language</li>
|
|
|
|
<li>Build with your choice (or multiple) toolsets from a single command
|
|
invocation</li>
|
|
|
|
<li>Build your choice of basic variants (e.g. debug, release, profile...)
|
|
and subvariant modifications (e.g. inlining off) from a single command
|
|
invocation</li>
|
|
|
|
<li>``Feature Normalization'' allows target configurations to be
|
|
described independently from the toolset used</li>
|
|
|
|
<li>Modular toolset description files allow build instructions for
|
|
different toolsets to be described independently</li>
|
|
|
|
<li>Multiple subproject support</li>
|
|
|
|
<li>Automatic building of subproject dependencies</li>
|
|
</ul>
|
|
|
|
<h2><a name="status" id="status">Status</a></h2>Boost.Build v1 is a useful,
|
|
mature system. However, its design and structure are not easily adapted to
|
|
support some of the features we'd like to see in the future. To this end,
|
|
the Boost.Build developers are working on <a href=
|
|
"../v2/index.html">Boost.Build v2</a>, which is pretty usable already. If
|
|
you are interested in contributing to this effort or you wish to discuss
|
|
the design of Boost.Build, please post inquiries to the <a href=
|
|
"http://groups.yahoo.com/group/jamboost/">jamboost</a> mailing list at
|
|
yahoogroups.
|
|
|
|
<p><a href="#design_criteria">Here</a> are some of the design criteria that
|
|
led to these features.</p>
|
|
|
|
<h2>Table of Contents</h2>
|
|
|
|
<ul>
|
|
<li><a href="#synopsis">Synopsis</a></li>
|
|
|
|
<li><a href="#status">Status</a></li>
|
|
|
|
<li>
|
|
<a href="#getting_started">Getting Started</a>
|
|
|
|
<ul>
|
|
<li><a href="#installing_jam">Installing Boost.Jam</a></li>
|
|
|
|
<li><a href="#initiating">Initiating a Build</a></li>
|
|
|
|
<li><a href="#setting_variables">Setting Jam Variables</a></li>
|
|
|
|
<li><a href="#example_jamfile">An Example Jamfile</a></li>
|
|
|
|
<li><a href="#support_files">Support Files</a></li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#design">Basic Design and Terminology</a>
|
|
|
|
<ul>
|
|
<li><a href="#project_subproject">Projects and Subprojects</a></li>
|
|
|
|
<li><a href="#targets">Targets</a></li>
|
|
|
|
<li><a href="#features">Features and Properties</a></li>
|
|
|
|
<li><a href="#variants">Build Variants</a></li>
|
|
|
|
<li><a href="#subvariants">Subvariants</a></li>
|
|
|
|
<li><a href="#dependents">Dependent Targets</a></li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#usage">Usage</a>
|
|
|
|
<ul>
|
|
<li>
|
|
<a href="#command_line">The Command-Line</a>
|
|
|
|
<ul>
|
|
<li><a href="#user_targets">User Targets</a></li>
|
|
|
|
<li><a href="#user_globals">Global Variables</a></li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#subproject_jamfiles">Subproject Jamfiles</a>
|
|
|
|
<ul>
|
|
<li><a href="#subproject_rule">The <tt>subproject</tt>
|
|
Rule</a></li>
|
|
|
|
<li><a href="#main_targets">Describing Main Targets</a></li>
|
|
|
|
<li><a href="#template_targets">Describing Template
|
|
Targets</a></li>
|
|
|
|
<li><a href="#stage_targets">Describing Stage Targets</a></li>
|
|
|
|
<li><a href="#jamfile_example">Example</a></li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li><a href="#external_project">Using External Projects</a></li>
|
|
|
|
<li><a href="#requirement_rules">Requirement Rules</a></li>
|
|
|
|
<li><a href="#install_descriptions">Install Descriptions</a></li>
|
|
|
|
<li><a href="#feature_description">Feature Descriptions</a></li>
|
|
|
|
<li><a href="#variant_description">Variant Descriptions</a></li>
|
|
|
|
<li>
|
|
<a href="#toolset_description">Toolset Description Files</a>
|
|
|
|
<ul>
|
|
<li><a href="#toolset_example">Example</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#internals">Internals</a>
|
|
|
|
<ul>
|
|
<li><a href="#target_names">Target Names</a></li>
|
|
|
|
<li><a href="#internal_globals">Global Variables</a></li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#design_criteria">Design Criteria</a>
|
|
|
|
<ul>
|
|
<li><a href="#assumptions">Assumptions</a></li>
|
|
|
|
<li><a href="#requirements">Requirements</a></li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li><a href="#footnotes">Footnotes</a></li>
|
|
</ul>
|
|
|
|
<h2><a name="getting_started" id="getting_started">Getting Started</a></h2>
|
|
|
|
<h3><a name="installing_jam" id="installing_jam">Installing
|
|
Boost.Jam</a></h3>Follow these <a href=
|
|
"../../../more/getting_started.html#step2">instructions</a> to acquire a
|
|
bjam executable for your platform. Install it somewhere in your path.
|
|
|
|
<h3><a name="initiating" id="initiating">Initiating a Build</a></h3>
|
|
|
|
<p>Boost.Build responds to several global variable settings. The easiest
|
|
way to get going is usually to use environment variables, though you can
|
|
also set them on the command-line, using
|
|
<tt>-s</tt><i>VARIABLE_NAME</i><tt>=</tt><i>value</i>. In addition to the
|
|
<a href="../../../more/getting_started.html#step3">toolset configuration
|
|
variables</a>, you can use the <tt>TOOLS</tt> variable to indicate which
|
|
toolset(s) to build with, and the <tt>BUILD</tt> variable to describe how
|
|
you want things built. In many cases it should be sufficient to invoke
|
|
<code>bjam</code> with no variable settings.</p>
|
|
|
|
<p>Some example Boost.Jam invocations:</p>
|
|
|
|
<table border="1" summary="Sample Jam Invocations=">
|
|
<tr>
|
|
<th>Command Line(s)</th>
|
|
|
|
<th>Effects</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>
|
|
<pre>
|
|
bjam -sTOOLS=gcc my_target
|
|
</pre>
|
|
</td>
|
|
|
|
<td>default (debug) <tt><a href="#build">BUILD</a></tt> of
|
|
<tt>my_target</tt>with GCC</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>
|
|
<pre>
|
|
bjam "-sTOOLS=msvc gcc"
|
|
</pre>
|
|
</td>
|
|
|
|
<td>default-build <tt>all</tt> with msvc and gcc</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>
|
|
<pre>
|
|
set TOOLS=msvc
|
|
bjam
|
|
</pre>
|
|
</td>
|
|
|
|
<td>Set an NT environment variable to always build with MSVC<br>
|
|
default-build <tt>all</tt>.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>
|
|
<pre>
|
|
bjam "-sBUILD=release <debug-symbols>on"
|
|
</pre>
|
|
</td>
|
|
|
|
<td>release build with debug symbols of <tt>all</tt> using default
|
|
<tt><a href="#tools">TOOLS</a></tt></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>
|
|
<pre>
|
|
bjam "-sBUILD=debug release"
|
|
</pre>
|
|
</td>
|
|
|
|
<td>debug and release build <tt>all</tt>.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>set TOOLS=msvc<br>
|
|
bjam "-sBUILD=<cxxflags>-G6"<br>
|
|
</code></td>
|
|
|
|
<td>Set an NT environment variable to always build with MSVC<br>
|
|
default-build <tt>all</tt>, adding a compiler command line switch</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>set TOOLS=msvc gcc<br>
|
|
bjam "-sBUILD=<msvc><*><cxxflags>-G6"<br>
|
|
</code></td>
|
|
|
|
<td>Set an NT environment variable to always build with MSVC and
|
|
GCC<br>
|
|
default-build <tt>all</tt>, adding a MSVC-specific compiler command
|
|
line switch</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>bjam "-sBUILD=<define>BOOST_POSIX"</code></td>
|
|
|
|
<td>build all, with the macro BOOST_POSIX defined for all
|
|
compilers</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h3><a name="setting_variables" id="setting_variables">Setting Jam
|
|
Variables</a></h3>
|
|
|
|
<p>The "<tt>-s</tt>" options in the command lines above are passing
|
|
variable settings to the build system. There are actually three ways to do
|
|
that:</p>
|
|
|
|
<ul>
|
|
<li>Jam picks up variable settings from your environment by default, so
|
|
you can set them there:
|
|
|
|
<blockquote>
|
|
<pre>
|
|
> <a href="#build">BUILD</a>="debug release" <i># assuming Unix</i>
|
|
> export <a href="#build">BUILD</a>
|
|
> bjam ...
|
|
</pre>
|
|
</blockquote>This approach can be OK for quick-and-dirty tests, but
|
|
environment variable settings tend to be unstable and non-uniform
|
|
across users and machines, so it's best not to rely on the environment
|
|
much.
|
|
</li>
|
|
|
|
<li>Explicitly on the command-line, with the "<tt>-s</tt>" option.</li>
|
|
|
|
<li>Directly in Jam code. A project's <a href="#jamrules">Jamrules</a>
|
|
file is a convenient place to make global settings.</li>
|
|
</ul>
|
|
|
|
<h3><a name="example_jamfile" id="example_jamfile">An Example
|
|
Jamfile</a></h3>Here is an example of a simple subproject Jamfile. In this
|
|
example, it is assumed that the user has set <tt>BOOST_ROOT</tt>, either as
|
|
an environment variable, on the command-line or in the project's
|
|
<tt><a href="#jamrules">Jamrules</a></tt> file:
|
|
|
|
<blockquote>
|
|
<pre>
|
|
subproject foo/bar/baz ; # path to here from project root
|
|
|
|
# A static library called 'baz'
|
|
lib baz : baz1.cpp baz2.cpp # C++ sources
|
|
parser/src/baz4.ll # Lex->C++ sources
|
|
parser/src/baz5.yy # Yacc->C++ sources
|
|
: <include>$(BOOST_PARENT_DIRECTORY) # Put boost in #include path
|
|
;
|
|
|
|
# An executable called 'test'
|
|
exe test : <lib>baz # use the 'baz' library
|
|
baz_test.cpp # C++ source
|
|
: <include>$(BOOST_ROOT)
|
|
;
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>That's it! The build system takes care of the rest. If the you want to
|
|
be able to build all subprojects from the project root directory, you can
|
|
add a Jamfile at the root:</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
project-root ; # declare this to be the project root directory
|
|
# Read subproject Jamfiles
|
|
subinclude foo/bar/baz <font color="#7F7F7F">foo/bar/...</font> ;
|
|
<font color="#7F7F7F">subinclude a/b/c ...</font> ; # more subincludes
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<h3><a name="support_files" id="support_files">Support Files</a></h3>
|
|
|
|
<p>To use the build system, the following must be located in your project's
|
|
root directory, or in a directory specified in the
|
|
<tt>BOOST_BUILD_PATH</tt> variable. It is usually convenient to specify the
|
|
<tt>BOOST_BUILD_PATH</tt> in your project's <a href=
|
|
"#jamrules">Jamrules</a> file. The <a href="../../../Jamrules">Boost
|
|
Jamrules</a> file shows an example.</p>
|
|
|
|
<table border="1" summary="Support Files">
|
|
<tr>
|
|
<th>Filename(s)</th>
|
|
|
|
<th>Meaning</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><i>toolset</i><tt>-tools.jam</tt></td>
|
|
|
|
<td>Feature-to-command-line mapping for <i>toolset</i>.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><tt>features.jam</tt></td>
|
|
|
|
<td>Abstract toolset feature descriptions.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><tt>boost-base.jam</tt></td>
|
|
|
|
<td>Boost build system-specific rule definitions.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><tt>unit-tests.jam</tt></td>
|
|
|
|
<td>Unit tests and assertions for boost Jam code.</td>
|
|
</tr>
|
|
</table>The <tt>boost-base.jam</tt> file is temporary, and will eventually
|
|
be compiled into our Jam executable.
|
|
|
|
<h2><a name="design" id="design">Basic Design and Terminology</a></h2>This
|
|
section gives an overview of the way that the system works, outlining the
|
|
system's capabilities and overall design. It also introduces the
|
|
terminology and concepts necessary to understand the sections on writing
|
|
Jamfiles and command-line invocations.
|
|
|
|
<h3><a name="project_subproject" id="project_subproject">Projects and
|
|
Subprojects</a></h3>
|
|
|
|
<p>A <b>project</b> is a source directory tree containing at least one
|
|
<tt>Jamfile</tt>. The root directory of the project is known as the
|
|
<b>project root</b>. <a name="jamrules" id="jamrules">The</a> root
|
|
directory of a project may contain a <tt>Jamrules</tt> file, which contains
|
|
project-specific Jam code. If the <tt>Jamrules</tt> file is not present
|
|
when Jam is invoked, a warning will be issued.</p>
|
|
|
|
<p>Subdirectories containing <tt>Jamfile</tt>s are called <b>subproject
|
|
directories</b>. Each such <tt>Jamfile</tt> describes a
|
|
<b>subproject</b>.</p>
|
|
|
|
<p>The <b>build system installation directory</b> is a directory containing
|
|
Jam files describing compilers and build variants. The installation
|
|
directory can be specified in a file called <tt>boost-build.jam</tt> in the
|
|
project root directory. This file should contain a line <tt>boost-build
|
|
$path-to-installation-dir</tt>. If no such file is available the
|
|
environment variable <tt>BOOST_BUILD_PATH</tt> will be used. This lists a
|
|
set of directories to search for the files comprising the build system. If
|
|
the installation directory is not specified, it is the same as the project
|
|
root, and <tt>BOOST_BUILD_PATH</tt> is set to include that directory.</p>
|
|
|
|
<h3><a name="targets" id="targets">Targets</a></h3>
|
|
|
|
<p>Each <tt>Jamfile</tt> describes one or more <b>main targets</b>.</p>
|
|
|
|
<p>Each main target is an abstract description of one or more <b>built
|
|
targets</b> which are expressions of the corresponding main target under
|
|
particular compilers and build variants. Intermediate files such as
|
|
<tt>.o</tt>/<tt>.obj</tt> files generated by compiling <tt>.cpp</tt> files
|
|
as a consequence of building a main target are also referred to as built
|
|
targets. The term <b>build directory tree</b> refers to the location of
|
|
built target files.</p>
|
|
|
|
<ul>
|
|
<li>By default, the build directory tree is overlaid with the project
|
|
directory tree, with targets generated into a subtree rooted at the
|
|
<tt>bin</tt> subdirectory of each subproject directory (the name of this
|
|
directory can be customized by changing the <tt>BIN_DIRECTORY</tt>
|
|
variable.</li>
|
|
|
|
<li><a name="all_locate_target" id="all_locate_target">If the variable
|
|
<tt>ALL_LOCATE_TARGET</tt> is set</a>, it specifies an alternate build
|
|
directory tree whose structure mirrors that of the project. In this case,
|
|
built targets of a subproject are generated into the corresponding
|
|
directory of the build directory tree.</li>
|
|
</ul>For each main target, there is a corresponding location in the build
|
|
directory tree known as the target's <b>build root</b>, where all
|
|
intermediate and final targets resulting from that main target are located.
|
|
|
|
<h3><a name="features" id="features">Features and Properties</a></h3>
|
|
|
|
<p>A <b>feature</b> is a normalized (toolset-independent) description of an
|
|
individual build parameter, such as whether inlining is enabled. Each
|
|
feature usually corresponds to a command-line option of one or more build
|
|
tools. Features come in four varieties:</p>
|
|
|
|
<ol>
|
|
<li><b>Simple features</b> can take on any of several predetermined
|
|
values. For example, the feature <tt>optimization</tt> might take one of
|
|
the values <tt>off</tt>, <tt>speed</tt>, or <tt>space</tt>. Simple
|
|
features have a default value. The key aspect of simple features is that
|
|
they are assumed to affect link compatibility: object files generated
|
|
with different values for a simple feature are generated into a separate
|
|
directories, and (with a few exceptions) main targets generated with
|
|
different values won't be linked together.</li>
|
|
|
|
<li><b>Free features</b> can either be single-valued, as above, or may
|
|
take on any number of user-specified values simultaneously. For example,
|
|
the <tt>define</tt> feature for a release build might have the values
|
|
<tt>NDEBUG</tt> and <tt>BOOST_RELEASE_BUILD</tt>. Free features are
|
|
assumed not to affect link compatibility.</li>
|
|
|
|
<li><b>Path features</b> are free features whose values describe paths
|
|
which may be relative to the subproject (such as linked libraries or
|
|
<tt>#include</tt> search directories). The build system treats the values
|
|
of these features specially to ensure that they are interpreted relative
|
|
to the subproject directory regardless of the directory where Jam was
|
|
invoked.</li>
|
|
|
|
<li><b>Dependency features</b> are path features whose values describe a
|
|
dependency of built targets. For example, an external library might be
|
|
specified with a dependency-feature: if the library is updated, the
|
|
target will be updated also. The <tt><library-file></tt> feature
|
|
works this way <a href="#two">[2]</a>.</li>
|
|
</ol>
|
|
|
|
<p>A feature-value pair is known as a <b>build property</b>, or simply
|
|
<b>property</b>. The prefixes <i>simple</i>, <i>free</i>, <i>path</i>, and
|
|
<i>dependency</i> apply to properties in an analogous way to features.</p>
|
|
|
|
<h3><a name="variants" id="variants">Build Variants</a></h3>
|
|
|
|
<p>A build variant, or simply <b>variant</b> is a named set of build
|
|
properties describing how targets should be built. Typically you'll want at
|
|
least two separate variants: one for debugging, and one for your release
|
|
code.</p>
|
|
|
|
<p>Built targets for distinct build variants and toolsets are generated in
|
|
separate parts of the build directory tree, known as the <b>variant
|
|
directories</b>. For example, a (sub)project with main targets <tt>foo</tt>
|
|
and <tt>bar</tt>, compiled with both GCC and KAI for <tt>debug</tt> and
|
|
<tt>release</tt> variants might generate the following structure (target
|
|
directories in <b>bold</b>).</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
bin
|
|
+-foo <font color="#7F7F7F"><--- foo's build root</font>
|
|
| +-gcc
|
|
| | +-<b>debug</b>
|
|
| | `-<b>release</b>
|
|
| `-kai
|
|
| +-<b>debug</b>
|
|
| `-<b>release</b>
|
|
`-bar <font color="#7F7F7F"><--- bar's build root</font>
|
|
+-gcc
|
|
| +-<b>debug</b>
|
|
| `-<b>release</b>
|
|
`-kai
|
|
+-<b>debug</b>
|
|
`-<b>release</b>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>The properties constituting a variant may differ according to toolset,
|
|
so <tt>debug</tt> may mean a slightly different set of properties for two
|
|
different compilers.</p>
|
|
|
|
<h3><a name="subvariants" id="subvariants">Subvariants</a></h3>
|
|
|
|
<p>When a target is built with <i>simple</i> properties that don't exactly
|
|
match those specified in a build variant, the non-matching features are
|
|
called <b>subvariant features</b> and the target is located in a
|
|
<b>subvariant directory</b> beneath the directory of the base variant. This
|
|
can occur for two reasons:</p>
|
|
|
|
<ol>
|
|
<li>Some features are only relevant to certain compilers. When relevant
|
|
simple features have no value specified in the build variant, a value
|
|
must be chosen. Even when the default value is used, the target is
|
|
generated into a subvariant directory. For example, the
|
|
<tt>runtime-link</tt> feature may be unspecified in the <tt>debug</tt>
|
|
variant, but relevant to MSVC. In that case, a fragment of the target
|
|
tree might look like:
|
|
|
|
<blockquote>
|
|
<pre>
|
|
bin
|
|
+-foo <font color="#7F7F7F"><--- foo's build root</font>
|
|
| +-msvc
|
|
| | +-debug
|
|
. . . `-<b>runtime-link-dynamic</b>
|
|
. . .
|
|
</pre>
|
|
</blockquote>Because the default value of <tt>runtime-link</tt> is
|
|
<tt>dynamic</tt>, when the <tt>debug</tt> variant is requested, the
|
|
<tt>runtime-link-dynamic</tt> subvariant of foo is built.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>It is possible to request (either on the command-line, or as part of
|
|
a main target description) that particular subvariants be built. For
|
|
example, it may be desirable to generate builds that link to the runtime
|
|
both statically <i>and</i> dynamically. In that case, both subvariant
|
|
directories in the example above would be generated:
|
|
|
|
<blockquote>
|
|
<pre>
|
|
bin
|
|
+-foo <font color="#7F7F7F"><--- foo's build root</font>
|
|
| +-msvc
|
|
| | +-debug
|
|
. . . +-<b>runtime-link-dynamic</b>
|
|
. . . `-<b>runtime-link-static</b>
|
|
. . .
|
|
</pre>
|
|
</blockquote>
|
|
</li>
|
|
</ol>In no case will targets be built directly into
|
|
<tt>bin/foo/msvc/debug</tt>, since the <tt>debug</tt> variant doesn't
|
|
include the <tt>runtime-link</tt> feature, which is relevant to MSVC.
|
|
|
|
<p>When a subvariant includes multiple subvariant features, targets are
|
|
built into a subvariant directory whose path is determined by concatenating
|
|
the properties sorted in order of their feature names. For example, the
|
|
borland compiler, which uses different libraries depending on whether the
|
|
target is a console or GUI program, might create the following structure
|
|
for a DLL:</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
bin
|
|
+-foo <font color="#7F7F7F"><--- foo's build root</font>
|
|
| +-msvc
|
|
| | +-debug
|
|
| | | +-runtime-link-dynamic
|
|
| | | | +-<b>user-interface-console</b>
|
|
| | | | `-<b>user-interface-gui</b>
|
|
. . . `-runtime-link-static
|
|
. . . +-<b>user-interface-console</b>
|
|
. . . `user-interface-gui
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>Any configuration of properties for which a target is built, whether
|
|
base variant or subvariant, is known as a <b>build configuration</b>, or
|
|
simply a <b>build</b>.</p>
|
|
|
|
<h3><a name="dependents" id="dependents">Dependent Targets</a></h3>
|
|
|
|
<p>When a main target depends on the product of a second main target (as
|
|
when an executable depends on and links to a static library), each build
|
|
configuration of the dependent target is depends on the
|
|
<i>corresponding</i> build of the dependency. Because only simple features
|
|
participate in build identity, the dependent and dependency targets may
|
|
have completely different free features. This puts the onus on the user for
|
|
ensuring link-compatibility when certain free properties are used. For
|
|
example, when <tt>assert()</tt> is used in header files, the preprocessor
|
|
symbol <tt>NDEBUG</tt> can impact link-compatibility of separate
|
|
compilation units. This danger can be minimized by encapsulating such
|
|
feature differences inside of build variants.</p>
|
|
|
|
<h2><a name="usage" id="usage">Usage</a></h2>
|
|
|
|
<p>This section describes how to start a build from the command-line and
|
|
how to write project and subproject Jamfiles. It also describes the other
|
|
files written in the Jam language: build-tool specification files, feature
|
|
descriptions files.</p>
|
|
|
|
<h3><a name="command_line" id="command_line">The Command Line</a></h3>
|
|
|
|
<p>This section describes in detail how the build system can be
|
|
invoked.</p>
|
|
|
|
<h4><a name="user_targets" id="user_targets">User Targets</a></h4>
|
|
|
|
<p>The Jam command line ends with an optional list of target names; if no
|
|
target names are supplied, the built-in pseudotarget <tt>all</tt> is built.
|
|
In a large project, naming targets can be dicey because of collisions. Jam
|
|
uses a mechanism called grist to distinguish targets that would otherwise
|
|
have the same name. Fortunately, you won't often have to supply grist at
|
|
the command-line. When you declare a main target, a Jam pseudotarget of the
|
|
same name is created which depends on <i>all</i> of the subvariants
|
|
requested for your invocation of the build system. For example, if your
|
|
subproject declares:</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
exe my_target : my_source1.cpp my_source2.c ;
|
|
</pre>
|
|
</blockquote>and you invoke Jam with <tt>-sBUILD="debug
|
|
release" my_target</tt>, you will build both the debug and release
|
|
versions of <tt>my_target</tt>.
|
|
|
|
<p>These simple, ungristed names are called <b>user targets</b>, and are
|
|
only available for the subproject where Jam is invoked. That way, builds
|
|
from the top level (which may include many Jamfiles through the subinclude
|
|
rule) and builds of library dependencies (which may live in other
|
|
subprojects), don't collide. If it is necessary to refer more explicitly to
|
|
a particular target from the command-line, you will have to add ``grist''.
|
|
Please see <a href="#target_names">this section</a> for a more complete
|
|
description of how to name particular targets in a build.</p>
|
|
|
|
<h4><a name="user_globals" id="user_globals">Global Variables</a></h4>
|
|
|
|
<p>This is a partial list of global variables that can be set on the
|
|
command-line. Of course you are free to write your own Jam rules which
|
|
interpret other variables from the command-line. This list just details
|
|
some of the variables used by the build system itself. Note also that if
|
|
you don't like the default values you can override them in your project's
|
|
<tt><a href="#jamrules">Jamrules</a></tt> file.</p>
|
|
|
|
<table border="1" summary="User Globals">
|
|
<tr>
|
|
<th>Variable <!-- <th>Meaning --></th>
|
|
|
|
<th>Default</th>
|
|
|
|
<th>Example</th>
|
|
|
|
<th>Notes</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td rowspan="2"><tt><a name="tools" id="tools">TOOLS</a></tt>
|
|
<!-- <td rowspan="2">Toolsets to build with --></td>
|
|
|
|
<td rowspan="2">Platform-dependent</td>
|
|
|
|
<td><tt>"-sTOOLS=gcc msvc"</tt></td>
|
|
|
|
<td>build with gcc and msvc</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><tt>-sTOOLS=gcc</tt></td>
|
|
|
|
<td>build with gcc</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td rowspan="4"><tt><a name="build" id="build">BUILD</a></tt>
|
|
<!-- <td rowspan="4">Build configuration (see -->
|
|
<!-- <a href="#default_build">here</a>). --></td>
|
|
|
|
<td rowspan="4"><tt>debug</tt></td>
|
|
|
|
<td><tt>-sBUILD=release</tt></td>
|
|
|
|
<td>build the <tt>release</tt> variant</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><tt>"-sBUILD=debug release"</tt></td>
|
|
|
|
<td>build both <tt>debug</tt> and <tt>release</tt> variants</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><tt>"-sBUILD=<optimization>speed"</tt></td>
|
|
|
|
<td>build a subvariant of the default variant (<tt>debug</tt>) with
|
|
optimization for speed.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><tt>"-sBUILD=debug release
|
|
<runtime-link>static/dynamic"</tt></td>
|
|
|
|
<td>build subvariants of the debug and release variants that link to
|
|
the runtime both statically and dynamically.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><tt>ALL_LOCATE_TARGET</tt>
|
|
<!-- <td>Alternate location for built targets (see <a -->
|
|
<!-- href="#all_locate_target">here</a>) --></td>
|
|
|
|
<td><i>empty</i></td>
|
|
|
|
<td><tt>-sALL_LOCATE_TARGET=~/build</tt></td>
|
|
|
|
<td>Generate all build results in the <tt>build</tt> subdirectory of
|
|
the user's home directory (UNIX).</td>
|
|
</tr>
|
|
</table>This section describes how to write a Jamfile for a subproject.
|
|
|
|
<h3><a name="subproject_jamfiles" id="subproject_jamfiles">SubProject
|
|
Jamfiles</a></h3>
|
|
|
|
<h4><a name="subproject_rule" id="subproject_rule">The <tt>subproject</tt>
|
|
rule</a></h4>
|
|
|
|
<p>A subproject's Jamfile begins with an invocation of the
|
|
<tt>subproject</tt> rule that specifies the subproject's location relative
|
|
to the top of the project tree:</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
subproject <i>path-from-top</i> ;
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>The <tt>subproject</tt> rule tells the build system where to place built
|
|
targets from the subproject in case <tt>ALL_LOCATE_TARGET</tt> is used to
|
|
specify the build directory tree. If there is a Jamfile in the project root
|
|
directory, you should use the <tt>project-root</tt> rule instead:</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
project-root ;
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<h4><a name="main_targets" id="main_targets">Describing Main
|
|
Targets</a></h4>
|
|
|
|
<p>A main target is described using the following syntax:</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
<i>target-type</i> <i>name</i> : <i>sources</i>
|
|
[ : <i>requirements</i> [ : <i><a href=
|
|
"#default_build">default-BUILD</a></i> ] ] ;
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<ul>
|
|
<li><i>target-type</i> may be one of <tt>exe</tt>, <tt>lib</tt>,
|
|
<tt>dll</tt>, <tt>stage</tt> or <tt>template</tt>. These are actually
|
|
names of Jam rules. Additional main target rules are possible; see
|
|
<tt><a href="../../../status/Jamfile">status/Jamfile</a></tt> or
|
|
<tt><a href=
|
|
"../../../libs/python/build/Jamfile">libs/python/build/Jamfile</a></tt>
|
|
for examples.<br>
|
|
<br></li>
|
|
|
|
<li><i>name</i> specifies the name of the main target, multiple targets
|
|
with the same name are allowed but only if they are of different types.
|
|
Normally this is not the name of the final target file generated. The
|
|
target file name depends on the type of target which controls how the
|
|
base target name is renamed to conform to platform conventions. For
|
|
<tt>exe</tt>s the name might be the same or <tt>*.exe</tt>. For
|
|
<tt>lib</tt>s the name might be <tt>*.lib</tt> or <tt>lib*.a</tt>. And
|
|
for <tt>dll</tt>s the name might be <tt>*.dll</tt> or <tt>lib*.so</tt>.
|
|
For platform specific naming consult the <tt><a href=
|
|
"allyourbase.jam">allyourbase.jam</a></tt> file in the build system.<br>
|
|
<br></li>
|
|
|
|
<li>
|
|
<i>sources</i> is a list of paths to source files and dependency
|
|
targets. <a name="dependency" id="dependency">The</a> syntax for
|
|
dependency targets is described by the following grammar:
|
|
|
|
<blockquote>
|
|
<pre>
|
|
<i>dependency-target</i> -> <i>type-tag</i> <i>location</i> <b>target-name</b>
|
|
|
|
<i>type-tag</i> -> "<template>" | "<lib>" | "<dll>" | "<exe>"
|
|
|
|
<i>location</i> -> ( @<b>project-id</b>/ )? <i>relative-path</i>
|
|
|
|
<i>relative-path</i> -> ( <b>path-element</b>/ ) *
|
|
</pre>
|
|
</blockquote>The <i>location</i> specifies the location of a Jamfile in
|
|
which a dependency target called <code><b>target-name</b></code> can be
|
|
found, declared with the given <i>type-tag</i>. Other <i>type-tag</i>s
|
|
are possible; for example the <a href="python.jam">python.jam</a>
|
|
module defines Python extensions with the <code>"<pyd>"</code>
|
|
tag. If <code>@<b>project-id</b></code> is specified, the
|
|
<i>relative-path</i> is interpreted with respect to the root directory
|
|
of the <a href="#external_project">specified project</a>. Otherwise, it
|
|
is interpreted with respect to the directory of the current Jamfile.
|
|
|
|
<p>The dependency's <i>type-tag</i> is also used to decide how to link
|
|
to it when needed. <tt><lib></tt> targets are linked statically
|
|
and <tt><dll></tt> targets are linked dynamically. On Unix
|
|
platforms dynamic linking will use (the appropriate platform equivalent
|
|
of) <tt>LD_LIBRARY_PATH</tt> and the "<tt>-l</tt>" linker flag to avoid
|
|
creating executables which expect to find dynamic libraries in
|
|
particular locations in the filesystem.</p>
|
|
|
|
<p><b>NOTE:</b> It is important to match the <i>type-tag</i> dependency
|
|
with the type of the dependency target. Trying to specify a
|
|
<i>type-tag</i> of <tt><lib></tt> when the target is defined as a
|
|
<tt><dll></tt> will cause an error.</p><br>
|
|
</li>
|
|
|
|
<li>
|
|
<i><a name="target_requirements" id=
|
|
"target_requirements">requirements</a></i> specifies the build
|
|
properties intrinsic to the target. Requirements are given as sets of
|
|
optionally-<b>qualified build properties</b>:
|
|
|
|
<blockquote>
|
|
<pre>
|
|
[[<<i>compiler</i>>]<<i>variant</i>>]<<i>feature</i>><i>value</i>
|
|
</pre>
|
|
</blockquote><tt><<i>compiler</i>></tt> and
|
|
<tt><<i>variant</i>></tt>, if supplied, can be used to restrict
|
|
the applicability of the requirement. Either one may be replaced by
|
|
<tt><*></tt>, which is the same as omitting it.
|
|
|
|
<p>The system checks that simple feature requirements are not violated
|
|
by explicit subvariant build requests, and will issue a warning
|
|
otherwise. Free features specified as requirements are simply added to
|
|
each corresponding build configuration.</p><br>
|
|
</li>
|
|
|
|
<li>
|
|
<i><a name="default_build" id="default_build">default-BUILD</a></i>
|
|
specifies the configurations that should be built if the <tt><a href=
|
|
"#build">BUILD</a></tt> variable is not otherwise specified. Any
|
|
elements not beginning with ``<tt><</tt>...<tt>></tt>'' refer to
|
|
build variants. Other elements use the same syntax as the <a href=
|
|
"#target_requirements">requirements</a> described above, except that
|
|
multiple values may be specified for a simple feature by separating
|
|
them with a slash, forming (qualified) <b>multi-valued properties</b>:
|
|
|
|
<blockquote>
|
|
<pre>
|
|
[[<<i>compiler</i>>]<<i>variant</i>>]<<i>feature</i>><i>value1</i>[/<i>value2</i>...]
|
|
</pre>
|
|
</blockquote>When multiple values are specified, it causes <i>all</i>
|
|
the implied configurations to be built by default. It is also possible
|
|
to prevent any default builds from occurring on this target by using
|
|
<code><suppress>true</code> . This suppresses any local targets,
|
|
either implicit or explicit, from building. But, this does not prevent
|
|
implied targets as required by a dependency by another target to this
|
|
one from being built. This is useful, for example, for defining a set
|
|
of libraries generically and having them built only when another target
|
|
like an exe is built. Such use might look like:
|
|
|
|
<blockquote>
|
|
<pre>
|
|
lib basic : basic.cpp : : <suppress>true ;<br>
|
|
<br>
|
|
exe test : test.cpp <lib>basic ;
|
|
</pre>
|
|
</blockquote>With that the <tt>basic</tt> library will only be built
|
|
when the <tt>test</tt> executable is built, and only the variations
|
|
required by the executable will be built.<br>
|
|
</li>
|
|
</ul>
|
|
|
|
<p><b>NOTE:</b> for simple features in both <i><a href=
|
|
"#target_requirements">requirements</a></i> and <i><a href=
|
|
"#default_build">default-BUILD</a></i>, more-specific qualification
|
|
overrides less-specific.</p>
|
|
|
|
<h4><a name="template_targets" id="template_targets">Describing Template
|
|
Targets</a></h4>
|
|
|
|
<p>Template targets provide a way to handle commonalities between projects
|
|
targets. They have the same form as <a href="#main_targets">main
|
|
targets</a> but do not initiate build requests. A target that lists a
|
|
template as a dependency inherits all the settings from the template, i.e.
|
|
the templates sources, requirements and default build settings will be
|
|
added to the targets settings. Paths mentioned in a template definition are
|
|
always relative to the subdirectory of the Jamfile containing the templates
|
|
definition, regardless of the subdirectory of the dependent main target.
|
|
Typically a project will have at least one template target that handles
|
|
defines, include paths and additional compiler flags common to all targets
|
|
in the project.</p>
|
|
|
|
<h4><a name="stage_targets" id="stage_targets">Describing Stage
|
|
Targets</a></h4>
|
|
|
|
<p>Stage targets are a special kind of target that don't build a single
|
|
file but to a collection of files. The goal is to create a directory which
|
|
is composed of the various files that other targets generate, or individual
|
|
files. When built a stage target creates a directory with the same name as
|
|
the target, and copies the dependent files to it. The form of the target is
|
|
the same as that of <a href="#main_targets">main targets</a> with some
|
|
differences...</p>
|
|
|
|
<ul>
|
|
<li><i>target-type</i> is <tt>stage</tt>. See <tt><a href=
|
|
"../../../libs/regex/build/Jamfile">libs/regex/build/Jamfile</a></tt> for
|
|
an example.<br>
|
|
<br></li>
|
|
|
|
<li><i>Name</i> specifies the name of the stage and is the name of the
|
|
directory created.<br>
|
|
<br></li>
|
|
|
|
<li><i>sources</i> is the same as main targets and one can list both
|
|
generated targets like <tt><exe>test_exe</tt> and individual files,
|
|
but not template targets.<br>
|
|
<br></li>
|
|
|
|
<li>
|
|
<i>Requirements</i> the build properties specified are used as with
|
|
main targets. But one additional type of requirement is possible:
|
|
<tt><tag></tt>... A tag specifies how to "augment" the names of
|
|
the copied files. This is needed to distinguish the various files if
|
|
you're collecting different builds of the same targets. The syntax is:
|
|
|
|
<blockquote>
|
|
<pre>
|
|
<tag><<i>feature|variant</i>><i>value</i>
|
|
</pre>
|
|
</blockquote><br>
|
|
If the <tt><i>feature</i></tt> or <tt><i>variant</i></tt> is present
|
|
for the a target the file for that target is renamed to include the
|
|
given <tt><i>value</i></tt> between the basename and the suffix. Two
|
|
special <tt>tag</tt>s, <tt><tag><prefix></tt> and
|
|
<tt><tag><postfix></tt>, let one prepend and append a value
|
|
to the "augmentation" respectively.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><i>default-BUILD</i> acts in the same manner as a main
|
|
target.<br></li>
|
|
</ul>
|
|
|
|
<h4><a name="jamfile_example" id="jamfile_example">Example</a></h4>
|
|
|
|
<p>This artificially complex example shows how two executables called "foo"
|
|
and "fop" might be described in a Jamfile. All common settings are factored
|
|
out in the templates "base" and "executable". Foo is composed of the
|
|
sources <tt>./foo.cpp</tt> and <tt>./src/bar.cpp</tt> (specified relative
|
|
to the directory in which the Jamfile resides). Fop only has one sourcefile
|
|
<tt>./fop.cpp</tt>. Both executables link against the built target which
|
|
results from building the target <tt>baz</tt> as described in
|
|
<tt>../bazlib/Jamfile</tt>.</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
template base :
|
|
## <a href="#target_requirements">Requirements</a> ##
|
|
: <include>../bazlib/include
|
|
<define>BUILDING_FOO=1
|
|
<release><define>FOO_RELEASE
|
|
<msvc><*><define>FOO_MSVC
|
|
<msvc><release><define>FOO_MSVC_RELEASE
|
|
<gcc><*><optimization>off
|
|
<gcc><release><optimization>space
|
|
<threading>multi
|
|
<sysinclude>/usr/local/foolib/include
|
|
|
|
## <a href="#default_build">default-BUILD</a> ##
|
|
: debug release
|
|
<debug><runtime-link>static/dynamic
|
|
;
|
|
|
|
template executable : <template>base <lib>../bazlib/baz ;
|
|
|
|
exe foo : <template>executable foo.cpp src/bar.cpp ;
|
|
|
|
exe fop : <template>executable fop.cpp ;
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>The <a href="#target_requirements">requirements</a> section:</p>
|
|
|
|
<ul>
|
|
<li>Adds <tt>../bazlib/include</tt> to the <tt>#include</tt> path</li>
|
|
|
|
<li>Sets the preprocessor symbol <tt>BUILDING_FOO</tt> to <tt>1</tt></li>
|
|
|
|
<li>In the <tt>release</tt> builds, <tt>#define</tt>s
|
|
<tt>FOO_RELEASE</tt>.</li>
|
|
|
|
<li>When built with MSVC, <tt>#define</tt>s <tt>FOO_MSVC</tt>.</li>
|
|
|
|
<li>In <tt>release</tt> variants built with MSVC, <tt>#define</tt>s
|
|
<tt>FOO_MSVC_RELEASE</tt>.</li>
|
|
|
|
<li>Most builds under GCC have optimization turned off, but...</li>
|
|
|
|
<li>...GCC <tt>release</tt> builds require optimization for space.</li>
|
|
|
|
<li>Requires multithread support on compilers where it's relevant.</li>
|
|
|
|
<li>Adds <tt>/usr/local/foolib/include</tt> to the <tt>#include
|
|
<*></tt> path</li>
|
|
</ul>
|
|
|
|
<p>The <a href="#default_build">default-BUILD</a> section:</p>
|
|
|
|
<ul>
|
|
<li>specifies that <tt>debug</tt> and <tt>release</tt> base variants are
|
|
built by default.</li>
|
|
|
|
<li>on compilers where the feature is relevant, requests both statically-
|
|
and dynamically-linked subvariants of the debug variant.</li>
|
|
</ul>
|
|
|
|
<h3><a name="external_project" id="external_project">Using External
|
|
Projects</a></h3>To use dependencies such as libraries from another project
|
|
tree, first use the <code>project</code> rule to declare a project id and
|
|
location for the external project. Then add the appropriate external
|
|
<a href="#dependency">dependency target specification</a> to your program's
|
|
list of sources. For example, if you are developing a program which uses
|
|
the Boost.Threads library, you might write
|
|
|
|
<blockquote>
|
|
<pre>
|
|
project boost : /home/dave/boost-cvs ;
|
|
</pre>
|
|
</blockquote>in your <a href="#jamrules">Jamrules</a> file, and place
|
|
|
|
<blockquote>
|
|
<pre>
|
|
<dll>@boost/libs/thread/build/boost_thread
|
|
</pre>
|
|
</blockquote>in your target's list of sources.
|
|
|
|
<h3><a name="requirement_rules" id="requirement_rules">Requirement
|
|
Rules</a></h3>
|
|
|
|
<p>Target requirements support the use of auxiliary rules to allow for more
|
|
complex decisions about the requirements. If specified, by using the name
|
|
of a rule in the requirements, the rule is called with the signature: <tt>(
|
|
toolset variant : subvariant-path properties * )</tt> and should return the
|
|
modified set of properties. There are a number of built-in rules for some
|
|
common tasks that Boost uses, and you can use:</p>
|
|
|
|
<blockquote>
|
|
<table border="1" summary="Built In Requirement Rules">
|
|
<tr>
|
|
<th>Rule</th>
|
|
|
|
<th>Effects</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><tt>std::locale-support</tt></td>
|
|
|
|
<td>Ensures that locale support is available for the target. For
|
|
example some toolsets, like CodeWarrior, locale support is only
|
|
available on specific platforms using a static runtime.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><tt>std::facet-support</tt></td>
|
|
|
|
<td>Ensures that facet support is available for the target.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><tt>common-variant-tag</tt></td>
|
|
|
|
<td>
|
|
<p>Adds a constructed prefix tag to the target to conform to the
|
|
Boost common naming conventions for libraries. The tag is
|
|
constructed as:</p>
|
|
|
|
<blockquote>
|
|
[-<toolset-tag>][-<thread-tag>][-<runtime-tag>][-<version-tag>]
|
|
</blockquote>
|
|
|
|
<ul>
|
|
<li><toolset-tag> maps to an abbreviated name of the
|
|
toolset and when possible, and applicable, the version of the
|
|
toolset.</li>
|
|
|
|
<li><thread-tag> "mt" when multi-threading is enabled.</li>
|
|
|
|
<li><runtime-tag> adds these single letter tags:<br>
|
|
"s" when static linking to runtime<br>
|
|
"g" when linking to debug runtime<br>
|
|
"y" when building debug-python variants<br>
|
|
"d" when building debug variants<br>
|
|
"p" when building with stlport libraries<br>
|
|
"n" when building with stlport and using native
|
|
iostreams</li>
|
|
|
|
<li><version-tag> adds "major_minor" from a
|
|
<tt><version></tt> property. Defaults to using
|
|
$(BOOST_VERSION) if no version property is present.</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</blockquote>
|
|
|
|
<h3><a name="install_descriptions" id="install_descriptions">Install
|
|
Descriptions</a></h3>
|
|
|
|
<p>Installable files and targets are described with:</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
install <i>name</i> <i>type</i> : <i>sources</i>... : [<i>options</i>]... ;
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>Install descriptions define files and targets that can be installed by
|
|
use of a <tt>stage</tt> target.</p>
|
|
|
|
<ul>
|
|
<li><i>name</i> specifies the name to group the given files and targets
|
|
as a collective entity. Multiple <tt>install</tt> descriptions can use
|
|
the same name, in which case they are all collected into a single
|
|
group.<br>
|
|
<br></li>
|
|
|
|
<li><i>type</i> indicates the type of files specified by the
|
|
<tt>install</tt>. This is used to later install files from different
|
|
groups but with the same type.<br>
|
|
<br></li>
|
|
|
|
<li><i>sources</i> can list both generated targets like
|
|
<tt><exe>test_exe</tt> and individual files, but not template
|
|
targets.<br>
|
|
<br></li>
|
|
|
|
<li><i>options</i> additional options, currently none defined.<br></li>
|
|
</ul>
|
|
|
|
<p>Install descriptions are meant to be used by <tt>stage</tt> targets to
|
|
collect the various sources of many install descriptions into one or more
|
|
destination directories. For this there are two rules that help in getting
|
|
the sources specified:</p>
|
|
|
|
<ul>
|
|
<li><tt>install-subinclude <i>jamfiles</i>... :
|
|
[<i>options</i>]...</tt><br>
|
|
<br>
|
|
Includes the listed Jamfiles to read in the install descriptions.
|
|
Multiple <tt><exclude><i>name</i></tt> options can be used to
|
|
exclude the named groups of install descriptions from getting
|
|
defined.<br>
|
|
<br></li>
|
|
|
|
<li><tt>install-source <i>type</i></tt><br>
|
|
<br>
|
|
Returns the list of sources and targets specified by the install for the
|
|
given type. The returned list can be used as the sources for a
|
|
<tt>stage</tt> target which would place all the sources into that
|
|
stage.<br>
|
|
<br></li>
|
|
</ul>
|
|
|
|
<h3><a name="feature_description" id="feature_description">Feature
|
|
Descriptions</a></h3>
|
|
|
|
<p>Features are described by stating the feature type (simple features are
|
|
specified with "<tt>feature</tt>"), followed by the feature name. An
|
|
optional second argument can be used to list the permissible values of the
|
|
feature. Examples can be found in <a href=
|
|
"features.jam">features.jam</a>.</p>
|
|
|
|
<h3><a name="variant_description" id="variant_description">Variant
|
|
Descriptions</a></h3>
|
|
|
|
<p>Variants are described with the following syntax:</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
variant <i>name</i> [ : parent-name] : [<<i>toolset-name</i>>]<<i>feature</i>>value... ;
|
|
</pre>
|
|
</blockquote>The <tt>variant</tt> rule specifies the list of properties
|
|
comprising a variant. Properties may be optionally qualified with a toolset
|
|
name, which specifies that the property applies only to that toolset. One
|
|
or more parent variants may be specified to inherit the properties
|
|
from those parent(s). For inherited properties precedence is given on
|
|
a left to right order, making the immediate properties override those in
|
|
the parent(s). This can be used to great effect for describing global
|
|
properties that are shared amongst various variants, and therefore targets.
|
|
For example:
|
|
|
|
<blockquote>
|
|
<pre>
|
|
variant my-globals : <rtti>off ;
|
|
|
|
variant my-debug : my-globals debug ;
|
|
|
|
variant my-release : my-globals release ;
|
|
</pre>
|
|
</blockquote>More examples can be found in <a href=
|
|
"features.jam">features.jam</a>.
|
|
|
|
<h3><a name="toolset_description" id="toolset_description">Toolset
|
|
Description Files</a></h3>
|
|
|
|
<p>Toolset descriptions are located in the project's root directory, or a
|
|
directory specified by <tt>BOOST_BUILD_INSTALLATION</tt>, which may be set
|
|
in a <tt>Jamfile</tt> or the project's <tt><a href=
|
|
"#jamrules">Jamrules</a></tt> file. Each file is called
|
|
<i>toolset-name</i><tt>-tools.jam</tt>, where <i>toolset-name</i> is the
|
|
name of the toolset. The toolset description file has two main jobs:</p>
|
|
|
|
<ol>
|
|
<li>redefine the following rules:
|
|
|
|
<ul>
|
|
<li><tt>Link-action</tt> - links an executable from objects and
|
|
libraries</li>
|
|
|
|
<li><tt>Archive-action</tt> - links a static library from object
|
|
files</li>
|
|
|
|
<li><tt>C++-action</tt> - compiles a 'C++' file into an object
|
|
file</li>
|
|
|
|
<li><tt>Cc-action</tt> - compiles a 'C' file into an object file</li>
|
|
</ul>These rules should simply invoke the action part of a rule whose
|
|
name is uniquely defined for the toolset. For example,
|
|
|
|
<blockquote>
|
|
<pre>
|
|
rule C++-action
|
|
{
|
|
msvc-C++-action $(<) : $(>) ;
|
|
}
|
|
|
|
actions msvc-C++-action
|
|
{
|
|
cl -nologo -GX -c -U$(UNDEFS) -D$(DEFINES) $(CFLAGS) $(C++FLAGS) -I$(HDRS) -I$(STDHDRS) -Fo$(<) -Tp$(>)
|
|
}
|
|
|
|
</pre>
|
|
</blockquote>Note that <tt>Link-action</tt> may require special care:
|
|
on platforms where the global variable <tt>gEXPORT_SUFFIX(DLL)</tt> is
|
|
defined (e.g. Windows), the first argument may have two elements when
|
|
linking a shared library. The first is the shared library target, and
|
|
the second is the import library target, with suffix given by
|
|
<tt>$(gEXPORT_SUFFIX(DLL))</tt>. It will always have a third argument
|
|
which is either ``<tt>EXE</tt>'' or ``<tt>DLL</tt>''. This can be used
|
|
to dispatch to different actions for linking DLLs and EXEs if
|
|
necessary, but usually it will be easier to take advantage of the
|
|
special <tt><target-type></tt> feature, which will have the same
|
|
value using the <tt>flags</tt> rule described below.
|
|
</li>
|
|
|
|
<li>Translate build settings given in the global
|
|
<tt>gBUILD_PROPERTIES</tt> variable into something that can be used by
|
|
the toolset. The build system provides the <tt>flags</tt> rule to help
|
|
translate build properties into elements of global variables which are
|
|
later attached to targets so that they can affect the build actions. The
|
|
<tt>flags</tt> rule is used as follows:
|
|
|
|
<blockquote>
|
|
<pre>
|
|
flags <i>toolset variable condition</i> [: <i>value</i>...]
|
|
</pre>
|
|
</blockquote>The parameters are:
|
|
|
|
<ul>
|
|
<li><i>toolset</i> - the name of the toolset</li>
|
|
|
|
<li><i>variable</i> - the name of a global variable which can be used
|
|
to carry information to a command-line</li>
|
|
|
|
<li>
|
|
<i>condition</i> - one one or more elements in the following forms:
|
|
|
|
<ol>
|
|
<li>a property-set of the form:
|
|
<tt><<i>feature</i>><i>value</i></tt>[<tt>/<<i>feature</i>>
|
|
<i>value</i></tt>...]</li>
|
|
|
|
<li><tt><<i>feature</i>></tt></li>
|
|
</ol>
|
|
</li>
|
|
|
|
<li><i>values</i> - anything</li>
|
|
</ul>
|
|
|
|
<p>Semantics only affect targets built with the specified toolset, and
|
|
depend on the target's build configuration:</p>
|
|
|
|
<ol>
|
|
<li>if any specified property-set is a subset of the target's build
|
|
properties, the <i>values</i> specified in <tt>$(3)</tt> will be
|
|
appended once to <i>variable</i>.</li>
|
|
|
|
<li>The value of each specified feature that participates in the
|
|
target's build properties is appended to <i>variable</i>. In either
|
|
case, the variable will be set "on" the target so it may be used in
|
|
the build actions.</li>
|
|
</ol>
|
|
</li>
|
|
</ol>
|
|
|
|
<h4><a name="toolset_example" id="toolset_example">Example</a></h4>
|
|
|
|
<p>The description of the <tt>flags</tt> rule above is actually more
|
|
complicated than it sounds. For example, the following line might be used
|
|
to specify how optimization can be turned off for MSVC:</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
flags msvc CFLAGS <optimization>off : /Od ;
|
|
</pre>
|
|
</blockquote>It says that the string <tt>/Od</tt> should be added to the
|
|
global <tt>CFLAGS</tt> variable whenever a build configuration includes the
|
|
property <tt><optimization>off</tt>.
|
|
|
|
<p>Similarly, in the following example,</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
flags msvc CFLAGS <runtime-build>release/<runtime-link>dynamic : /MD ;
|
|
</pre>
|
|
</blockquote>we add <tt>/MD</tt> to the CFLAGS variable when both of the
|
|
specified conditions are satisfied. We could grab all of the values of the
|
|
free feature <tt><include></tt> in the <tt>HDRS</tt> variable as
|
|
follows:
|
|
|
|
<blockquote>
|
|
<pre>
|
|
flags msvc HDRS <include> ;
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>The use of these variables should be apparent from the declaration of
|
|
<tt>actions msvc-C++-action</tt> in the previous section.</p>
|
|
|
|
<h2><a name="internals" id="internals">Internals</a></h2>
|
|
|
|
<h3><a name="target_names" id="target_names">Target Names</a></h3>
|
|
|
|
<p>In addition to <a href="#user_targets">user targets</a>, which
|
|
correspond directly to the names the user writes in her subproject Jamfile,
|
|
several additional targets are generated, regardless of the directory from
|
|
which Jam was invoked:</p>
|
|
|
|
<ul>
|
|
<li>A <b>main target</b> has all the same dependencies as a user target
|
|
(i.e. building it updates all requested subvariants). Its name is the
|
|
same except for the addition of <tt>$(SOURCE_GRIST)</tt>, which
|
|
identifies the subproject. The identification looks like the names of the
|
|
path components from the project root to the subproject, separated by
|
|
exclamation points. Thus, if the project is rooted at <tt>foo</tt>, in
|
|
the subproject at <tt>foo/bar/baz</tt> the target <tt>my_target</tt> is
|
|
identified by <tt><bar!baz>my_target</tt>.</li>
|
|
|
|
<li>A <b>subvariant target</b> has additional grist identifying its main
|
|
target and subvariant. This grist is joined to <tt>$(SOURCE_GRIST)</tt>
|
|
with the platform's directory separator. Thus, on UNIX, a subvariant
|
|
target of <tt>my_target</tt> above might be identified as
|
|
<tt><bar!baz/my_target/optimization-space/runtime-link-static>my_source.o</tt>.
|
|
Note that the part of the grist following the first slash, known as the
|
|
<b>subvariant id</b>, also corresponds to a fragment of the subvariant
|
|
directory path where the corresponding target is generated. Most built
|
|
targets will be identified this way.</li>
|
|
</ul>
|
|
|
|
<h3><a name="internal_globals" id="internal_globals">Global
|
|
Variables</a></h3>
|
|
|
|
<p>This section describes some of the global variables used by the build
|
|
system. Please note that some parts of the system (particularly those in
|
|
<tt>allyourbase.jam</tt>) are heavily based on the Jambase file supplied
|
|
with Jam, and as such do not follow the conventions described below.</p>
|
|
|
|
<p>Global variables used in the build system fall into three
|
|
categories:</p>
|
|
|
|
<ul>
|
|
<li>Global variables intended to be set by the user on the command-line
|
|
or in the environment use <tt>ALL_UPPER_CASE</tt> names.</li>
|
|
|
|
<li>Internal global variables begin with a lower-case "g" and continue in
|
|
upper-case: <tt>gSOME_GLOBAL</tt></li>
|
|
|
|
<li>Global variables of the form:
|
|
<tt>gBASE_NAME(</tt><i>arguments</i><tt>)</tt>, where <i>arguments</i> is
|
|
a comma-separated argument list, are used internally to achieve a kind of
|
|
indirection by concatenating variable values:
|
|
|
|
<blockquote>
|
|
<pre>
|
|
ECHO $(gFUBAR($(x),$(y))) ;
|
|
</pre>
|
|
</blockquote>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>Please note that the build system commonly takes advantage of <a href=
|
|
"../jam_src/Jam.html#bindingmods">Jam's Dynamic Scoping feature</a> (see
|
|
the <tt>local</tt> command in the "Flow of Control" section below the link
|
|
target) to temporarily "change" a global variable by declaring a
|
|
<tt>local</tt> of the same name.</p>
|
|
|
|
<p>Many of the variables that are used to configure how Boost.Build works
|
|
internally are listed <a href="variables.html">here</a> with brief
|
|
descriptions.</p>
|
|
|
|
<h3>Variables Associated with SubProject Identity</h3>
|
|
|
|
<ul>
|
|
<li><tt>SUBDIR_TOKENS</tt> - a list of the path elements relative to the
|
|
project root of the current subproject.</li>
|
|
|
|
<li><tt>SUBDIR</tt> - the path from the invocation directory to the
|
|
current subproject directory.</li>
|
|
</ul>
|
|
|
|
<h3>Grist Variables</h3>
|
|
|
|
<ul>
|
|
<li><tt>TARGET_GRIST</tt> takes the form
|
|
<tt><i>subproject!id</i>/target/toolset/variant/<i>subvariant-path</i></tt>.</li>
|
|
</ul>
|
|
|
|
<h2><a name="design_criteria" id="design_criteria">Design Criteria</a></h2>
|
|
|
|
<h3><a name="assumptions" id="assumptions">Assumptions</a></h3>
|
|
|
|
<p>The requirements are driven by several basic assumptions:</p>
|
|
|
|
<ul>
|
|
<li>There is no single Boost developer or test facility with access to or
|
|
knowledge of all the platforms and compilers Boost libraries are used
|
|
with.</li>
|
|
|
|
<li>Boost libraries are used across such a wide range of platforms and
|
|
compilers that almost no other assumptions can be made.</li>
|
|
</ul>
|
|
|
|
<h3><a name="requirements" id="requirements">Requirements</a></h3>
|
|
|
|
<p>This build system was designed to satisfy the following
|
|
requirements:</p>
|
|
|
|
<ul>
|
|
<li>A developer adding a new library or test program must only have to
|
|
add simple entries naming the source files to a text file, and not have
|
|
to know anything about platform specific files. The developer should not
|
|
have to supply header dependency information.</li>
|
|
|
|
<li>There should be a very high likelihood of builds succeeding on all
|
|
platforms if a build succeeds on any platform. In other words, a
|
|
developer must not be required to have access to many platforms or
|
|
compilers to ensure correct builds</li>
|
|
|
|
<li>A user or developer adding support for a new platform or compiler
|
|
should only have to add to a single file describing how to do the build
|
|
for that platform or compiler, and shouldn't have to identify the files
|
|
that will need to be built.</li>
|
|
|
|
<li>The build should rely only on tools native to the platform and
|
|
compiler, or supplied via the boost download.</li>
|
|
|
|
<li>The details of how the build is done for a particular platform or
|
|
compiler should be appropriate for that platform.</li>
|
|
|
|
<li>It should be possible to build multiple variants (e.g. debug/release)
|
|
of a single target.</li>
|
|
|
|
<li>It should be possible to build multiple variants of multiple targets
|
|
with multiple compilers from a single build command.</li>
|
|
|
|
<li>The build tools must be able to handle Boost growth issues such as
|
|
identified in Directory Structure proposals and discussion.</li>
|
|
|
|
<li>Support for dynamic and static linking should be included.</li>
|
|
|
|
<li>It should be relatively straightforward to add support for a new
|
|
compiler. In most cases, no modification of files used to describe
|
|
existing targets should be required.</li>
|
|
|
|
<li>Support for compiler- and variant-specific configuration for each
|
|
target</li>
|
|
|
|
<li>It should be possible to build targets into a directory unrelated to
|
|
the source directories (they may be read-only)</li>
|
|
</ul>
|
|
|
|
<h2><a name="footnotes" id="footnotes">Footnotes</a></h2><a name="one" id=
|
|
"one">[1]</a> Boost Jam is actually descended directly from <a href=
|
|
"http://freetype.sourceforge.net/jam/index.html">FTJam</a>, which was
|
|
itself a variant of <a href=
|
|
"http://www.perforce.com/jam/jam.html">Jam/MR</a>. It is hoped that crucial
|
|
features we rely on will eventually be incorporated back into the Jam/MR
|
|
release.
|
|
|
|
<p><a name="two" id="two">[2]</a> Note: right now, a dependency feature of
|
|
a main target makes <b>all</b> resulting built targets dependent, including
|
|
intermediate targets. That means that if an executable is dependent on an
|
|
external library, and that library changes, all the sources comprising the
|
|
executable will be recompiled as well. This behavior should probably be
|
|
fixed.</p>
|
|
<hr>
|
|
|
|
<p>Revised $Date$</p>
|
|
|
|
<p>Copyright © Dave Abrahams 2001.</p>
|
|
|
|
<p><small>Distributed under the Boost Software License, Version 1.0. (See
|
|
accompanying file <a href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
|
|
copy at <a href=
|
|
"http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a>)</small></p>
|
|
</body>
|
|
</html>
|