Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/doc/html/jam/usage.html @ 35

Last change on this file since 35 was 29, checked in by landauf, 17 years ago

updated boost from 1_33_1 to 1_34_1
File size: 18.2 KB
Line 
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title> Using BJam</title>
5<link rel="stylesheet" href="../boostbook.css" type="text/css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.68.1">
7<link rel="start" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
8<link rel="up" href="../jam.html" title="Chapter 24. Boost.Jam : 3.1.14">
9<link rel="prev" href="building.html" title=" Building BJam">
10<link rel="next" href="language.html" title=" Language">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
13<table cellpadding="2" width="100%">
14<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
15<td align="center"><a href="../../../index.htm">Home</a></td>
16<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
17<td align="center"><a href="../../../people/people.htm">People</a></td>
18<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
19<td align="center"><a href="../../../more/index.htm">More</a></td>
20</table>
21<hr>
22<div class="spirit-nav">
23<a accesskey="p" href="building.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../jam.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>
24</div>
25<div class="section" lang="en">
26<div class="titlepage"><div><div><h2 class="title" style="clear: both">
27<a name="jam.usage"></a> Using BJam</h2></div></div></div>
28<div class="toc"><dl>
29<dt><span class="section"><a href="usage.html#jam.usage.options"> Options</a></span></dt>
30<dt><span class="section"><a href="usage.html#jam.usage.operation"> Operation</a></span></dt>
31</dl></div>
32<p>
33      If <span class="emphasis"><em>target</em></span> is provided on the command line, <code class="literal">bjam</code>
34      builds <span class="emphasis"><em>target</em></span>; otherwise <code class="literal">bjam</code> builds
35      the target <code class="literal">all</code>.
36    </p>
37<pre class="programlisting">bjam ( -option [value] | target ) *
38</pre>
39<div class="section" lang="en">
40<div class="titlepage"><div><div><h3 class="title">
41<a name="jam.usage.options"></a> Options</h3></div></div></div>
42<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>
43<p>
44        Options are either singular or have an accompanying value. When a value is
45        allowed, or required, it can be either given as an argument following the
46        option argument, or it can be given immediately after the option as part
47        of the option argument. The allowed options are:
48      </p>
49<div class="variablelist">
50<p class="title"><b></b></p>
51<dl>
52<dt><span class="term"><code class="literal">-a</code></span></dt>
53<dd>
54          Build all targets anyway, even if they are up-to-date.
55        </dd>
56<dt><span class="term"><code class="literal">-d
57 
58        <span class="emphasis"><em>n</em></span></code></span></dt>
59<dd>
60          Enable cummulative debugging levels from 1 to n. Values are:<br> 1 -
61          Show the actions taken for building targets, as they are executed (the
62          default).<br> 2 - Show "quiet" actions and display all action
63          text, as they are executed.<br> 3 - Show dependency analysis, and target/source
64          timestamps/paths.<br> 4 - Show arguments and timming of shell invocations.<br>
65          5 - Show rule invocations and variable expansions.<br> 6 - Show directory/header
66          file/archive scans, and attempts at binding to targets.<br> 7 - Show
67          variable settings.<br> 8 - Show variable fetches, variable expansions,
68          and evaluation of '"if"' expressions.<br> 9 - Show variable
69          manipulation, scanner tokens, and memory usage.<br> 10 - Show profile
70          information for rules, both timing and memory.<br> 11 - Show parsing
71          progress of Jamfiles.<br> 12 - Show graph of target dependencies.<br>
72          13 - Show change target status (fate).
73        </dd>
74<dt><span class="term"><code class="literal">-d
75 
76        +<span class="emphasis"><em>n</em></span></code></span></dt>
77<dd>
78          Enable debugging level <span class="emphasis"><em>n</em></span>.
79        </dd>
80<dt><span class="term"><code class="literal">-d
81 
82        0</code></span></dt>
83<dd>
84          Turn off all debugging levels. Only errors are reported.
85        </dd>
86<dt><span class="term"><code class="literal">-f
87 
88        <span class="emphasis"><em>Jambase</em></span></code></span></dt>
89<dd>
90          Read <span class="emphasis"><em>Jambase</em></span> instead of using the built-in Jambase.
91          Only one -f flag is permitted, but the <span class="emphasis"><em>Jambase</em></span> may
92          explicitly include other files. A <span class="emphasis"><em>Jambase</em></span> name of
93          "-" is allowed, in which case console input is read until it
94          is closed, at which point the input is treated as the Jambase.
95        </dd>
96<dt><span class="term"><code class="literal">-j
97 
98        <span class="emphasis"><em>n</em></span></code></span></dt>
99<dd>
100          Run up to <span class="emphasis"><em>n</em></span> shell commands concurrently (UNIX and
101          NT only). The default is 1.
102        </dd>
103<dt><span class="term"><code class="literal">-l
104 
105        <span class="emphasis"><em>n</em></span></code></span></dt>
106<dd>
107          Limit actions to running for <span class="emphasis"><em>n</em></span> number of seconds,
108          after which they are stopped. Note: Windows only.
109        </dd>
110<dt><span class="term"><code class="literal">-n</code></span></dt>
111<dd>
112          Don't actually execute the updating actions, but do everything else. This
113          changes the debug level default to <code class="literal">-d 2</code>.
114        </dd>
115<dt><span class="term"><code class="literal">-o
116 
117        <span class="emphasis"><em>file</em></span></code></span></dt>
118<dd>
119          Write the updating actions to the specified file instead of running them.
120        </dd>
121<dt><span class="term"><code class="literal">-q</code></span></dt>
122<dd>
123          Quit quickly (as if an interrupt was received) as soon as <span class="bold"><strong>any</strong></span>
124          target fails.
125        </dd>
126<dt><span class="term"><code class="literal">-s
127 
128        <span class="emphasis"><em>var</em></span>=<span class="emphasis"><em>value</em></span></code></span></dt>
129<dd>
130          Set the variable <span class="emphasis"><em>var</em></span> to <span class="emphasis"><em>value</em></span>,
131          overriding both internal variables and variables imported from the environment.
132        </dd>
133<dt><span class="term"><code class="literal">-t
134 
135        <span class="emphasis"><em>target</em></span></code></span></dt>
136<dd>
137          Rebuild <span class="emphasis"><em>target</em></span> and everything that depends on it,
138          even if it is up-to-date.
139        </dd>
140<dt><span class="term"><code class="literal">--
141 
142        <span class="emphasis"><em>value</em></span></code></span></dt>
143<dd>
144          The option and <span class="emphasis"><em>value</em></span> is ignored, but is available
145          from the <code class="literal">$(ARGV)</code> variable.
146        </dd>
147<dt><span class="term"><code class="literal">-v</code></span></dt>
148<dd>
149          Print the version of <code class="literal">bjam</code> and exit.
150        </dd>
151</dl>
152</div>
153<div class="section" lang="en">
154<div class="titlepage"><div><div><h4 class="title">
155<a name="jam.usage.options.command_line_and_environment_variable_quoting"></a>Command-line and Environment Variable Quoting</h4></div></div></div>
156<p>
157          Classic Jam had an odd behavior with respect to command-line variable (<code class="literal">-s...</code>)
158          and environment variable settings which made it impossible to define an
159          arbitrary variable with spaces in the value. Boost Jam remedies that by
160          treating all such settings as a single string if they are surrounded by
161          double-quotes. Uses of this feature can look interesting, since shells
162          require quotes to keep characters separated by whitespace from being treated
163          as separate arguments:
164        </p>
165<pre class="programlisting">jam -sMSVCNT="\"\"C:\Program Files\Microsoft Visual C++\VC98\"\"" ...
166</pre>
167<p>
168          The outer quote is for the shell. The middle quote is for Jam, to tell
169          it to take everything within those quotes literally, and the inner quotes
170          are for the shell again when paths are passed as arguments to build actions.
171          Under NT, it looks a lot more sane to use environment variables before
172          invoking jam when you have to do this sort of quoting:
173        </p>
174<pre class="programlisting">set MSVCNT=""C:\Program Files\Microsoft Visual C++\VC98\""
175</pre>
176</div>
177</div>
178<div class="section" lang="en">
179<div class="titlepage"><div><div><h3 class="title">
180<a name="jam.usage.operation"></a> Operation</h3></div></div></div>
181<div class="toc"><dl>
182<dt><span class="section"><a href="usage.html#jam.usage.operation.startup"> Start-up</a></span></dt>
183<dt><span class="section"><a href="usage.html#jam.usage.operation.parsing"> Parsing</a></span></dt>
184<dt><span class="section"><a href="usage.html#jam.usage.operation.binding"> Binding</a></span></dt>
185<dt><span class="section"><a href="usage.html#jam.usage.operation.updating"> Updating</a></span></dt>
186</dl></div>
187<p>
188        BJam has four phases of operation: start-up, parsing, binding, and updating.
189      </p>
190<div class="section" lang="en">
191<div class="titlepage"><div><div><h4 class="title">
192<a name="jam.usage.operation.startup"></a> Start-up</h4></div></div></div>
193<p>
194          Upon start-up, <code class="literal">bjam</code> imports environment variable settings
195          into <code class="literal">bjam</code> variables. Environment variables are split
196          at blanks with each word becoming an element in the variable's list of
197          values. Environment variables whose names end in <code class="literal">PATH</code>
198          are split at <code class="literal">$(SPLITPATH)</code> characters (e.g., <code class="literal">":"</code>
199          for Unix).
200        </p>
201<p>
202          To set a variable's value on the command line, overriding the variable's
203          environment value, use the <code class="literal">-s</code> option. To see variable
204          assignments made during bjam's execution, use the <code class="literal">-d+7</code>
205          option.
206        </p>
207<p>
208          The Boost.Build v2 initialization behavior has been implemented. This behavior
209          only applies when the executable being invoked is called "<code class="literal">bjam</code>"
210          or, for backward-compatibility, when the <code class="literal">BOOST_ROOT</code>
211          variable is set.
212        </p>
213<div class="orderedlist"><ol type="1">
214<li>
215            We attempt to load "<code class="literal">boost-build.jam</code>" by
216            searching from the current invocation directory up to the root of the
217            file system. This file is expected to invoke the <code class="literal">boost-build</code>
218            rule to indicate where the Boost.Build system files are, and to load
219            them.
220          </li>
221<li>
222            If <code class="literal">boost-build.jam</code> is not found we error and exit,
223            giving brief instructions on possible errors. As a backward-compatibility
224            measure for older versions of Boost.Build, when the <code class="literal">BOOST_ROOT</code>
225            variable is set, we first search for <code class="literal">boost-build.jam</code>
226            in <code class="literal">$(BOOST_ROOT)/tools/build</code> and <code class="literal">$(BOOST_BUILD_PATH)</code>.
227            If found, it is loaded and initialization is complete.
228          </li>
229<li>
230            The <code class="literal">boost-build</code> rule adds its (optional) argument
231            to the front of <code class="literal">BOOST_BUILD_PATH</code>, and attempts to
232            load <code class="literal">bootstrap.jam</code> from those directories. If a relative
233            path is specified as an argument, it is treated as though it was relative
234            to the <code class="literal">boost-build.jam</code> file.
235          </li>
236<li>
237            If the <code class="literal">bootstrap.jam</code> file was not found, we print
238            a likely error message and exit.
239          </li>
240</ol></div>
241</div>
242<div class="section" lang="en">
243<div class="titlepage"><div><div><h4 class="title">
244<a name="jam.usage.operation.parsing"></a> Parsing</h4></div></div></div>
245<p>
246          In the parsing phase, <code class="literal">bjam</code> reads and parses the <code class="literal">Jambase</code>
247          file, by default the built-in one. It is written in the <a href="language.html" title=" Language">jam
248          language</a>. The last action of the <code class="literal">Jambase</code> is to
249          read (via the "include" rule) a user-provided file called "<code class="literal">Jamfile</code>".
250        </p>
251<p>
252          Collectively, the purpose of the <code class="literal">Jambase</code> and the <code class="literal">Jamfile</code>
253          is to name build targets and source files, construct the dependency graph
254          among them, and associate build actions with targets. The <code class="literal">Jambase</code>
255          defines boilerplate rules and variable assignments, and the <code class="literal">Jamfile</code>
256          uses these to specify the actual relationship among the target and source
257          files.
258        </p>
259</div>
260<div class="section" lang="en">
261<div class="titlepage"><div><div><h4 class="title">
262<a name="jam.usage.operation.binding"></a> Binding</h4></div></div></div>
263<div class="toc"><dl>
264<dt><span class="section"><a href="usage.html#jam.usage.operation.binding.fate"> Update Determination</a></span></dt>
265<dt><span class="section"><a href="usage.html#jam.usage.operation.binding.headerscan"> Header File Scanning</a></span></dt>
266</dl></div>
267<p>
268          After parsing, <code class="literal">bjam</code> recursively descends the dependency
269          graph and binds every file target with a location in the filesystem. If
270          <code class="literal">bjam</code> detects a circular dependency in the graph, it
271          issues a warning.
272        </p>
273<p>
274          File target names are given as absolute or relative path names in the filesystem.
275          If the path name is absolute, it is bound as is. If the path name is relative,
276          it is normally bound as is, and thus relative to the current directory.
277          This can be modified by the settings of the <code class="literal">$(SEARCH)</code>
278          and <code class="literal">$(LOCATE)</code> variables, which enable jam to find and
279          build targets spread across a directory tree. See <a href="language.html#jam.language.variables.builtins.search" title=" SEARCH and LOCATE">SEARCH
280          and LOCATE Variables</a> below.
281        </p>
282<div class="section" lang="en">
283<div class="titlepage"><div><div><h5 class="title">
284<a name="jam.usage.operation.binding.fate"></a> Update Determination</h5></div></div></div>
285<p>
286            After binding each target, <code class="literal">bjam</code> determines whether
287            the target needs updating, and if so marks the target for the updating
288            phase. A target is normally so marked if it is missing, it is older than
289            any of its sources, or any of its sources are marked for updating. This
290            behavior can be modified by the application of special built-in rules,
291            <code class="literal">ALWAYS</code>, <code class="literal">LEAVES</code>, <code class="literal">NOCARE</code>,
292            <code class="literal">NOTFILE</code>, <code class="literal">NOUPDATE</code>, and <code class="literal">TEMPORARY</code>.
293            See <a href="language.html#jam.language.rules.builtins.modifying_binding" title="Modifying Binding">Modifying
294            Binding</a> below.
295          </p>
296</div>
297<div class="section" lang="en">
298<div class="titlepage"><div><div><h5 class="title">
299<a name="jam.usage.operation.binding.headerscan"></a> Header File Scanning</h5></div></div></div>
300<p>
301            During the binding phase, <code class="literal">bjam</code> also performs header
302            file scanning, where it looks inside source files for the implicit dependencies
303            on other files caused by C's #include syntax. This is controlled by the
304            special variables $(HDRSCAN) and $(HDRRULE). The result of the scan is
305            formed into a rule invocation, with the scanned file as the target and
306            the found included file names as the sources. Note that this is the only
307            case where rules are invoked outside the parsing phase. See <a href="language.html#jam.language.variables.builtins.hdrscan" title=" HDRSCAN and HDRRULE">HDRSCAN
308            and HDRRULE Variables</a> below.
309          </p>
310</div>
311</div>
312<div class="section" lang="en">
313<div class="titlepage"><div><div><h4 class="title">
314<a name="jam.usage.operation.updating"></a> Updating</h4></div></div></div>
315<p>
316          After binding, <code class="literal">bjam</code> again recursively descends the dependency
317          graph, this time executing the update actions for each target marked for
318          update during the binding phase. If a target's updating actions fail, then
319          all other targets which depend on that target are skipped.
320        </p>
321<p>
322          The <code class="literal">-j</code> flag instructs <code class="literal">bjam</code> to build
323          more than one target at a time. If there are multiple actions on a single
324          target, they are run sequentially.
325        </p>
326</div>
327</div>
328</div>
329<table width="100%"><tr>
330<td align="left"></td>
331<td align="right"><small>Copyright © 2003-2006 Rene
332      Rivera, David Abrahams, Vladimir Prus</small></td>
333</tr></table>
334<hr>
335<div class="spirit-nav">
336<a accesskey="p" href="building.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../jam.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>
337</div>
338</body>
339</html>
Note: See TracBrowser for help on using the repository browser.