| <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> |