<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Using BJam</title>
<link rel="stylesheet" href="../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
<link rel="home" href="../index.html" title="Boost.Jam : 3.1.18">
<link rel="up" href="../index.html" title="Boost.Jam : 3.1.18">
<link rel="prev" href="building.html" title="Building BJam">
<link rel="next" href="language.html" title="Language">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr><td valign="top"></td></tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="building.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="language.html"><img src="../images/next.png" alt="Next"></a>
</div>
<div class="section" title="Using BJam">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="jam.usage"></a><a class="link" href="usage.html" title="Using BJam"> Using BJam</a>
</h2></div></div></div>
<div class="toc"><dl>
<dt><span class="section"><a href="usage.html#jam.usage.options"> Options</a></span></dt>
<dt><span class="section"><a href="usage.html#jam.usage.operation"> Operation</a></span></dt>
</dl></div>
<div class="warning" title="Warning"><table border="0" summary="Warning">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../images/warning.png"></td>
<th align="left">Warning</th>
</tr>
<tr><td align="left" valign="top"><p>
Most probably, you are looking for <a href="http://boost.org/boost-build2/doc/html/index.html" target="_top">Boost.Build
manual</a> or <a href="http://www.boost.org/boost-build2/doc/html/bbv2/overview/invocation.html" target="_top">Boost.Build
command-line syntax</a>. This section documents only low-level options
used by the Boost.Jam build engine, and does not mention any high-level syntax
of Boost.Build
</p></td></tr>
</table></div>
<p>
If <span class="emphasis"><em>target</em></span> is provided on the command line, <code class="literal">bjam</code>
builds <span class="emphasis"><em>target</em></span>; otherwise <code class="literal">bjam</code> builds
the target <code class="literal">all</code>.
</p>
<pre class="programlisting">bjam ( -option [value] | target ) *
</pre>
<div class="section" title="Options">
<div class="titlepage"><div><div><h3 class="title">
<a name="jam.usage.options"></a><a class="link" href="usage.html#jam.usage.options" title="Options"> Options</a>
</h3></div></div></div>
<div class="toc"><dl><dt><span class="section"><a href="usage.html#jam.usage.options.command_line_and_environment_variable_quoting">Command-line
and Environment Variable Quoting</a></span></dt></dl></div>
<p>
Options are either singular or have an accompanying value. When a value is
allowed, or required, it can be either given as an argument following the
option argument, or it can be given immediately after the option as part
of the option argument. The allowed options are:
</p>
<div class="variablelist">
<p class="title"><b></b></p>
<dl>
<dt><span class="term"><div class="literallayout"><p><code class="literal">-a</code></p></div></span></dt>
<dd><p>
Build all targets anyway, even if they are up-to-date.
</p></dd>
<dt><span class="term"><div class="literallayout"><p><code class="literal">-d <span class="emphasis"><em>n</em></span></code></p></div></span></dt>
<dd>
<p>
Enable cummulative debugging levels from 1 to n. Values are:
</p>
<p>
</p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">Show the actions taken for building targets, as they are executed (the
default).</li>
<li class="listitem">Show "quiet" actions and display all action text,
as they are executed.</li>
<li class="listitem">Show dependency analysis, and target/source timestamps/paths.</li>
<li class="listitem">Show
arguments and timming of shell invocations.</li>
<li class="listitem">Show rule invocations and
variable expansions.</li>
<li class="listitem">Show directory/header file/archive scans, and attempts
at binding to targets.</li>
<li class="listitem">Show variable settings.</li>
<li class="listitem">Show variable fetches,
variable expansions, and evaluation of '"if"' expressions.</li>
<li class="listitem">Show
variable manipulation, scanner tokens, and memory usage.</li>
<li class="listitem">Show profile
information for rules, both timing and memory.</li>
<li class="listitem">Show parsing progress
of Jamfiles.</li>
<li class="listitem">Show graph of target dependencies.</li>
<li class="listitem">Show change target status
(fate).</li>
</ol></div>
<p>
</p>
</dd>
<dt><span class="term"><div class="literallayout"><p><code class="literal">-d +<span class="emphasis"><em>n</em></span></code></p></div></span></dt>
<dd><p>
Enable debugging level <span class="emphasis"><em>n</em></span>.
</p></dd>
<dt><span class="term"><div class="literallayout"><p><code class="literal">-d 0</code></p></div></span></dt>
<dd><p>
Turn off all debugging levels. Only errors are reported.
</p></dd>
<dt><span class="term"><div class="literallayout"><p><code class="literal">-f <span class="emphasis"><em>Jambase</em></span></code></p></div></span></dt>
<dd><p>
Read <span class="emphasis"><em>Jambase</em></span> instead of using the built-in Jambase.
Only one -f flag is permitted, but the <span class="emphasis"><em>Jambase</em></span>
may explicitly include other files. A <span class="emphasis"><em>Jambase</em></span>
name of "-" is allowed, in which case console input is read
until it is closed, at which point the input is treated as the Jambase.
</p></dd>
<dt><span class="term"><div class="literallayout"><p><code class="literal">-j <span class="emphasis"><em>n</em></span></code></p></div></span></dt>
<dd><p>
Run up to <span class="emphasis"><em>n</em></span> shell commands concurrently (UNIX
and NT only). The default is 1.
</p></dd>
<dt><span class="term"><div class="literallayout"><p><code class="literal">-l <span class="emphasis"><em>n</em></span></code></p></div></span></dt>
<dd><p>
Limit actions to running for <span class="emphasis"><em>n</em></span> number of seconds,
after which they are stopped. Note: Windows only.
</p></dd>
<dt><span class="term"><div class="literallayout"><p><code class="literal">-n</code></p></div></span></dt>
<dd><p>
Don't actually execute the updating actions, but do everything else.
This changes the debug level default to <code class="literal">-d 2</code>.
</p></dd>
<dt><span class="term"><div class="literallayout"><p><code class="literal">-o <span class="emphasis"><em>file</em></span></code></p></div></span></dt>
<dd><p>
Write the updating actions to the specified file instead of running
them.
</p></dd>
<dt><span class="term"><div class="literallayout"><p><code class="literal">-q</code></p></div></span></dt>
<dd><p>
Quit quickly (as if an interrupt was received) as soon as <span class="bold"><strong>any</strong></span> target fails.
</p></dd>
<dt><span class="term"><div class="literallayout"><p><code class="literal">-s <span class="emphasis"><em>var</em></span>=<span class="emphasis"><em>value</em></span></code></p></div></span></dt>
<dd><p>
Set the variable <span class="emphasis"><em>var</em></span> to <span class="emphasis"><em>value</em></span>,
overriding both internal variables and variables imported from the
environment.
</p></dd>
<dt><span class="term"><div class="literallayout"><p><code class="literal">-t <span class="emphasis"><em>target</em></span></code></p></div></span></dt>
<dd><p>
Rebuild <span class="emphasis"><em>target</em></span> and everything that depends on
it, even if it is up-to-date.
</p></dd>
<dt><span class="term"><div class="literallayout"><p><code class="literal">-- <span class="emphasis"><em>value</em></span></code></p></div></span></dt>
<dd><p>
The option and <span class="emphasis"><em>value</em></span> is ignored, but is available
from the <code class="literal">$(ARGV)</code> variable.
</p></dd>
<dt><span class="term"><div class="literallayout"><p><code class="literal">-v</code></p></div></span></dt>
<dd><p>
Print the version of <code class="literal">bjam</code> and exit.
</p></dd>
</dl>
</div>
<div class="section" title="Command-line and Environment Variable Quoting">
<div class="titlepage"><div><div><h4 class="title">
<a name="jam.usage.options.command_line_and_environment_variable_quoting"></a><a class="link" href="usage.html#jam.usage.options.command_line_and_environment_variable_quoting" title="Command-line and Environment Variable Quoting">Command-line
and Environment Variable Quoting</a>
</h4></div></div></div>
<p>
Classic Jam had an odd behavior with respect to command-line variable (<code class="literal">-s...</code>)
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:
</p>
<pre class="programlisting">jam -sMSVCNT="\"\"C:\Program Files\Microsoft Visual C++\VC98\"\"" ...
</pre>
<p>
The outer quote is for the shell. The middle quote is for Jam, to tell
it to take everything within those quotes literally, and the inner quotes
are for the shell again when paths are passed as arguments to build actions.
Under NT, it looks a lot more sane to use environment variables before
invoking jam when you have to do this sort of quoting:
</p>
<pre class="programlisting">set MSVCNT=""C:\Program Files\Microsoft Visual C++\VC98\""
</pre>
</div>
</div>
<div class="section" title="Operation">
<div class="titlepage"><div><div><h3 class="title">
<a name="jam.usage.operation"></a><a class="link" href="usage.html#jam.usage.operation" title="Operation"> Operation</a>
</h3></div></div></div>
<div class="toc"><dl>
<dt><span class="section"><a href="usage.html#jam.usage.operation.startup"> Start-up</a></span></dt>
<dt><span class="section"><a href="usage.html#jam.usage.operation.parsing"> Parsing</a></span></dt>
<dt><span class="section"><a href="usage.html#jam.usage.operation.binding"> Binding</a></span></dt>
<dt><span class="section"><a href="usage.html#jam.usage.operation.updating"> Updating</a></span></dt>
</dl></div>
<p>
BJam has four phases of operation: start-up, parsing, binding, and updating.
</p>
<div class="section" title="Start-up">
<div class="titlepage"><div><div><h4 class="title">
<a name="jam.usage.operation.startup"></a><a class="link" href="usage.html#jam.usage.operation.startup" title="Start-up"> Start-up</a>
</h4></div></div></div>
<p>
Upon start-up, <code class="literal">bjam</code> imports environment variable settings
into <code class="literal">bjam</code> variables. Environment variables are split
at blanks with each word becoming an element in the variable's list of
values. Environment variables whose names end in <code class="literal">PATH</code>
are split at <code class="literal">$(SPLITPATH)</code> characters (e.g., <code class="literal">":"</code>
for Unix).
</p>
<p>
To set a variable's value on the command line, overriding the variable's
environment value, use the <code class="literal">-s</code> option. To see variable
assignments made during bjam's execution, use the <code class="literal">-d+7</code>
option.
</p>
<p>
The Boost.Build v2 initialization behavior has been implemented. This behavior
only applies when the executable being invoked is called "<code class="literal">bjam</code>"
or, for backward-compatibility, when the <code class="literal">BOOST_ROOT</code>
variable is set.
</p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">
We attempt to load "<code class="literal">boost-build.jam</code>" by
searching from the current invocation directory up to the root of the
file system. This file is expected to invoke the <code class="literal">boost-build</code>
rule to indicate where the Boost.Build system files are, and to load
them.
</li>
<li class="listitem">
If <code class="literal">boost-build.jam</code> is not found we error and exit,
giving brief instructions on possible errors. As a backward-compatibility
measure for older versions of Boost.Build, when the <code class="literal">BOOST_ROOT</code>
variable is set, we first search for <code class="literal">boost-build.jam</code>
in <code class="literal">$(BOOST_ROOT)/tools/build</code> and <code class="literal">$(BOOST_BUILD_PATH)</code>.
If found, it is loaded and initialization is complete.
</li>
<li class="listitem">
The <code class="literal">boost-build</code> rule adds its (optional) argument
to the front of <code class="literal">BOOST_BUILD_PATH</code>, and attempts to
load <code class="literal">bootstrap.jam</code> from those directories. If a relative
path is specified as an argument, it is treated as though it was relative
to the <code class="literal">boost-build.jam</code> file.
</li>
<li class="listitem">
If the <code class="literal">bootstrap.jam</code> file was not found, we print
a likely error message and exit.
</li>
</ol></div>
</div>
<div class="section" title="Parsing">
<div class="titlepage"><div><div><h4 class="title">
<a name="jam.usage.operation.parsing"></a><a class="link" href="usage.html#jam.usage.operation.parsing" title="Parsing"> Parsing</a>
</h4></div></div></div>
<p>
In the parsing phase, <code class="literal">bjam</code> reads and parses the <code class="literal">Jambase</code>
file, by default the built-in one. It is written in the <a class="link" href="language.html" title="Language">jam
language</a>. The last action of the <code class="literal">Jambase</code> is to
read (via the "include" rule) a user-provided file called "<code class="literal">Jamfile</code>".
</p>
<p>
Collectively, the purpose of the <code class="literal">Jambase</code> and the <code class="literal">Jamfile</code>
is to name build targets and source files, construct the dependency graph
among them, and associate build actions with targets. The <code class="literal">Jambase</code>
defines boilerplate rules and variable assignments, and the <code class="literal">Jamfile</code>
uses these to specify the actual relationship among the target and source
files.
</p>
</div>
<div class="section" title="Binding">
<div class="titlepage"><div><div><h4 class="title">
<a name="jam.usage.operation.binding"></a><a class="link" href="usage.html#jam.usage.operation.binding" title="Binding"> Binding</a>
</h4></div></div></div>
<div class="toc"><dl>
<dt><span class="section"><a href="usage.html#jam.usage.operation.binding.fate"> Update Determination</a></span></dt>
<dt><span class="section"><a href="usage.html#jam.usage.operation.binding.headerscan"> Header File
Scanning</a></span></dt>
</dl></div>
<p>
After parsing, <code class="literal">bjam</code> recursively descends the dependency
graph and binds every file target with a location in the filesystem. If
<code class="literal">bjam</code> detects a circular dependency in the graph, it
issues a warning.
</p>
<p>
File target names are given as absolute or relative path names in the filesystem.
If the path name is absolute, it is bound as is. If the path name is relative,
it is normally bound as is, and thus relative to the current directory.
This can be modified by the settings of the <code class="literal">$(SEARCH)</code>
and <code class="literal">$(LOCATE)</code> variables, which enable jam to find and
build targets spread across a directory tree. See <a class="link" href="language.html#jam.language.variables.builtins.search" title="SEARCH and LOCATE">SEARCH
and LOCATE Variables</a> below.
</p>
<div class="section" title="Update Determination">
<div class="titlepage"><div><div><h5 class="title">
<a name="jam.usage.operation.binding.fate"></a><a class="link" href="usage.html#jam.usage.operation.binding.fate" title="Update Determination"> Update Determination</a>
</h5></div></div></div>
<p>
After binding each target, <code class="literal">bjam</code> determines whether
the target needs updating, and if so marks the target for the updating
phase. A target is normally so marked if it is missing, it is older than
any of its sources, or any of its sources are marked for updating. This
behavior can be modified by the application of special built-in rules,
<code class="literal">ALWAYS</code>, <code class="literal">LEAVES</code>, <code class="literal">NOCARE</code>,
<code class="literal">NOTFILE</code>, <code class="literal">NOUPDATE</code>, and <code class="literal">TEMPORARY</code>.
See <a class="link" href="language.html#jam.language.rules.builtins.modifying_binding" title="Modifying Binding">Modifying
Binding</a> below.
</p>
</div>
<div class="section" title="Header File Scanning">
<div class="titlepage"><div><div><h5 class="title">
<a name="jam.usage.operation.binding.headerscan"></a><a class="link" href="usage.html#jam.usage.operation.binding.headerscan" title="Header File Scanning"> Header File
Scanning</a>
</h5></div></div></div>
<p>
During the binding phase, <code class="literal">bjam</code> also performs header
file scanning, where it looks inside source files for the implicit dependencies
on other files caused by C's #include syntax. This is controlled by the
special variables $(HDRSCAN) and $(HDRRULE). The result of the scan is
formed into a rule invocation, with the scanned file as the target and
the found included file names as the sources. Note that this is the only
case where rules are invoked outside the parsing phase. See <a class="link" href="language.html#jam.language.variables.builtins.hdrscan" title="HDRSCAN and HDRRULE">HDRSCAN
and HDRRULE Variables</a> below.
</p>
</div>
</div>
<div class="section" title="Updating">
<div class="titlepage"><div><div><h4 class="title">
<a name="jam.usage.operation.updating"></a><a class="link" href="usage.html#jam.usage.operation.updating" title="Updating"> Updating</a>
</h4></div></div></div>
<p>
After binding, <code class="literal">bjam</code> again recursively descends the dependency
graph, this time executing the update actions for each target marked for
update during the binding phase. If a target's updating actions fail, then
all other targets which depend on that target are skipped.
</p>
<p>
The <code class="literal">-j</code> flag instructs <code class="literal">bjam</code> to build
more than one target at a time. If there are multiple actions on a single
target, they are run sequentially.
</p>
</div>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2003-2007 Rene Rivera, David Abrahams, Vladimir Prus<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="building.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="language.html"><img src="../images/next.png" alt="Next"></a>
</div>
</body>
</html>
