fixes to INSTALL
[k8jam.git] / doc / Jam.html
blob238ccb59957cd3d011af1bf56119604a7899e740
1 <HTML>
2 <TITLE>Jam - Make(1) Redux</TITLE>
3 <BODY>
4 <CENTER>
5 <H1>Jam - Make(1) Redux</H1>
6 <P>The <a href="http://gitorious.org/projects/kjam">K8Jam</a> Executable<BR>
7 Based on Perforce <a href="http://www.perforce.com/jam/jam.html">Jam</a>
8 </P>
9 </CENTER>
11 <DL>
12 <DT><P><H2>USAGE</H2><DD>
13 <PRE>
14 jam [ -a ] [ -g ] [ -n ] [ -q ] [ -v ]
15 [ -d <I>debug</I> ]
16 [ -f <I>jambase</I> ]
17 [ -j <I>jobs</I> ]
18 [ -o <I>actionsfile</I> ]
19 [ -s <I>var</I>=<I>value</I> ]
20 [ -t <I>target</I> ]
21 [ <I>target</I> ... ]
22 </PRE>
24 <DT><P><H2>DESCRIPTION</H2><DD>
25 <P><B>Jam</B> is a program construction tool, like <B>make</B>(1).</P>
26 <P><B>Jam</B> recursively builds target files from source files,
27 using dependency information and updating actions expressed in
28 the Jambase file, which is written in <B>jam</B>'s own interpreted
29 language. The default Jambase is compiled into <B>jam</B> and
30 provides a boilerplate for common use, relying on a user-provide
31 file "Jamfile" to enumerate actual targets and sources.</P>
32 <P>The Jambase is described in the <a href="Jambase.html">Jambase
33 Reference</a> and the document <a href="Jamfile.html">Using
34 Jamfiles and Jambase</A>.</P>
36 <DT><P><H2>OPTIONS</H2><DD>
37 <P>If <I>target</I> is provided on the command line, <B>jam</B>
38 builds <I>target;</I> otherwise <B>jam</B> builds the target
39 'all'.</P>
41 <P><B>Jam</b> may be invoked with the following options:</P>
42 <P><TABLE WIDTH="85%" ALIGN="CENTER" BORDER="1" CELLPADDING="2">
43 <TR><TD VALIGN="TOP" WIDTH="20%"><CODE>-a</CODE></TD>
44 <TD>Build all targets anyway, even if they are up-to-date.</TD></TR>
46 <TR><TD VALIGN="TOP"><CODE>-d <I>c</I></CODE></TD>
47 <TD>Turn on display option <I>c</I> and off the default
48 display (summary info and actions):
50 <DL COMPACT>
51 <DT>a<DD> Show summary info, actions, quiet actions, and the
52 use of temporary targets
53 <DT>c<DD> Show the names of files that cause rebuilds, i.e.
54 new sources, missing targets, etc.
55 <DT>d<DD> Display a dependency graph (in <B>jam</B> syntax).
56 <DT>m<DD> Display the dependency analysis, and target/source
57 timestamps and paths
58 <DT>x<DD> Show shell arguments
59 </DL>
60 </TD></TR>
62 <TR><TD VALIGN="TOP"><CODE>-d<I>n</I></CODE></TD>
63 <TD>Enable cummulative debugging levels from 1 to <I>n</I>.
64 Interesting values are:
65 <DL COMPACT>
66 <DT>1<DD> Show actions and summary info (the default)
67 <DT>3<DD> Old name for -dm (described above)
68 <DT>5<DD> Show rule invocations and variable expansions
69 <DT>6<DD> Show directory/header file/archive scans
70 <DT>7<DD> Show variable settings
71 <DT>8<DD> Show variable fetches
72 <DT>9<DD> Show variable manipulation, scanner tokens
73 </DL>
74 </TD></TR>
76 <TR><TD VALIGN="TOP"><CODE>-d +<I>n</I> </CODE></TD>
77 <TD>Enable debugging level <I>n</I>.</TD></TR>
79 <TR><TD VALIGN="TOP"><CODE>-d 0</CODE></TD>
80 <TD>Turn off all debugging levels. Only errors are emitted.</TD></TR>
82 <TR><TD VALIGN="TOP"><CODE>-f<I>jambase</I></CODE></TD>
83 <TD>Read <I>jambase</I> instead of using the built-in Jambase.
84 Multiple -f flags are permitted.</TD></TR>
86 <TR><TD VALIGN="TOP"><CODE>-g</CODE></TD>
87 <TD>Build targets with the newest sources first, rather than
88 in the order of appearance in the Jambase/Jamfiles.</TD></TR>
90 <TR><TD VALIGN="TOP"><CODE>-j<I>n</I></CODE></TD>
91 <TD> Run up to <I>n</I> shell commands concurrently (UNIX
92 and NT only). The default is 1.</TD></TR>
94 <TR><TD VALIGN="TOP"><CODE>-n</CODE></TD>
95 <TD>Don't actually execute the updating actions, but do
96 everything else. This changes the debug level to -dax.</TD></TR>
98 <TR><TD VALIGN="TOP"><CODE>-o<I>file</I></CODE></TD>
99 <TD>Write the updating actions to the specified file instead
100 of running them (or outputting them, as on the Mac).</TD></TR>
102 <TR><TD VALIGN="TOP"><CODE>-q</CODE></TD>
103 <TD>Quit quickly (as if an interrupt was received)
104 as soon as any target build fails.</TD></TR>
106 <TR><TD VALIGN="TOP"><CODE>-s<I>var</I>=<I>value</I></CODE></TD>
107 <TD>Set the variable <I>var</I> to <I>value</I>, overriding
108 both internal variables and variables imported from the
109 environment.</TD></TR>
111 <TR><TD VALIGN="TOP"><CODE>-t<I>target</I></CODE></TD>
112 <TD>Rebuild <I>target</I> and everything that depends on it,
113 even if it is up-to-date.</TD></TR>
115 <TR><TD VALIGN="TOP"><CODE>-v</CODE></TD>
116 <TD>Print the version of <B>jam</B> and exit.</TD></TR>
118 <TR><TD VALIGN="TOP"><CODE>-H<I>x</I></CODE></TD>
119 <TD>Show header cache statistics. Interesting <I>x</I> values are:
120 <DL COMPACT>
121 <DT>a<DD> all
122 <DT>h<DD> hits
123 <DT>s<DD> stats
124 </DL>
125 </TD></TR>
127 <TR><TD VALIGN="TOP"><CODE>-Z</CODE></TD>
128 <TD>Register old-style all-caps builtin names.</TD></TR>
129 </TABLE></P>
131 <DT><P><H2>OPERATION</H2><DD>
132 <P><b>Jam</b> has four phases of operation: start-up, parsing,
133 binding, and updating.</P>
135 <DT><P><H3>Start-up</H3><DD>
136 <P>Upon start-up, <b>jam</b> imports environment variable settings
137 into <b>jam</b> variables. Environment variables are split at
138 blanks with each word becoming an element in the variable's list
139 of values. Environment variables whose names end in PATH are
140 split at $(SPLITPATH) characters (e.g., ":" for Unix).</P>
142 <P>To set a variable's value on the command line, overriding the
143 variable's environment value, use the -s option. If a command
144 line argument includes, but doesn't start with a "=", it is
145 treated as an implicit "-s" option. To see variable
146 assignments made during <b>jam</b>'s execution, use the -d+7
147 option.</P>
149 <DT><P><H3>Parsing</H3><DD>
150 <P>In the parsing phase, <b>jam</b> reads and executes the Jambase
151 file, by default the built-in one. It is written in the <b>jam</b>
152 language. See <a href="#language">Language</a> below. The
153 last action of the Jambase is to read (via the "include" rule)
154 a user-provided file called "Jamfile".</P>
156 <P>Collectively, the purpose of the Jambase and the Jamfile is to
157 name built target and source files, construct the dependency
158 graph among them, and associate build actions with targets.
159 The Jambase defines boilerplate rules and variable assignments,
160 and the Jamfile uses these to specify the actual relationship
161 among the target and source files. See the
162 <a href="Jambase.html">Jambase Reference</a> and the document
163 <a href="Jamfile.html">Using Jamfiles and Jambase</a> for information.</P>
165 <A NAME="binding">
166 <DT><P><H3>Binding</H3><DD>
167 </A>
168 <P><H5>Binding</H5>
169 After parsing, <B>jam</B> recursively descends the dependency
170 graph and binds every file target with a location in the
171 filesystem.</P>
173 <P><H5>Targets</H5><DD>
174 Any string value in <b>jam</b> can represent a target, and it
175 does so if the DEPENDS or INCLUDES rules make it part of the
176 dependency graph. Build targets are files to be updated. Source
177 targets are the files used in updating build targets. Build
178 targets and source targets are collectively referred to as file
179 targets, and frequently build targets are source targets for
180 other build targets. Pseudotargets are symbols which represent
181 dependencies on other targets, but which are not themselves
182 associated with any real file.</P>
184 <P>A file target's identifier is generally the file's name, which can
185 be absolutely rooted, relative to the directory of <b>jam</b>'s
186 invocation, or simply local (no directory). Most often it is the
187 last case, and the actual file path is bound using the $(SEARCH)
188 and $(LOCATE) special variables. See
189 <A HREF="#search">SEARCH and LOCATE Variables</A> below. A local
190 filename is optionally qualified with "grist," a string value used
191 to assure uniqueness. A file target with an identifier of the form
192 <I>file(member)</I> is a library member (usually an ar(1) archive
193 on UNIX).</P>
195 <P>The use of $(SEARCH) and $(LOCATE) allows <b>jam</b> to separate
196 the the location of files from their names, so that Jamfiles can
197 refer to files locally (i.e. relative to the Jamfile's directory),
198 yet still be usable when <b>jam</b> is invoked from a distant
199 directory. The use of grist allows files with the same name
200 to be identified uniquely, so that <b>jam</b> can read a whole
201 directory tree of Jamfiles and not mix up same-named targets.</P>
203 <P><H5>Update Determination</H5>
204 After binding each target, <B>jam</B> determines whether the
205 target needs updating, and if so marks the target for the updating
206 phase. A target is normally so marked if it is missing, it is
207 older than any of its sources, or any of its sources are marked
208 for updating. This behavior can be modified by the application
209 of special built-in rules. See
210 <A HREF="#bindingmods">Modifying Binding</A> below.</P>
212 <P><H5>Header File Scanning</H5>
213 During the binding phase, <b>jam</b> also performs header file
214 scanning, where it looks inside source files for the implicit
215 dependencies on other files caused by C's #include syntax. This
216 is controlled by the special variables $(HDRSCAN) and $(HDRRULE).
217 The result of the scan is formed into a rule invocation, with
218 the scanned file as the target and the found included file names
219 as the sources. Note that this is the only case where rules
220 are invoked outside the parsing phase. See
221 <A HREF="#hdrscan">HDRSCAN and HDRRULE Variables</A> below.</P>
223 <DT><P><H3>Updating</H3><DD>
224 <P>After binding, <B>jam</B> again recursively descends the dependency
225 graph, this time executing the update actions for each target
226 marked for update during the binding phase. If a target's
227 updating actions fail, then all other targets which depend on
228 that target are skipped.</P>
230 <P>The -j flag instructs <B>jam</B> to build more than one target
231 at a time. If there are multiple actions on a single target,
232 they are run sequentially. The -g flag reorders builds so that
233 targets with newest sources are built first. Normally, they are
234 built in the order of appearance in the Jamfiles.</P>
236 <A NAME="language">
237 <DT><P><H2>LANGUAGE</H2><DD>
238 </A>
239 <DT><P><H3>Overview</H3><DD>
240 <B>Jam</b> has a interpreted, procedural language with a few
241 select features to effect program construction. Statements in
242 <b>jam</b> are rule (procedure) definitions, rule invocations,
243 updating action definitions, flow-of-control structures, variable
244 assignments, and sundry language support.</P>
246 <DT><P><H3>Lexical Features</H3></P><DD>
247 <P><B>Jam</b> treats its input files as whitespace-separated tokens,
248 with two exceptions: double quotes (") can enclose whitespace to
249 embed it into a token, and everything between the matching curly
250 braces ({}) in the definition of a updating actions is treated
251 as a single string. A backslash (\) can escape a double quote,
252 or any single whitespace character.</P>
254 <P><B>Jam</b> requires whitespace (blanks, tabs, or newlines) to
255 surround all tokens, <b>including the colon (:) and semicolon
256 (;) tokens</b>.</P>
258 <P><B>Jam</b> keywords (as mentioned in this document) are reserved
259 and generally must be quoted with double quotes (") to be used
260 as arbitrary tokens, such as variable or target names.</P>
262 <DT><P><H3>Datatype</H3></P><DD>
263 <P><B>Jam</B>'s only data type is a one-dimensional list of arbitrary
264 strings. They arise as literal (whitespace-separated) tokens in
265 the Jambase or included files, as the result of variable expansion
266 of those tokens, or as the return value from a rule invocation.</P>
268 <DT><P><H3>Rules</H3></P><DD>
269 <P>The basic <B>jam</b> language entity is called a rule. A rule
270 is simply a procedure definition, with a body of <b>jam</b>
271 statements to be run when the rule is invoked. The syntax of
272 rule invocation make it possible to write Jamfiles that look
273 a bit like Makefiles.</P>
275 <P>Rules take up to 9 arguments ($(1) through $(9), each a list)
276 and can have a return value (a single list). A rule's return
277 value can be expanded in a list by enclosing the rule invocation
278 with <tt>[</tt> and <tt>]</tt>.</P>
280 <DT><P><H3>Updating Actions</H3></P><DD>
281 <P>A rule may have updating actions associated with it, in which
282 case arguments $(1) and $(2) are treated as built targets and
283 sources, respectively. Updating actions are the OS shell commands
284 to execute when updating the built targets of the rule.</P>
286 <P>When an rule with updating actions is invoked, those actions are
287 added to those associated with its built targets ($(1)) before
288 the rule's procedure is run. Later, to build the targets in the
289 updating phase, the actions are passed to the OS command shell,
290 with $(1) and $(2) replaced by bound versions of the target names.
291 See <A HREF="#binding">Binding</A> above.</P>
293 <DT><P><H3>Statements</H3></P><DD>
294 <P><b>Jam</b>'s langauge has the following statements:</P>
295 <P><TABLE WIDTH="75%" ALIGN="CENTER"><TR><TD><DL>
296 <P><DT><CODE>
297 <I>rulename field1</I> : <I>field2</I> : <I>...</I> : <I>fieldN</I> ;
298 </CODE></P>
299 <P><DD>Invoke a rule. A rule is invoked with values in
300 <I>field1</I> through <I>fieldN</I> (9 max). They may be
301 referenced in the procedure's <I>statements</I> as $(1)
302 through $(<9>N</I>). $(&lt;) and $(&gt;) are synonymous
303 with $(1) and $(2).</P>
305 <P><i>rulename</i> undergoes <A HREF="#varexp"> variable
306 expansion</A>. If the resulting list is more than one value,
307 each rule is invoked with the same arguments, and the result
308 of the invocation is the concatenation of all the results.</P>
310 <P><DT><CODE>
311 actions [ <I>modifiers</I> ] <I>rulename</I> { <I>commands</I> }
312 </CODE></P>
313 <P><DD> Define a rule's updating actions, replacing any previous
314 definition. The first two arguments may be referenced in
315 the action's <I>commands</I> as $(1) and $(2) or $(&lt;)
316 and $(&gt;).</P>
318 <P>The following action <i>modifiers</i> are understood:
319 <P><TABLE BORDER="1">
320 <TR><TD WIDTH=30%><CODE>actions bind <I>vars</I></CODE></TD>
321 <TD>$(vars) will be replaced with bound values.</TD>
322 </TR>
323 <TR><TD><CODE>actions existing</CODE></TD>
324 <TD>$(>) includes only source targets currently existing.</TD>
325 </TR>
326 <TR><TD><CODE>actions ignore</CODE></TD>
327 <TD>The return status of the <I>commands</I> is ignored.</TD>
328 </TR>
329 <TR><TD><CODE>actions piecemeal</CODE></TD>
330 <TD><I>commands</I> are repeatedly invoked with a subset
331 of $(>) small enough to fit in the command buffer on this
332 OS.</TD>
333 </TR>
334 <TR><TD><CODE>actions quietly</CODE></TD>
335 <TD>The action is not echoed to the standard output.</TD>
336 </TR>
337 <TR><TD><CODE>actions together</CODE></TD>
338 <TD>The $(>) from multiple invocations of the same action
339 on the same built target are glommed together.</TD>
340 </TR>
341 <TR><TD><CODE>actions updated</CODE></TD>
342 <TD>$(>) includes only source targets themselves marked
343 for updating.</TD>
344 </TR>
345 </TABLE></P>
347 <P><DT><CODE>break</CODE></P>
348 <P><DD>Breaks out of the closest enclosing <I>for</I> or <I>while</I> loop.</P>
350 <P><DT><CODE>continue</CODE></P>
351 <P><DD>Jumps to the end of the closest enclosing <I>for</I> or <I>while</I> loop.
353 <P><DT><CODE>
354 for <I>var</I> in <I>list</I> { <I>statements</I> }
355 </CODE></P>
356 <P><DD>Executes <i>statements</i> for each element in
357 <i>list</i>, setting the variable <i>var</i> to the element value.</P>
359 <A name="if"></A>
360 <P><DT><CODE>
361 if <I>cond</I> { <I>statements</I> } [ else <I>statement</I> ]
362 </CODE></P>
363 <P><DD>Does the obvious; the else clause is optional. <i>cond</i> is built of:
364 <TABLE BORDER="1">
365 <TR><TD WIDTH="25%"><CODE><I>a</I></CODE></TD>
366 <TD>true if any <I>a</I> element is a non-zero-length string</TD>
367 </TR>
368 <TR><TD><CODE><I>a</I> = <I>b</I></CODE></TD>
369 <TD>list <I>a</I> matches list <I>b</I> string-for-string</TD>
370 </TR>
371 <TR><TD><CODE><I>a</I> != <I>b</I></CODE></TD>
372 <TD>list <I>a</I> does not match list <I>b</I></TD>
373 </TR>
374 <TR><TD><CODE><I>a</I> &lt; <I>b</I></CODE></TD>
375 <TD><I>a[i]</I> string is less than <I>b[i]</I> string, where <i>i</i> is first mismatched element
376 in lists <I>a</I> and <I>b</I></TD>
377 </TR>
378 <TR><TD><CODE><I>a</I> &lt;= <I>b</I></CODE></TD>
379 <TD>every <I>a</I> string is less than or equal to its <I>b</I> counterpart</TD>
380 </TR>
381 <TR><TD><CODE><I>a</I> &gt; <I>b</I></CODE></TD>
382 <TD><I>a[i]</I> string is greater than <I>b[i]</I> string, where <i>i</i> is first mismatched element</TD>
383 </TR>
384 <TR><TD><CODE><I>a</I> &gt;= <I>b</I></CODE></TD>
385 <TD>every <I>a</I> string is greater than or equal to its <I>b</I> counterpart</TD>
386 </TR>
387 <TR><TD><CODE><I>a</I> in <I>b</I></CODE></TD>
388 <TD>true if all elements of <I>a</I> can be found in <I>b</I>, or if <I>a</I> has no elements</TD>
389 </TR>
390 <TR><TD><CODE>! <I>cond</I></CODE></TD>
391 <TD>condition not true</TD>
392 </TR>
393 <TR><TD><CODE><I>cond</I> && <I>cond</I></CODE></TD>
394 <TD>conjunction</TD>
395 </TR>
396 <TR><TD> <CODE><I>cond</I> || <I>cond</I></CODE></TD>
397 <TD>disjunction</TD>
398 </TR>
399 <TR><TD><CODE>( <I>cond</I> )</CODE></TD>
400 <TD>precedence grouping</TD>
401 </TR>
402 </TABLE></P>
404 <P><DT><CODE>include <I>file</I> ;</CODE></P>
405 <P><DD>Causes <b>jam</b> to read the named <i>file</i>.
406 The file is bound like a regular target (see <A HREF="#binding">Binding</A>
407 above) but unlike a regular target the include file cannot be built.
408 Marking an include file target with the <b>NOCARE</b> rule makes it optional:
409 if it is missing, it causes no error.</P>
411 <P>The include file is inserted into the input stream during
412 the parsing phase. The primary input file and all the included
413 file(s) are treated as a single file; that is, <b>jam</b>
414 infers no scope boundaries from included files.</P>
416 <P><DT><CODE>local <i>vars</I> [ = <i>values</i> ] ;</CODE></P>
417 <P><DD>Creates new <i>vars</i> inside to the enclosing {}
418 block, obscuring any previous values they might have. The
419 previous values for <i>vars</i> are restored when the current
420 block ends. Any rule called or file included will see the
421 local and not the previous value (this is sometimes called
422 Dynamic Scoping). The local statement may appear anywhere,
423 even outside of a block (in which case the previous value
424 is restored when the input ends). The <i>vars</i> are
425 initialized to <i>values</i> if present, or left uninitialized
426 otherwise.</P>
428 <P><DT><CODE>on <I>target</I> <I>statement</I> ;</CODE></P>
429 <P><DD>Run <I>statement</I> under the influence of
430 <I>target</I>'s target-specific variables. These variables
431 become local copies during <I>statement</I>'s run, but they
432 may be updated as target-specific variables using the usual
433 "<I>variable</I> on <I>targets</I> =" syntax.</P>
435 <P><DT><CODE>return <I>values</I> ;</CODE></P>
436 <P><DD>Within a rule body, the return statement sets the return
437 value for an invocation of the rule and terminates the rule's
438 execution.</P>
440 <P><DT><CODE>rule <I>rulename</I> [ : <I>vars</I> ] { <I>statements</I> }</CODE></P>
441 <P><DD>Define a rule's procedure, replacing any previous
442 definition. If <I>vars</I> are provided, they are assigned
443 the values of the parameters ($(1) to $(9)) when <I>statements</I>
444 are executed, as with the <B>local</B> statement.</P>
446 <A NAME="switch"></A>
447 <P><DT><CODE>switch <I>value</I>
448 <BR> {
449 <BR> case <I>pattern1</I> : <I>statements</I> ;
450 <BR> case <I>pattern2</I> : <I>statements</I> ;
451 <BR> ...
452 <BR> }
453 </CODE></P>
454 <P><DD>The switch statement executes zero or one of the
455 enclosed <i>statements</i>, depending on which, if any, is
456 the first case whose <i>pattern</I> matches <i>value</i>.
457 The <i>pattern</I> values are not variable-expanded. The
458 <i>pattern</I> values may include the following wildcards:
459 <TABLE>
460 <TR><TD><CODE>?</CODE></TD><TD>match any single character</TD></TR>
461 <TR><TD><CODE>*</CODE></TD><TD>match zero or more characters</TD></TR>
462 <TR><TD><CODE>[<i>chars</i>]</CODE></TD><TD>match any single character in <i>chars</i></TD></TR>
463 <TR><TD><CODE>[^<i>chars</i>]</CODE></TD><TD>match any single character not in <i>chars</i></TD></TR>
464 <TR><TD><CODE>\<i>x</i></CODE></TD><TD>match <i>x</i> (escapes the other wildcards)</i></TD></TR>
465 </TABLE>
466 Note that escaping isn't working in range definitions. To include "]" in range, one can
467 write range as "[]...]" or "[^]...]".</P>
469 <P><DT><CODE>while <I>cond</I> { <I>statements</I> }</CODE></P>
470 <P><DD>Repeatedly execute <I>statements</I> while <I>cond</I>
471 remains true upon entry. (See the description of <I>cond</I>
472 expression syntax under <a href="#if">if</a>, above).
473 </DL></TD></TR></TABLE></P>
476 <DT><P><H3>Variables</H3><DD>
477 <P><B>Jam</b> variables are lists of zero or more elements, with
478 each element being a string value. An undefined variable is
479 indistinguishable from a variable with an empty list, however,
480 a defined variable may have one more elements which are null
481 strings. All variables are referenced as $(<I>variable</I>).</P>
483 <P>Variables are either global or target-specific. In the latter
484 case, the variable takes on the given value only during the
485 target's binding, header file scanning, and updating; and during
486 the "on <I>target</I> <I>statement</I>" statement.</P>
488 <P>A variable is defined with:</P>
489 <P><TABLE WIDTH="75%" ALIGN="CENTER"><TR><TD><DL>
490 <DT><CODE><I>variable</I> = <I>elements</I> ;</CODE>
491 <DT><CODE><I>variable</I> += <I>elements</I> ;</CODE>
492 <DT><CODE><I>variable</I> -= <I>elements</I> ;</CODE>
493 <DT><CODE><I>variable</I> ?= <I>elements</I> ;</CODE>
494 <DT><CODE><I>variable</I> on <I>targets</I> = <I>elements</I> ;</CODE>
495 <DT><CODE><I>variable</I> on <I>targets</I> += <I>elements</I> ;</CODE>
496 <DT><CODE><I>variable</I> on <I>targets</I> -= <I>elements</I> ;</CODE>
497 <DT><CODE><I>variable</I> on <I>targets</I> ?= <I>elements</I> ;</CODE>
498 </DL></TD></TR></TABLE>
500 <P>The first three forms set <I>variable</I> globally. The last
501 three forms set a target-specific variable. The = operator
502 replaces any previous elements of <I>variable</I> with
503 <I>elements</I>; the += operation adds <I>elements</I> to
504 <I>variable</I>'s list of elements; the -= operation removes
505 <I>elements</I> from <I>variable</I>'s list of elements; the
506 ?= operator sets <I>variable</I> only if it was previously unset.
507 The last form "<I>variable</I> on <I>targets</I> ?= <I>elements</I>"
508 checks to see if the target-specific, not the global, variable is set.</P>
510 <P>Variables referenced in updating commands will be replaced with
511 their values; target-specific values take precedence over global
512 values. Variables passed as arguments ($(1) and $(2)) to actions
513 are replaced with their bound values; the "bind" modifier can
514 be used on actions to cause other variables to be replaced with
515 bound values. See <A HREF="#actionmods">Action Modifiers</A>
516 above.</P>
518 <P><B>Jam</b> variables are not re-exported to the environment of
519 the shell that executes the updating actions, but the updating
520 actions can reference <b>jam</b> variables with $(<I>variable</I>).</P>
522 <A NAME="varexp"></A>
523 <DT><P><H3>Variable Expansion</H3></P><DD>
524 <P>During parsing, <b>jam</b> performs variable expansion on each
525 token that is not a keyword or rule name. Such tokens with
526 embedded variable references are replaced with zero or more
527 tokens. Variable references are of the form $(<I>v</I>) or
528 $(<I>vm</I>), where <i>v</i> is the variable name, and <I>m</I>
529 are optional modifiers.</P>
531 <P>Variable expansion in a rule's actions is similar to variable
532 expansion in statements, except that the action string is
533 tokenized at whitespace regardless of quoting.</P>
535 <P>The result of a token after variable expansion is the
536 <i>product</i> of the components of the token, where each
537 component is a literal substring or a list substituting a variable
538 reference. For example:</P>
539 <P><TABLE WIDTH="75%" ALIGN="CENTER"><TR><TD><CODE>
540 <BR>$(X) -> a b c
541 <BR>t$(X) -> ta tb tc
542 <BR>$(X)z -> az bz cz
543 <BR>$(X)-$(X) -> a-a a-b a-c b-a b-b b-c c-a c-b c-c
544 </CODE></TD></TR></TABLE></P>
546 <P>The variable name and modifiers can themselves contain
547 a variable reference, and this partakes of the product
548 as well:</P>
549 <P><TABLE WIDTH="75%" ALIGN="CENTER"><TR><TD><CODE>
550 <BR>$(X) -> a b c
551 <BR>$(Y) -> 1 2
552 <BR>$(Z) -> X Y
553 <BR>$($(Z)) -> a b c 1 2
554 </CODE></TD></TR></TABLE></P>
556 <P>Because of this product expansion, if any variable reference in
557 a token is undefined, the result of the expansion is an empty
558 list. If any variable element is a null string, the result
559 propagates the non-null elements:</P>
560 <P><TABLE WIDTH="75%" ALIGN="CENTER"><TR><TD><CODE>
561 <BR>$(X) -> a ""
562 <BR>$(Y) -> "" 1
563 <BR>$(Z) ->
564 <BR>*$(X)$(Y)* -> *a* *a1* ** *1*
565 <BR>*$(X)$(Z)* ->
566 </CODE></TD></TR></TABLE></P>
568 <P>A variable element's string value can be parsed into grist and
569 filename-related components. Modifiers to a variable are used
570 to select elements, select components, and replace components.
571 The modifiers are:</P>
572 <P><TABLE WIDTH="75%" BORDER="1" ALIGN="CENTER">
573 <TR><TD><CODE>[<I>n</I>]</CODE></TR>
574 <TD>Select element number <I>n</I> (starting at 1).
575 If the variable contains fewer than <I>n</I> elements,
576 the result is a zero-element list.
577 </TD></TR>
578 <TR><TD><CODE>[<I>n</I>-<I>m</I>]</CODE></TD>
579 <TD>Select elements number <I>n</I> through <I>m</I>.</TD></TR>
580 <TR><TD><CODE>[<I>n</I>-]</CODE></TD>
581 <TD>Select elements number <I>n</I> through the last.</TD></TR>
582 <TR><TD><CODE>:B</CODE></TD><TD>Select filename base.</TD></TR>
583 <TR><TD><CODE>:S</CODE></TD><TD>Select (last) filename suffix.</TD></TR>
584 <TR><TD><CODE>:M</CODE></TD><TD>Select archive member name.</TD></TR>
585 <TR><TD><CODE>:D</CODE></TD><TD>Select directory path.</TD></TR>
586 <TR><TD><CODE>:P</CODE></TD><TD>Select parent directory.</TD></TR>
587 <TR><TD><CODE>:G</CODE></TD><TD>Select grist.</TD></TR>
588 <TR><TD><CODE>:U</CODE></TD><TD>Replace lowercase characters with uppercase.</TD></TR>
589 <TR><TD><CODE>:L</CODE></TD><TD>Replace uppercase characters with lowercase.</TD></TR>
590 <TR><TD><CODE>:Q</CODE></TD><TD>Quote special characters for safe shell execution.</TD></TR>
591 <TR><TD><CODE>:<i>chars</I></CODE></TD><TD>Select the components listed in <i>chars</i>.</TD></TR>
592 <TR><TD><CODE>:G=<I>grist</I></CODE></TD><TD>Replace grist with <I>grist</I>.</TD></TR>
593 <TR><TD><CODE>:D=<I>path</I></CODE></TD><TD>Replace directory with <I>path</I>.</TD></TR>
594 <TR><TD><CODE>:B=<I>base</I></CODE></TD><TD>Replace the base part of file name with <I>base</I>.</TD></TR>
595 <TR><TD><CODE>:S=<I>suf</I></CODE></TD><TD>Replace the suffix of file name with <I>suf</I>.</TD></TR>
596 <TR><TD><CODE>:M=<I>mem</I></CODE></TD><TD>Replace the archive member name with <I>mem</I>.</TD></TR>
597 <TR><TD><CODE>:R=<I>root</I></CODE></TD><TD>Prepend <I>root</I> to the whole file name, if not already rooted.</TD></TR>
598 <TR><TD><CODE>:E=<I>value</I></CODE></TD><TD>Use <I>value</I> instead if the variable is unset.</TD></TR>
599 <TR><TD><CODE>:J=<I>joinval</I></CODE></TD><TD>Concatentate list elements into single element, separated by <I>joinval</I>.</TD></TR>
600 </TABLE></P>
602 <P>on Unix and NT, $(var:P) and $(var:D) are the same.<BR/>
603 <b><u>TODO:</u></b> <i>make $(var:P) return parent dir on Unix and NT!</i>
604 </P>
607 <DT><P><H3>Built-in Rules</H3></P><DD>
608 <P><B>Jam</b> has twelve built-in rules, all of which are pure
609 procedure rules without updating actions. They are in
610 three groups: the first builds the dependency graph;
611 the second modifies it; and the third are just utility
612 rules.</P>
614 <P><H5>Dependency Building</H5></P>
615 <P><TABLE WIDTH="75%" ALIGN="CENTER"><TR><TD><DL>
616 <P><DT><CODE>Depends <I>targets1</I> : <I>targets2</I> ;</CODE>
617 <DD>Builds a direct dependency: makes each of <I>targets1</I>
618 depend on each of <I>targets2</I>. Generally, <I>targets1</I>
619 will be rebuilt if <I>targets2</I> are themselves rebuilt are
620 or are newer than <I>targets1</I>.</P>
621 <P><DT><CODE>Includes <I>targets1</I> : <I>targets2</I> ;</CODE>
622 <DD>Builds a sibling dependency: makes any target that depends
623 on any of <I>targets1</I> also depend on each of <I>targets2</I>.
624 This reflects the dependencies that arise when one source file
625 includes another: the object built from the source file depends
626 both on the original and included source file, but the two
627 sources files don't depend on each other. For example:
628 <CODE>
629 <P>Depends foo.o : foo.c ;
630 <BR>Includes foo.c : foo.h ;
631 </P></CODE></P>
632 <P>"foo.o" depends on "foo.c" and "foo.h" in this example.</P>
633 <P><DT><CODE>DependsList <I>targets</I> ;</CODE>
634 <DD>Returns list of dependencies for <I>targets</I>.</P>
635 </DL></TD></TR></TABLE></P>
637 <A NAME="bindingmods"></A>
638 <P><H5>Modifying Binding</H5></P>
639 <P>The six rules Always, Leaves, NoCare, ForceCare, NotFile, NoUpdate,
640 and Temporary modify the dependency graph so that <b>jam</b> treats
641 the targets differently during its target binding phase. See
642 <A HREF="#binding">Binding</A> above. Normally, <b>jam</b>
643 updates a target if it is missing, if its filesystem modification
644 time is older than any of its dependencies (recursively), or if
645 any of its dependencies are being updated. This basic behavior
646 can be changed by invoking the following rules:</P>
647 <P><TABLE WIDTH="75%" ALIGN="CENTER"><TR><TD><DL>
648 <P><DT><CODE>Always <I>targets</I> ;</CODE>
649 <DD>Causes <I>targets</I> to be rebuilt regardless of whether
650 they are up-to-date (they must still be in the dependency graph).
651 This is used for the clean and uninstall targets, as they have
652 no dependencies and would otherwise appear never to need building.
653 It is best applied to targets that are also NotFile targets,
654 but it can also be used to force a real file to be updated as
655 well.</P>
656 <P><DT><CODE>Leaves <I>targets</I> ;</CODE>
657 <DD> Makes each of <I>targets</I> depend only on its leaf sources,
658 and not on any intermediate targets. This makes it immune to
659 its dependencies being updated, as the "leaf" dependencies are
660 those without their own dependencies and without updating actions.
661 This allows a target to be updated only if original source files
662 change.</P>
663 <P><DT><CODE>NoCare <I>targets</I> ;</CODE>
664 <DD>Causes <b>jam</b> to ignore <I>targets</I> that neither
665 can be found nor have updating actions to build them. Normally
666 for such targets <B>jam</B> issues a warning and then skips
667 other targets that depend on these missing targets. The HdrRule
668 in Jambase uses NoCare on the header file names found during
669 header file scanning, to let <b>jam</b> know that the included
670 files may not exist. For example, if a #include is within an
671 #ifdef, the included file may not actually be around.</P>
672 <P><DT><CODE>ForceCare <I>targets</I> ;</CODE>
673 <DD>Causes <b>jam</b> to never ignore <I>targets</I>.<BR>
674 <B>TODO: document this!</B></P>
675 <P><DT><CODE>NotFile <I>targets</I> ;</CODE>
676 <DD>Marks <I>targets</I> as pseudotargets and not real files.
677 No timestamp is checked, and so the actions on such a target
678 are only executed if the target's dependencies are updated, or
679 if the target is also marked with Always. The default <b>jam</b>
680 target "all" is a pseudotarget. In Jambase, NotFile is used to
681 define several addition convenient pseudotargets.</P>
682 <P><DT><CODE>NoUpdate <I>targets</I> ;</CODE>
683 <DD>Causes the timestamps on <I>targets</I> to be ignored.
684 This has two effects: first, once the target has been created
685 it will never be updated; second, manually updating target will
686 not cause other targets to be updated. In Jambase, for example,
687 this rule is applied to directories by the MkDir rule, because
688 MkDir only cares that the target directory exists, not when it
689 has last been updated.</P>
690 <P><DT><CODE>Temporary <I>targets</I> ;</CODE>
691 <DD>Marks <I>targets</I> as temporary, allowing them to be
692 removed after other targets that depend upon them have been
693 updated. If a Temporary target is missing, <b>jam</b> uses the
694 timestamp of the target's parent. Jambase uses Temporary to
695 mark object files that are archived in a library after they are
696 built, so that they can be deleted after they are archived.</P>
697 </DL></TD></TR></TABLE></P>
699 <P><H5>Utility Rules</H5></P>
700 The remaining rules are utility rules.
701 <P><TABLE WIDTH="75%" ALIGN="CENTER"><TR><TD><DL>
702 <P><DT><CODE>
703 Echo <i>args</I> ; <br>
704 echo <i>args</I> ;
705 </CODE>
706 <DD>Blurts out the message <i>args</I> to stdout.</P>
707 <P><DT><CODE>
708 Exit <i>args</I> ; <br>
709 exit <i>args</I> ;
710 </CODE>
711 <DD>Blurts out the message <i>args</I> to stdout and then exits
712 with a failure status.</P>
713 <P><DT><CODE>
714 Glob <i>directories</I> : <I>patterns</I> [ : <i>flags</i> ] ;
715 </CODE>
716 <DD>Scans <i>directories</i> for files matching <i>patterns</i>,
717 returning the list of matching files (with directory prepended).
718 <i>patterns</i> uses the same syntax as in the <b>switch</b>
719 statement. Only useful within the <tt>[ ]</tt> construct, to
720 change the result into a list. Files with names "." and ".." will
721 be automatically ommited.<BR>
722 <i>flags:</i>
723 <UL>
724 <LI><i>ignore-case</i>, <i>case-insensitive</i></LI>
725 <LI><i>regexp</i>: use <b>egrep</b>-style regexps instead of shell-like patterns</LI>
726 <LI><i>glob</i>: use shell-like patterns instead of <b>egrep</b>-style regexps (default)</LI>
727 <LI><i>plain</i>: use str(i)cmp</LI>
728 <LI><i>any</i>: return both directories and files (default)</LI>
729 <LI><i>dirs-only</i>: return only directories</LI>
730 <LI><i>files-only</i>: return only files</LI>
731 <LI><i>names-only</i>: return only name part</LI>
732 <LI><i>full-path</i>: return full name (with dir) (default)</LI>
733 </UL></P>
734 <P><DT><CODE>
735 Match <i>regexps</I> : <I>list</I> [ : <i>flags</i> ] ;
736 </CODE>
737 <DD>Matches the <b>egrep</b>(1) style regular expressions
738 <I>regexps</I> against the strings in <I>list</I>. The result
739 is the concatenation of matching <tt>()</tt> subexpressions for
740 each string in <I>list</I>, and for each regular expression in
741 <I>regexps</I>. Only useful within the <tt>[ ]</tt> construct,
742 to change the result into a list.<BR>
743 <i>flags:</i>
744 <UL>
745 <LI><i>ignore-case</i>, <i>case-insensitive</i></LI>
746 <LI><i>regexp</i>: use <b>egrep</b>-style regexps instead of shell-like patterns (default)</LI>
747 <LI><i>glob</i>: use shell-like patterns instead of <b>egrep</b>-style regexps</LI>
748 </UL></P>
749 <P><DT><CODE>
750 Command <i>shellcmd</i> : <i>options</i> ;
751 </CODE>
752 <DD>Execute external command and return exit code and/or command output.
753 Only useful within the <tt>[ ]</tt> construct.
754 <P>possible "options" values (can be combined):</P>
755 <P><TABLE WIDTH="75%" BORDER="1" ALIGN="CENTER">
756 <TR><TD><CODE>exit-status, exit-code</CODE></TD>
757 <TD>Return exit code as the last list element (default: return as the first element).</TD></TR>
758 <TR><TD><CODE>no-output</CODE></TD>
759 <TD>Don't process and return command output (default: process).</TD></TR>
760 <TR><TD><CODE>no-trim</CODE></TD>
761 <TD>Don't trim command output (default: trim left and right).</TD></TR>
762 <TR><TD><CODE>no-trim-left</CODE></TD>
763 <TD>Don't left-trim command output (default: trim left and right).</TD></TR>
764 <TR><TD><CODE>no-trim-right</CODE></TD>
765 <TD>Don't right-trim command output (default: trim left and right).</TD></TR>
766 <TR><TD><CODE>status-first, code-first</CODE></TD>
767 <TD>Put exit code first (default: last)</TD></TR>
768 <TR><TD><CODE>parse-output</CODE></TD>
769 <TD>Parse output as list (break on chars witch codes 1..32) (default: don't break).</TD></TR>
770 <TR><TD><CODE>no-space-break</CODE></TD>
771 <TD>Don't break on spaces (' ') when 'parse-output' activated.</TD></TR>
772 <TR><TD><CODE>no-tab-break</CODE></TD>
773 <TD>Don't break on tabs ('\t') when 'parse-output' activated.</TD></TR>
774 <TR><TD><CODE>no-nl-break, no-lf-break</CODE></TD>
775 <TD>Don't break on LF ('\n') when 'parse-output' activated.</TD></TR>
776 <TR><TD><CODE>no-cr-break</CODE></TD>
777 <TD>Don't break on CR ('\r') when 'parse-output' activated.</TD></TR>
778 </TABLE></P>
779 </P>
780 <P><DT><CODE>
781 Sort <i>list</i> ;
782 </CODE>
783 <DD>Sort list alphabetically (ascending).
784 Only useful within the <tt>[ ]</tt> construct.
785 </P>
786 <P><DT><CODE>
787 Pwd ;
788 </CODE>
789 <DD>Return current working directory. Only useful within the <tt>[ ]</tt> construct.
790 </P>
791 <P><DT><CODE>
792 HaveRule <i>namelist</i> [ : <i>flags</i> ] ;<BR>
793 HaveActions <i>namelist</i> [ : <i>flags</i> ] ;
794 </CODE>
795 <DD>Checks if all specified rules/actions are defined.<BR>
796 <i>flags:</i>
797 <UL>
798 <LI><i>ignore-case</i>, <i>case-insensitive</i></LI>
799 <LI><i>regexp</i>: use <b>egrep</b>-style regexps instead of shell-like patterns</LI>
800 <LI><i>glob</i>: use shell-like patterns instead of <b>egrep</b>-style regexps</LI>
801 </UL></P>
802 <P><DT><CODE>
803 ExprI1 <i>num0</i> <i>op</i> <i>num1</i> ;
804 </CODE>
805 <DD>Integer math, understands 5 standard ops ('%' as C '%') and comparisons.</P>
806 <P><DT><CODE>
807 Split <i>string</i> : <i>delims</i> ;
808 </CODE>
809 <DD>Split <i>string</i> using set of <i>delims</i>. If no delimiters specified,
810 just split string to chars (explode)</P>
811 </DL>
812 <B>TODO: document others! see <I>doc/ChangeLog</I> file for more docs.</B>
813 </TD></TR></TABLE></P>
815 <DT><P><H3>Built-in Variables</H3></P><DD>
816 <P>This section discusses variables that have special meaning to <b>jam</b>.</P>
817 <A NAME="search"></A>
818 <P><H4>SEARCH and LOCATE Variables</H4></P>
819 <P>These two variables control the binding of file target names to
820 locations in the file system. Generally, $(SEARCH) is used to
821 find existing sources while $(LOCATE) is used to fix the location
822 for built targets.</P>
824 <P>Rooted (absolute path) file targets are bound as is. Unrooted
825 file target names are also normally bound as is, and thus relative
826 to the current directory, but the settings of $(LOCATE) and
827 $(SEARCH) alter this:</P>
829 <P><UL>
830 <LI>If $(LOCATE) is set then the target is bound relative to
831 the first directory in $(LOCATE). Only the first element is
832 used for binding.</LI>
833 <LI>If $(SEARCH) is set then the target is bound to the first
834 directory in $(SEARCH) where the target file already exists.</LI>
835 <LI>If the $(SEARCH) search fails, the target is bound relative
836 to the current directory anyhow.</LI>
837 </UL></P>
839 <P>Both $(SEARCH) and $(LOCATE) should be set target-specific and
840 not globally. If they were set globally, <b>jam</b> would use
841 the same paths for all file binding, which is not likely to
842 produce sane results. When writing your own rules, especially
843 ones not built upon those in Jambase, you may need to set
844 $(SEARCH) or $(LOCATE) directly. Almost all of the rules defined
845 in Jambase set $(SEARCH) and $(LOCATE) to sensible values for
846 sources they are looking for and targets they create, respectively.</P>
848 <A NAME="hdrscan"></A>
849 <P><H4>HDRSCAN and HDRRULE Variables</H4></P>
850 <P>These two variable control header file scanning. $(HDRSCAN) is
851 an <b>egrep</b>(1) pattern, with ()'s surrounding the file name,
852 used to find file inclusion statements in source files. Jambase
853 uses $(HDRPATTERN) as the pattern for $(HDRSCAN). $(HDRRULE)
854 is the name of a rule to invoke with the results of the scan:
855 the scanned file is the target, the found files are the sources.
856 $(HDRRULE) is run under the influence of the scanned file's
857 target-specific variables.</P>
859 <P>Both $(HDRSCAN) and $(HDRRULE) must be set for header file
860 scanning to take place, and they should be set target-specific
861 and not globally. If they were set globally, all files, including
862 executables and libraries, would be scanned for header file
863 include statements.</P>
865 <P>The scanning for header file inclusions is not exact, but it is
866 at least dynamic, so there is no need to run something like
867 <b>makedepend</b>(GNU) to create a static dependency file. The
868 scanning mechanism errs on the side of inclusion (i.e., it is
869 more likely to return filenames that are not actually used by
870 the compiler than to miss include files) because it can't tell
871 if #include lines are inside #ifdefs or other conditional logic.
872 In Jambase, HdrRule applies the NoCare rule to each header file
873 found during scanning so that if the file isn't present yet
874 doesn't cause the compilation to fail, <b>jam</b> won't care.</P>
876 <P>Also, scanning for regular expressions only works where the
877 included file name is literally in the source file. It can't
878 handle languages that allow including files using variable names
879 (as the Jam language itself does).</P>
881 <P><H4>Platform Identifier Variables</H4></P>
882 <P>A number of Jam built-in variables can be used to identify
883 runtime platform:</P>
884 <P><TABLE WIDTH="75%" ALIGN="CENTER">
885 <TR><TD>OS</TD><TD>OS identifier string</TD></TR>
886 <TR><TD>OSPLAT</TD><TD>Underlying architecture, when applicable</TD></TR>
887 <TR><TD>NT</TD><TD>true on NT platform</TD></TR>
888 <TR><TD>UNIX</TD><TD>true on Unix platforms</TD></TR>
889 </TABLE></P>
891 <P><H4>Jam Version Variables</H4></P>
892 <P><TABLE WIDTH="75%" ALIGN="CENTER">
893 <TR><TD>JAMDATE</TD><TD>Time and date at <b>jam</b> start-up.</TD></TR>
894 <TR><TD>JAMUNAME</TD><TD>Ouput of <b>uname</b>(1) command (Unix only)</TD></TR>
895 <TR><TD>JAMVERSION</TD><TD><b>jam</b> version, as reported by jam -v.</TD></TR>
896 <TR><TD>JAMBASEDATE</TD><TD><i>Obsolete:</i> <i>Jambase</i> date.</TD></TR>
897 <TR><TD>THIS_IS_K8JAM</TD><TD>Not empty if this is <b>K8Jam</b>.</TD></TR>
898 </TABLE></P>
900 <P><H4>JAMCMDARGS Variable</H4></P>
901 <P>A new builting variable has been defined. When K8Jam start, it defines
902 the variable JAMCMDARGS which contains the list of targets used on the
903 command line when Jam was invoked.</P>
905 <P>This is useful to provide richer control flow in the Jambase depending
906 on command line arguments.</P>
908 <P><H4>JAMSHELL Variable</H4></P>
909 <P>When <b>jam</b> executes a rule's action block, it forks and
910 execs a shell, passing the action block as an argument to the
911 shell. The invocation of the shell can be controlled by
912 $(JAMSHELL).The default on Unix is, for example:</P>
914 <P><CODE>JAMSHELL = /bin/sh -c % ;</CODE></P>
915 <P>The % is replaced with the text of the action block.</P>
917 <P><B>Jam</b> does not directly support building in parallel across
918 multiple hosts, since that is heavily dependent on the local
919 environment. To build in parallel across multiple hosts, you
920 need to write your own shell that provides access to the multiple
921 hosts. You then reset $(JAMSHELL) to reference it.</P>
923 <P>Just as <b>jam</b> expands a % to be the text of the rule's
924 action block, it expands a ! to be the multi-process slot number.
925 The slot number varies between 1 and the number of concurrent
926 jobs permitted by the -j flag given on the command line. Armed
927 with this, it is possible to write a multiple host shell. For
928 example:</P>
930 <P><TABLE WIDTH="75%" ALIGN="CENTER"><TR><TD><CODE>
931 <BR>#!/bin/sh
932 <BR>
933 <BR># This sample JAMSHELL uses the SunOS on(1) command to execute a
934 <BR># command string with an identical environment on another host.
935 <BR>
936 <BR># Set JAMSHELL = jamshell ! %
937 <BR>#
938 <BR># where jamshell is the name of this shell file.
939 <BR>#
940 <BR># This version handles up to -j6; after that they get executed
941 <BR># locally.
942 <BR>
943 <BR>case $1 in
944 <BR>1|4) on winken sh -c "$2";;
945 <BR>2|5) on blinken sh -c "$2";;
946 <BR>3|6) on nod sh -c "$2";;
947 <BR>*) eval "$2";;
948 <BR>esac
949 </CODE></TD></TR></TABLE></P>
952 <DT><P><H2>DIAGNOSTICS</H2></P><DD>
953 <P>In addition to generic error messages, <B>jam</B> may emit one of the following:</P>
954 <P><TABLE WIDTH="75%" ALIGN="CENTER"><TR><TD><DL>
955 <P><DT><CODE>warning: unknown rule X</CODE><DD>
956 A rule was invoked that has not been defined with an "actions" or "rule" statement.
957 <P><DT><CODE>using N temp target(s)</CODE><DD>
958 Targets marked as being temporary (but nonetheless present) have been found.
959 <P><DT><CODE>updating N target(s)</CODE><DD>
960 Targets are out-of-date and will be updated.
961 <P><DT><CODE>can't find N target(s)</CODE><DD>
962 Source files can't be found and there are no actions to create them.
963 <P><DT><CODE>can't make N target(s)</CODE><DD>
964 Due to sources not being found, other targets cannot be made.
965 <P><DT><CODE>warning: X depends on itself</CODE><DD>
966 A target depends on itself either directly or through its sources.
967 <P><DT><CODE>don't know how to make X</CODE><DD>
968 A target is not present and no actions have been defined to create it.
969 <P><DT><CODE>X skipped for lack of Y</CODE><DD>
970 A source failed to build, and thus a target cannot be built.
971 <P><DT><CODE>warning: using independent target X</CODE><DD>
972 A target that is not a dependency of any other target is being referenced with $(&lt;) or $(&gt;).
973 <P><DT><CODE>X removed</CODE><DD>
974 <b>Jam</b> removed a partially built target after being interrupted.
975 </DL></TD></TR></TABLE></P>
977 <DT><P><H2>BUGS, LIMITATIONS</H2></P><DD>
978 <P>The -j flag can cause <B>jam</B> to get confused when single
979 actions update more than one target at a time. <B>jam</B> may
980 proceed as if the targets were built even though they are still
981 under construction.</P>
983 <P>For parallel building to be successful, the dependencies among
984 files must be properly spelled out, as targets tend to get built
985 in a quickest-first ordering. Also, beware of un-parallelizable
986 commands that drop fixed-named files into the current directory,
987 like <b>yacc</b>(1) does.</P>
989 <P>With the -j flag, errors from failed commands can get staggeringly
990 mixed up.</P>
992 <P>A poorly set $(JAMSHELL) is likely to result in silent failure.</P>
994 <DT><P><H2>SEE ALSO</H2><DD>
995 <P><UL>
996 <LI><a href="Jambase.html">Jambase Reference</a></LI>
997 <LI><a href="Jamfile.html">Using Jamfiles and Jambase</a></LI>
998 </UL></P>
1000 <P>Jam documentation and source are available from the
1001 <A HREF="http://public.perforce.com/public/index.html">Perforce Public Depot</a>.</P>
1003 <DT><P><H2>AUTHOR</H2></P><DD>
1004 <P>Jam's author is Christopher Seiwald (<a href="mailto:seiwald@perforce.com">seiwald@perforce.com</A>).<BR/>
1005 Documentation is provided by <A HREF="http://www.perforce.com">Perforce Software, Inc.</A><BR/>
1006 "FT-Jam" is a simple derivative of the Jam build tool, based and 100% compatible with Jam 2.5.
1007 See <a href="http://www.freetype.org/jam/">http://www.freetype.org/jam/</a> for more details.<BR/>
1008 "K8Jam" is a derivative of FT-Jam.
1009 See <a href="https://github.com/ketmar/k8jam">GitHub repository</a> for the latest sources.
1010 Note that K8Jam is not 100% compatible with Perforce Jam or FT-Jam.
1011 </P>
1012 </DL>
1014 <P><HR>
1015 <P>Copyright 1993-2002 Christopher Seiwald and Perforce Software, Inc.<BR>
1016 Changes and additions by Ketmar // Vampire Avalon
1017 </P>
1018 </BODY>
1019 </HTML>