boost_1_45_0/doc/html/jam/usage.html - nest-learning-thermostat/5.0/boost - Git at Google

 <html>
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
 <title>Using BJam</title>
 <link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
 <meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
 <link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
 <link rel="up" href="../jam.html" title="Chapter&#160;32.&#160;Boost.Jam : 3.1.19">
 <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"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
 <td align="center"><a href="../../../index.html">Home</a></td>
 <td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
 <td align="center"><a href="../../../more/index.htm">More</a></td>
 </tr></table>
 <hr>
 <div class="spirit-nav">
 <a accesskey="p" href="building.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../jam.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="language.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
 </div>
 <div class="section">
 <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"><table border="0" summary="Warning">
 <tr>
 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../doc/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">
 <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&#160;<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&#160;+<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&#160;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&#160;<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&#160;<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&#160;<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&#160;<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&#160;<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&#160;<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">--&#160;<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">
 <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">
 <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">
 <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">
 <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">
 <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">
 <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">
 <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">
 <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 &#169; 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="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../jam.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="language.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
 </div>
 </body>
 </html>
	<html>
	<head>
	<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
	<title>Using BJam</title>
	<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
	<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
	<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
	<link rel="up" href="../jam.html" title="Chapter 32. Boost.Jam : 3.1.19">
	<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"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
	<td align="center"><a href="../../../index.html">Home</a></td>
	<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
	<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
	<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
	<td align="center"><a href="../../../more/index.htm">More</a></td>
	</tr></table>
	<hr>
	<div class="spirit-nav">
	<a accesskey="p" href="building.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../jam.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="language.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
	</div>
	<div class="section">
	<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"><table border="0" summary="Warning">
	<tr>
	<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../doc/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">
	<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">
	<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">
	<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">
	<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">
	<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">
	<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">
	<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">
	<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">
	<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="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../jam.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="language.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
	</div>
	</body>
	</html>