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> 20jam [ -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>). $(<) and $(>) 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 $(<) 386 and $(>). 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> < <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> <= <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> > <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> >= <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>JAMJOBS<TD>Number of shell commands to run concurrently, as specified by jam -jx. 1138 <TR><TD>JAMUNAME<TD>Ouput of <b>uname</b>(1) command (Unix only) 1139 <TR><TD>JAMVERSION<TD><b>jam</b> version, as reported by jam -v. 1140 1141 </TABLE> 1142 1143 <P> <H4> JAMSHELL Variable </H4> 1144 1145 <P> 1146 1147 When <b>jam</b> executes a rule's action block, it forks and 1148 execs a shell, passing the action block as an argument to the 1149 shell. The invocation of the shell can be controlled by 1150 $(JAMSHELL). The default on Unix is, for example: 1151 1152 <P> 1153 1154 <CODE>JAMSHELL = /bin/sh -c % ;</CODE> 1155 1156 <P> 1157 1158 The % is replaced with the text of the action block. 1159 1160 <P> 1161 1162 <B>Jam</b> does not directly support building in parallel across 1163 multiple hosts, since that is heavily dependent on the local 1164 environment. To build in parallel across multiple hosts, you 1165 need to write your own shell that provides access to the multiple 1166 hosts. You then reset $(JAMSHELL) to reference it. 1167 1168 <P> 1169 1170 Just as <b>jam</b> expands a % to be the text of the rule's 1171 action block, it expands a ! to be the multi-process slot number. 1172 The slot number varies between 1 and the number of concurrent 1173 jobs permitted by the -j flag given on the command line. Armed 1174 with this, it is possible to write a multiple host shell. For 1175 example: 1176 1177 <P> 1178 1179 <TABLE WIDTH=75% ALIGN=CENTER><TR><TD><CODE> 1180 1181 <BR>#!/bin/sh 1182 <BR> 1183 <BR># This sample JAMSHELL uses the SunOS on(1) command to execute a 1184 <BR># command string with an identical environment on another host. 1185 <BR> 1186 <BR># Set JAMSHELL = jamshell ! % 1187 <BR># 1188 <BR># where jamshell is the name of this shell file. 1189 <BR># 1190 <BR># This version handles up to -j6; after that they get executed 1191 <BR># locally. 1192 <BR> 1193 <BR>case $1 in 1194 <BR>1|4) on winken sh -c "$2";; 1195 <BR>2|5) on blinken sh -c "$2";; 1196 <BR>3|6) on nod sh -c "$2";; 1197 <BR>*) eval "$2";; 1198 <BR>esac 1199 1200 </CODE></TABLE> 1201 1202 1203<DT> <P> <H2> DIAGNOSTICS </H2> <DD> 1204 1205 <P> 1206 1207 In addition to generic error messages, <B>jam</B> may emit one of 1208 the following: 1209 1210 <P><TABLE WIDTH=75% ALIGN=CENTER><TR><TD><DL> 1211 1212 <P><DT><CODE> warning: unknown rule X </CODE> <DD> 1213 1214 A rule was invoked that has not been defined with 1215 an "actions" or "rule" statement. 1216 1217 <P><DT><CODE> using N temp target(s) </CODE> <DD> 1218 1219 Targets marked as being temporary (but nonetheless 1220 present) have been found. 1221 1222 <P><DT><CODE> updating N target(s) </CODE> <DD> 1223 1224 Targets are out-of-date and will be updated. 1225 1226 <P><DT><CODE> can't find N target(s) </CODE> <DD> 1227 1228 Source files can't be found and there are no 1229 actions to create them. 1230 1231 <P><DT><CODE> can't make N target(s) </CODE> <DD> 1232 1233 Due to sources not being found, other targets cannot be made. 1234 1235 <P><DT><CODE> warning: X depends on itself </CODE> <DD> 1236 1237 A target depends on itself either directly or 1238 through its sources. 1239 1240 <P><DT><CODE> don't know how to make X </CODE> <DD> 1241 1242 A target is not present and no actions have been 1243 defined to create it. 1244 1245 <P><DT><CODE> X skipped for lack of Y </CODE> <DD> 1246 1247 A source failed to build, and thus a target cannot 1248 be built. 1249 1250 <P><DT><CODE> warning: using independent target X </CODE> <DD> 1251 1252 A target that is not a dependency of any other 1253 target is being referenced with $(<) or $(>). 1254 1255 <P><DT><CODE> X removed </CODE> <DD> 1256 1257 <b>Jam</b> removed a partially built target after being 1258 interrupted. 1259 1260 </DL></TABLE> 1261 1262<DT> <P> <H2> BUGS, LIMITATIONS </H2> <DD> 1263 1264 <P> 1265 1266 The -j flag can cause <B>jam</B> to get confused when single 1267 actions update more than one target at a time. <B>jam</B> may 1268 proceed as if the targets were built even though they are still 1269 under construction. 1270 1271 <P> 1272 1273 For parallel building to be successful, the dependencies among 1274 files must be properly spelled out, as targets tend to get built 1275 in a quickest-first ordering. Also, beware of un-parallelizable 1276 commands that drop fixed-named files into the current directory, 1277 like <b>yacc</b>(1) does. 1278 1279 <P> 1280 1281 With the -j flag, errors from failed commands can get staggeringly 1282 mixed up. 1283 1284 <P> 1285 1286 A poorly set $(JAMSHELL) is likely to result in silent failure. 1287 1288<DT> <P> <H2> SEE ALSO </H2> <DD> 1289 1290 <P> 1291 1292 <UL> 1293 1294 <LI> <a href="Jambase.html">Jambase Reference</a> 1295 1296 <LI> <a href="Jamfile.html">Using Jamfiles and Jambase</a> 1297 1298 </UL> 1299 1300 <P> 1301 1302 Jam documentation and source are available from the <A 1303 HREF="http://public.perforce.com/public/index.html">Perforce 1304 Public Depot</a>. 1305 1306<DT> <P> <H2> AUTHOR </H2> <DD> 1307 1308 <P> 1309 Jam's author is Christopher Seiwald (<a 1310 href="mailto:seiwald@perforce.com">seiwald@perforce.com</A>). 1311 Documentation is provided by 1312 <A HREF="http://www.perforce.com">Perforce Software, Inc.</A> 1313 1314</DL> 1315 1316<P> <HR> 1317 1318 <P> 1319 1320 Copyright 1993-2002 Christopher Seiwald and Perforce Software, Inc. 1321 <BR> 1322 Comments to <A HREF="mailto:info@perforce.com">info@perforce.com</A> 1323 <BR> 1324 Last updated: May, 2002 1325 <BR> 1326 $Id: //public/jam/src/Jam.html#19 $ 1327 1328</BODY> 1329</HTML> 1330 1331