1[[bbv2.jam]] 2= Boost.Jam Documentation 3 4____ 5Jam is a make(1) replacement that makes building simple things simple and building 6complicated things manageable. 7____ 8 9[[jam.building]] 10== Building B2 11 12Installing `B2` after building it is simply a matter of copying the 13generated executables someplace in your `PATH`. For building the 14executables there are a set of `build` bootstrap scripts to accommodate 15particular environments. The scripts take one optional argument, the 16name of the toolset to build with. When the toolset is not given an 17attempt is made to detect an available toolset and use that. The build 18scripts accept these arguments: 19 20[source,shell] 21---- 22build [toolset] 23---- 24 25Running the scripts without arguments will give you the best chance of 26success. On Windows platforms from a command console do: 27 28[source,bat] 29---- 30cd jam source location 31.\build.bat 32---- 33 34On Unix type platforms do: 35 36[source,shell] 37---- 38cd jam source location 39sh ./build.sh 40---- 41 42For the Boost.Jam source included with the Boost distribution the _jam 43source location_ is `BOOST_ROOT/tools/build/src/engine`. 44 45If the scripts fail to detect an appropriate toolset to build with your 46particular toolset may not be auto-detectable. In that case, you can 47specify the toolset as the first argument, this assumes that the toolset 48is readily available in the `PATH`. 49 50NOTE: The toolset used to build Boost.Jam is independent of the toolsets used 51for B2. Only one version of Boost.Jam is needed to use 52B2. 53 54The supported toolsets, and whether they are auto-detected, are: 55 56[%autowidth] 57.Supported Toolsets 58[cols=",,,",options="header",] 59|=== 60|Script |Platform |Toolset |Detection and Notes 61 62|`build.bat` 63|Windows NT, 2000, and XP 64|http://www.codegear.com/downloads/free/cppbuilder[`borland`], 65http://www.borland.com/[Borland] {CPP}Builder (BCC 5.5) 66a| 67* Common install location: `C:\Borland\BCC55` 68* `BCC32.EXE` in `PATH` 69 70| | |http://www.comeaucomputing.com/[`como`], Comeau Computing C/{CPP} | 71 72| | |http://gcc.gnu.org/[`gcc`], GNU GCC | 73 74| | |http://gcc.gnu.org/[`gcc-nocygwin`], GNU GCC | 75 76| | 77|http://www.intel.com/software/products/compilers/c60[`intel-win32`], 78Intel {CPP} Compiler for Windows 79a| 80* `ICL.EXE` in `PATH` 81 82| | |http://www.metrowerks.com/[`metrowerks`], MetroWerks CodeWarrior 83C/{CPP} 7.x, 8.x, 9.x 84a| 85* `CWFolder` variable configured 86* `MWCC.EXE` in PATH 87 88| | |http://www.mingw.org/[`mingw`], GNU http://gcc.gnu.org/[GCC] as the 89http://www.mingw.org/[MinGW] configuration 90a| 91* Common install location: `C:\MinGW` 92 93| | |http://msdn.microsoft.com/visualc/[`msvc`], Microsoft Visual {CPP} 946.x 95a| 96* `VCVARS32.BAT` already configured 97* `%MSVCDir%` is present in environment 98* Common install locations: `%ProgramFiles%\Microsoft Visual Studio`, 99`%ProgramFiles%\Microsoft Visual {CPP}` 100* `CL.EXE` in `PATH` 101 102| | |http://msdn.microsoft.com/visualc/[`vc7`], Microsoft Visual {CPP} 7.x 103a| 104* `VCVARS32.BAT` or `VSVARS32.BAT` already configured 105* `%VS71COMNTOOLS%` is present in environment 106* `%VCINSTALLDIR%` is present in environment 107* Common install locations: `%ProgramFiles%\Microsoft Visual Studio .NET`, 108 `%ProgramFiles%\Microsoft Visual Studio .NET 2003` 109* `CL.EXE` in `PATH` 110 111| | |http://msdn.microsoft.com/visualc/[`vc8` and `vc9`], Microsoft 112Visual {CPP} 8.x and 9.x 113a| 114Detection: 115 116* `VCVARSALL.BAT` already configured 117* `%VS90COMNTOOLS%` is present in environment 118* Common install location: `%ProgramFiles%\Microsoft Visual Studio 9` 119* `%VS80COMNTOOLS%` is present in environment 120* Common install location: `%ProgramFiles%\Microsoft Visual Studio 8` 121* `CL.EXE` in `PATH` 122 123Notes: 124 125* If `VCVARSALL.BAT` 126is called to set up the toolset, it is passed all the extra arguments, 127see below for what those arguments are. This can be used to build, for 128example, a Win64 specific version of `b2`. Consult the VisualStudio 129documentation for what the possible argument values to the `VCVARSALL.BAT` 130are. 131 132|`build.sh` |Unix, Linux, Cygwin, etc. |http://www.hp.com/go/c++[`acc`], 133HP-UX aCC 134a| 135* `aCC` in `PATH` 136* `uname` is "HP-UX" 137 138| | |http://www.comeaucomputing.com/[`como`], Comeau Computing C/{CPP} 139a| 140* `como` in `PATH` 141 142| | |http://gcc.gnu.org/[`gcc`], GNU GCC 143a| 144* `gcc` in `PATH` 145 146| | 147|http://www.intel.com/software/products/compilers/c60l/[`intel-linux`], 148Intel {CPP} for Linux 149a| 150* `icc` in `PATH` 151* Common install locations: `/opt/intel/cc/9.0`, `/opt/intel_cc_80`, 152 `/opt/intel/compiler70`, `/opt/intel/compiler60`, `/opt/intel/compiler50` 153 154| | |`kcc`, Intel KAI {CPP} 155a| 156* `KCC` in `PATH` 157 158| | |http://www.codegear.com/downloads/free/cppbuilder[`kylix`], 159http://www.borland.com/[Borland] {CPP}Builder 160a| 161* `bc++` in `PATH` 162 163| | 164|http://www.sgi.com/developers/devtools/languages/mipspro.html[`mipspro`], 165SGI MIPSpro C 166a| 167* `uname` is "IRIX" or "IRIX64" 168 169| | |`sunpro`, Sun Workshop 6 {CPP} 170a| 171* Standard install location: `/opt/SUNWspro` 172 173| | |`qcc`, http://www.qnx.com/[QNX Neutrino] 174a| 175* `uname` is "QNX" and `qcc` in `PATH` 176 177| | |http://www.tru64unix.compaq.com/cplus/[`true64cxx`], Compaq {CPP} 178Compiler for True64 UNIX 179a| 180* `uname` is "OSF1" 181 182| | |http://www.ibm.com/software/awdtools/vacpp/[`vacpp`], IBM VisualAge 183{CPP} 184a| 185* `xlc` in `PATH` 186 187| |MacOS X |http://developer.apple.com/tools/compilers.html[`darwin`], 188Apple MacOS X GCC 189a| 190* `uname` is "Darwin" 191 192| |Windows NT, 2000, and XP |http://www.mingw.org/[`mingw`], GNU 193http://gcc.gnu.org/[GCC] as the http://www.mingw.org/[MinGW] 194configuration with the MSYS shell 195a| 196* Common install location: `/mingw` 197 198|=== 199 200The built executables are placed in a subdirectory specific to your 201platform. For example, in Linux running on an Intel x86 compatible chip, 202the executables are placed in: `bin.linuxx86`. The `b2[.exe]` 203executable can be used to invoke B2. 204 205The build scripts support additional invocation arguments for use by 206developers of Boost.Jam and for additional setup of the toolset. The 207extra arguments come after the toolset: 208 209* Arguments not in the form of an option, before option arguments, are 210used for extra setup to toolset configuration scripts. 211* Arguments of the form `--option`, which are passed to the 212`build.jam` build script. 213* Arguments not in the form of an option, after the options, which are 214targets for the `build.jam` script. 215 216---- 217build [toolset] [setup*] [--option+ target*] 218---- 219 220The arguments immediately after the toolset are passed directly to the 221setup script of the toolset, if available and if it needs to be invoked. 222This allows one to configure the toolset ass needed to do non-default 223builds of `b2`. For example to build a Win64 version with `vc8`. See the 224toolset description above for when particular toolsets support this. 225 226The arguments starting with the `--option` forms are passed to the 227`build.jam` script and are used to further customize what gets built. 228Options and targets supported by the `build.jam` script: 229 230`---`:: 231 Empty option when one wants to only specify a target. 232`--release`:: 233 The default, builds the optimized executable. 234`--debug`:: 235 Builds debugging versions of the executable. When built they are 236 placed in their own directory `bin./platform/.debug`. 237`--grammar`:: 238 Normally the Jam language grammar parsing files are not regenerated. 239 This forces building of the grammar, although it may not force the 240 regeneration of the grammar parser. If the parser is out of date it 241 will be regenerated and subsequently built. 242`--with-python=path`:: 243 Enables Python integration, given a path to the Python libraries. 244`--gc`:: 245 Enables use of the Boehm Garbage Collector. The build will look for 246 the Boehm-GC source in a "boehm_gc" subdirectory from the `b2` 247 sources. 248`--duma`:: 249 Enables use of the DUMA (Detect Unintended Memory Access) debugging 250 memory allocator. The build expects to find the DUMA source files in a 251 "duma" subdirectory from the `b2` sources. 252`--toolset-root=path`:: 253 Indicates where the toolset used to build is located. This option is 254 passed in by the bootstrap (`build.bat` or `build.sh`) script. 255`--show-locate-target`:: 256 For information, prints out where it will put the built executable. 257`--noassert`:: 258 Disable debug assertions, even if building the debug version of the 259 executable. 260`dist`:: 261 Generate packages (compressed archives) as appropriate for 262 distribution in the platform, if possible. 263`clean`:: 264 Remove all the built executables and objects. 265 266[[jam.language]] 267== Language 268 269`B2` has an interpreted, procedural language. Statements in `b2` are 270rule (procedure) definitions, rule invocations, flow-of-control 271structures, variable assignments, and sundry language support. 272 273[[jam.language.lexical]] 274=== Lexical Features 275 276`B2` treats its input files as whitespace-separated tokens, with two 277exceptions: double quotes (") can enclose whitespace to embed it into a 278token, and everything between the matching curly braces (\{}) in the 279definition of a rule action is treated as a single string. A backslash 280(\) can escape a double quote, or any single whitespace character. 281 282`B2` requires whitespace (blanks, tabs, or newlines) to surround all 283tokens, including the colon (:) and semicolon (;) tokens. 284 285`B2` keywords (an mentioned in this document) are reserved and generally 286must be quoted with double quotes (") to be used as arbitrary tokens, 287such as variable or target names. 288 289Comments start with the `\#` character and extend until the end of line. 290And block comments start with `#|` and extend until the next `|#`. 291 292[[jam.language.target]] 293=== Targets 294 295The essential `b2` data entity is a target. Build targets are files to 296be updated. Source targets are the files used in updating built targets. 297Built targets and source targets are collectively referred to as file 298targets, and frequently built targets are source targets for other built 299targets. Pseudo-targets are symbols representing dependencies on other 300targets, but which are not themselves associated with any real file. 301 302A file target's identifier is generally the file's name, which can be 303absolutely rooted, relative to the directory of `b2`s invocation, or 304simply local (no directory). Most often it is the last case, and the 305actual file path is bound using the `$(SEARCH)` and `$(LOCATE)` special 306variables. See link:#jam.language.variables.builtins.search[SEARCH and 307LOCATE Variables] below. A local filename is optionally qualified with 308grist, a string value used to assure uniqueness. A file target with an 309identifier of the form _file(member)_ is a library member (usually an 310`ar`(1) archive on Unix). 311 312[[jam.language.target.binding_detection]] 313==== Binding Detection 314 315Whenever a target is bound to a location in the filesystem, Boost Jam 316will look for a variable called `BINDRULE` (first "on" the target being 317bound, then in the global module). If non-empty, `$(BINDRULE[1])` names 318a rule which is called with the name of the target and the path it is 319being bound to. The signature of the rule named by `$(BINDRULE[1])` 320should match the following: 321 322[source] 323---- 324rule bind-rule ( target : path ) 325---- 326 327This facility is useful for correct header file scanning, since many 328compilers will search for `#include` files first in the directory 329containing the file doing the `#include` directive. `$(BINDRULE)` can be 330used to make a record of that directory. 331 332[[jam.language.rules]] 333=== Rules 334 335The basic `b2` language entity is called a rule. A rule is defined in 336two parts: the procedure and the actions. The procedure is a body of jam 337statements to be run when the rule is invoked; the actions are the OS 338shell commands to execute when updating the built targets of the rule. 339 340Rules can return values, which can be expanded into a list with "[ 341_rule_ _args_ ... ]". A rule's value is the value of its last statement, 342though only the following statements have values: 'if' (value of the leg 343chosen), 'switch' (value of the case chosen), set (value of the 344resulting variable), and 'return' (value of its arguments). 345 346The `b2` statements for defining and invoking rules are as follows: 347 348Define a rule's procedure, replacing any previous definition. 349 350[source] 351---- 352rule rulename { statements } 353---- 354 355Define a rule's updating actions, replacing any previous definition. 356 357[source] 358---- 359actions [ modifiers ] rulename { commands } 360---- 361 362Invoke a rule. 363 364[source] 365---- 366rulename field1 : field2 : ... : fieldN ; 367---- 368 369Invoke a rule under the influence of target's specific variables.. 370 371[source] 372---- 373on target rulename field1 : field2 : ... : fieldN ; 374---- 375 376Used as an argument, expands to the return value of the rule invoked. 377 378[source] 379---- 380[ rulename field1 : field2 : ... : fieldN ] 381[ on target rulename field1 : field2 : ... : fieldN ] 382---- 383 384A rule is invoked with values in _field1_ through _fieldN_. They may be 385referenced in the procedure's statements as `$(1)` through `$(N)` (9 386max), and the first two only may be referenced in the action's 387_commands_ as `$(1)` and `$(2)`. `$(<)` and `$(>)` are synonymous with 388`$(1)` and `$(2)`. 389 390Rules fall into two categories: updating rules (with actions), and pure 391procedure rules (without actions). Updating rules treat arguments `$(1)` 392and `$(2)` as built targets and sources, respectively, while pure 393procedure rules can take arbitrary arguments. 394 395When an updating rule is invoked, its updating actions are added to 396those associated with its built targets (`$(1)`) before the rule's 397procedure is run. Later, to build the targets in the updating phase, 398_commands_ are passed to the OS command shell, with `$(1)` and `$(2)` 399replaced by bound versions of the target names. See Binding above. 400 401Rule invocation may be indirected through a variable: 402 403[source] 404---- 405$(var) field1 : field2 : ... : fieldN ; 406 407on target $(var) field1 : field2 : ... : fieldN ; 408 409[ $(var) field1 : field2 : ... : fieldN ] 410[ on target $(var) field1 : field2 : ... : fieldN ] 411---- 412 413The variable's value names the rule (or rules) to be invoked. A rule is 414invoked for each element in the list of `$(var)`s values. The fields 415`field1 : field2 : ...` are passed as arguments for each invocation For the [ 416... ] forms, the return value is the concatenation of the return values 417for all of the invocations. 418 419[[jam.language.rules.action_modifiers]] 420==== Action Modifiers 421 422The following action modifiers are understood: 423 424`actions bind vars`:: 425 `$(vars)` will be replaced with bound values. 426`actions existing`:: 427 `$(>)` includes only source targets currently existing. 428`actions ignore`:: 429 The return status of the commands is ignored. 430`actions piecemeal`:: 431 commands are repeatedly invoked with a subset of `$(>)` small enough 432 to fit in the command buffer on this OS. 433`actions quietly`:: 434 The action is not echoed to the standard output. 435`actions together`:: 436 The `$(>)` from multiple invocations of the same action on the same 437 built target are glommed together. 438`actions updated`:: 439 `$(>)` includes only source targets themselves marked for updating. 440 441[[jam.language.rules.argument_lists]] 442==== Argument lists 443 444You can describe the arguments accepted by a rule, and refer to them by 445name within the rule. For example, the following prints "I'm sorry, 446Dave" to the console: 447 448[source] 449---- 450rule report ( pronoun index ? : state : names + ) 451{ 452 local he.suffix she.suffix it.suffix = s ; 453 local I.suffix = m ; 454 local they.suffix you.suffix = re ; 455 ECHO $(pronoun)'$($(pronoun).suffix) $(state), $(names[$(index)]) ; 456} 457report I 2 : sorry : Joe Dave Pete ; 458---- 459 460Each name in a list of formal arguments (separated by `:` in the rule 461declaration) is bound to a single element of the corresponding actual 462argument unless followed by one of these modifiers: 463 464[%autowidth] 465[cols=",",options="header",] 466|=== 467|Symbol |Semantics of preceding symbol 468|`?` |optional 469 470|`*` |Bind to zero or more unbound elements of the actual argument. When 471`*` appears where an argument name is expected, any number of additional 472arguments are accepted. This feature can be used to implement "varargs" 473rules. 474 475|`+` |Bind to one or more unbound elements of the actual argument. 476|=== 477 478The actual and formal arguments are checked for inconsistencies, which 479cause `b2` to exit with an error code: 480 481[source] 482---- 483### argument error 484# rule report ( pronoun index ? : state : names + ) 485# called with: ( I 2 foo : sorry : Joe Dave Pete ) 486# extra argument foo 487### argument error 488# rule report ( pronoun index ? : state : names + ) 489# called with: ( I 2 : sorry ) 490# missing argument names 491---- 492 493If you omit the list of formal arguments, all checking is bypassed as in 494"classic" Jam. Argument lists drastically improve the reliability and 495readability of your rules, however, and are *strongly recommended* for 496any new Jam code you write. 497 498[[jam.language.rules.builtins]] 499=== Built-in Rules 500 501`B2` has a growing set of built-in rules, all of which are pure 502procedure rules without updating actions. They are in three groups: the 503first builds the dependency graph; the second modifies it; and the third 504are just utility rules. 505 506[[jam.language.rules.builtins.dependency_building]] 507==== Dependency Building 508 509[[jam.language.rules.builtins.dependency_building._depends__]] 510===== `DEPENDS` 511 512[source] 513---- 514rule DEPENDS ( targets1 * : targets2 * ) 515---- 516 517Builds a direct dependency: makes each of _targets1_ depend on each of 518_targets2_. Generally, _targets1_ will be rebuilt if _targets2_ are 519themselves rebuilt or are newer than _targets1_. 520 521[[jam.language.rules.builtins.dependency_building._includes__]] 522===== `INCLUDES` 523 524[source] 525---- 526rule INCLUDES ( targets1 * : targets2 * ) 527---- 528 529Builds a sibling dependency: makes any target that depends on any of 530_targets1_ also depend on each of _targets2_. This reflects the 531dependencies that arise when one source file includes another: the 532object built from the source file depends both on the original and 533included source file, but the two sources files don't depend on each 534other. For example: 535 536[source] 537---- 538DEPENDS foo.o : foo.c ; 539INCLUDES foo.c : foo.h ; 540---- 541 542`foo.o` depends on `foo.c` and `foo.h` in this example. 543 544[[jam.language.rules.builtins.modifying_binding]] 545==== Modifying Binding 546 547The six rules `ALWAYS`, `LEAVES`, `NOCARE`, `NOTFILE`, `NOUPDATE`, and 548`TEMPORARY` modify the dependency graph so that `b2` treats the targets 549differently during its target binding phase. See Binding above. 550Normally, `b2` updates a target if it is missing, if its filesystem 551modification time is older than any of its dependencies (recursively), 552or if any of its dependencies are being updated. This basic behavior can 553be changed by invoking the following rules: 554 555[[jam.language.rules.builtins.modifying_binding._always__]] 556===== `ALWAYS` 557 558[source] 559---- 560rule ALWAYS ( targets * ) 561---- 562 563Causes _targets_ to be rebuilt regardless of whether they are up-to-date 564(they must still be in the dependency graph). This is used for the clean 565and uninstall targets, as they have no dependencies and would otherwise 566appear never to need building. It is best applied to targets that are 567also `NOTFILE` targets, but it can also be used to force a real file to 568be updated as well. 569 570[[jam.language.rules.builtins.modifying_binding._leaves__]] 571===== `LEAVES` 572 573[source] 574---- 575rule LEAVES ( targets * ) 576---- 577 578Makes each of _targets_ depend only on its leaf sources, and not on any 579intermediate targets. This makes it immune to its dependencies being 580updated, as the "leaf" dependencies are those without their own 581dependencies and without updating actions. This allows a target to be 582updated only if original source files change. 583 584[[jam.language.rules.builtins.modifying_binding._nocare__]] 585===== `NOCARE` 586 587[source] 588---- 589rule NOCARE ( targets * ) 590---- 591 592Causes `b2` to ignore _targets_ that neither can be found nor have 593updating actions to build them. Normally for such targets `b2` issues a 594warning and then skips other targets that depend on these missing 595targets. The `HdrRule` in `Jambase` uses `NOCARE` on the header file 596names found during header file scanning, to let `b2` know that the 597included files may not exist. For example, if an `#include` is within an 598`#ifdef`, the included file may not actually be around. 599 600WARNING: For targets with build actions: if their build actions exit with a 601nonzero return code, dependent targets will still be built. 602 603[[jam.language.rules.builtins.modifying_binding._notfile__]] 604===== `NOTFILE` 605 606[source] 607---- 608rule NOTFILE ( targets * ) 609---- 610 611Marks _targets_ as pseudo-targets and not real files. No timestamp is 612checked, and so the actions on such a target are only executed if the 613target's dependencies are updated, or if the target is also marked with 614`ALWAYS`. The default `b2` target `all` is a pseudo-target In 615`Jambase`, `NOTFILE` is used to define several addition convenient 616pseudo-targets 617 618[[jam.language.rules.builtins.modifying_binding._noupdate__]] 619===== `NOUPDATE` 620 621[source] 622---- 623rule NOUPDATE ( targets * ) 624---- 625 626Causes the timestamps on _targets_ to be ignored. This has two effects: 627first, once the target has been created it will never be updated; 628second, manually updating target will not cause other targets to be 629updated. In `Jambase`, for example, this rule is applied to directories 630by the `MkDir` rule, because `MkDir` only cares that the target 631directory exists, not when it has last been updated. 632 633[[jam.language.rules.builtins.modifying_binding._temporary__]] 634===== `TEMPORARY` 635 636[source] 637---- 638rule TEMPORARY ( targets * ) 639---- 640 641Marks _targets_ as temporary, allowing them to be removed after other 642targets that depend upon them have been updated. If a `TEMPORARY` target 643is missing, `b2` uses the timestamp of the target's parent. `Jambase` 644uses `TEMPORARY` to mark object files that are archived in a library 645after they are built, so that they can be deleted after they are 646archived. 647 648[[jam.language.rules.builtins.modifying_binding._fail_expected__]] 649===== `FAIL_EXPECTED` 650 651[source] 652---- 653rule FAIL_EXPECTED ( targets * ) 654---- 655 656For handling targets whose build actions are expected to fail (e.g. when 657testing that assertions or compile-time type checking work properly), 658Boost Jam supplies the `FAIL_EXPECTED` rule in the same style as 659`NOCARE`, et. al. During target updating, the return code of the build 660actions for arguments to `FAIL_EXPECTED` is inverted: if it fails, 661building of dependent targets continues as though it succeeded. If it 662succeeds, dependent targets are skipped. 663 664[[jam.language.rules.builtins.modifying_binding._rmold__]] 665===== `RMOLD` 666 667[source] 668---- 669rule RMOLD ( targets * ) 670---- 671 672`B2` removes any target files that may exist on disk when the rule used 673to build those targets fails. However, targets whose dependencies fail 674to build are not removed by default. The `RMOLD` rule causes its 675arguments to be removed if any of their dependencies fail to build. 676 677[[jam.language.rules.builtins.modifying_binding._isfile__]] 678===== `ISFILE` 679 680[source] 681---- 682rule ISFILE ( targets * ) 683---- 684 685`ISFILE` marks targets as required to be files. This changes the way 686`b2` searches for the target such that it ignores matches for file 687system items that are not files, like directories. This makes it 688possible to avoid `#include "exception"` matching if one happens to have 689a directory named exception in the header search path. 690 691WARNING: This is currently not fully implemented. 692 693[[jam.language.rules.builtins.utility]] 694==== Utility 695 696The two rules `ECHO` and `EXIT` are utility rules, used only in `b2`s 697parsing phase. 698 699[[jam.language.rules.builtins.utility._echo__]] 700===== `ECHO` 701 702[source] 703---- 704rule ECHO ( args * ) 705---- 706 707Blurts out the message _args_ to stdout. 708 709[[jam.language.rules.builtins.utility._exit__]] 710===== `EXIT` 711 712[source] 713---- 714rule EXIT ( message * : result-value ? ) 715---- 716 717Blurts out the _message_ to stdout and then exits with a failure status 718if no _result-value_ is given, otherwise it exits with the given 719_result-value_. 720 721`Echo`, `echo`, `Exit`, and `exit` are accepted as aliases for 722`ECHO` and `EXIT`, since it is hard to tell that these are built-in 723rules and not part of the language, like `include`. 724 725[[jam.language.rules.builtins.utility._glob__]] 726===== `GLOB` 727 728The `GLOB` rule does filename globing 729 730[source] 731---- 732rule GLOB ( directories * : patterns * : downcase-opt ? ) 733---- 734 735Using the same wildcards as for the patterns in the switch statement. It 736is invoked by being used as an argument to a rule invocation inside of 737"[ ]". For example: `FILES = [ GLOB dir1 dir2 : *.c *.h ]` sets `FILES` to 738the list of C source 739and header files in `dir1` and `dir2`. The resulting filenames are the 740full pathnames, including the directory, but the pattern is applied only 741to the file name without the directory. 742 743If _downcase-opt_ is supplied, filenames are converted to all-lowercase 744before matching against the pattern; you can use this to do 745case-insensitive matching using lowercase patterns. The paths returned 746will still have mixed case if the OS supplies them. On Windows NT and 747Cygwin, and OpenVMS, filenames are always down-cased before matching. 748 749[[jam.language.rules.builtins.utility._glob_archive__]] 750===== `GLOB_ARCHIVE` 751 752The `GLOB_ARCHIVE` rule does name globing of object archive members. 753 754[source] 755---- 756rule GLOB_ARCHIVE ( archives * : member-patterns * : downcase-opt ? : symbol-patterns ? ) 757---- 758 759Similarly to `GLOB`, this rule is used to match names of member files in 760an archive (static object library). List of successfully matched members 761is returned or null otherwise. The resulting member names are qualified 762with pathname of the containing archive in the form 763`archive-path(member-name)`. Member patterns are for matching member 764name only; when no wildcards specified -- an exact match is assumed. 765Member names generally correspond to object file names and as such are 766platform-specific -- use of platform-defined object suffix in the 767matching patterns can allow for portability. 768 769If _downcase-opt_ is supplied, the member names are converted to 770all-lowercase before matching against the pattern; you can use this to 771do case-insensitive matching using lowercase patterns. The paths 772returned will still have mixed case if the OS supplies them. On Windows 773NT, Cygwin, and OpenVMS, filenames are always down-cased before matching. 774 775Additionally, members can be matched with symbol/function patterns on 776supported platforms (currently, OpenVMS only). In this case, members 777containing the matching symbols are returned. Member and symbol patterns 778are applied as OR conditions, with member patterns taking precedence. On 779unsupported platforms, null is returned when any symbol patterns are 780specified. 781 782[[jam.language.rules.builtins.utility._match__]] 783===== `MATCH` 784 785The `MATCH` rule does pattern matching. 786 787[source] 788---- 789rule MATCH ( regexps + : list * ) 790---- 791 792Matches the `egrep`(1) style regular expressions _regexps_ against the 793strings in _list_. The result is a list of matching `()` subexpressions 794for each string in _list_, and for each regular expression in _regexps_. 795 796[[jam.language.rules.builtins.utility._backtrace__]] 797===== `BACKTRACE` 798 799[source] 800---- 801rule BACKTRACE ( ) 802---- 803 804Returns a list of quadruples: _filename_ _line_ _module_ _rulename_..., 805describing each shallower level of the call stack. This rule can be used 806to generate useful diagnostic messages from Jam rules. 807 808[[jam.language.rules.builtins.utility._update__]] 809===== `UPDATE` 810 811[source] 812---- 813rule UPDATE ( targets * ) 814---- 815 816Classic jam treats any non-option element of command line as a name of 817target to be updated. This prevented more sophisticated handling of 818command line. This is now enabled again but with additional changes to 819the `UPDATE` rule to allow for the flexibility of changing the list of 820targets to update. The UPDATE rule has two effects: 821 8221. It clears the list of targets to update, and 8232. Causes the specified targets to be updated. 824 825If no target was specified with the `UPDATE` rule, no targets will be 826updated. To support changing of the update list in more useful ways, the 827rule also returns the targets previously in the update list. This makes 828it possible to add targets as such: 829 830[source] 831---- 832local previous-updates = [ UPDATE ] ; 833UPDATE $(previous-updates) a-new-target ; 834---- 835 836[[jam.language.rules.builtins.utility._w32_getreg__]] 837===== `W32_GETREG` 838 839[source] 840---- 841rule W32_GETREG ( path : data ? ) 842---- 843 844Defined only for win32 platform. It reads the registry of Windows. 845'_path_' is the location of the information, and '_data_' is the name of 846the value which we want to get. If '_data_' is omitted, the default 847value of '_path_' will be returned. The '_path_' value must conform to 848MS key path format and must be prefixed with one of the predefined root 849keys. As usual, 850 851* `HKLM` is equivalent to `HKEY_LOCAL_MACHINE`. 852* `HKCU` is equivalent to `HKEY_CURRENT_USER`. 853* `HKCR` is equivalent to `HKEY_CLASSES_ROOT`. 854 855Other predefined root keys are not supported. 856 857Currently supported data types : `REG_DWORD`, `REG_SZ`, 858`REG_EXPAND_SZ`, `REG_MULTI_SZ`. The data with `REG_DWORD` type 859will be turned into a string, `REG_MULTI_SZ` into a list of strings, 860and for those with `REG_EXPAND_SZ` type environment variables in it 861will be replaced with their defined values. The data with `REG_SZ` 862type and other unsupported types will be put into a string without 863modification. If it can't receive the value of the data, it just return 864an empty list. For example, 865 866[source] 867---- 868local PSDK-location = 869 [ W32_GETREG HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\MicrosoftSDK\\Directories : "Install Dir" ] ; 870---- 871 872[[jam.language.rules.builtins.utility._w32_getregnames__]] 873===== `W32_GETREGNAMES` 874 875[source] 876---- 877rule W32_GETREGNAMES ( path : result-type ) 878---- 879 880Defined only for win32 platform. It reads the registry of Windows. 881'_path_' is the location of the information, and '_result-type_' is 882either `subkeys` or `values`. For more information on '_path_' 883format and constraints, please see `W32_GETREG`. 884 885Depending on '_result-type_', the rule returns one of the following: 886 887`subkeys`:: 888 Names of all direct sub-keys of '_path_'. 889`values`:: 890 Names of values contained in registry key given by '_path_'. The 891 "default" value of the key appears in the returned list only if its 892 value has been set in the registry. 893 894If '_result-type_' is not recognized, or requested data cannot be 895retrieved, the rule returns an empty list. Example: 896 897[source] 898---- 899local key = "HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\App Paths" ; 900local subkeys = [ W32_GETREGNAMES "$(key)" : subkeys ] ; 901for local subkey in $(subkeys) 902{ 903 local values = [ W32_GETREGNAMES "$(key)\\$(subkey)" : values ] ; 904 for local value in $(values) 905 { 906 local data = [ W32_GETREG "$(key)\\$(subkey)" : "$(value)" ] ; 907 ECHO "Registry path: " $(key)\\$(subkey) ":" $(value) "=" $(data) ; 908 } 909} 910---- 911 912[[jam.language.rules.builtins.utility._shell__]] 913===== `SHELL` 914 915[source] 916---- 917rule SHELL ( command : * ) 918---- 919 920`SHELL` executes _command_, and then returns the standard output of 921_command_. `SHELL` only works on platforms with a `popen()` function in 922the C library. On platforms without a working `popen()` function, 923`SHELL` is implemented as a no-op. `SHELL` works on Unix, MacOS X, and 924most Windows compilers. `SHELL` is a no-op on Metrowerks compilers under 925Windows. There is a variable set of allowed options as additional 926arguments: 927 928`exit-status`:: 929 In addition to the output the result status of the executed command is 930 returned as a second element of the result. 931`no-output`:: 932 Don't capture the output of the command. Instead an empty ("") string 933 value is returned in place of the output. 934`strip-eol`:: 935 Remove trailing end-of-line character from output, if any. 936 937Because the Perforce/Jambase defines a `SHELL` rule which hides the 938builtin rule, `COMMAND` can be used as an alias for `SHELL` in such a 939case. 940 941[[jam.language.rules.builtins.utility._md5__]] 942===== `MD5` 943 944[source] 945---- 946rule MD5 ( string ) 947---- 948 949`MD5` computes the MD5 hash of the string passed as parameter and 950returns it. 951 952[[jam.language.rules.builtins.utility._split_by_characters__]] 953===== `SPLIT_BY_CHARACTERS` 954 955[source] 956---- 957rule SPLIT_BY_CHARACTERS ( string : delimiters ) 958---- 959 960`SPLIT_BY_CHARACTERS` splits the specified _string_ on any delimiter 961character present in _delimiters_ and returns the resulting list. 962 963[[jam.language.rules.builtins.utility._precious__]] 964===== `PRECIOUS` 965 966[source] 967---- 968rule PRECIOUS ( targets * ) 969---- 970 971The `PRECIOUS` rule specifies that each of the targets passed as the 972arguments should not be removed even if the command updating that target 973fails. 974 975[[jam.language.rules.builtins.utility._pad__]] 976===== `PAD` 977 978[source] 979---- 980rule PAD ( string : width ) 981---- 982 983If _string_ is shorter than _width_ characters, pads it with whitespace 984characters on the right, and returns the result. Otherwise, returns 985_string_ unmodified. 986 987[[jam.language.rules.builtins.utility._file_open__]] 988===== `FILE_OPEN` 989 990[source] 991---- 992rule FILE_OPEN ( filename : mode ) 993---- 994 995The `FILE_OPEN` rule opens the specified file and returns a file 996descriptor. The _mode_ parameter can be either "w" or "r". Note that at 997present, only the `UPDATE_NOW` rule can use the resulting file 998descriptor number. 999 1000[[jam.language.rules.builtins.utility._update_now__]] 1001===== `UPDATE_NOW` 1002 1003[source] 1004---- 1005rule UPDATE_NOW ( targets * : log ? : ignore-minus-n ? ) 1006---- 1007 1008The `UPDATE_NOW` caused the specified targets to be updated immediately. 1009If update was successful, non-empty string is returned. The _log_ 1010parameter, if present, specifies a descriptor of a file where all output 1011from building is redirected. If the _ignore-minus-n_ parameter is 1012specified, the targets are updated even if the `-n` parameter is 1013specified on the command line. 1014 1015[[jam.language.flow_of_control]] 1016=== Flow-of-Control 1017 1018`B2` has several simple flow-of-control statements: 1019 1020[source] 1021---- 1022for var in list { statements } 1023---- 1024 1025Executes _statements_ for each element in _list_, setting the variable 1026_var_ to the element value. 1027 1028[source] 1029---- 1030if cond { statements } 1031[ else { statements } ] 1032---- 1033 1034Does the obvious; the `else` clause is optional. _cond_ is built of: 1035 1036`a`:: 1037 true if any _a_ element is a non-zero-length string 1038`a = b`:: 1039 list _a_ matches list _b_ string-for-string 1040`a != b`:: 1041 list _a_ does not match list _b_ 1042`a < b`:: 1043 _a[i]_ string is less than _b[i]_ string, where _i_ is first 1044 mismatched element in lists _a_ and _b_ 1045`+a <= b+`:: 1046 every _a_ string is less than or equal to its _b_ counterpart 1047`a > b`:: 1048 _a[i]_ string is greater than _b[i]_ string, where _i_ is first 1049 mismatched element 1050`a >= b`:: 1051 every _a_ string is greater than or equal to its _b_ counterpart 1052`a in b`:: 1053 true if all elements of _a_ can be found in _b_, or if _a_ has no 1054 elements 1055`! cond`:: 1056 condition not true 1057`cond && cond`:: 1058 conjunction 1059`cond || cond`:: 1060 disjunction 1061`( cond )`:: 1062 precedence grouping 1063 1064[source] 1065---- 1066include file ; 1067---- 1068 1069Causes `b2` to read the named _file_. The _file_ is bound like a regular 1070target (see Binding above) but unlike a regular target the include 1071_file_ cannot be built. 1072 1073The include _file_ is inserted into the input stream during the parsing 1074phase. The primary input file and all the included file(s) are treated 1075as a single file; that is, `b2` infers no scope boundaries from included 1076files. 1077 1078[source] 1079---- 1080local vars [ = values ] ; 1081---- 1082 1083Creates new _vars_ inside to the enclosing `{}` block, obscuring any 1084previous values they might have. The previous values for vars are 1085restored when the current block ends. Any rule called or file included 1086will see the local and not the previous value (this is sometimes called 1087Dynamic Scoping). The local statement may appear anywhere, even outside 1088of a block (in which case the previous value is restored when the input 1089ends). The _vars_ are initialized to _values_ if present, or left 1090uninitialized otherwise. 1091 1092[source] 1093---- 1094return values ; 1095---- 1096 1097Within a rule body, the return statement sets the return value for an 1098invocation of the rule and returns to the caller. 1099 1100[source] 1101---- 1102switch value 1103{ 1104 case pattern1 : statements ; 1105 case pattern2 : statements ; 1106 ... 1107} 1108---- 1109 1110The switch statement executes zero or one of the enclosed _statements_, 1111depending on which, if any, is the first case whose _pattern_ matches 1112_value_. The _pattern_ values are not variable-expanded. The pattern 1113values may include the following wildcards: 1114 1115`?`:: 1116 match any single character 1117`*`:: 1118 match zero or more characters 1119`[chars]`:: 1120 match any single character in _chars_ 1121`[^chars]`:: 1122 match any single character not in _chars_ 1123`\x`:: 1124 match _x_ (escapes the other wildcards) 1125 1126[source] 1127---- 1128while cond { statements } 1129---- 1130 1131Repeatedly execute _statements_ while _cond_ remains true upon entry. 1132(See the description of _cond_ expression syntax under if, above). 1133 1134[source] 1135---- 1136break ; 1137---- 1138 1139Immediately exits the nearest enclosing while or for loop. 1140 1141[source] 1142---- 1143continue ; 1144---- 1145 1146Jumps to the top of the nearest enclosing while or for loop. 1147 1148[[jam.language.variables]] 1149=== Variables 1150 1151`B2` variables are lists of zero or more elements, with each element 1152being a string value. An undefined variable is indistinguishable from a 1153variable with an empty list, however, a defined variable may have one 1154more elements which are null strings. All variables are referenced as 1155`$(variable)`. 1156 1157Variables are either global or target-specific. In the latter case, the 1158variable takes on the given value only during the updating of the 1159specific target. 1160 1161A variable is defined with: 1162 1163[source] 1164---- 1165variable = elements ; 1166variable += elements ; 1167variable on targets = elements ; 1168variable on targets += elements ; 1169variable default = elements ; 1170variable ?= elements ; 1171---- 1172 1173The first two forms set _variable_ globally. The third and forth forms 1174set a target-specific variable. The `=` operator replaces any previous 1175elements of _variable_ with _elements_; the `+=` operation adds 1176_elements_ to _variable_'s list of elements. The final two forms are 1177synonymous: they set _variable_ globally, but only if it was previously 1178unset. 1179 1180Variables referenced in updating commands will be replaced with their 1181values; target-specific values take precedence over global values. 1182Variables passed as arguments (`$(1)` and `$(2)`) to actions are 1183replaced with their bound values; the `bind` modifier can be used on 1184actions to cause other variables to be replaced with bound values. See 1185Action Modifiers above. 1186 1187`B2` variables are not re-exported to the environment of the shell that 1188executes the updating actions, but the updating actions can reference 1189`b2` variables with `$(variable)`. 1190 1191[[jam.language.variables.expansion]] 1192==== Variable Expansion 1193 1194During parsing, `b2` performs variable expansion on each token that is 1195not a keyword or rule name. Such tokens with embedded variable 1196references are replaced with zero or more tokens. Variable references 1197are of the form `$(v)` or `$(vm)`, where _v_ is the variable name, and 1198_m_ are optional modifiers. 1199 1200Variable expansion in a rule's actions is similar to variable expansion 1201in statements, except that the action string is tokenized at whitespace 1202regardless of quoting. 1203 1204The result of a token after variable expansion is the _product_ of the 1205components of the token, where each component is a literal substring or 1206a list substituting a variable reference. For example: 1207 1208---- 1209$(X) -> a b c 1210t$(X) -> ta tb tc 1211$(X)z -> az bz cz 1212$(X)-$(X) -> a-a a-b a-c b-a b-b b-c c-a c-b c-c 1213---- 1214 1215The variable name and modifiers can themselves contain a variable 1216reference, and this partakes of the product as well: 1217 1218---- 1219$(X) -> a b c 1220$(Y) -> 1 2 1221$(Z) -> X Y 1222$($(Z)) -> a b c 1 2 1223---- 1224 1225Because of this product expansion, if any variable reference in a token 1226is undefined, the result of the expansion is an empty list. If any 1227variable element is a null string, the result propagates the non-null 1228elements: 1229 1230---- 1231$(X) -> a "" 1232$(Y) -> "" 1 1233$(Z) -> 1234-$(X)$(Y)- -> -a- -a1- -- -1- 1235-$(X)$(Z)- -> 1236---- 1237 1238A variable element's string value can be parsed into grist and 1239filename-related components. Modifiers to a variable are used to select 1240elements, select components, and replace components. The modifiers are: 1241 1242`[n]`:: 1243+ 1244Select element number _n_ (starting at 1). If the variable contains 1245fewer than _n_ elements, the result is a zero-element list. _n_ can be 1246negative in which case the element number _n_ from the last leftward 1247is returned. 1248 1249`[n-m]`:: 1250+ 1251Select elements number _n_ through _m_. _n_ and _m_ can be negative in 1252which case they refer to elements counting from the last leftward. 1253 1254`[n-]`:: 1255+ 1256Select elements number _n_ through the last. _n_ can be negative in 1257which case it refers to the element counting from the last leftward. 1258 1259`:B`:: 1260+ 1261Select filename base -- a basename without extension. 1262 1263`:S`:: 1264+ 1265Select file extension -- a (last) filename suffix. 1266 1267`:M`:: 1268+ 1269Select archive member name. 1270`:D`:: 1271+ 1272Select directory path. 1273 1274`:P`:: 1275+ 1276Select parent directory. 1277 1278`:G`:: 1279+ 1280Select grist. 1281 1282`:U`:: 1283+ 1284Replace lowercase characters with uppercase. 1285 1286`:L`:: 1287+ 1288Replace uppercase characters with lowercase. 1289 1290`:T`:: 1291+ 1292Converts all back-slashes ("\") to forward slashes ("/"). For example 1293+ 1294---- 1295x = "C:\\Program Files\\Borland" ; ECHO $(x:T) ; 1296---- 1297+ 1298prints `C:/Program Files/Borland` 1299 1300`:W`:: 1301+ 1302When invoking Windows-based tools from http://www.cygwin.com/[Cygwin] 1303it can be important to pass them true windows-style paths. The `:W` 1304modifier, *under Cygwin only*, turns a cygwin path into a Win32 path 1305using the 1306http://www.cygwin.com/cygwin-api/func-cygwin-conv-to-win32-path.html[`cygwin_conv_to_win32_path`] 1307function. For example 1308+ 1309---- 1310x = "/cygdrive/c/Program Files/Borland" ; ECHO $(x:W) ; 1311---- 1312+ 1313prints `C:\Program Files\Borland` on Cygwin 1314+ 1315Similarly, when used on OpenVMS, the `:W` modifier translates a 1316POSIX-style path into native VMS-style format using `decc$to_vms` CRTL 1317function. This modifier is generally used inside action blocks to 1318properly specify file paths in VMS-specific commands. For example 1319+ 1320---- 1321x = "subdir/filename.c" ; ECHO $(x:W) ; 1322---- 1323+ 1324prints `[.subdir]filename.c` on OpenVMS 1325+ 1326On other platforms, the string is unchanged. 1327 1328`:chars`:: 1329Select the components listed in _chars_. 1330+ 1331For example, `:BS` selects filename (basename and extension). 1332 1333`:G=grist`:: 1334Replace grist with _grist_. 1335 1336`:D=path`:: 1337Replace directory with _path_. 1338 1339`:B=base`:: 1340Replace the base part of file name with _base_. 1341 1342`:S=suf`:: 1343Replace the suffix of file name with _suf_. 1344 1345`:M=mem`:: 1346Replace the archive member name with _mem_. 1347 1348`:R=root`:: 1349Prepend _root_ to the whole file name, if not already rooted. 1350 1351`:E=value`:: 1352Assign _value_ to the variable if it is unset. 1353 1354`:J=joinval`:: 1355Concatenate list elements into single element, separated by 1356_joinval_. 1357 1358On VMS, `$(var:P)` is the parent directory of `$(var:D)`. 1359 1360[[jam.language.variables.local_for_loop_variables]] 1361==== Local For Loop Variables 1362 1363Boost Jam allows you to declare a local for loop control variable right 1364in the loop: 1365 1366[source] 1367---- 1368x = 1 2 3 ; 1369y = 4 5 6 ; 1370for local y in $(x) 1371{ 1372 ECHO $(y) ; # prints "1", "2", or "3" 1373} 1374ECHO $(y) ; # prints "4 5 6" 1375---- 1376 1377[[jam.language.variables.atfile]] 1378==== Generated File Expansion 1379 1380During expansion of expressions `b2` also looks for subexpressions of 1381the form `@(filename:E=filecontents)` and replaces the expression with 1382`filename` after creating the given file with the contents set to 1383`filecontents`. This is useful for creating compiler response files, and 1384other "internal" files. The expansion works both during parsing and 1385action execution. Hence it is possible to create files during any of the 1386three build phases. 1387 1388[[jam.language.variables.builtins]] 1389==== Built-in Variables 1390 1391This section discusses variables that have special meaning to `b2`. All 1392of these must be defined or used in the global module -- using those 1393variables inside a named module will not have the desired effect. See 1394link:#jam.language.modules[Modules]. 1395 1396[[jam.language.variables.builtins.search]] 1397===== SEARCH and LOCATE 1398 1399These two variables control the binding of file target names to 1400locations in the file system. Generally, `$(SEARCH)` is used to find 1401existing sources while `$(LOCATE)` is used to fix the location for built 1402targets. 1403 1404Rooted (absolute path) file targets are bound as is. Unrooted file 1405target names are also normally bound as is, and thus relative to the 1406current directory, but the settings of `$(LOCATE)` and `$(SEARCH)` alter 1407this: 1408 1409* If `$(LOCATE)` is set then the target is bound relative to the first 1410directory in `$(LOCATE)`. Only the first element is used for binding. 1411* If `$(SEARCH)` is set then the target is bound to the first directory 1412in `$(SEARCH)` where the target file already exists. 1413* If the `$(SEARCH)` search fails, the target is bound relative to the 1414current directory anyhow. 1415 1416Both `$(SEARCH)` and `$(LOCATE)` should be set target-specific and not 1417globally. If they were set globally, `b2` would use the same paths for 1418all file binding, which is not likely to produce sane results. When 1419writing your own rules, especially ones not built upon those in Jambase, 1420you may need to set `$(SEARCH)` or `$(LOCATE)` directly. Almost all of 1421the rules defined in Jambase set `$(SEARCH)` and `$(LOCATE)` to sensible 1422values for sources they are looking for and targets they create, 1423respectively. 1424 1425[[jam.language.variables.builtins.hdrscan]] 1426===== HDRSCAN and HDRRULE 1427 1428These two variables control header file scanning. `$(HDRSCAN)` is an 1429`egrep(1)` pattern, with ()'s surrounding the file name, used to find 1430file inclusion statements in source files. `Jambase` uses 1431`$(HDRPATTERN)` as the pattern for `$(HDRSCAN)`. `$(HDRRULE)` is the 1432name of a rule to invoke with the results of the scan: the scanned file 1433is the target, the found files are the sources. This is the only place 1434where `b2` invokes a rule through a variable setting. 1435 1436Both `$(HDRSCAN)` and `$(HDRRULE)` must be set for header file scanning 1437to take place, and they should be set target-specific and not globally. 1438If they were set globally, all files, including executables and 1439libraries, would be scanned for header file include statements. 1440 1441The scanning for header file inclusions is not exact, but it is at least 1442dynamic, so there is no need to run something like `makedepend(GNU)` to 1443create a static dependency file. The scanning mechanism errs on the side 1444of inclusion (i.e., it is more likely to return filenames that are not 1445actually used by the compiler than to miss include files) because it 1446can't tell if `#include` lines are inside `#ifdefs` or other conditional 1447logic. In `Jambase`, `HdrRule` applies the `NOCARE` rule to each header 1448file found during scanning so that if the file isn't present yet doesn't 1449cause the compilation to fail, `b2` won't care. 1450 1451Also, scanning for regular expressions only works where the included 1452file name is literally in the source file. It can't handle languages 1453that allow including files using variable names (as the `Jam` language 1454itself does). 1455 1456[[jam.language.variables.builtins.semaphores]] 1457===== Semaphores 1458 1459It is sometimes desirable to disallow parallel execution of some 1460actions. For example: 1461 1462* Old versions of yacc use files with fixed names. So, running two yacc 1463actions is dangerous. 1464* One might want to perform parallel compiling, but not do parallel 1465linking, because linking is i/o bound and only gets slower. 1466 1467Craig McPeeters has extended Perforce Jam to solve such problems, and 1468that extension was integrated in Boost.Jam. 1469 1470Any target can be assigned a _semaphore_, by setting a variable called 1471`SEMAPHORE` on that target. The value of the variable is the semaphore 1472name. It must be different from names of any declared target, but is 1473arbitrary otherwise. 1474 1475The semantic of semaphores is that in a group of targets which have the 1476same semaphore, only one can be updated at the moment, regardless of 1477`-j` option. 1478 1479[[jam.language.variables.builtins.platform_identifier]] 1480===== Platform Identifier 1481 1482A number of Jam built-in variables can be used to identify runtime 1483platform: 1484 1485`OS`:: 1486 OS identifier string 1487`OSPLAT`:: 1488 Underlying architecture, when applicable 1489`MAC`:: 1490 true on MAC platform 1491`NT`:: 1492 true on NT platform 1493`OS2`:: 1494 true on OS2 platform 1495`UNIX`:: 1496 true on Unix platforms 1497`VMS`:: 1498 true on VMS platform 1499 1500[[jam.language.variables.builtins.jam_version]] 1501==== Jam Version 1502 1503`JAMDATE`:: 1504 Time and date at `b2` start-up as an ISO-8601 UTC value. 1505`JAMUNAME`:: 1506 Output of uname(1) command (Unix only) 1507`JAMVERSION`:: 1508 `b2` version, as a sematic triplet "X.Y.Z". 1509`JAM_VERSION`:: 1510 A predefined global variable with two elements indicates the version 1511 number of Boost Jam. Boost Jam versions start at `03` `00`. 1512 Earlier versions of `Jam` do not automatically define `JAM_VERSION`. 1513 1514[[jam.language.variables.builtins.jamshell]] 1515===== JAMSHELL 1516 1517When `b2` executes a rule's action block, it forks and execs a shell, 1518passing the action block as an argument to the shell. The invocation of 1519the shell can be controlled by `$(JAMSHELL)`. The default on Unix is, 1520for example: 1521 1522[source] 1523---- 1524JAMSHELL = /bin/sh -c % ; 1525---- 1526 1527The `%` is replaced with the text of the action block. 1528 1529`B2` does not directly support building in parallel across multiple 1530hosts, since that is heavily dependent on the local environment. To 1531build in parallel across multiple hosts, you need to write your own 1532shell that provides access to the multiple hosts. You then reset 1533`$(JAMSHELL)` to reference it. 1534 1535Just as `b2` expands a `%` to be the text of the rule's action block, it 1536expands a `!` to be the multi-process slot number. The slot number 1537varies between 1 and the number of concurrent jobs permitted by the `-j` 1538flag given on the command line. Armed with this, it is possible to write 1539a multiple host shell. For example: 1540 1541[source,bash] 1542---- 1543#!/bin/sh 1544 1545# This sample JAMSHELL uses the SunOS on(1) command to execute a 1546# command string with an identical environment on another host. 1547 1548# Set JAMSHELL = jamshell ! % 1549# 1550# where jamshell is the name of this shell file. 1551# 1552# This version handles up to -j6; after that they get executed 1553# locally. 1554 1555case $1 in 15561|4) on winken sh -c "$2";; 15572|5) on blinken sh -c "$2";; 15583|6) on nod sh -c "$2";; 1559*) eval "$2";; 1560esac 1561---- 1562 1563[[jam.language.variables.builtins.actionrule]] 1564===== `+__TIMING_RULE__+` and `+__ACTION_RULE__+` 1565 1566The `+__TIMING_RULE__+` and `+__ACTION_RULE__+` can be set to the name of a 1567rule for `b2` to call *after* an action completes for a target. They 1568both give diagnostic information about the action that completed. For 1569`+__TIMING_RULE__+` the rule is called as: 1570 1571[source] 1572---- 1573rule timing-rule ( args * : target : start end user system ) 1574---- 1575 1576And `+__ACTION_RULE__+` is called as: 1577 1578[source] 1579---- 1580rule action-rule ( args * : target : command status start end user system : output ? ) 1581---- 1582 1583The arguments for both are: 1584 1585`args`:: 1586 Any values following the rule name in the `+__TIMING_RULE__+` or 1587 `+__ACTION_RULE__+` are passed along here. 1588`target`:: 1589 The `b2` target that was built. 1590`command`:: 1591 The text of the executed command in the action body. 1592`status`:: 1593 The integer result of the executed command. 1594`start`:: 1595 The starting timestamp of the executed command as a ISO-8601 UTC 1596 value. 1597`end`:: 1598 The completion timestamp of the executed command as a ISO-8601 UTC 1599 value. 1600`user`:: 1601 The number of user CPU seconds the executed command spent as a 1602 floating point value. 1603`system`:: 1604 The number of system CPU seconds the executed command spent as a 1605 floating point value. 1606`output`:: 1607 The output of the command as a single string. The content of the 1608 output reflects the use of the `-pX` option. 1609 1610NOTE: If both variables are set for a target both are called, first 1611`+__TIMING_RULE__+` then `+__ACTION_RULE__+`. 1612 1613[[jam.language.modules]] 1614=== Modules 1615 1616Boost Jam introduces support for modules, which provide some rudimentary 1617namespace protection for rules and variables. A new keyword, `module` 1618was also introduced. The features described in this section are 1619primitives, meaning that they are meant to provide the operations needed 1620to write Jam rules which provide a more elegant module interface. 1621 1622[[jam.language.modules.declaration]] 1623==== Declaration 1624 1625[source] 1626---- 1627module expression { ... } 1628---- 1629 1630Code within the `{ ... }` executes within the module named by evaluating 1631expression. Rule definitions can be found in the module's own namespace, 1632and in the namespace of the global module as _module-name_._rule-name_, 1633so within a module, other rules in that module may always be invoked 1634without qualification: 1635 1636[source] 1637---- 1638module my_module 1639{ 1640 rule salute ( x ) { ECHO $(x), world ; } 1641 rule greet ( ) { salute hello ; } 1642 greet ; 1643} 1644my_module.salute goodbye ; 1645---- 1646 1647When an invoked rule is not found in the current module's namespace, it 1648is looked up in the namespace of the global module, so qualified calls 1649work across modules: 1650 1651[source] 1652---- 1653module your_module 1654{ 1655 rule bedtime ( ) { my_module.salute goodnight ; } 1656} 1657---- 1658 1659[[jam.language.modules.variable_scope]] 1660==== Variable Scope 1661 1662Each module has its own set of dynamically nested variable scopes. When 1663execution passes from module A to module B, all the variable bindings 1664from A become unavailable, and are replaced by the bindings that belong 1665to B. This applies equally to local and global variables: 1666 1667[source] 1668---- 1669module A 1670{ 1671 x = 1 ; 1672 rule f ( ) 1673 { 1674 local y = 999 ; # becomes visible again when B.f calls A.g 1675 B.f ; 1676 } 1677 rule g ( ) 1678 { 1679 ECHO $(y) ; # prints "999" 1680 } 1681} 1682module B 1683{ 1684 y = 2 ; 1685 rule f ( ) 1686 { 1687 ECHO $(y) ; # always prints "2" 1688 A.g ; 1689 } 1690} 1691---- 1692 1693The only way to access another module's variables is by entering that 1694module: 1695 1696[source] 1697---- 1698rule peek ( module-name ? : variables + ) 1699{ 1700 module $(module-name) 1701 { 1702 return $($(>)) ; 1703 } 1704} 1705---- 1706 1707Note that because existing variable bindings change whenever a new 1708module scope is entered, argument bindings become unavailable. That 1709explains the use of `$(>)` in the peek rule above. 1710 1711[[jam.language.modules.local_rules]] 1712==== Local Rules 1713 1714[source] 1715---- 1716local rule rulename... 1717---- 1718 1719The rule is declared locally to the current module. It is not entered in 1720the global module with qualification, and its name will not appear in 1721the result of: 1722 1723[source] 1724---- 1725[ RULENAMES module-name ] 1726---- 1727 1728[[jam.language.modules.the__rulenames__rule]] 1729==== The `RULENAMES` Rule 1730 1731[source] 1732---- 1733rule RULENAMES ( module ? ) 1734---- 1735 1736Returns a list of the names of all non-local rules in the given module. 1737If _module_ is omitted, the names of all non-local rules in the global 1738module are returned. 1739 1740[[jam.language.modules.the__varnames__rule]] 1741==== The `VARNAMES` Rule 1742 1743[source] 1744---- 1745rule VARNAMES ( module ? ) 1746---- 1747 1748Returns a list of the names of all variable bindings in the given 1749module. If _module_ is omitted, the names of all variable bindings in 1750the global module are returned. 1751 1752NOTE: This includes any local variables in rules from the call stack which 1753have not returned at the time of the `VARNAMES` invocation. 1754 1755[[jam.language.modules.the__import__rule]] 1756==== The `IMPORT` Rule 1757 1758`IMPORT` allows rule name aliasing across modules: 1759 1760[source] 1761---- 1762rule IMPORT ( source_module ? : source_rules * 1763 : target_module ? : target_rules * ) 1764---- 1765 1766The `IMPORT` rule copies rules from the _source_module_ into the 1767_target_module_ as local rules. If either _source_module_ or 1768_target_module_ is not supplied, it refers to the global module. 1769_source_rules_ specifies which rules from the _source_module_ to import; 1770_target_rules_ specifies the names to give those rules in 1771_target_module_. If _source_rules_ contains a name which doesn't 1772correspond to a rule in _source_module_, or if it contains a different 1773number of items than _target_rules_, an error is issued. For example, 1774 1775[source] 1776---- 1777# import m1.rule1 into m2 as local rule m1-rule1. 1778IMPORT m1 : rule1 : m2 : m1-rule1 ; 1779# import all non-local rules from m1 into m2 1780IMPORT m1 : [ RULENAMES m1 ] : m2 : [ RULENAMES m1 ] ; 1781---- 1782 1783[[jam.language.modules.the__export__rule]] 1784==== The `EXPORT` Rule 1785 1786`EXPORT` allows rule name aliasing across modules: 1787 1788[source] 1789---- 1790rule EXPORT ( module ? : rules * ) 1791---- 1792 1793The `EXPORT` rule marks _rules_ from the `source_module` as non-local 1794(and thus exportable). If an element of _rules_ does not name a rule in 1795_module_, an error is issued. For example, 1796 1797[source] 1798---- 1799module X { 1800 local rule r { ECHO X.r ; } 1801} 1802IMPORT X : r : : r ; # error - r is local in X 1803EXPORT X : r ; 1804IMPORT X : r : : r ; # OK. 1805---- 1806 1807[[jam.language.modules.the__caller_module__rule]] 1808==== The `CALLER_MODULE` Rule 1809 1810[source] 1811---- 1812rule CALLER_MODULE ( levels ? ) 1813---- 1814 1815`CALLER_MODULE` returns the name of the module scope enclosing the call 1816to its caller (if levels is supplied, it is interpreted as an integer 1817number of additional levels of call stack to traverse to locate the 1818module). If the scope belongs to the global module, or if no such module 1819exists, returns the empty list. For example, the following prints "\{Y} 1820\{X}": 1821 1822[source] 1823---- 1824module X { 1825 rule get-caller { return [ CALLER_MODULE ] ; } 1826 rule get-caller's-caller { return [ CALLER_MODULE 1 ] ; } 1827 rule call-Y { return Y.call-X2 ; } 1828} 1829module Y { 1830 rule call-X { return X.get-caller ; } 1831 rule call-X2 { return X.get-caller's-caller ; } 1832} 1833callers = [ X.get-caller ] [ Y.call-X ] [ X.call-Y ] ; 1834ECHO {$(callers)} ; 1835---- 1836 1837[[jam.language.modules.the__delete_module__rule]] 1838==== The `DELETE_MODULE` Rule 1839 1840[source] 1841---- 1842rule DELETE_MODULE ( module ? ) 1843---- 1844 1845`DELETE_MODULE` removes all of the variable bindings and 1846otherwise-unreferenced rules from the given module (or the global 1847module, if no module is supplied), and returns their memory to the 1848system. 1849 1850NOTE: Though it won't affect rules that are currently executing until they 1851complete, `DELETE_MODULE` should be used with extreme care because it 1852will wipe out any others and all variable (including locals in that 1853module) immediately. Because of the way dynamic binding works, variables 1854which are shadowed by locals will not be destroyed, so the results can 1855be really unpredictable. 1856 1857[[jam.miscellaneous]] 1858== Miscellaneous 1859 1860[[jam.miscellaneous.diagnostics]] 1861=== Diagnostics 1862 1863In addition to generic error messages, `b2` may emit one of the 1864following: 1865 1866---- 1867warning: unknown rule X 1868---- 1869 1870A rule was invoked that has not been defined with an `actions` or 1871`rule` statement. 1872 1873---- 1874using N temp target(s) 1875---- 1876 1877Targets marked as being temporary (but nonetheless present) have been 1878found. 1879 1880---- 1881updating N target(s) 1882---- 1883 1884Targets are out-of-date and will be updated. 1885 1886---- 1887can't find N target(s) 1888---- 1889 1890Source files can't be found and there are no actions to create them. 1891 1892---- 1893can't make N target(s) 1894---- 1895 1896Due to sources not being found, other targets cannot be made. 1897 1898---- 1899warning: X depends on itself 1900---- 1901 1902A target depends on itself either directly or through its sources. 1903 1904---- 1905don't know how to make X 1906---- 1907 1908A target is not present and no actions have been defined to create it. 1909 1910---- 1911X skipped for lack of Y 1912---- 1913 1914A source failed to build, and thus a target cannot be built. 1915 1916---- 1917warning: using independent target X 1918---- 1919 1920A target that is not a dependency of any other target is being 1921referenced with `$(<)` or `$(>)`. 1922 1923---- 1924X removed 1925---- 1926 1927`B2` removed a partially built target after being interrupted. 1928 1929[[jam.miscellaneous.bugs__limitations]] 1930=== Bugs, Limitations 1931 1932For parallel building to be successful, the dependencies among files 1933must be properly spelled out, as targets tend to get built in a 1934quickest-first ordering. Also, beware of un-parallelizable commands that 1935drop fixed-named files into the current directory, like `yacc(1)` does. 1936 1937A poorly set `$(JAMSHELL)` is likely to result in silent failure. 1938 1939[[jam.miscellaneous.fundamentals]] 1940=== Fundamentals 1941 1942This section is derived from the official Jam documentation and from 1943experience using it and reading the Jambase rules. We repeat the 1944information here mostly because it is essential to understanding and 1945using Jam, but is not consolidated in a single place. Some of it is 1946missing from the official documentation altogether. We hope it will be 1947useful to anyone wishing to become familiar with Jam and the Boost build 1948system. 1949 1950* Jam `rules` are actually simple procedural entities. Think of them 1951as functions. Arguments are separated by colons. 1952* A Jam *target* is an abstract entity identified by an arbitrary 1953string. The built-in `DEPENDS` rule creates a link in the dependency 1954graph between the named targets. 1955* Note that the original Jam documentation for the built-in `INCLUDES` 1956rule is incorrect: `INCLUDES targets1 : targets2` causes everything that 1957depends on a member of 1958_targets1_ to depend on all members of _targets2_. It does this in an 1959odd way, by tacking _targets2_ onto a special tail section in the 1960dependency list of everything in _targets1_. It seems to be OK to create 1961circular dependencies this way; in fact, it appears to be the "right 1962thing to do" when a single build action produces both _targets1_ and 1963_targets2_. 1964* When a rule is invoked, if there are `actions` declared with the same 1965name as the rule, the actions are added to the updating actions for the 1966target identified by the rule's first argument. It is actually possible 1967to invoke an undeclared rule if corresponding actions are declared: the 1968rule is treated as empty. 1969* Targets (other than `NOTFILE` targets) are associated with paths in 1970the file system through a process called binding. Binding is a process 1971of searching for a file with the same name as the target (sans grist), 1972based on the settings of the target-specific `SEARCH` and `LOCATE` 1973variables. 1974* In addition to local and global variables, jam allows you to set a 1975variable `on` a target. Target-specific variable values can usually not 1976be read, and take effect only in the following contexts: 1977** In updating actions, variable values are first looked up `on` the 1978target named by the first argument (the target being updated). Because 1979Jam builds its entire dependency tree before executing actions, Jam 1980rules make target-specific variable settings as a way of supplying 1981parameters to the corresponding actions. 1982** Binding is controlled _entirely_ by the target-specific setting of 1983the `SEARCH` and `LOCATE` variables, as described here. 1984** In the special rule used for header file scanning, variable values 1985are first looked up `on` the target named by the rule's first argument 1986(the source file being scanned). 1987* The "bound value" of a variable is the path associated with the target 1988named by the variable. In build actions, the first two arguments are 1989automatically replaced with their bound values. Target-specific 1990variables can be selectively replaced by their bound values using the 1991`bind` action modifier. 1992* Note that the term "binding" as used in the Jam documentation 1993indicates a phase of processing that includes three sub-phases: 1994_binding_ (yes!), update determination, and header file scanning. The 1995repetition of the term "binding" can lead to some confusion. In 1996particular, the Modifying Binding section in the Jam documentation 1997should probably be titled "Modifying Update Determination". 1998* "Grist" is just a string prefix of the form <__characters__>. It is 1999used in Jam to create unique target names based on simpler names. For 2000example, the file name `test.exe` may be used by targets in separate 2001sub-projects, or for the debug and release variants of the "same" 2002abstract target. Each distinct target bound to a file called "test.exe" 2003has its own unique grist prefix. The Boost build system also takes full 2004advantage of Jam's ability to divide strings on grist boundaries, 2005sometimes concatenating multiple gristed elements at the beginning of a 2006string. Grist is used instead of identifying targets with absolute paths 2007for two reasons: 20081. The location of targets cannot always be derived solely from what 2009the user puts in a Jamfile, but sometimes depends also on the binding 2010process. Some mechanism to distinctly identify targets with the same 2011name is still needed. 20122. Grist allows us to use a uniform abstract identifier for each built 2013target, regardless of target file location (as allowed by setting 2014ALL_LOCATE_TARGET). 2015* When grist is extracted from a name with $(var:G), the result includes 2016the leading and trailing angle brackets. When grist is added to a name 2017with `$(var:G=expr)`, existing grist is first stripped. Then, if `expr` is 2018non-empty, leading <s and trailing >s are added if necessary to form an 2019expression of the form <expr2>; <expr2> is then prepended. 2020* When Jam is invoked it imports all environment variable settings into 2021corresponding Jam variables, followed by all command-line (-s...) 2022variable settings. Variables whose name ends in PATH, Path, or path are 2023split into string lists on OS-specific path-list separator boundaries 2024(e.g. ":" for UNIX and ";" for Windows). All other variables are split 2025on space (" ") boundaries. Boost Jam modifies that behavior by allowing 2026variables to be quoted. 2027* A variable whose value is an empty list or which consists entirely of 2028empty strings has a negative logical value. Thus, for example, code like 2029the following allows a sensible non-empty default which can easily be 2030overridden by the user: 2031+ 2032---- 2033MESSAGE ?\= starting jam... ; 2034if $(MESSAGE) { ECHO The message is: $(MESSAGE) ; } 2035---- 2036+ 2037If the user wants a specific message, he invokes jam with 2038`-sMESSAGE=message 2039 text`. If he wants no message, he invokes jam with 2040`-sMESSAGE=` and nothing at all is printed. 2041* The parsing of command line options in Jam can be rather unintuitive, 2042with regards to how other Unix programs accept options. There are two 2043variants accepted as valid for an option: 20441. `-xvalue`, and 20452. `-x value`. 2046