1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title> Using BJam</title>
<link rel="stylesheet" href="../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.68.1">
<link rel="start" href="../index.html" title="Boost.Jam : 3.1.13">
<link rel="up" href="../index.html" title="Boost.Jam : 3.1.13">
<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%"><td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src=".././boost.png"></td></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="building.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="language.html"><img src="../images/next.png" alt="Next"></a>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="jam.usage"></a><a 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>
<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" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="jam.usage.options"></a><a 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"><code class="literal">-a</code></span></dt>
<dd>
Build all targets anyway, even if they are up-to-date.
</dd>
<dt><span class="term"><code class="literal">-d<span class="emphasis"><em>n</em></span></code></span></dt>
<dd>
Enable cummulative debugging levels from 1 to n. Values are:<br> 1 -
Show the actions taken for building targets, as they are executed (the
default).<br> 2 - Show "quiet" actions and display all action
text, as they are executed.<br> 3 - Show dependency analysis, and target/source
timestamps/paths.<br> 4 - Show arguments and timming of shell invocations.<br>
5 - Show rule invocations and variable expansions.<br> 6 - Show directory/header
file/archive scans, and attempts at binding to targets.<br> 7 - Show
variable settings.<br> 8 - Show variable fetches, variable expansions,
and evaluation of '"if"' expressions.<br> 9 - Show variable
manipulation, scanner tokens, and memory usage.<br> 10 - Show profile
information for rules, both timing and memory.<br> 11 - Show parsing
progress of Jamfiles.<br> 12 - Show graph of target dependencies.<br>
13 - Show change target status (fate).
</dd>
<dt><span class="term"><code class="literal">-d+<span class="emphasis"><em>n</em></span></code></span></dt>
<dd>
Enable debugging level <span class="emphasis"><em>n</em></span>.
</dd>
<dt><span class="term"><code class="literal">-d0</code></span></dt>
<dd>
Turn off all debugging levels. Only errors are reported.
</dd>
<dt><span class="term"><code class="literal">-f<span class="emphasis"><em>Jambase</em></span></code></span></dt>
<dd>
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.
</dd>
<dt><span class="term"><code class="literal">-j<span class="emphasis"><em>n</em></span></code></span></dt>
<dd>
Run up to <span class="emphasis"><em>n</em></span> shell commands concurrently (UNIX and
NT only). The default is 1.
</dd>
<dt><span class="term"><code class="literal">-l<span class="emphasis"><em>n</em></span></code></span></dt>
<dd>
Limit actions to running for <span class="emphasis"><em>n</em></span> number of seconds,
after which they are stopped. Note: Windows only.
</dd>
<dt><span class="term"><code class="literal">-n</code></span></dt>
<dd>
Don't actually execute the updating actions, but do everything else. This
changes the debug level default to <code class="literal">-d 2</code>.
</dd>
<dt><span class="term"><code class="literal">-o<span class="emphasis"><em>file</em></span></code></span></dt>
<dd>
Write the updating actions to the specified file instead of running them.
</dd>
<dt><span class="term"><code class="literal">-q</code></span></dt>
<dd>
Quit quickly (as if an interrupt was received) as soon as <span class="bold"><strong>any</strong></span>
target fails.
</dd>
<dt><span class="term"><code class="literal">-s<span class="emphasis"><em>var</em></span>=<span class="emphasis"><em>value</em></span></code></span></dt>
<dd>
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.
</dd>
<dt><span class="term"><code class="literal">-t<span class="emphasis"><em>target</em></span></code></span></dt>
<dd>
Rebuild <span class="emphasis"><em>target</em></span> and everything that depends on it,
even if it is up-to-date.
</dd>
<dt><span class="term"><code class="literal">--<span class="emphasis"><em>value</em></span></code></span></dt>
<dd>
The option and <span class="emphasis"><em>value</em></span> is ignored, but is available
from the <code class="literal">$(ARGV)</code> variable.
</dd>
<dt><span class="term"><code class="literal">-v</code></span></dt>
<dd>
Print the version of <code class="literal">bjam</code> and exit.
</dd>
</dl>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="jam.usage.options.command_line_and_environment_variable_quoting"></a><a 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" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="jam.usage.operation"></a><a 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" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="jam.usage.operation.startup"></a><a 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 type="1">
<li>
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>
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>
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>
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" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="jam.usage.operation.parsing"></a><a 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 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" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="jam.usage.operation.binding"></a><a 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 href="language.html#jam.language.variables.builtins.search" title=" SEARCH and
LOCATE">SEARCH
and LOCATE Variables</a> below.
</p>
<div class="section" lang="en">
<div class="titlepage"><div><div><h5 class="title">
<a name="jam.usage.operation.binding.fate"></a><a 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 href="language.html#jam.language.rules.builtins.modifying_binding" title="Modifying
Binding">Modifying
Binding</a> below.
</p>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h5 class="title">
<a name="jam.usage.operation.binding.headerscan"></a><a 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 href="language.html#jam.language.variables.builtins.hdrscan" title=" HDRSCAN
and HDRRULE">HDRSCAN
and HDRRULE Variables</a> below.
</p>
</div>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="jam.usage.operation.updating"></a><a 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 width="100%"><tr>
<td align="left"></td>
<td align="right"><small>Copyright 2003-2006 Rene
Rivera, David Abrahams, Vladimir Prus</small></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="building.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="language.html"><img src="../images/next.png" alt="Next"></a>
</div>
</body>
</html>
|
