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