boost/build
2
0
Fork 0
mirror of https://github.com/boostorg/build.git synced 2026-02-15 13:02:11 +00:00
Code Issues Projects Releases Wiki Activity
Files
a3e20c8efdd85a18b29de839e38dfa3fc5cf46d3
build/build_system.htm
Dave Abrahams 5692c16a8f updated CALLER_MODULE docs 
[SVN r11686]
2001-11-14 19:54:30 +00:00

1906 lines
71 KiB
HTML
Raw Blame History

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<head>
<meta name="generator" content="HTML Tidy, see www.w3.org">
<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
Boost Jam, a descendant of &quot;<a
href="http://www.perforce.com/jam/jam.html">Perforce Jam</a>&quot;, 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="#core_extensions">Core Jam Extensions</a>
<ul>
<li><a href="#variable_quoting">Command-line and Environment Variable Quoting</a>
<li><a href="#jambase_replacement">Jambase Replacement</a>
<li><a href="#rule_indirection">Rule Indirection</a>
<li><a href="#argument_lists">Argument Lists</a>
<li>
<a href="#module_support">Module Support</a>
<ul>
<li><a href="#module_declaration">Declaration</a>
<li><a href="#module_locals">Local Variables</a>
<li><a href="#IMPORT_rule">The <tt>IMPORT</tt> rule</a>
<li><a href="#CALLER_MODULE_rule">The <tt>CALLER_MODULE</tt> rule</a>
</ul>
<li><a href="#local_foreach">Local for Loop Variables</a>
<li><a href="#while_loops">While Loops</a>
<li><a href="#negative_indexing">Negative Indexing</a>
<li><a href="#BINDRULE">Target Binding Detection</a>
<li><a href="#FAIL_EXPECTED">Return Code Inversion</a>
<li><a href="#NOCARE">Ignoring Return Codes</a>
<li><a href="#SUBST_rule">The <tt>SUBST</tt> Rule</a>
<li><a href="#JAM_VERSION">The <tt>JAM_VERSION</tt> global variable</a>
<li>
<a href="#debugging_support">Debugging Support</a>
<ul>
<li><a href="#profiling">Profiling</a>
<li><a href="#parse_debugging">Parser Debugging</a>
</ul>
</ul>
<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 Boost Jam</a></h3>
<ul>
<li>The Boost Jam sources are located in the <tt>tools/build/jam_src</tt>
subdirectory of the Boost installation.
<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, the make process may prompt you to
set some environment variables, and stop. Don't be alarmed; just follow
the instructions and start over. Please keep in mind that thses variable
settings are case-sensitive. The variable settings necessary for
bootstrapping Jam are not needed once it has been built.
<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>The easiest way to get going is to set the <tt>BOOST_ROOT</tt>
environment variable to point at the Boost installation directory, though
you can also set <tt>BOOST_ROOT</tt> on the command-line, using
<tt>-s...</tt>. 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 most cases it should be sufficient to invoke Jam
with no variable settings. The following examples all assume that
<tt>BOOST_ROOT</tt> has been set in the environment.
<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 -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=&quot;msvc gcc&quot;</pre>
<td>default-build <tt>all</tt> with msvc and gcc
<tr>
<td>
<pre>
set TOOLS=msvc
jam
</pre>
<td>Set an NT environment variable to always build with MSVC<br>
default-build <tt>all</tt>.
<tr>
<td>
<pre>
jam -sBUILD=release
</pre>
<td>release build <tt>all</tt> with default <tt><a href=
"#tools">TOOLS</a></tt>:<br>
<tr>
<td><pre>jam -sBUILD=&quot;debug release&quot;</pre>
<td>debug and release build <tt>all</tt>.
</table>
<h3><a name="setting_variables">Setting Jam Variables</a></h3>
<p>The &quot;<tt>-s</tt>&quot; 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>
&gt; <a href="#build">BUILD</a>=&quot;debug release&quot; <i># assuming Unix</i>
&gt; export <a href="#build">BUILD</a>
&gt; 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 &quot;<tt>-s</tt>&quot;
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-&gt;C++ sources
parser/src/baz5.yy # Yacc-&gt;C++ sources
: &lt;include&gt;$(BOOST_PARENT_DIRECTORY) # Put boost in #include path
;
# An executable called 'test'
exe test : &lt;lib&gt;baz # use the 'baz' library
baz_test.cpp # C++ source
: &lt;include&gt;$(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>&lt;library-file&gt;</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">&lt;--- foo's build root</font>
| +-gcc
| | +-<b>debug</b>
| | `-<b>release</b>
| `-kai
| +-<b>debug</b>
| `-<b>release</b>
`-bar <font color="#7f7f7f">&lt;--- 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">&lt;--- 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">&lt;--- 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">&lt;--- 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"<22>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<63>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="&lt;optimization&gt;speed"</tt>
<td>build a subvariant of the default variant (<tt>debug</tt>) with
optimization for speed.
<tr>
<td><tt>-sBUILD="debug release &lt;runtime-link&gt;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>&lt;lib&gt;</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>
[[&lt;<i>compiler</i>&gt;]&lt;<i>variant</i>&gt;]&lt;<i>feature</i>&gt;<i>value</i>
</pre>
</blockquote>
<tt>&lt;<i>compiler</i>&gt;</tt> and <tt>&lt;<i>variant</i>&gt;</tt>,
if supplied, can be used to restrict the applicability of the
requirement. Either one may be replaced by <tt>&lt;*&gt;</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>&lt;</tt>...<tt>&gt;</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>
[[&lt;<i>compiler</i>&gt;]&lt;<i>variant</i>&gt;]&lt;<i>feature</i>&gt;<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 &lt;lib&gt;../bazlib/baz
## <a href="#target_requirements">Requirements</a> ##
: &lt;include&gt;../bazlib/include
&lt;define&gt;BUILDING_FOO=1
&lt;release&gt;&lt;define&gt;FOO_RELEASE
&lt;msvc&gt;&lt;*&gt;&lt;define&gt;FOO_MSVC
&lt;msvc&gt;&lt;release&gt;&lt;define&gt;FOO_MSVC_RELEASE
&lt;gcc&gt;&lt;*&gt;&lt;optimization&gt;off
&lt;gcc&gt;&lt;release&gt;&lt;optimization&gt;space
&lt;threading&gt;multi
## <a href="#default_build">default-BUILD</a> ##
: debug release
&lt;debug&gt;&lt;runtime-link&gt;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 &quot;<tt>feature</tt>&quot;), 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> : [&lt;<i>toolset-name</i>&gt;]&lt;<i>feature</i>&gt;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 $(&lt;) : $(&gt;) ;
}
actions msvc-C++-action
{
cl -nologo -GX -c -U$(UNDEFS) -D$(DEFINES) $(CFLAGS) $(C++FLAGS) -I$(HDRS) -I$(STDHDRS) -Fo$(&lt;) -Tp$(&gt;)
}
</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>&lt;target-type&gt;</tt> feature, which will have the same
value using the <tt>flags</tt> rule described below.
<p>
<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>&lt;<i>feature</i>&gt;<i>value</i></tt>[<tt>/&lt;<i>feature</i>&gt;
<i>value</i></tt>...]
<li><tt>&lt;<i>feature</i>&gt;</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>
</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 &lt;optimization&gt;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>&lt;optimization&gt;off</tt>.
<p>Similarly, in the following example,
<blockquote>
<pre>
flags msvc CFLAGS &lt;runtime-build&gt;release/&lt;runtime-link&gt;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>&lt;include&gt;</tt> in the <tt>HDRS</tt> variable as follows:
<blockquote>
<pre>
flags msvc HDRS &lt;include&gt; ;
</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><a name="jam_fundamentals">Jam Fundamentals</a></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.
<p>
<ul>
<li>
Jam ``<b>rules</b>'' are actually simple procedural entities. Think of
them as functions. Arguments are separated by colons.
<p>
<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.
<p>
<li>
Note that the documentation for the built-in <tt>INCLUDES</tt> rule is
incorrect: <tt>INCLUDES&nbsp;targets1&nbsp;:&nbsp;targets2</tt> causes
everything that depends on a member of <i>targets1</i> to depend on all
members of <i>targets2</i>. It does this in an odd way, by tacking
<i>targets2</i> onto a special tail section in the dependency list of
everything in <i>targets1</i>. It seems to be OK to create circular
dependencies this way; in fact, it appears to be the ``right thing to
do'' when a single build action produces both <i>targets1</i> and
<i>targets2</i>.
<p>
<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.
<p>
<li>
<a name="binding">Targets</a> (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>.
Binding is a process of searching for a file with the same name as the
target (sans <a href="#grist">grist</a>), based on the settings of the
<a href="#target_specific">target-specific</a> <tt>SEARCH</tt> and
<tt>LOCATE</tt> variables.
<p>
<li>
<a name="target_specific">In addition to</a> local and global
variables, jam allows you to set a variable <tt><b>on</b></tt> a
target. Target-specific variable values can usually not be read, and
take effect <i>only</i> in the following contexts:
<p>
<ul>
<li>In updating <tt>actions</tt>, variable values are first looked up
<tt><b>on</b></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><b>on</b></tt> the target named by the rule's first argument (the
source file being scanned).
</ul>
<p>
<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.
<p>
<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''.
<p>
<li>
<p>``<a href="#grist">Grist</a>'' is just a string prefix of the form
<tt>&lt;</tt><i>characters</i><tt>&gt;</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. Each distinct target bound to a file called
``<tt>test.exe</tt>'' has its own unique grist prefix. 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. Grist is used instead of identifying targets
with absolute paths for two reasons:
<ol summary="">
<li>The location of targets cannot always be derived solely from what
the user puts in a Jamfile, but sometimes depends also on the <a
href="#binding">binding</a> process. Some mechanism to distinctly
identify targets 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, leading
<tt>&lt;</tt>s and trailing <tt>&gt;</tt>s are added if neccessary to
form an expression of the form <tt>&lt;</tt><i>expr2</i><tt>&gt;</tt>;
<tt>&lt;</tt><i>expr2</i><tt>&gt;</tt> is then prepended.
<p>
<li>
<a name="variable_splitting">When Jam</a> is invoked it imports all
environment variable settings into corresponding Jam variables, followed
by all command-line (<tt>-s...</tt>) variable settings. Variables whose
name ends in <tt>PATH</tt>, <tt>Path</tt>, or <tt>path</tt> are split
into string lists on OS-specific path-list separator boundaries
(e.g. &quot;<tt>:</tt>&quot; for Unix and &quot;<tt>;</tt>&quot; for
Windows). All other variables are split on space
(&quot;<tt>&nbsp;</tt>&quot;) boundaries. Boost Jam modifies that
behavior by allowing variables to be <a
href="#variable_quoting">quoted</a>.
<p>
<li>
A variable whose value is an empty list <i>or</i> which consists
entirely of empty strings has a negative logical value. Thus, for
example, code like the following allows a sensible non-empty default
which can easily be overridden by the user:
<blockquote><pre>
MESSAGE ?= starting jam... ;
if $(MESSAGE) { ECHO The message is: $(MESSAGE) ; }
</pre></blockquote>
If the user wants a specific message, he invokes jam with
<tt>&quot;-sMESSAGE=</tt><i>message&nbsp;text</i><tt>&quot;</tt>. If he
wants no message, he invokes jam with <tt>-sMESSAGE=</tt> and nothing at
all is printed.
<p>
</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="core_extensions">Core Jam Extensions</a></h3>
<p>A number of enhancements have been made to the core language of Classic
Jam. These changes were aimed primarily at making it easier to manage the
complexity of a large system such as Boost.Build.
<blockquote>
<h4><a name="variable_quoting">Command-line and Environment Variable Quoting</h4>
<p>Classic Jam had an <a href="#variable_splitting">odd behavior</a> with
respect to command-line variable ( <tt>-s...</tt>) and environment
variable settings which made it impossible to define an arbitrary variable
with spaces in the value. Boost Jam remedies that by treating all such
settings as a single string if they are surrounded by double-quotes. Uses
of this feature can look interesting, since shells require quotes to keep
characters separated by whitespace from being treated as separate
arguments:
<blockquote><pre>
jam -sMSVCNT=&quot;\&quot;C:\Program Files\Microsoft Visual C++\VC98\&quot;&quot; ...
</pre></blockquote>
<h4><a name="jambase_replacement">Jambase Replacement</a></h4>
<p>New logic has been added to allow the built-in Jambase to be replaced
without recompiling Jam or adding command-line arguments. The user can
control the location of the build system by setting any of the <tt>JAMBASE</tt>,
<tt>BOOST_ROOT</tt>, or <tt>BOOST_BUILD_PATH</tt> environment variables (the settings of
these variables can also be overridden on the command-line using the
<tt>-s<i>VARIABLE</i>=</tt>... option).
<p>The process is controlled by variables (in decreasing
precedence):
<ul>
<li>If <tt>JAMBASE</tt> is set, it specifies the path to the Jambase
replacement. Non-rooted paths are computed relative to the directory of
Jam's invocation.
<li>Otherwise, if <tt>BOOST_BUILD_PATH</tt> or <tt>BOOST_ROOT</tt> is set,
the build system filename is <tt><b>boost-build.jam</b></tt>.
<li>If the build system filename does not contain a path specification,
the build system file is searched for on <tt>$(BOOST_BUILD_PATH)</tt>,
then at <tt>$(BOOST_ROOT)/tools/build</tt>.
<li>If <tt>BOOST_BUILD_PATH</tt> was not set, it will be set to
<tt>$(BOOST_ROOT)/tools/build</tt>.
<li>If neither <tt>JAMBASE</tt>, <tt>BOOST_ROOT</tt>, nor
<tt>BOOST_BUILD_PATH</tt> is set, we use the built-in Jambase (nearly
identical to the <a
href="http://freetype.sourceforge.net/jam/index.html">FTJam</a> Jambase)
and load the user's Jamfile. Perforce Jam has this behavior, and it is
used for building Jam itself. <b>Thus, when you rebuild Jam, these
variables should be unset</b>.
</ul>
<p>The rationale for this behavior is as follows:
<ul>
<li> The Jam executable should allow the Jambase to be overridden to
implement other build systems without the user having any knowledge
of Boost, thus the <tt>JAMBASE</tt> variable.
<li> <tt>BOOST_BUILD_PATH</tt> is designed to be used to find all <a
href="#module_support">modules</a> used by the build system, so that users
and system administrators may non-intrusively add modules to the system.
<li> Many Boost users already have <tt>BOOST_ROOT</tt> set. If a user
doesn't want to explicitly set up <tt>BOOST_BUILD_PATH</tt>,
<tt>BOOST_ROOT</tt> will supply reasonable behavior.
</ul>
<h4><a name="rule_indirection">Rule Indirection</a></h4>
<p>Boost Jam allows you to call a rule whose name is held in a variable or
computed as the result of an expression:
<blockquote><pre>
x = foo ;
rule foobar { ECHO foobar ; } # a trivial rule
$(x)bar ; # invokes foobar
</pre></blockquote>
<h4><a name="argument_lists">Argument lists</a></h4>
<p>You can now describe the arguments accepted by a rule, and refer to
them by name within the rule. For example, the following prints ``I'm
sorry, Dave'' to the console:
<blockquote>
<pre>
rule report ( pronoun index ? : state : names + )
{
local he.suffix she.suffix it.suffix = s ;
local I.suffix = m ;
local they.suffix you.suffix = re ;
ECHO $(pronoun)'$($(pronoun).suffix) $(state), $(names[$(index)]) ;
}
report I 2 : sorry : Joe Dave Pete ;
</pre>
</blockquote>
Each name in a list of formal arguments (separated by ``<tt>:</tt>'' in
the rule declaration) is bound to a single element of the corresponding
actual argument unless followed by one of these modifiers:
<table border="1" summary="Argument modifiers">
<tr>
<th>Symbol
<th>Semantics of preceding symbol
<tr>
<td><tt>?</tt>
<td>optional
<tr>
<td><tt>*</tt>
<td>Bind to zero or more unbound elements of the actual argument.
<tr>
<td><tt>+</tt>
<td>Bind to one or more unbound elements of the actual argument.
</table>
<p>The acutal and formal arguments are checked for inconsistencies, which
cause Jam to exit with an error code:
<blockquote>
<pre>
### argument error
# rule report ( pronoun index ? : state : names + )
# called with: ( I 2 foo : sorry : Joe Dave Pete )
# extra argument foo
### argument error
# rule report ( pronoun index ? : state : names + )
# called with: ( I 2 : sorry )
# missing argument names
</pre>
</blockquote>
<p>If you omit the list of formal arguments, all checking is
bypassed as in ``classic'' Jam. Argument lists drastically improve the
reliability and readability of your rules, however, and are <b>strongly
recommended</b> for any new Jam code you write.
<h4><a name="module_support">Module Support</a></h4>
<p>Boost Jam introduces support for modules, which provide some
rudimentary namespace protection for rules and variables. A new keyword,
``<tt>module</tt>'' was also introduced.
<p>
<blockquote>
<h5><a name="module_support">Declaration</a></h5>
<a name="module_declaration"><tt>module<EFBFBD></tt>
<i>expression</i><tt><EFBFBD>{<7B></tt> ...<tt><EFBFBD>}<7D></tt></a>
<p>Code within the <tt>{<7B></tt> ...<tt><EFBFBD>}</tt> executes within the
module named by evaluating <i>expression</i>. Rule definitions can be
found in the module's own namespace, and in the namespace of the global
module as <i>module-name</i><tt>.</tt><i>rule-name</i>, so within a
module, other rules in that module may always be invoked without
qualification:
<blockquote>
<pre>
<b>module my_module
{</b>
rule salute ( x ) { ECHO $(x), world ; }
rule greet ( ) { salute hello ; }
greet ;
<b>}
my_module.salute</b> goodbye ;
</pre>
</blockquote>
When an invoked rule is not found in the current module's namespace, it
is looked up in the namespace of the global module, so qualified calls
work across modules:
<blockquote>
<pre>
module your_module
{
rule bedtime ( ) { <b>my_module.salute</b> goodnight ; }
}
</pre>
</blockquote>
<p>Note that, like the <a
href="#IMPORT_rule"><tt>IMPORT</tt></a> and <a
href="#CALLER_MODULE_rule"><tt>CALLER_MODULE</tt></a> rules, module
declaration is really a <i>primitive</i>, and is best used through a
wrapper interface which implements a system of module files using the
built-in <tt>INCLUDE</tt> rule.
<p>
<h5><a name="module_locals">Local Variables</a></h5>
<tt>module<EFBFBD>local<EFBFBD></tt> <i>expression</i><tt><EFBFBD>;</tt><br>
<i>- or -</i><br>
<tt>module<EFBFBD>local<EFBFBD></tt> <i>expression</i><tt><EFBFBD>=<3D></tt>
<i>expression2</i><tt><EFBFBD>;</tt>
<p>The variables named by <i>expression</i> are given a distinct value
in the module, and can be manipulated by code executing in the module
without affecting variable bindings seen by other modules. If the
assignment form is used, <i>expression2</i> is assigned to the
variables when the declaration is executed. For example:
<blockquote>
<pre>
module M {
<b>module local</b> x = a b c ;
rule f ( )
{
{
local x = 1 2 3 ; # temp override for M's x
N.g ; # call into module N, below
}
ECHO $(x) ; # prints "a b c"
}
}
module N {
rule g ( )
{
x = foo bar baz ; # sets global x
M.h ; # call back into M, below
}
}
module M {
rule h ( )
{
ECHO $(x) ; # prints "1 2 3"
}
}
M.f ;
ECHO $(x) ; # prints "foo bar baz"
</pre>
</blockquote>
The only way to access another module's local variables is through a
rule defined in that module:
<blockquote>
<pre>
module M {
rule get ( names * )
{
return $($(names)) ;
}
}
ECHO [ <b>M.get</b> x ] ; # prints "a b c"
</pre>
</blockquote>
<h5><a name="IMPORT_rule">The <tt>IMPORT</tt> Rule</a></h5>
<tt>IMPORT</tt> allows rule name aliasing across modules:
<blockquote>
<pre>
rule IMPORT ( target_module ? : source_module ?
: rule_names * : target_names * )
</pre>
</blockquote>
Rules are copied from the <tt>source_module</tt> into the
<tt>target_module</tt>. If either module name is missing, the global
module is used in its place. If any <tt>rule_names</tt> are supplied,
they specify which rules from the <tt>source_module</tt> to import;
otherwise all rules are imported. The rules are given the names in
<tt>target_names</tt>; if not enough <tt>target_names</tt> are supplied,
the excess rules are given the same names as they had in
<tt>source_module</tt>. For example,
<blockquote>
<pre>
IMPORT m1 : m2 ; # imports all rules from m2 into m1
IMPORT : m2 : my-rule ; # imports m2.my-rule into the global module
IMPORT m1 : m2 : r1 x : r2 y ; # imports m2.r1 as r2 and m2.x as y into m1
</pre>
</blockquote>
Like the <a href="#module_declaration">module declaration syntax</a> and
the <a href="#CALLER_MODULE_rule"><tt>CALLER_MODULE</tt></a> rule, this
rule is a <i>primitive</i>, and is probably best wrapped in a Jam rule.
<h5><a name="CALLER_MODULE_rule">The <tt>CALLER_MODULE</tt> Rule</a></h5>
<blockquote>
<pre>
rule CALLER_MODULE ( levels ? )
</pre>
</blockquote>
<tt>CALLER_MODULE</tt> returns the name of the module scope
enclosing the call to its caller (if levels is supplied, it is
interpreted as an integer number of additional levels of call stack to
traverse to locate the module). If the scope belongs to the global
module, or if no such module exists, returns the empty list. For
example, the following prints &quot;{Y} {X}&quot;:
<blockquote>
<pre>
module X {
rule get-caller { return [ CALLER_MODULE ] ; }
rule get-caller's-caller { return [ CALLER_MODULE 1 ] ; }
rule call-Y { return Y.call-X2 ; }
}
module Y {
rule call-X { return X.get-caller ; }
rule call-X2 { return X.get-caller's-caller ; }
}
callers = [ X.get-caller ] [ Y.call-X ] [ X.call-Y ] ;
ECHO {$(callers)} ;
</pre>
Like the <a href="#module_declaration">module declaration syntax</a> and
the <a href="#IMPORT_rule"><tt>IMPORT</tt></a> rule, this rule is a
<i>primitive</i>, and is probably best wrapped in a Jam rule.
</blockquote>
</blockquote>
<h4><a name="local_foreach">Local For Loop Variables</a></h4>
<p>Boost Jam allows you to declare a local <tt>for</tt> loop control
variable right in the loop:
<blockquote><pre>
x = 1 2 3 ;
y = 4 5 6 ;
for <b>local</b> y in $(x)
{
ECHO $(y) ; # prints &quot;1&quot;, &quot;2&quot;, or &quot;3&quot;
}
ECHO $(y) ; # prints &quot;4 5 6&quot;
</pre></blockquote>
<h4><a name="while_loops">While Loops</a></h4>
In classic Jam, some constructs are only possible using recursion:
<blockquote><pre>
# returns the part of $(list) following the first occurrence of $(symbol)
rule after-symbol ( symbol : list * )
{
if ! $(list) || ( $(symbol) = $(list[1]) )
{
return $(list[2-]) ;
}
else
{
return [ after-symbol $(symbol) : $(list[2-]) ] ;
}
}
</pre></blockquote>
The addition of <tt>while</tt> loops allows a simpler formulation for this and
many other rules:
<blockquote><pre>
rule after-symbol ( symbol : list * )
{
while $(list) &amp;&amp; $(list[1]) != $(symbol)
{
list = $(list[2-]) ;
}
return $(list) ;
}
</pre></blockquote>
<h4><a name="negative_indexing">Negative Indexing</a></h4>
Classic Jam supplies 1-based list indexing, and slicing on a closed
(inclusive) range:
<blockquote><pre>
x = 1 2 3 4 5 ;
ECHO $(x[3]) ; # prints &quot;3&quot;
ECHO $(x[2-4]) ; # prints &quot;2 3 4&quot;
ECHO $(x[2-]) ; # prints &quot;2 3 4 5&quot;
</pre></blockquote>
Boost Jam adds Python-style negative indexing to access locations relative
to the <i>end</i> of the list.
<blockquote><pre>
ECHO $(x[-1]) $(x[-3]) ; # prints &quot;5 3&quot;
ECHO $(x[-3--1]) ; # prints &quot;3 4 5&quot;
ECHO $(x[-3-4]) ; # prints &quot;3 4&quot;
ECHO $(x[2--2]) ; # prints &quot;2 3 4&quot;
</pre></blockquote>
Consistency with the 1-based, inclusive
indexing of Classic Jam and the use of ``<tt>-</tt>'' as the
range separator make this feature a bit clumsier than it would otherwise
need to be, but it does work.
<h4><a name="BINDRULE">Target Binding Detection</a></h4>
<p>Whenever a target is <a href="#binding">bound</a> to a location in the
filesystem, Boost Jam will look for a variable called <tt>BINDRULE</tt> (first
``<tt>on</tt>'' the target being bound, then in the global module). If
non-empty, <tt>$(BINDRULE[1])</tt> names a rule which is called with the
name of the target and the path it is being bound to. The signature of the
rule named by <tt>$(BINDRULE[1])</tt> should match the following:
<blockquote><pre>
rule bind-rule ( target : path )
</pre></blockquote>
This facility is useful for correct header file scanning, since many
compilers will search for <tt>#include</tt>d files first in the directory
containing the file doing the <tt>#include</tt>
directive. <tt>$(BINDRULE)</tt> can be used to make a record of that
directory.
<h4><a name="FAIL_EXPECTED">Return Code Inversion</a></h4>
<p>For handling targets whose build actions are expected to fail
(e.g. when testing that assertions or compile-time type checkin work
properly), Boost Jam supplies a <tt>FAIL_EXPECTED</tt> rule in the same
style as <tt>NOCARE</tt>, et. al. During target updating, the return code
of the build actions for arguments to <tt>FAIL_EXPECTED</tt> is inverted:
if it fails, building of dependent targets continues as though it
succeeded. If it succeeds, dependent targets are skipped.
<h4><a name="NOCARE">Ignoring Return Codes</a></h4>
<p>Perforce Jam suppplied a <tt>NOCARE</tt> rule which is typically used
for header files to indicate that if they are not found, the dependent
targets should be built anyway. Boost Jam extends <tt>NOCARE</tt> to apply
to targets with build actions: if their build actions exit with a nonzero
return code, dependent targets will still be built.
<h4><a name="SUBST_rule">The <tt>SUBST</tt> Rule</a></h4>
<p>The behavior of the <tt>SUBST</tt> rule for regular-expression matching
and replacement (originally added in <a href=
"http://freetype.sourceforge.net/jam/index.html">FTJam</a>) has been
modified:
<ul>
<li>
One or more replacement patterns may be supplied. The new signature
for <tt>SUBST</tt> is:
<blockquote>
<pre>
SUBST ( source pattern replacements + )
</pre>
</blockquote>
The return value is the concatenated results of applying each element
of <tt>replacements</tt> in turn. For example, the following will
print ``<tt>[x] (y) {z}</tt>'':
<blockquote>
<pre>
ECHO [ SUBST xyz (.)(.)(.) [$1] ($2) {$3} ] ;
</pre>
</blockquote>
<li>
If there is no match, <tt>SUBST</tt> now returns an empty list. In
FTJam, the original <tt>source</tt> string was returned, making it
awkward to check whether a pattern was matched.
<p>
<li>Compiled regular expressions are now internally cached, making it
much faster to use <tt>SUBST</tt> multiple times with the same string.
</ul>
<h4><a name="#JAM_VERSION">The <tt>JAM_VERSION</tt> global variable</a></h4>
<p>A predefined global variable with two elements indicates the version
number of Boost Jam. Boost Jam versions start at <tt>&quot;03&quot; &quot;00&quot;</tt>. Earlier
versions of Jam do not automatically define <tt>JAM_VERSION</tt>.
<h4><a name="debugging_support">Debugging Support</a></h4>
<p>The <tt>-d</tt> command-line option admits new arguments:
<ul>
<li> <tt>-d+10</tt> - enables <a name="profiling"><b>profiling</b></a> of rule
invocations. When Jam exits, it dumps all rules invoked, their gross
and net times in platform-dependent units, and the number of times the
rule was invoked.
<li> <tt>-d+11</tt> - enables <a name="parse_debugging"><b>parser
debugging</b></a>, if Jam has been compiled with the &quot;--debug&quot;
option to the parser generator named by $(YACC).
</ul>
</blockquote>
<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>&lt;bar!baz&gt;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>&lt;bar!baz/my_target/optimization-space/runtime-link-static&gt;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 &quot;g&quot; 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
&quot;Flow of Control&quot; section below the link target) to temporarily
&quot;change&quot; 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.
</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> 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 incorportated back into the Jam/MR
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>&copy; 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
-->11 November, 2001
<!--webbot bot="Timestamp" endspan i-checksum="21080"
-->
</body>
Reference in New Issue View Git Blame Copy Permalink