Jam.html

   1 <HTML>
   2
   3 <TITLE> Jam - Make(1) Redux </TITLE>
   4
   5 <BODY>
   6
   7 <CENTER>
   8
   9 <H1> Jam - Make(1) Redux </H1>
  10
  11 <P> The <a href=http://www.perforce.com/jam/jam.html>Jam</a> Executable
  12
  13 </CENTER>
  14
  15 <DL>
  16
  17 <DT> <P> <H2> USAGE </H2> <DD>
  18
  19 <PRE>
  20 jam [ -a ] [ -g ] [ -n ] [ -q ] [ -v ]
  21     [ -d <I>debug</I> ]
  22     [ -f <I>jambase</I> ]
  23     [ -j <I>jobs</I> ]
  24     [ -o <I>actionsfile</I> ]
  25     [ -s <I>var</I>=<I>value</I> ]
  26     [ -t <I>target</I> ]
  27     [ <I>target</I> ... ]
  28 </PRE>
  29
  30 <DT> <P> <H2> DESCRIPTION </H2> <DD>
  31
  32   <P>
  33
  34   <B>Jam</B> is a program construction tool, like <B>make</B>(1).
  35
  36   <P>
  37
  38   <B>Jam</B> recursively builds target files from source files,
  39   using dependency information and updating actions expressed in
  40   the Jambase file, which is written in <B>jam</B>'s own interpreted
  41   language.  The default Jambase is compiled into <B>jam</B> and
  42   provides a boilerplate for common use, relying on a user-provide
  43   file "Jamfile" to enumerate actual targets and sources.
  44
  45   <P>
  46
  47   The Jambase is described in the <a href="Jambase.html">Jambase
  48   Reference</a> and the document <a href="Jamfile.html">Using
  49   Jamfiles and Jambase</A>.
  50
  51 <DT> <P> <H2> OPTIONS </H2> <DD>
  52
  53   <P>
  54
  55   If <I>target</I> is provided on the command line, <B>jam</B>
  56   builds <I>target;</I> otherwise <B>jam</B> builds the target
  57   'all'.
  58
  59   <P>
  60
  61   <B>Jam</b> may be invoked with the following options:
  62
  63   <P> <TABLE WIDTH=85% ALIGN=CENTER BORDER=1 CELLPADDING=2>
  64
  65       <TR><TD VALIGN=TOP WIDTH=20%><CODE> -a </CODE>
  66       <TD> Build all targets anyway, even if they are up-to-date.
  67
  68       <TR><TD VALIGN=TOP><CODE> -d <I>c</I>  </CODE>
  69       <TD> Turn on display option <I>c</I> and off the default
  70       display (summary info and actions):
  71
  72       <DL COMPACT>
  73       <DT> a <DD> Show summary info, actions, quiet actions, and the
  74       use of temporary targets
  75       <DT> c <DD> Show the names of files that cause rebuilds, i.e.
  76       new sources, missing targets, etc.
  77       <DT> d <DD> Display a dependency graph (in <B>jam</B> syntax).
  78       <DT> m <DD> Display the dependency analysis, and target/source
  79             timestamps and paths
  80       <DT> x <DD> Show shell arguments
  81       </DL>
  82
  83       <TR><TD VALIGN=TOP><CODE> -d <I>n</I>  </CODE>
  84       <TD> Enable cummulative debugging levels from 1 to <I>n</I>.
  85       Interesting values are:
  86
  87       <DL COMPACT>
  88       <DT> 1 <DD> Show actions and summary info (the default)
  89       <DT> 3 <DD> Old name for -dm (described above)
  90       <DT> 5 <DD> Show rule invocations and variable expansions
  91       <DT> 6 <DD> Show directory/header file/archive scans
  92       <DT> 7 <DD> Show variable settings
  93       <DT> 8 <DD> Show variable fetches
  94       <DT> 9 <DD> Show variable manipulation, scanner tokens
  95       </DL>
  96
  97       <TR><TD VALIGN=TOP><CODE> -d +<I>n</I> </CODE>
  98       <TD> Enable debugging level <I>n</I>.
  99
 100       <TR><TD VALIGN=TOP><CODE> -d 0 </CODE>
 101       <TD> Turn off all debugging levels.  Only errors are emitted.
 102
 103       <TR><TD VALIGN=TOP><CODE> -f <I>jambase</I></CODE>
 104       <TD>Read <I>jambase</I> instead of using the built-in Jambase.
 105       Multiple -f flags are permitted.
 106
 107       <TR><TD VALIGN=TOP><CODE> -g </CODE>
 108       <TD> Build targets with the newest sources first, rather than
 109       in the order of appearance in the Jambase/Jamfiles.
 110
 111       <TR><TD VALIGN=TOP><CODE> -j <I>n</I></CODE>
 112       <TD> Run up to <I>n</I> shell commands concurrently (UNIX
 113       and NT only).  The default is 1.
 114
 115       <TR><TD VALIGN=TOP><CODE> -n</CODE>
 116       <TD> Don't actually execute the updating actions, but do
 117       everything else.  This changes the debug level to -dax.
 118
 119       <TR><TD VALIGN=TOP><CODE> -o <I>file</I></CODE>
 120       <TD> Write the updating actions to the specified file instead
 121       of running them (or outputting them, as on the Mac).
 122
 123       <TR><TD VALIGN=TOP><CODE> -q </CODE>
 124       <TD> Quit quickly (as if an interrupt was received)
 125       as soon as any target build fails.
 126
 127       <TR><TD VALIGN=TOP><CODE> -s <I>var</I>=<I>value</I></CODE>
 128       <TD> Set the variable <I>var</I> to <I>value</I>, overriding
 129       both internal variables and variables imported from the
 130       environment.
 131
 132       <TR><TD VALIGN=TOP><CODE> -t <I>target</I></CODE>
 133       <TD> Rebuild <I>target</I> and everything that depends on it,
 134        even if it is up-to-date.
 135
 136       <TR><TD VALIGN=TOP><CODE> -v</CODE>
 137       <TD> Print the version of <B>jam</B> and exit.
 138
 139   </TABLE>
 140
 141 <DT> <P> <H2> OPERATION </H2> <DD>
 142
 143   <P>
 144
 145   <b>Jam</b> has four phases of operation: start-up, parsing,
 146   binding, and updating.
 147
 148 <DT> <P> <H3> Start-up </H3> <DD>
 149
 150   <P>
 151
 152   Upon start-up, <b>jam</b> imports environment variable settings
 153   into <b>jam</b> variables.  Environment variables are split at
 154   blanks with each word becoming an element in the variable's list
 155   of values.  Environment variables whose names end in PATH are
 156   split at $(SPLITPATH) characters (e.g., ":" for Unix).
 157
 158   <P>
 159
 160   To set a variable's value on the command line, overriding the
 161   variable's environment value, use the -s option.  To see variable
 162   assignments made during <b>jam</b>'s execution, use the -d+7
 163   option.
 164
 165 <DT> <P> <H3> Parsing </H3> <DD>
 166
 167   <P>
 168
 169   In the parsing phase, <b>jam</b> reads and executes the Jambase
 170   file, by default the built-in one.  It is written in the <b>jam</b>
 171   language.  See <a href="#language"> Language</a> below.  The
 172   last action of the Jambase is to read (via the "include" rule)
 173   a user-provided file called "Jamfile".
 174
 175   <P>
 176
 177   Collectively, the purpose of the Jambase and the Jamfile is to
 178   name built target and source files, construct the dependency
 179   graph among them, and associate build actions with targets.
 180   The Jambase defines boilerplate rules and variable assignments,
 181   and the Jamfile uses these to specify the actual relationship
 182   among the target and source files.  See the <a
 183   href="Jambase.html">Jambase Reference</a> and the document <a
 184   href="Jamfile.html">Using Jamfiles and Jambase</A> for information.
 185
 186 <A NAME="binding">
 187 <DT> <P> <H3> Binding </H3> <DD>
 188 </A>
 189
 190   <P> <H5> Binding </H5>
 191
 192   After parsing, <B>jam</B> recursively descends the dependency
 193   graph and binds every file target with a location in the
 194   filesystem.
 195
 196   <P> <H5> Targets </H5> <DD>
 197
 198   Any string value in <b>jam</b> can represent a target, and it
 199   does so if the DEPENDS or INCLUDES rules make it part of the
 200   dependency graph.  Build targets are files to be updated.  Source
 201   targets are the files used in updating build targets.  Build
 202   targets and source targets are collectively referred to as file
 203   targets, and frequently build targets are source targets for
 204   other build targets.  Pseudotargets are symbols which represent
 205   dependencies on other targets, but which are not themselves
 206   associated with any real file.
 207
 208   <P>
 209
 210   A file target's identifier is generally the file's name, which can
 211   be absolutely rooted, relative to the directory of <b>jam</b>'s
 212   invocation, or simply local (no directory).  Most often it is the
 213   last case, and the actual file path is bound using the $(SEARCH)
 214   and $(LOCATE) special variables.  See <A HREF="#search"> SEARCH
 215   and LOCATE Variables</A> below.  A local filename is optionally
 216   qualified with "grist," a string value used to assure uniqueness.
 217   A file target with an identifier of the form <I>file(member)</I>
 218   is a library member (usually an ar(1) archive on UNIX).
 219
 220   <P>
 221
 222   The use of $(SEARCH) and $(LOCATE) allows <b>jam</b> to separate
 223   the the location of files from their names, so that Jamfiles can
 224   refer to files locally (i.e. relative to the Jamfile's directory),
 225   yet still be usable when <b>jam</b> is invoked from a distant
 226   directory.  The use of grist allows files with the same name
 227   to be identified uniquely, so that <b>jam</b> can read a whole
 228   directory tree of Jamfiles and not mix up same-named targets.
 229
 230   <P> <H5> Update Determination </H5>
 231
 232   After binding each target, <B>jam</B> determines whether the
 233   target needs updating, and if so marks the target for the updating
 234   phase.  A target is normally so marked if it is missing, it is
 235   older than any of its sources, or any of its sources are marked
 236   for updating.  This behavior can be modified by the application
 237   of special built-in rules.  See <A HREF="#bindingmods">Modifying
 238   Binding</A> below.
 239
 240   <P> <H5> Header File Scanning </H5>
 241
 242   During the binding phase, <b>jam</b> also performs header file
 243   scanning, where it looks inside source files for the implicit
 244   dependencies on other files caused by C's #include syntax.  This
 245   is controlled by the special variables $(HDRSCAN) and $(HDRRULE).
 246   The result of the scan is formed into a rule invocation, with
 247   the scanned file as the target and the found included file names
 248   as the sources.  Note that this is the only case where rules
 249   are invoked outside the parsing phase.  See <A
 250   HREF="#hdrscan">HDRSCAN and HDRRULE Variables</A> below.
 251
 252 <DT> <P> <H3> Updating </H3> <DD>
 253
 254   <P>
 255
 256   After binding, <B>jam</B> again recursively descends the dependency
 257   graph,  this time executing the update actions for each target
 258   marked for update during the binding phase.  If a  target's
 259   updating actions fail, then all other targets which depend on
 260   that target are skipped.
 261
 262   <P>
 263
 264   The -j flag instructs <B>jam</B> to build more than one target
 265   at a time.  If there are multiple actions on a single target,
 266   they are run sequentially.   The -g flag reorders builds so that
 267   targets with newest sources are built first.  Normally, they are
 268   built in the order of appearance in the Jamfiles.
 269
 270 <A NAME="language">
 271 <DT> <P> <H2> LANGUAGE </H2> <DD>
 272 </A>
 273
 274 <DT> <P> <H3> Overview </H3> <DD>
 275
 276   <B>Jam</b> has a interpreted, procedural language with a few
 277   select features to effect program construction.  Statements in
 278   <b>jam</b> are rule (procedure) definitions, rule invocations,
 279   updating action definitions, flow-of-control structures, variable
 280   assignments, and sundry language support.
 281
 282 <DT> <P> <H3> Lexical Features </H3> <DD>
 283
 284   <P>
 285
 286   <B>Jam</b> treats its input files as whitespace-separated tokens,
 287   with two exceptions: double quotes (") can enclose whitespace to
 288   embed it into a token, and everything between the matching curly
 289   braces ({}) in the definition of a updating actions is treated
 290   as a single string.  A backslash (\) can escape a double quote,
 291   or any single whitespace character.
 292
 293   <P>
 294
 295   <B>Jam</b> requires whitespace (blanks, tabs, or newlines) to
 296   surround all tokens, <b>including the colon (:) and semicolon
 297   (;) tokens</b>.
 298
 299   <P>
 300
 301   <B>Jam</b> keywords (as mentioned in this document) are reserved
 302   and generally must be quoted with double quotes (") to be used
 303   as arbitrary tokens, such as variable or target names.
 304
 305 <DT> <P> <H3> Datatype </H3> <DD>
 306
 307   <P>
 308
 309   <B>Jam</B>'s only data type is a one-dimensional list of arbitrary
 310   strings.  They arise as literal (whitespace-separated) tokens in
 311   the Jambase or included files, as the result of variable expansion
 312   of those tokens, or as the return value from a rule invocation.
 313
 314 <DT> <P> <H3> Rules </H3> <DD>
 315
 316   <P>
 317
 318   The basic <B>jam</b> language entity is called a rule.  A rule
 319   is simply a procedure definition, with a body of <b>jam</b>
 320   statements to be run when the rule is invoked.  The syntax of
 321   rule invocation make it possible to write Jamfiles that look
 322   a bit like Makefiles.
 323
 324   <P>
 325
 326   Rules take up to 9 arguments ($(1) through $(9), each a list)
 327   and can have a return value (a single list).  A rule's return
 328   value can be expanded in a list by enclosing the rule invocation
 329   with <tt>[</tt> and <tt>]</tt>.
 330
 331 <DT> <P> <H3> Updating Actions </H3> <DD>
 332
 333   <P>
 334
 335   A rule may have updating actions associated with it, in which
 336   case arguments $(1) and $(2) are treated as built targets and
 337   sources, respectively.  Updating actions are the OS shell commands
 338   to execute when updating the built targets of the rule.
 339
 340   <P>
 341
 342   When an rule with updating actions is invoked, those actions are
 343   added to those associated with its built targets ($(1)) before
 344   the rule's procedure is run.  Later, to build the targets in the
 345   updating phase, the actions are passed to the OS command shell,
 346   with $(1) and $(2) replaced by bound versions of the target names.
 347   See <A HREF="#binding"> Binding</A> above.
 348
 349
 350 <DT> <P> <H3> Statements </H3> <DD>
 351
 352   <P>
 353
 354   <b>Jam</b>'s langauge has the following statements:
 355
 356   <P><TABLE WIDTH=75% ALIGN=CENTER><TR><TD><DL>
 357
 358       <P> <DT> <CODE>
 359
 360     <I>rulename field1</I> : <I>field2</I> : <I>...</I>
 361       : <I>fieldN</I> ;
 362
 363       </CODE>
 364
 365       <P><DD> Invoke a rule.  A rule is invoked with values in
 366       <I>field1</I> through <I>fieldN</I> (9 max).  They may be
 367       referenced in the procedure's <I>statements</I> as $(1)
 368       through $(<9>N</I>).  $(&lt;) and $(&gt;) are synonymous
 369       with $(1) and $(2).
 370
 371   <P>
 372       <i>rulename</i> undergoes <A HREF="#varexp"> variable
 373       expansion</A>.  If the resulting list is more than one value,
 374       each rule is invoked with the same arguments, and the result
 375       of the invocation is the concatenation of all the results.
 376
 377       <P> <DT> <CODE>
 378
 379     actions [ <I>modifiers</I> ] <I>rulename</I> { <I>commands</I> }
 380
 381   </CODE>
 382
 383       <P><DD> Define a rule's updating actions, replacing any previous
 384       definition.  The first two arguments may be referenced in
 385       the action's <I>commands</I> as $(1) and $(2) or $(&lt;)
 386       and $(&gt;).
 387
 388   <P>
 389
 390       The following action <i>modifiers</i> are understood:
 391
 392       <P><TABLE BORDER=1>
 393
 394     <TR><TD WIDTH=30%><CODE> actions bind <I>vars</I> </CODE></TD>
 395     <TD> $(vars) will be replaced with bound values.</TD>
 396     </TR>
 397
 398     <TR><TD><CODE> actions existing </CODE></TD>
 399     <TD> $(>) includes only source targets currently existing.</TD>
 400     </TR>
 401
 402     <TR><TD><CODE> actions ignore </CODE></TD>
 403     <TD> The return status of the <I>commands</I> is ignored.</TD>
 404     </TR>
 405
 406     <TR><TD><CODE> actions piecemeal </CODE></TD>
 407     <TD> <I>commands</I>  are repeatedly invoked with a subset
 408     of $(>) small enough to fit in the command buffer on this
 409     OS.</TD>
 410     </TR>
 411
 412     <TR><TD><CODE> actions quietly </CODE></TD>
 413     <TD> The action is not echoed to the standard output.</TD>
 414     </TR>
 415
 416     <TR><TD><CODE> actions together </CODE></TD>
 417     <TD> The $(>) from multiple invocations of the same action
 418     on the same built target are glommed together.</TD>
 419     </TR>
 420
 421     <TR><TD><CODE> actions updated </CODE></TD>
 422     <TD> $(>) includes only source targets themselves marked
 423     for updating.</TD>
 424     </TR>
 425
 426       </TABLE>
 427
 428   <P><DT><CODE>
 429
 430     break
 431
 432   </CODE>
 433
 434       <P><DD> Breaks out of the closest enclosing <I>for</I>
 435       or <I>while</I> loop.
 436
 437   <P><DT><CODE>
 438
 439     continue
 440
 441   </CODE>
 442
 443       <P><DD> Jumps to the end of the closest enclosing <I>for</I>
 444       or <I>while</I> loop.
 445
 446       <P><DT><CODE>
 447
 448     for <I>var</I> in <I>list</I> { <I>statements</I> }
 449
 450       </CODE>
 451
 452       <P><DD> Executes <i>statements</i> for each element in
 453       <i>list</i>, setting the variable <i>var</i> to the element
 454       value.
 455
 456       <A name=if>
 457       <P><DT><CODE>
 458       </A>
 459
 460     if <I>cond</I> { <I>statements</I> } [ else <I>statement</I> ]
 461
 462       </CODE>
 463
 464       <P><DD> Does the obvious;  the else clause is optional.
 465       <i>cond</i> is built of:
 466
 467       <TABLE BORDER=1>
 468
 469     <TR><TD WIDTH=25%> <CODE><I>a</I></CODE></TD>
 470     <TD> true if any <I>a</I> element is a non-zero-length
 471     string</TD>
 472     <TR><TD> <CODE><I>a</I> = <I>b</I></CODE> </TD>
 473     <TD> list <I>a</I> matches list <I>b</I>
 474     string-for-string</TD>
 475     <TR><TD> <CODE><I>a</I> != <I>b</I> </CODE></TD>
 476     <TD> list <I>a</I> does not match list <I>b</I></TD>
 477     <TR><TD> <CODE><I>a</I> &lt; <I>b</I> </CODE></TD>
 478     <TD> <I>a[i]</I> string is less than <I>b[i]</I>
 479     string, where <i>i</i> is first mismatched element
 480     in lists <I>a</I> and <I>b</I></TD>
 481     <TR><TD> <CODE><I>a</I> &lt;= <I>b</I> </CODE></TD>
 482     <TD> every <I>a</I> string is less than or equal to
 483     its <I>b</I> counterpart</TD>
 484     <TR><TD> <CODE><I>a</I> &gt; <I>b</I> </CODE></TD>
 485     <TD> <I>a[i]</I> string is greater than <I>b[i]</I>
 486     string, where <i>i</i> is first mismatched element</TD>
 487     <TR><TD> <CODE><I>a</I> &gt;= <I>b</I> </CODE></TD>
 488     <TD> every <I>a</I> string is greater than or equal to
 489     its <I>b</I> counterpart</TD>
 490     <TR><TD> <CODE><I>a</I> in <I>b</I> </CODE></TD>
 491     <TD> true if all elements of <I>a</I> can be found
 492     in <I>b</I>, or if <I>a</I> has no elements</TD>
 493     <TR><TD> <CODE>! <I>cond</I> </CODE></TD>
 494     <TD> condition not true</TD>
 495     <TR><TD> <CODE><I>cond</I> && <I>cond</I> </CODE></TD>
 496     <TD> conjunction</TD>
 497     <TR><TD> <CODE><I>cond</I> || <I>cond</I> </CODE></TD>
 498     <TD> disjunction</TD>
 499     <TR><TD> <CODE>( <I>cond</I> ) </CODE></TD>
 500     <TD> precedence grouping</TD>
 501
 502       </TABLE>
 503
 504       <P><DT> <CODE>
 505
 506     include <I>file</I> ;
 507
 508       </CODE>
 509
 510       <P><DD> Causes <b>jam</b> to read the named <i>file</i>.
 511       The file is bound like a regular target (see <A
 512       HREF="#binding"> Binding</A> above) but unlike a regular
 513       target the include file cannot be built.  Marking an include
 514       file target with the <b>NOCARE</b> rule makes it optional:
 515       if it is missing, it causes no error.
 516
 517       <P>
 518
 519       The include file is inserted into the input stream during
 520       the parsing phase. The primary input file and all the included
 521       file(s) are treated as a single file; that is, <b>jam</b>
 522       infers no scope boundaries from included files.
 523
 524       <P><DT> <CODE>
 525
 526     local <i>vars</I> [ = <i>values</i> ] ;
 527
 528       </CODE>
 529
 530       <P><DD> Creates new <i>vars</i> inside to the enclosing {}
 531       block, obscuring any previous values they might have.  The
 532       previous values for <i>vars</i> are restored when the current
 533       block ends.  Any rule called or file included will see the
 534       local and not the previous value (this is sometimes called
 535       Dynamic Scoping).  The local statement may appear anywhere,
 536       even outside of a block (in which case the previous value
 537       is restored when the input ends).  The <i>vars</i> are
 538       initialized to <i>values</i> if present, or left uninitialized
 539       otherwise.
 540
 541       <P> <DT> <CODE>
 542
 543     on <I>target</I> <I>statement</I> ;
 544
 545       </CODE>
 546
 547       <P><DD> Run <I>statement</I> under the influence of
 548       <I>target</I>'s target-specific variables.  These variables
 549       become local copies during <I>statement</I>'s run, but they
 550       may be updated as target-specific variables using the usual
 551       "<I>variable</I> on <I>targets</I> =" syntax.
 552
 553
 554       <P><DT> <CODE>
 555
 556     return <I>values</I> ;
 557
 558       </CODE>
 559
 560       <P><DD> Within a rule body, the return statement sets the return
 561       value for an invocation of the rule and terminates the rule's
 562       execution.
 563
 564       <P> <DT> <CODE>
 565
 566     rule <I>rulename</I> [ : <I>vars</I> ] { <I>statements</I> }
 567
 568       </CODE>
 569
 570       <P><DD> Define a rule's procedure, replacing any previous
 571       definition.  If <I>vars</I> are provided, they are assigned
 572       the values of the parameters ($(1) to $(9)) when <I>statements</I>
 573       are executed, as with the <B>local</B> statement.
 574
 575       <P><DT> <CODE>
 576
 577     <A NAME="switch">
 578     switch <I>value</I>
 579     </A>
 580     <BR> {
 581     <BR> case <I>pattern1</I> : <I>statements</I> ;
 582     <BR> case <I>pattern2</I> : <I>statements</I> ;
 583     <BR> ...
 584     <BR> }
 585
 586       </CODE>
 587
 588       <P><DD> The switch statement executes zero or one of the
 589       enclosed <i>statements</i>, depending on which, if any, is
 590       the first case whose <i>pattern</I> matches <i>value</i>.
 591       The <i>pattern</I> values are not variable-expanded.  The
 592       <i>pattern</I>  values may include the following wildcards:
 593
 594       <TABLE>
 595
 596     <TR><TD><CODE> ? </CODE></TD>
 597     <TD> match any single character </TD>
 598     <TR><TD><CODE> * </CODE></TD>
 599     <TD> match zero or more characters </TD>
 600     <TR><TD><CODE> [<i>chars</i>] </CODE></TD>
 601     <TD> match any single character in <i>chars</i> </TD>
 602     <TR><TD><CODE> [^<i>chars</i>] </CODE></TD>
 603     <TD> match any single character not in <i>chars</i> </TD>
 604     <TR><TD><CODE> \<i>x</i> </CODE></TD>
 605     <TD> match <i>x</i> (escapes the other wildcards)</i> </TD>
 606
 607       </TABLE>
 608
 609       <P><DT> <CODE>
 610
 611     while <I>cond</I> { <I>statements</I> }
 612
 613       </CODE>
 614
 615       <P><DD> Repeatedly execute <I>statements</I> while <I>cond</I>
 616       remains true upon entry. (See the description of <I>cond</I>
 617       expression syntax under <a href="#if">if</a>, above).
 618   </DL></TABLE>
 619
 620
 621 <DT> <P> <H3> Variables </H3> <DD>
 622
 623   <P>
 624
 625   <B>Jam</b> variables are lists of zero or more elements, with
 626   each element being a string value.  An undefined variable is
 627   indistinguishable from a variable with an empty list, however,
 628   a defined variable may have one more elements which are null
 629   strings.  All variables are referenced as $(<I>variable</I>).
 630
 631   <P>
 632
 633   Variables are either global or target-specific.  In the latter
 634   case, the variable takes on the given value only during the
 635   target's binding, header file scanning, and updating; and during
 636   the "on <I>target</I> <I>statement</I>" statement.
 637
 638   <P>
 639
 640   A variable is defined with:
 641
 642   <P> <TABLE WIDTH=75% ALIGN=CENTER> <TR><TD> <DL>
 643
 644       <DT><CODE>
 645       <I>variable</I> = <I>elements</I> ; </CODE>
 646       <DT><CODE>
 647       <I>variable</I> += <I>elements</I> ; </CODE>
 648       <DT><CODE>
 649       <I>variable</I> ?= <I>elements</I> ; </CODE>
 650       <DT><CODE>
 651       <I>variable</I> on <I>targets</I> = <I>elements</I> ; </CODE>
 652       <DT><CODE>
 653       <I>variable</I> on <I>targets</I> += <I>elements</I> ; </CODE>
 654       <DT><CODE>
 655       <I>variable</I> on <I>targets</I> ?= <I>elements</I> ; </CODE>
 656
 657   </DL></TABLE>
 658
 659   <P>
 660
 661   The first three forms set <I>variable</I> globally.  The last
 662   three forms set a target-specific variable.  The = operator
 663   replaces any previous elements of <I>variable</I> with
 664   <I>elements</I>; the += operation adds <I>elements</I> to
 665   <I>variable</I>'s list of elements; the ?= operator sets
 666   <I>variable</I> only if it was previously unset.  The last form
 667   "<I>variable</I> on <I>targets</I> ?= <I>elements</I>" checks
 668   to see if the target-specific, not the global, variable is set.
 669   (The ?= operator also has an old form "default =".)
 670
 671   <P>
 672
 673   Variables referenced in updating commands will be replaced with
 674   their values; target-specific values take precedence over global
 675   values.  Variables passed as arguments ($(1) and $(2)) to actions
 676   are replaced with their bound values; the "bind" modifier can
 677   be used on actions to cause other variables to be replaced with
 678   bound values.  See <A HREF="#actionmods">Action Modifiers</A>
 679   above.
 680
 681   <P>
 682
 683   <B>Jam</b> variables are not re-exported to the environment of
 684   the shell that executes the updating actions, but the updating
 685   actions can reference <b>jam</b> variables with $(<I>variable</I>).
 686
 687 <A NAME="varexp">
 688 <DT> <P> <H3> Variable Expansion </H3> <DD>
 689 </A>
 690
 691   <P>
 692
 693   During parsing, <b>jam</b> performs variable expansion on each
 694   token that is not a keyword or rule name.  Such tokens with
 695   embedded variable references are replaced with zero or more
 696   tokens.  Variable references are of the form $(<I>v</I>) or
 697   $(<I>vm</I>), where <i>v</i> is the variable name,  and  <I>m</I>
 698   are optional modifiers.
 699
 700   <P>
 701
 702   Variable expansion in a rule's actions is similar to variable
 703   expansion in statements,  except that the action string is
 704   tokenized at whitespace regardless of quoting.
 705
 706   <P>
 707
 708   The result of a token after variable expansion is the
 709   <i>product</i> of the components of the token, where each
 710   component is a literal substring or a list substituting a variable
 711   reference.  For example:
 712
 713   <P> <TABLE WIDTH=75% ALIGN=CENTER><TR><TD><CODE>
 714
 715       <BR>$(X)      -> a b c
 716       <BR>t$(X)     -> ta tb tc
 717       <BR>$(X)z     -> az bz cz
 718       <BR>$(X)-$(X) -> a-a a-b a-c b-a b-b b-c c-a c-b c-c
 719
 720   </CODE></TABLE>
 721
 722   <P>
 723
 724   The variable name and modifiers can themselves contain
 725   a variable reference,  and this partakes of the product
 726   as well:
 727
 728   <P> <TABLE WIDTH=75% ALIGN=CENTER><TR><TD><CODE>
 729
 730       <BR>$(X)      -> a b c
 731       <BR>$(Y)      -> 1 2
 732       <BR>$(Z)      -> X Y
 733       <BR>$($(Z))   -> a b c 1 2
 734
 735   </CODE></TABLE>
 736
 737   <P>
 738
 739   Because of this product expansion, if any variable reference in
 740   a token is undefined, the result of the expansion is an empty
 741   list.  If any variable element is a null string, the result
 742   propagates the non-null elements:
 743
 744   <P> <TABLE WIDTH=75% ALIGN=CENTER><TR><TD><CODE>
 745
 746       <BR>$(X)        -> a ""
 747       <BR>$(Y)        -> "" 1
 748       <BR>$(Z)    ->
 749       <BR>*$(X)$(Y)*  -> *a* *a1* ** *1*
 750       <BR>*$(X)$(Z)*  ->
 751
 752   </CODE></TABLE>
 753
 754   <P>
 755
 756   A variable element's string value can be parsed into grist and
 757   filename-related components.  Modifiers to a variable are used
 758   to select elements, select components, and replace components.
 759   The modifiers are:
 760
 761   <P> <TABLE WIDTH=75% BORDER=1 ALIGN=CENTER>
 762
 763       <TR><TD><CODE> [<I>n</I>] </CODE>
 764       <TD>Select element number <I>n</I> (starting at 1).  If
 765       the variable contains fewer than <I>n</I> elements,
 766       the result is a zero-element list.
 767
 768       <TR><TD><CODE> [<I>n</I>-<I>m</I>] </CODE>
 769       <TD>Select elements number <I>n</I> through <I>m</I>.
 770
 771       <TR><TD><CODE> [<I>n</I>-] </CODE>
 772       <TD>Select elements number <I>n</I> through the last.
 773
 774       <TR><TD><CODE> :B </CODE>
 775       <TD>Select filename base.
 776
 777       <TR><TD><CODE> :S </CODE>
 778       <TD>Select (last) filename suffix.
 779
 780       <TR><TD><CODE> :M </CODE>
 781       <TD>Select archive member name.
 782
 783       <TR><TD><CODE> :D </CODE>
 784       <TD>Select directory path.
 785
 786       <TR><TD><CODE> :P </CODE>
 787       <TD>Select parent directory.
 788
 789       <TR><TD><CODE> :G </CODE>
 790       <TD>Select grist.
 791
 792       <TR><TD><CODE> :U </CODE>
 793       <TD>Replace lowercase characters with uppercase.
 794
 795       <TR><TD><CODE> :L </CODE>
 796       <TD>Replace uppercase characters with lowercase.
 797
 798       <TR><TD><CODE> :<i>chars</I> </CODE>
 799       <TD>Select the components listed in <i>chars</i>.
 800
 801       <TR><TD><CODE> :G=<I>grist</I> </CODE>
 802       <TD>Replace grist with <I>grist</I>.
 803
 804       <TR><TD><CODE> :D=<I>path</I> </CODE>
 805       <TD>Replace directory with <I>path</I>.
 806
 807       <TR><TD><CODE> :B=<I>base</I> </CODE>
 808       <TD>Replace the base part of file name with <I>base</I>.
 809
 810       <TR><TD><CODE> :S=<I>suf</I> </CODE>
 811       <TD>Replace the suffix of file name with <I>suf</I>.
 812
 813       <TR><TD><CODE> :M=<I>mem</I> </CODE>
 814       <TD>Replace the archive member name with <I>mem</I>.
 815
 816       <TR><TD><CODE> :R=<I>root</I> </CODE>
 817       <TD>Prepend <I>root</I> to the whole file name,  if not
 818       already rooted.
 819
 820       <TR><TD><CODE> :E=<I>value</I> </CODE>
 821       <TD>Use <I>value</I> instead if the variable is unset.
 822
 823       <TR><TD><CODE> :J=<I>joinval</I> </CODE>
 824       <TD>Concatentate list elements into single
 825             element, separated by <I>joinval</I>.
 826
 827   </TABLE>
 828
 829   <P>
 830
 831   On VMS, $(var:P) is the parent directory of $(var:D); on Unix
 832   and NT, $(var:P) and $(var:D) are the same.
 833
 834
 835 <DT> <P> <H3> Built-in Rules </H3> <DD>
 836
 837   <P>
 838   <B>Jam</b> has twelve built-in rules, all of which are pure
 839   procedure rules without updating actions.  They are in
 840   three groups:  the first builds the dependency graph;
 841   the second modifies it; and the third are just utility
 842   rules.
 843
 844   <P> <H5> Dependency Building </H5>
 845
 846   <P><TABLE WIDTH=75% ALIGN=CENTER><TR><TD><DL>
 847
 848   <P><DT><CODE>
 849   DEPENDS <I>targets1</I> : <I>targets2</I> ;
 850   </CODE>
 851
 852   <DD> Builds a direct dependency: makes each of <I>targets1</I>
 853   depend on each of <I>targets2</I>.  Generally, <I>targets1</I>
 854   will be rebuilt if <I>targets2</I> are themselves rebuilt are
 855   or are newer than <I>targets1</I>.
 856
 857   <P><DT><CODE>
 858   INCLUDES <I>targets1</I> : <I>targets2</I> ;
 859   </CODE>
 860
 861   <DD> Builds a sibling dependency: makes any target that depends
 862   on any of <I>targets1</I> also depend on each of <I>targets2</I>.
 863   This reflects the dependencies that arise when one source file
 864   includes another:  the object built from the source file depends
 865   both on the original and included source file,  but the two
 866   sources files don't depend on each other.  For example:
 867
 868   <CODE>
 869   <P>DEPENDS foo.o : foo.c ;
 870   <BR>INCLUDES foo.c : foo.h ;
 871   </CODE>
 872
 873   <P>
 874
 875   "foo.o" depends on "foo.c" and "foo.h" in this example.
 876
 877   </DL></TABLE>
 878
 879   <A NAME="bindingmods">
 880   <P> <H5> Modifying Binding </H5>
 881   </A>
 882
 883   <P>
 884
 885   The six rules ALWAYS, LEAVES, NOCARE, NOTFILE, NOUPDATE, and
 886   TEMPORARY modify the dependency graph so that <b>jam</b> treats
 887   the targets differently during its target binding phase.  See
 888   <A HREF="#binding">Binding</A> above.  Normally, <b>jam</b>
 889   updates a target if it is missing, if its filesystem modification
 890   time is older than any of its dependencies (recursively), or if
 891   any of its dependencies are being updated.  This basic behavior
 892   can be changed by invoking the following rules:
 893
 894   <P><TABLE WIDTH=75% ALIGN=CENTER><TR><TD><DL>
 895
 896   <P><DT><CODE>
 897   ALWAYS <I>targets</I> ;
 898   </CODE>
 899
 900   <DD> Causes <I>targets</I> to be rebuilt regardless of whether
 901   they are up-to-date (they must still be in the dependency graph).
 902   This is used for the clean and uninstall targets, as they have
 903   no dependencies and would otherwise appear never to need building.
 904   It is best applied to targets that are also NOTFILE targets,
 905   but it can also be used to force a real file to be updated as
 906   well.
 907
 908   <P><DT><CODE>
 909   LEAVES <I>targets</I> ;
 910   </CODE>
 911
 912   <DD> Makes each of <I>targets</I> depend only on its leaf sources,
 913   and not on any intermediate targets.  This makes it immune to
 914   its dependencies being updated, as the "leaf" dependencies are
 915   those without their own dependencies and without updating actions.
 916   This allows a target to be updated only if original source files
 917   change.
 918
 919   <P><DT><CODE>
 920   NOCARE <I>targets</I> ;
 921   </CODE>
 922
 923   <DD> Causes <b>jam</b> to ignore <I>targets</I> that neither
 924   can be found nor have updating actions to build them.  Normally
 925   for such targets <B>jam</B> issues a warning and then skips
 926   other targets that depend on these missing targets.  The HdrRule
 927   in Jambase uses NOCARE on the header file names found during
 928   header file scanning, to let <b>jam</b> know that the included
 929   files may not exist.   For example,  if a #include is within an
 930   #ifdef, the included file may not actually be around.
 931
 932   <P><DT><CODE>
 933   NOTFILE <I>targets</I> ;
 934   </CODE>
 935
 936   <DD> Marks <I>targets</I> as pseudotargets and not real files.
 937   No timestamp is checked, and so the actions on such a target
 938   are only executed if the target's dependencies are updated, or
 939   if the target is also marked with ALWAYS.  The default <b>jam</b>
 940   target "all" is a pseudotarget. In Jambase, NOTFILE is used to
 941   define several addition convenient pseudotargets.
 942
 943   <P><DT><CODE>
 944   NOUPDATE <I>targets</I> ;
 945   </CODE>
 946
 947   <DD> Causes the timestamps on <I>targets</I> to be ignored.
 948   This has two effects:  first,  once the target has been created
 949   it will never be updated; second, manually updating target will
 950   not cause other targets to be updated.  In Jambase, for example,
 951   this rule is applied to directories by the MkDir rule, because
 952   MkDir only cares that the target directory exists, not when it
 953   has last been updated.
 954
 955   <P><DT><CODE>
 956   TEMPORARY <I>targets</I> ;
 957   </CODE>
 958
 959   <DD> Marks <I>targets</I> as temporary, allowing them to be
 960   removed after other targets that depend upon them have been
 961   updated.  If a TEMPORARY target is missing, <b>jam</b> uses the
 962   timestamp of the target's parent.  Jambase uses TEMPORARY to
 963   mark object files that are archived in a library after they are
 964   built, so that they can be deleted after they are archived.
 965
 966   </DL></TABLE>
 967
 968   <P> <H5> Utility Rules </H5>
 969
 970   The remaining rules are utility rules.
 971
 972   <P><TABLE WIDTH=75% ALIGN=CENTER><TR><TD><DL>
 973
 974   <P><DT><CODE>
 975   ECHO <i>args</I> ; <br>
 976   Echo <i>args</I> ; <br>
 977   echo <i>args</I> ;
 978   </CODE>
 979
 980   <DD> Blurts out the message <i>args</I> to stdout.
 981
 982   <P><DT><CODE>
 983   EXIT <i>args</I> ; <br>
 984   Exit <i>args</I> ; <br>
 985   exit <i>args</I> ;
 986   </CODE>
 987
 988   <DD> Blurts out the message <i>args</I> to stdout and then exits
 989   with a failure status.
 990
 991   <P><DT><CODE>
 992   GLOB <i>directories</I> : <I>patterns</I> ;
 993   </CODE>
 994
 995   <DD> Scans <i>directories</i> for files matching <i>patterns</i>,
 996   returning the list of matching files (with directory prepended).
 997   <i>patterns</i> uses the same syntax as in the <b>switch</b>
 998   statement.  Only useful within the <tt>[ ]</tt> construct, to
 999   change the result into a list.
1000
1001   <P><DT><CODE>
1002   MATCH <i>regexps</I> : <I>list</I> ;
1003   </CODE>
1004
1005   <DD> Matches the <b>egrep</b>(1) style regular expressions
1006   <I>regexps</I> against the strings in <I>list</I>.  The result
1007   is the concatenation of matching <tt>()</tt> subexpressions for
1008   each string in <I>list</I>, and for each regular expression in
1009   <I>regexps</I>.  Only useful within the <tt>[ ]</tt> construct,
1010   to change the result into a list.
1011
1012   </DL></TABLE>
1013
1014 <DT> <P> <H3> Built-in Variables </H3> <DD>
1015
1016   <P>
1017
1018   This section discusses variables that have special meaning to
1019   <b>jam</b>.
1020
1021   <A NAME="search">
1022   <P> <H4> SEARCH and LOCATE Variables </H4>
1023   </A>
1024
1025   <P>
1026
1027   These two variables control the binding of file target names to
1028   locations in the file system.  Generally, $(SEARCH) is used to
1029   find existing sources while $(LOCATE) is used to fix the location
1030   for built targets.
1031
1032   <P>
1033
1034   Rooted (absolute path) file targets are bound as is.  Unrooted
1035   file target names are also normally bound as is, and thus relative
1036   to the current directory, but the settings of $(LOCATE) and
1037   $(SEARCH) alter this:
1038
1039   <P>
1040
1041   <UL>
1042
1043   <LI> If $(LOCATE) is set then the target is bound relative to
1044   the first directory in $(LOCATE).  Only the first element is
1045   used for binding.
1046
1047   <LI> If $(SEARCH) is set then the target is bound to the first
1048   directory in $(SEARCH) where the target file already exists.
1049
1050   <LI> If the $(SEARCH) search fails, the target is bound relative
1051   to the current directory anyhow.
1052
1053   </UL>
1054
1055   <P>
1056
1057   Both $(SEARCH) and $(LOCATE) should be set target-specific and
1058   not globally.  If they were set globally,  <b>jam</b> would use
1059   the same paths for all file binding, which is not likely to
1060   produce sane results.  When writing your own rules,  especially
1061   ones not built upon those in Jambase, you may need to set
1062   $(SEARCH) or $(LOCATE) directly.  Almost all of the rules defined
1063   in Jambase set $(SEARCH) and $(LOCATE) to sensible values for
1064   sources they are looking for and targets they create, respectively.
1065
1066   <A NAME="hdrscan">
1067   <P> <H4> HDRSCAN and HDRRULE Variables </H4>
1068   </A>
1069
1070   <P>
1071
1072   These two variable control header file scanning.  $(HDRSCAN) is
1073   an <b>egrep</b>(1) pattern, with ()'s surrounding the file name,
1074   used to find file inclusion statements in source files.  Jambase
1075   uses $(HDRPATTERN) as the pattern for $(HDRSCAN).  $(HDRRULE)
1076   is the name of a rule to invoke with the results of the scan:
1077   the scanned file is the target, the found files are the sources.
1078   $(HDRRULE) is run under the influence of the scanned file's
1079   target-specific variables.
1080
1081   <P>
1082
1083   Both $(HDRSCAN) and $(HDRRULE) must be set for header file
1084   scanning to take place, and they should be set target-specific
1085   and not globally.  If they were set globally, all files, including
1086   executables and libraries, would be scanned for header file
1087   include statements.
1088
1089   <P>
1090
1091   The scanning for header file inclusions is not exact, but it is
1092   at least dynamic, so there is no need to run something like
1093   <b>makedepend</b>(GNU) to create a static dependency file. The
1094   scanning mechanism errs on the side of inclusion (i.e., it is
1095   more likely to return filenames that are not actually used by
1096   the compiler than to miss include files) because it can't tell
1097   if #include lines are inside #ifdefs or other conditional logic.
1098   In Jambase, HdrRule applies the NOCARE rule to each header file
1099   found during scanning so that if the file isn't present yet
1100   doesn't cause the compilation to fail, <b>jam</b> won't care.
1101
1102   <P>
1103
1104   Also, scanning for regular expressions only works where the
1105   included file name is literally in the source file.  It can't
1106   handle languages that allow including files using variable names
1107   (as the Jam language itself does).
1108
1109   <P> <H4> Platform Identifier Variables </H4>
1110
1111   <P>
1112
1113   A number of Jam built-in variables can be used to identify
1114   runtime platform:
1115
1116   <P>
1117
1118   <TABLE WIDTH=75% ALIGN=CENTER>
1119
1120       <TR><TD>OS<TD>OS identifier string
1121       <TR><TD>OSPLAT<TD>Underlying architecture, when applicable
1122       <TR><TD>MAC<TD>true on MAC platform
1123       <TR><TD>NT<TD>true on NT platform
1124       <TR><TD>OS2<TD>true on OS2 platform
1125       <TR><TD>UNIX<TD>true on Unix platforms
1126       <TR><TD>VMS<TD>true on VMS platform
1127
1128   </TABLE>
1129
1130   <P> <H4> Jam Version Variables </H4>
1131
1132   <P>
1133
1134   <TABLE WIDTH=75% ALIGN=CENTER>
1135
1136       <TR><TD>JAMDATE<TD>Time and date at <b>jam</b> start-up.
1137       <TR><TD>JAMUNAME<TD>Ouput of <b>uname</b>(1) command (Unix only)
1138       <TR><TD>JAMVERSION<TD><b>jam</b> version, as reported by jam -v.
1139
1140   </TABLE>
1141
1142   <P> <H4> JAMSHELL Variable </H4>
1143
1144   <P>
1145
1146   When  <b>jam</b>  executes a  rule's action block, it forks and
1147   execs a shell, passing the action block as an argument to the
1148   shell.   The invocation of the shell can be controlled by
1149   $(JAMSHELL).  The default on Unix is, for example:
1150
1151   <P>
1152
1153   <CODE>JAMSHELL = /bin/sh -c % ;</CODE>
1154
1155   <P>
1156
1157   The % is replaced with the text of the action block.
1158
1159   <P>
1160
1161   <B>Jam</b>  does not directly support building in parallel across
1162   multiple hosts, since that is heavily dependent on the local
1163   environment.   To build in parallel across multiple hosts, you
1164   need to write your own shell that provides access to the multiple
1165   hosts.  You then reset $(JAMSHELL) to reference it.
1166
1167   <P>
1168
1169   Just as <b>jam</b> expands a % to be the text of the rule's
1170   action block, it expands a ! to be the multi-process slot number.
1171   The slot number varies between 1 and the number of concurrent
1172   jobs permitted by the -j flag given on the command line.  Armed
1173   with this, it is possible to write a multiple host shell.  For
1174   example:
1175
1176   <P>
1177
1178   <TABLE WIDTH=75% ALIGN=CENTER><TR><TD><CODE>
1179
1180       <BR>#!/bin/sh
1181       <BR>
1182       <BR># This sample JAMSHELL uses the SunOS on(1) command to execute a
1183       <BR># command string with an identical environment on another host.
1184       <BR>
1185       <BR># Set JAMSHELL = jamshell ! %
1186       <BR>#
1187       <BR># where jamshell is the name of this shell file.
1188       <BR>#
1189       <BR># This version handles up to -j6; after that they get executed
1190       <BR># locally.
1191       <BR>
1192       <BR>case $1 in
1193       <BR>1|4) on winken sh -c "$2";;
1194       <BR>2|5) on blinken sh -c "$2";;
1195       <BR>3|6) on nod sh -c "$2";;
1196       <BR>*)   eval "$2";;
1197       <BR>esac
1198
1199   </CODE></TABLE>
1200
1201
1202 <DT> <P> <H2> DIAGNOSTICS </H2>  <DD>
1203
1204   <P>
1205
1206        In addition to generic error messages, <B>jam</B> may emit one of
1207        the following:
1208
1209        <P><TABLE WIDTH=75% ALIGN=CENTER><TR><TD><DL>
1210
1211        <P><DT><CODE> warning: unknown rule X </CODE> <DD>
1212
1213               A rule was invoked that has not been defined with
1214               an "actions" or "rule" statement.
1215
1216        <P><DT><CODE> using N temp target(s) </CODE> <DD>
1217
1218               Targets marked as being temporary (but nonetheless
1219               present) have been found.
1220
1221        <P><DT><CODE> updating N target(s) </CODE> <DD>
1222
1223               Targets are out-of-date and will be updated.
1224
1225        <P><DT><CODE> can't find N target(s) </CODE> <DD>
1226
1227               Source files can't be found and there are no
1228               actions to create them.
1229
1230        <P><DT><CODE> can't make N target(s) </CODE> <DD>
1231
1232               Due to sources not being found, other targets cannot be made.
1233
1234        <P><DT><CODE> warning: X depends on itself </CODE> <DD>
1235
1236               A target depends on itself either directly or
1237               through its sources.
1238
1239        <P><DT><CODE> don't know how to make X </CODE> <DD>
1240
1241               A target is not present and no actions have been
1242               defined to create it.
1243
1244        <P><DT><CODE> X skipped for lack of Y </CODE> <DD>
1245
1246               A source failed to build, and thus a target cannot
1247               be built.
1248
1249        <P><DT><CODE> warning: using independent target X </CODE> <DD>
1250
1251               A target that is not a dependency of any other
1252               target is being referenced with $(&lt;) or $(&gt;).
1253
1254        <P><DT><CODE> X removed </CODE> <DD>
1255
1256               <b>Jam</b>  removed a  partially built target after being
1257               interrupted.
1258
1259   </DL></TABLE>
1260
1261 <DT> <P> <H2> BUGS, LIMITATIONS </H2> <DD>
1262
1263   <P>
1264
1265   The -j flag can cause <B>jam</B> to get confused when single
1266   actions update more than one target at a time. <B>jam</B> may
1267   proceed as if the targets were built even though they are still
1268   under construction.
1269
1270   <P>
1271
1272   For parallel building to be successful, the dependencies among
1273   files must be properly spelled out, as targets tend to get built
1274   in a quickest-first ordering.  Also, beware of un-parallelizable
1275   commands that drop fixed-named files into the current directory,
1276   like <b>yacc</b>(1) does.
1277
1278   <P>
1279
1280   With the -j flag, errors from failed commands can get staggeringly
1281   mixed up.
1282
1283   <P>
1284
1285   A poorly set $(JAMSHELL) is likely to result in silent failure.
1286
1287 <DT> <P> <H2> SEE ALSO </H2> <DD>
1288
1289   <P>
1290
1291   <UL>
1292
1293   <LI> <a href="Jambase.html">Jambase Reference</a>
1294
1295   <LI> <a href="Jamfile.html">Using Jamfiles and Jambase</a>
1296
1297   </UL>
1298
1299   <P>
1300
1301   Jam documentation and source are available from the <A
1302   HREF="http://public.perforce.com/public/index.html">Perforce
1303   Public Depot</a>.
1304
1305 <DT> <P> <H2> AUTHOR </H2>   <DD>
1306
1307   <P>
1308   Jam's author is Christopher Seiwald (<a
1309   href="mailto:seiwald@perforce.com">seiwald@perforce.com</A>).
1310   Documentation is provided by
1311   <A HREF="http://www.perforce.com">Perforce Software, Inc.</A>
1312
1313 </DL>
1314
1315 <P> <HR>
1316
1317   <P>
1318
1319         Copyright 1993-2002 Christopher Seiwald and Perforce Software, Inc.
1320         <BR>
1321         Comments to <A HREF="mailto:info@perforce.com">info@perforce.com</A>
1322         <BR>
1323         Last updated: May, 2002
1324   <BR>
1325   $Id: //public/jam/src/Jam.html#19 $
1326
1327 </BODY>
1328 </HTML>