mirror of
https://github.com/boostorg/build.git
synced 2026-02-15 13:02:11 +00:00
1212 lines
50 KiB
HTML
1212 lines
50 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<head>
|
|
|
|
<meta name="generator" content="Microsoft FrontPage 4.0">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
|
|
|
|
<title>Boost Build System</title>
|
|
</head>
|
|
|
|
<body bgcolor="#FFFFFF" text="#000000">
|
|
|
|
<img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align= "center" width="277" height="86">
|
|
|
|
<h1>Boost Build System</h1>
|
|
|
|
<h2><a name="synopsis">Synopsis</a></h2>
|
|
|
|
<p>Boost.Build is a system for large project software construction built on
|
|
<a href="http://freetype.sourceforge.net/jam/index.html">FTJam</a>,
|
|
an open-source make replacement<a href="#1">[1]</a>. Key features are:
|
|
|
|
<ul>
|
|
<li>A simple target description language
|
|
<li>Build with your choice (or multiple) toolsets from a single command
|
|
invocation
|
|
<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>``Feature Normalization'' allows target configurations to be described
|
|
independently from the toolset used
|
|
<li>Modular toolset description files allow build instructions for different
|
|
toolsets to be described independently
|
|
<li>Multiple subproject support
|
|
<li>Automatic building of subproject dependencies
|
|
</ul>
|
|
|
|
<p><a href="#design_criteria">Here</a> are some of the design criteria that
|
|
led to these features.
|
|
|
|
<h2>Table of Contents</h2>
|
|
|
|
<ul>
|
|
<li><a href="#synopsis">Synopsis</a>
|
|
|
|
<li><a href="#getting_started">Getting Started</a>
|
|
<ul>
|
|
<li><a href="#installing_jam">Installing Jam</a>
|
|
<li><a href="#initiating">Initiating a Build</a>
|
|
<li><a href="#setting_variables">Setting Jam Variables</a>
|
|
<li><a href="#example_jamfile">An Example Jamfile</a>
|
|
<li><a href="#support_files">Support Files</a>
|
|
</ul>
|
|
|
|
<li>
|
|
<a href="#design">Basic Design and Terminology</a>
|
|
|
|
<ul>
|
|
<li><a href="#project_subproject">Projects and Subprojects</a>
|
|
|
|
<li><a href="#targets">Targets</a>
|
|
|
|
<li><a href="#features">Features and Properties</a>
|
|
|
|
<li><a href="#variants">Build Variants</a>
|
|
|
|
<li><a href="#subvariants">Subvariants</a>
|
|
|
|
<li><a href="#dependents">Dependent Targets</a>
|
|
</ul>
|
|
|
|
<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><a href="#user_globals">Global Variables</a>
|
|
</ul>
|
|
<li><a href="#subproject_jamfiles">Subproject Jamfiles</a>
|
|
<ul>
|
|
<li><a href="#subproject_rule">The <tt>subproject</tt> Rule</a>
|
|
<li><a href="#main_targets">Describing Main Targets</a>
|
|
<li><a href="#jamfile_example">Example</a>
|
|
</ul>
|
|
<li><a href="#feature_description">Feature Descriptions</a>
|
|
<li><a href="#variant_description">Variant Descriptions</a>
|
|
<li><a href="#toolset_description">Toolset Description Files</a>
|
|
<ul>
|
|
<li><a href="#toolset_example">Example</a>
|
|
</ul>
|
|
</ul>
|
|
|
|
<li><a href="#internals">Internals</a>
|
|
<ul>
|
|
<li><a href="#jam_fundamentals">Jam Fundamentals</a>
|
|
<li><a href="#target_names">Target Names</a>
|
|
<li><a href="#internal_globals">Global Variables</a>
|
|
</ul>
|
|
|
|
<li>
|
|
<a href="#design_criteria">Design Criteria</a>
|
|
<ul>
|
|
<li><a href="#assumptions">Assumptions</a>
|
|
|
|
<li><a href="#requirements">Requirements</a>
|
|
</ul>
|
|
|
|
<li><a href="#footnotes">Footnotes</a>
|
|
</ul>
|
|
|
|
<h2><a name="getting_started">Getting Started</a></h2>
|
|
|
|
<h3><a name="installing_jam">Installing FTJam</a></h3>
|
|
|
|
<ul>
|
|
<li><a href="http://freetype.sourceforge.net/jam/index.html#where">This
|
|
page</a> describes how and where to get FTJam sources.
|
|
|
|
<li>The <a href="http://public.perforce.com/public/jam/src/README">Jam
|
|
README</a> contains basic installation instructions.
|
|
|
|
<li>If you are installing on Windows NT, please read <a href=
|
|
"http://frankenrouter.perforce.com/lists/jamming/msg00474.html">this
|
|
note</a>. You may need to use the ``<tt>SUBST</tt> hack'' described at
|
|
the bottom of the message to bootstrap Jam. Also, when defining the
|
|
<tt>MSVCNT</tt>, <tt>BCCROOT</tt>, etc. environment variables as
|
|
described in the <a href="http://public.perforce.com/public/jam/src/README">Jam
|
|
README</a>, please remember that they are case-sensitive.
|
|
|
|
<li>Note that the supplied Makefile may require editing for your
|
|
platform; see the <a href="http://public.perforce.com/public/jam/src/README">Jam
|
|
README</a> for details. The Makefile is used for bootstrapping Jam; it builds Jam
|
|
into a subdirectory called <tt>bin.</tt><i>platform</i>.
|
|
</ul>
|
|
|
|
<h3><a name="initiating">Initiating a Build</a></h3>
|
|
|
|
<p>Currently, the build system must be invoked with the
|
|
<tt>-f<i>allyourbase-path</i></tt> option, where <i>allyourbase-path</i> is
|
|
the path to the <tt><a href="allyourbase.jam">allyourbase.jam</a></tt> file
|
|
supplied in this directory. When the system matures, this file may be
|
|
compiled directly into Jam as the <tt>Jambase</tt> or we will find another
|
|
way to make sure the <tt>-f</tt> option is no longer needed. The environment
|
|
variables necessary for bootstrapping Jam are not needed once it has been
|
|
built.
|
|
|
|
<p>Here are some sample Boost Jam invocations:
|
|
|
|
<table border="1" summary="Sample Jam Invocations=">
|
|
<tr>
|
|
<th>Command Line(s)
|
|
|
|
<th>Effects
|
|
|
|
<tr>
|
|
<td><pre>jam -f<i>allyourbase-path</i> -sTOOLS=gcc my_target</pre>
|
|
|
|
<td>default (debug) <tt><a href="#build">BUILD</a></tt> of <tt>my_target</tt>with GCC
|
|
|
|
<tr>
|
|
<td><pre>jam -f<i>allyourbase-path</i> -sTOOLS="msvc gcc"</pre>
|
|
|
|
<td>default-build <tt>all</tt> with msvc and gcc
|
|
|
|
<tr>
|
|
<td><pre>set TOOLS=msvc
|
|
jam -f<i>allyourbase-path</i></pre>
|
|
|
|
<td>Set an NT environment variable to always build with MSVC<br>
|
|
default-build <tt>all</tt>.
|
|
|
|
<tr>
|
|
<td><pre>jam -f<i>allyourbase-path</i> -sBUILD=release</pre>
|
|
|
|
<td>release build <tt>all</tt> with default <tt><a href="#tools">TOOLS</a></tt>:<br>
|
|
|
|
|
|
<tr>
|
|
<td><pre>jam -f<i>allyourbase-path</i> -sBUILD="debug release"</pre>
|
|
|
|
<td>debug and release build <tt>all</tt>.
|
|
</table>
|
|
|
|
<h3><a name="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:
|
|
|
|
<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>
|
|
> jam ...
|
|
</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>Explicitly on the command-line, with the "<tt>-s</tt>"
|
|
option.
|
|
<li>Directly in Jam code. A project's <a href="#jamrules">Jamrules</a> file is a convenient place
|
|
to make global settings.
|
|
</ul>
|
|
|
|
<h3><a name="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:
|
|
|
|
<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">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_INSTALLATION</tt>
|
|
variable. It is usually convenient to specify the
|
|
<tt>BOOST_BUILD_INSTALLATION</tt> in your project's <a
|
|
href="#jamrules">Jamrules</a> file. The <a href="../../Jamrules">Boost
|
|
Jamrules</a> file shows an example.
|
|
|
|
<table border="1" summary="Support Files">
|
|
<tr><th>Filename(s) <th>Meaning
|
|
|
|
<tr><td><i>toolset</i><tt>-tools.jam</tt>
|
|
<td>Feature-to-command-line mapping for <i>toolset</i>.
|
|
|
|
<tr><td><tt>features.jam</tt> <td>Abstract toolset
|
|
feature descriptions.
|
|
|
|
<tr><td><tt>boost-base.jam</tt> <td>Boost build
|
|
system-specific rule definitions.
|
|
|
|
<tr><td><tt>unit-tests.jam</tt> <td>Unit tests
|
|
and assertions for boost Jam code.
|
|
|
|
</table>
|
|
|
|
The <tt>boost-base.jam</tt> file is temporary, and will eventually be
|
|
compiled into our Jam executable.
|
|
|
|
|
|
<h2><a name="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 neccessary to understand the sections on writing
|
|
Jamfiles and command-line invocations.
|
|
|
|
<h3><a name="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">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>Subdirectories containing <tt>Jamfile</tt>s are called <b>subproject
|
|
directories</b>. Each such <tt>Jamfile</tt> describes a <b>subproject</b>.
|
|
|
|
<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 explicitly by setting the variable
|
|
<tt>BOOST_BUILD_INSTALLATION</tt>. If the installation directory is not
|
|
specified, it is the same as the project root, and
|
|
<tt>BOOST_BUILD_INSTALLATION</tt> is set to refer to that directory.
|
|
|
|
<h3><a name="targets">Targets</a></h3>
|
|
|
|
<p>Each <tt>Jamfile</tt> describes one or more <b>main targets</b>.
|
|
|
|
<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.
|
|
|
|
<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><a name="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.
|
|
|
|
</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">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 three varieties:
|
|
|
|
<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><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><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><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="#2">[2]</a>.
|
|
|
|
</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.
|
|
|
|
<h3><a name="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>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>).
|
|
|
|
<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.
|
|
|
|
<h3><a name="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:
|
|
|
|
<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>
|
|
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>
|
|
</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:
|
|
|
|
<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>
|
|
. . . `-<b>user-interface-gui</b>
|
|
</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>.
|
|
|
|
<h3><a name="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.
|
|
|
|
<h2><a name="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.
|
|
|
|
<h3><a name="command_line">The Command Line</a></h3>
|
|
|
|
<p>This section describes in detail how the build system can be invoked.
|
|
|
|
<h4><a name="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 <a href="#grist">grist</a> 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:
|
|
<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 neccessary 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.
|
|
|
|
<h4><a name="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.
|
|
|
|
<table border="1" summary="User Globals">
|
|
<tr><th>Variable <!-- <th>Meaning --> <th>Default <th>Example <th>Notes
|
|
|
|
<tr><td rowspan="2"><tt><a name="tools">TOOLS</a></tt> <!-- <td rowspan="2">Toolsets to build with --> <td rowspan="2">Platform-dependent
|
|
<td><tt>-sTOOLS="gcc msvc"</tt> <td>build with gcc and msvc
|
|
<tr><td><tt>-sTOOLS=gcc</tt> <td>build with gcc
|
|
|
|
<tr><td rowspan="4"><tt><a name="build">BUILD</a></tt> <!-- <td rowspan="4">Build configuration (see -->
|
|
<!-- <a href="#default_build">here</a>). -->
|
|
<td rowspan="4"><tt>debug</tt>
|
|
|
|
<td><tt>-sBUILD=release</tt> <td>build the <tt>release</tt> variant
|
|
|
|
<tr><td><tt>-sBUILD="debug release"</tt> <td>build both
|
|
<tt>debug</tt> and <tt>release</tt> variants
|
|
|
|
<tr><td><tt>-sBUILD="<optimization>speed"</tt> <td>build a
|
|
subvariant of the default variant (<tt>debug</tt>) with optimization for speed.
|
|
|
|
<tr><td><tt>-sBUILD="debug release <runtime-link>static/dynamic"</tt> <td>build
|
|
subvariants of the debug and release variants that link to the runtime
|
|
both statically and dynamically.
|
|
|
|
<tr><td><tt>ALL_LOCATE_TARGET</tt>
|
|
<!-- <td>Alternate location for built targets (see <a -->
|
|
<!-- href="#all_locate_target">here</a>) -->
|
|
<td><i>empty</i>
|
|
<td><tt>-sALL_LOCATE_TARGET=~/build</tt>
|
|
<td>Generate all build results in the <tt>build</tt> subdirectory of the
|
|
user's home directory (Unix).
|
|
|
|
</table>
|
|
|
|
<h3><a name="#subproject_jamfiles">SubProject Jamfiles</a></h3>
|
|
This section describes how to write a Jamfile for a subproject.
|
|
|
|
<h4><a name="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:
|
|
|
|
<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:
|
|
<blockquote><pre>
|
|
project-root ;
|
|
</pre></blockquote>
|
|
|
|
<h4><a name="main_targets">Describing Main Targets</a></h4>
|
|
|
|
<p>A main target is described using the following syntax:
|
|
|
|
<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>, or
|
|
<tt>dll</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><i>name</i> specifies the name of the main target <br>
|
|
<br>
|
|
|
|
|
|
<li><i>sources</i> is a list of paths to source files and dependency
|
|
targets. A dependency target path is preceded by <tt><lib></tt>,
|
|
and the final path component specifies the name of a main target in a
|
|
Jamfile located in the directory given by the inital path components.
|
|
Paths may be absolute or relative. <br>
|
|
<br>
|
|
|
|
|
|
<li>
|
|
<i><a name="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 ommitting 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.
|
|
<br>
|
|
<br>
|
|
|
|
<li>
|
|
<i><a name="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.
|
|
</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.
|
|
|
|
<h4><a name="jamfile_example">Example</a></h4>
|
|
|
|
<p>This artificially complex example shows how an executable called "foo"
|
|
might be described in a Jamfile. The executable 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), and the built target which results
|
|
from building the target <tt>baz</tt> as described in
|
|
<tt>../bazlib/Jamfile</tt>.
|
|
|
|
<blockquote>
|
|
<pre>
|
|
exe foo : foo.cpp src/bar.cpp <lib>../bazlib/baz
|
|
## <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
|
|
|
|
## <a href="#default_build">default-BUILD</a> ##
|
|
: debug release
|
|
<debug><runtime-link>static/dynamic
|
|
;
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>The <a href="#target_requirements">requirements</a> section:
|
|
|
|
<ul>
|
|
<li>Adds <tt>../bazlib/include</tt> to the <tt>#include</tt> path
|
|
|
|
<li>Sets the preprocessor symbol <tt>BUILDING_FOO</tt> to <tt>1</tt>
|
|
|
|
<li>In the <tt>release</tt> builds, <tt>#define</tt>s
|
|
<tt>FOO_RELEASE</tt>.
|
|
|
|
<li>When built with MSVC, <tt>#define</tt>s <tt>FOO_MSVC</tt>.
|
|
|
|
<li>In <tt>release</tt> variants built with MSVC, <tt>#define</tt>s
|
|
<tt>FOO_MSVC_RELEASE</tt>.
|
|
|
|
<li>Most builds under GCC have optimization turned off, but...
|
|
|
|
<li>...GCC <tt>release</tt> builds require optimization for space.
|
|
|
|
<li>Requires multithread support on compilers where it's relevant.
|
|
</ul>
|
|
|
|
<p>The <a href="#default_build">default-BUILD</a> section:
|
|
|
|
<ul>
|
|
<li>specifies that <tt>debug</tt> and <tt>release</tt> base variants are
|
|
built by default.
|
|
|
|
<li>on compilers where the feature is relevant, requests both statically-
|
|
and dynamically-linked subvariants of the debug variant.
|
|
</ul>
|
|
|
|
<h3><a name="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>.
|
|
|
|
<h3><a name="variant_description">Variant Descriptions</a></h3>
|
|
|
|
<p>Variants are described with the following syntax:
|
|
<blockquote><pre>
|
|
variant <i>name</i> : [<<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. Examples
|
|
can be found in <a href="features.jam">features.jam</a>.
|
|
|
|
<h3><a name="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:
|
|
|
|
<ol>
|
|
<li>
|
|
redefine the following rules:
|
|
|
|
<ul>
|
|
<li><tt>Link-action</tt> - links an executable from objects and
|
|
libraries
|
|
|
|
<li><tt>Archive-action</tt> - links a static library from object
|
|
files
|
|
|
|
<li><tt>C++-action</tt> - compiles a 'C++' file into an object file
|
|
|
|
<li><tt>Cc-action</tt> - compiles a 'C' file into an object file
|
|
</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
|
|
neccessary, 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>
|
|
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><i>variable</i> - the name of a global variable which can be used
|
|
to carry information to a command-line
|
|
|
|
<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><tt><<i>feature</i>></tt>
|
|
</ol>
|
|
|
|
<li><i>values</i> - anything
|
|
</ul>
|
|
|
|
<p>Semantics only affect targets built with the specified toolset, and
|
|
depend on the target's build configuration:
|
|
|
|
<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>The value of each specified feature that participates in the target's
|
|
build properaties 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.
|
|
</ol>
|
|
|
|
<h4><a name="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:
|
|
|
|
<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,
|
|
|
|
<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.
|
|
|
|
|
|
<h2><a name="internals">Internals</a></h2>
|
|
|
|
<h3>Jam Fundamentals</h3>
|
|
|
|
<p> This section is derived from the official Jam documentation and from my
|
|
experience using it and reading the Jambase rules. I repeat the information
|
|
here mostly because it is essential to understanding and using Jam, but is
|
|
not consolidated in a single place. Some of it is missing from the official
|
|
documentation altogether. I hope it will be useful to anyone wishing to
|
|
become familiar with Jam and the Boost build system.
|
|
|
|
<ul>
|
|
|
|
<li>Jam ``<b>rules</b>'' are actually simple procedural entities. Think of
|
|
them as functions. Arguments are separated by colons.
|
|
|
|
<li>A Jam <b>target</b> is an abstract entity identified by an arbitrary
|
|
string. The build-in <tt>DEPENDS</tt> rule creates a link in the dependency
|
|
graph between the named targets.
|
|
|
|
<li>Note that the documentation for the built-in <tt>INCLUDES</tt> rule is
|
|
incorrect:
|
|
<tt>INCLUDES targets1 : targets2 </tt>
|
|
causes everything that depends on a member of <i>targets1</i> to depend on all members of <i>targets2</i>.
|
|
|
|
<li>When a rule is invoked, if there are <b><tt>actions</tt></b> declared
|
|
with the same name as the rule, the <tt>actions</tt> are added to the
|
|
updating actions for the target identified by the rule's first argument. It
|
|
is actually possible to invoke an undeclared rule if corresponding actions
|
|
are declared: the rule is treated as empty.
|
|
|
|
<li>Targets (other than <tt>NOTFILE</tt> targets) are associated with
|
|
paths in the file system through a process called <a
|
|
href="http://public.perforce.com/public/jam/src/Jam.html#binding">binding</a>.
|
|
|
|
<li>In addition to local and global variables, jam allows you to set a
|
|
variable <tt>on</tt> a target. Target-specific variable values can usually
|
|
not be read, and take effect <i>only</i> in the following contexts:
|
|
|
|
<ul>
|
|
<li>In updating <tt>actions</tt>, variable values are first looked up <tt>on</tt>
|
|
the target named by the first argument (the target being updated).
|
|
Because Jam builds its entire dependency tree before executing
|
|
<tt>actions</tt>, Jam rules make target-specific variable settings as
|
|
a way of supplying parameters to the corresponding
|
|
<tt>actions</tt>.
|
|
|
|
<li>Binding is controlled <i>entirely</i> by the target-specific setting of the
|
|
<tt>SEARCH</tt> and <tt>LOCATE</tt> variables, as described <a
|
|
href="http://public.perforce.com/public/jam/src/Jam.html#search">here</a>.
|
|
|
|
<li>In the special rule used for <a
|
|
href="http://public.perforce.com/public/jam/src/Jam.html#hdrscan">header
|
|
file scanning</a>, variable values are first looked up <tt>on</tt> the target
|
|
named by the rule's first argument (the source file being
|
|
scanned).
|
|
</ul>
|
|
|
|
<li>The ``<b>bound value</b>'' of a variable is the path associated with the
|
|
target named by the variable. In build <tt>actions</tt>, the first two
|
|
arguments are automatically replaced with their bound
|
|
values. Target-specific variables can be selectively replaced by their bound
|
|
values using the <a
|
|
href="http://public.perforce.com/public/jam/src/Jam.html#actionmods">bind</a>
|
|
action modifier.
|
|
|
|
<li>
|
|
Note that the term ``binding'' as used in the Jam documentation indicates
|
|
a phase of processing that includes three sub-phases: <i>binding</i>
|
|
(yes!), update determination, and header file scanning. The repetition of
|
|
the term ``binding'' can lead to some confusion. In particular, the <a
|
|
href="http://public.perforce.com/public/jam/src/Jam.html#bindingmods">Modifying
|
|
Binding</a> section in the Jam documentation should probably be titled
|
|
``Modifying Update Determination''.
|
|
|
|
<li>
|
|
|
|
<p><a name="grist">In the Jam</a> language, a name can be divided into two
|
|
parts. If the name starts with a '<tt><</tt>' symbol and contains a
|
|
'<tt>></tt>' symbol, the characters between the '<tt><</tt>' and the
|
|
first '<tt>></tt>', inclusive, is known as <i>grist</i> (if the name
|
|
doesn't match this format, the grist is empty). The rest of the name is
|
|
known as the <i>ungristed part</i>. In Jam, Grist is added to user-specified
|
|
target names from different subprojects to distinguish them from one another
|
|
in case the same target name is used twice. The Boost build system also
|
|
takes full advantage of Jam's ability to divide strings on grist boundaries,
|
|
sometimes concatenating multiple gristed elements at the beginning of a
|
|
string.
|
|
|
|
``<a href="#grist">Grist</a>'' is just a string prefix of the form
|
|
<tt><</tt><i>characters</i><tt>></tt>. It is used in Jam to create
|
|
unique target names based on simpler names. For example, the file
|
|
name ``<tt>test.exe</tt>'' may be used by targets in separate subprojects,
|
|
or for the debug and release variants of the ``same'' abstract target. Grist
|
|
is used instead of identifying targets with absolute paths for two reasons:
|
|
|
|
<ol summary="">
|
|
<li>The location of header files can not be derived solely from what the
|
|
user puts in a Jamfile, but depend also on the binding process. Some
|
|
mechanism to identify headers with the same name is still needed.
|
|
|
|
<li>Grist allows us to use a uniform abstract identifier for each built
|
|
target, regardless of target file location (as allowed by setting
|
|
<tt>ALL_LOCATE_TARGET</tt>
|
|
</ol>
|
|
|
|
When grist is extracted from a name with
|
|
<tt>$(</tt><i>var</i><tt>:G)</tt>, the result includes the leading and
|
|
trailing angle brackets. When grist is added to a name with
|
|
<tt>$(</tt><i>var</i><tt>:G=</tt><i>expr</i><tt>)</tt>, existing grist is
|
|
first stripped. Then, if <i>expr</i> is non-empty, as few leading
|
|
<tt><</tt>s and <tt>></tt>s as
|
|
neccessary
|
|
to form an expression of the form
|
|
<tt><</tt><i>expr2</i><tt>></tt> are added;
|
|
<tt><</tt><i>expr2</i><tt>></tt> is then prepended.
|
|
Grist prefixes are stripped from target names when binding them to
|
|
filesystem paths.
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
<p>Please also read <a href="http://public.perforce.com/public/jam/src/Jam.html">The
|
|
Jam language reference</a> for the additional details, and the <a
|
|
href="http://public.perforce.com/public/jam/src/RELNOTES">Jam release
|
|
notes</a> for a brief description of recent, but <b>fundamental changes to the
|
|
Jam language</b> without which you will probably not understand any of the
|
|
build system code. In particular, note that the <tt>return</tt> statement does
|
|
not affect control flow.
|
|
|
|
|
|
<h3><a name="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:
|
|
|
|
<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>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.
|
|
</ul>
|
|
|
|
<h3><a name="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>Global variables used in the build system fall into three categories:
|
|
|
|
<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> Internal global variables begin with a lower-case "g" and
|
|
continue in upper-case: <tt>gSOME_GLOBAL</tt>
|
|
|
|
<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>
|
|
</ul>
|
|
|
|
<p>Please note that the build system commonly takes advantage of <a
|
|
href="http://public.perforce.com/public/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.
|
|
|
|
<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><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>.
|
|
|
|
</ul>
|
|
|
|
<h2><a name="design_criteria">Design Criteria</a></h2>
|
|
|
|
<h3><a name="assumptions">Assumptions</a></h3>
|
|
|
|
<p>The requirements are driven by several basic assumptions:
|
|
|
|
<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>Boost libraries are used across such a wide range of platforms and
|
|
compilers that almost no other assumptions can be made.
|
|
</ul>
|
|
|
|
<h3><a name="requirements">Requirements</a></h3>
|
|
|
|
<p>This build system was designed to satisfy the following requirements:
|
|
|
|
<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>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>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>The build should rely only on tools native to the platform and
|
|
compiler, or supplied via the boost download.
|
|
|
|
<li>The details of how the build is done for a particular platform or
|
|
compiler should be appropriate for that platform.
|
|
|
|
<li>It should be possible to build multiple variants (e.g. debug/release)
|
|
of a single target.
|
|
|
|
<li>It should be possible to build multiple variants of multiple targets
|
|
with multiple compilers from a single build command.
|
|
|
|
<li>The build tools must be able to handle Boost growth issues such as
|
|
identified in Directory Structure proposals and discussion.
|
|
|
|
<li>Support for dynamic and static linking should be included.
|
|
|
|
<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>Support for compiler- and variant-specific configuration for each
|
|
target
|
|
|
|
<li>It should be possible to build targets into a directory unrelated to
|
|
the source directories (they may be read-only)
|
|
</ul>
|
|
|
|
<h2><a name="footnotes">Footnotes</a></h2>
|
|
|
|
<a name="1">[1]</a> FTJam is a variant of <a
|
|
href="http://www.perforce.com/jam/jam.html">Jam/MR</a>. It is hoped that
|
|
crucial features we rely on from FTJam will eventually be incorportated into
|
|
the official Jam release.
|
|
|
|
<p><a name="2">[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.
|
|
|
|
<hr>
|
|
<p>© Copyright David Abrahams 2001. Permission to copy, use, modify,
|
|
sell and distribute this document is granted provided this copyright notice
|
|
appears in all copies. This document is provided "as is" without express or
|
|
implied warranty, and with no claim as to its suitability for any purpose.
|
|
|
|
<p>Revised
|
|
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan
|
|
-->29 July, 2001<!--webbot bot="Timestamp" endspan i-checksum="21080"
|
|
--> |