[   [] []    [[lines        [line [@http://www.tru64unix.compaq.com/cplus/ =true64cxx=]]        [line Compaq C++ Compiler for True64 UNIX]        ]]    [[list        [li =uname= is "=OSF1="]        ]]][   [] []    [[lines        [line [@http://www-306.ibm.com/software/awdtools/vacpp/ =vacpp=]]        [line IBM VisualAge C++]        ]]    [[list        [li =xlc= in =PATH=]        ]]][   [] [MacOS X]    [[lines        [line [@http://developer.apple.com/tools/compilers.html =darwin=]]        [line Apple MacOS X GCC]        ]]    [[list        [li =uname= is "=Darwin="]        ]]][   [] [Windows NT, 2000, and XP]    [[lines        [line [@http://www.mingw.org/ =mingw=]]        [line GNU [@http://gcc.gnu.org/ GCC] as the [@http://www.mingw.org/ MinGW] configuration with the MSYS shell]        ]]    [[list        [li Common install location: "=/mingw="]        ]]]]The built executables are placed in a subdirectory specific to your platform. For example, in Linux running on an Intel x86 compatible chip, the executables are placed in: "=bin.linuxx86=". The =bjam[.exe]= executable can be used to invoke Boost.Build.The build scripts support additional invocation arguments for use by developers of Boost.Jam and for additional setup of the toolset. The extra arguments come after the toolset:* Arguments not in the form of an option, before option arguments, are used for extra setup to toolset configuration scripts.* Arguments of the form "=--option=", which are passed to the =build.jam= build script.* Arguments not in the form of an option, after the options, which are targets for the =build.jam= script.[pre/build/ \[/toolset/\] \[/setup/\*\] \[--/option/+ /target/\*\]]The arguments immediately after the toolset are passed directly to the setup script of the toolset, if available and if it needs to be invoked. This allows one to configure the toolset ass needed to do non-default builds of =bjam=. For example to build a Win64 version with =vc8=. See the toolset descriptiona above for when particular toolsets support this.The arguments starting with the "=--option=" forms are passed to the =build.jam= script and are used to further customize what gets built. Options and targets supported by the =build.jam= script:[variablelist    [[[^---]]        [Empty option when one wants to only specify a target.]]    [[[^--release]]        [The default, builds the optimized executable.]]    [[[^--debug]]        [Builds debugging versions of the executable. When built they are placed in their own directory "=bin./platform/.debug=".]]    [[[^--grammar]]        [Normally the Jam language grammar parsing files are not regenerated. This forces building of the grammar, although it may not force the regeneration of the grammar parser. If the parser is out of date it will be regenerated and subsequently built.]]    [[[^--with-python=/path/]]        [Enables Python integration, given a path to the Python libraries.]]    [[[^--gc]]        [Enables use of the Boehm Garbage Collector. The build will look for the Boehm-GC source in a "boehm_gc" subdirectory from the =bjam= sources.]]    [[[^--duma]]        [Enables use of the DUMA (Detect Uintended Memory Access) debugging memory allocator. The build expects to find the DUMA source files in a "duma" subdirectory from the =bjam= sources.]]    [[[^--toolset-root=/path/]]        [Indicates where the toolset used to build is located. This option is passed in by the bootstrap (=build.bat= or =build.sh=) script.]]    [[[^--show-locate-target]]        [For information, prints out where it will put the built executable.]]    [[[^--noassert]]        [Disable debug assertions, even if building the debug version of the executable.]]    [[[^dist]]        [Generate packages (compressed archives) as appropriate for distribution in the platform, if possible.]]    [[[^clean]]        [Remove all the built executables and objects.]]][endsect][section:usage Using BJam]If /target/ is provided on the command line, =bjam=  builds /target/; otherwise =bjam= builds the target =all=.[prebjam ( -option \[value\] | target ) *][section:options Options]Options are either singular or have an accompanying value. When a value is allowed, or required, it can be either given as an argument following the option argument, or it can be given immediately after the option as part of the option argument. The allowed options are:[variablelist    [ [[^-a]]    [Build all targets anyway, even if they are up-to-date.] ]    [ [[^-d'''&nbsp;'''/n/]]    [    Enable cummulative debugging levels from 1 to n. Values are:        [orderedlist        [li Show the actions taken for building targets, as they are executed (the default).]        [li Show "quiet" actions and display all action text, as they are executed.]        [li Show dependency analysis, and target/source timestamps/paths.]        [li Show arguments and timming of shell invocations.]        [li Show rule invocations and variable expansions.]        [li Show directory/header file/archive scans, and attempts at binding to targets.]        [li Show variable settings.]        [li Show variable fetches, variable expansions, and evaluation of '"if"' expressions.]        [li Show variable manipulation, scanner tokens, and memory usage.]        [li Show profile information for rules, both timing and memory.]        [li Show parsing progress of Jamfiles.]        [li Show graph of target dependencies.]        [li Show change target status (fate).]        ]    ] ]    [ [[^-d'''&nbsp;'''+/n/]]    [Enable debugging level /n/.] ]    [ [[^-d'''&nbsp;'''0]]    [Turn off all debugging levels. Only errors are reported.] ]    [ [[^-f'''&nbsp;'''/Jambase/]] [Read /Jambase/ instead of using the built-in    Jambase. Only one -f flag is permitted, but the /Jambase/ may explicitly    include other files. A /Jambase/ name of "-" is allowed, in which case    console input is read until it is closed, at which point the input is    treated as the Jambase.] ]    [ [[^-j'''&nbsp;'''/n/]]    [Run up to /n/ shell commands concurrently (UNIX and NT only). The default is 1.] ]    [ [[^-l'''&nbsp;'''/n/]]    [Limit actions to running for /n/ number of seconds, after which they are stopped. Note: Windows only.] ]    [ [[^-n]]    [Don't actually execute the updating actions, but do everything else. This changes the debug level default to =-d 2=.] ]    [ [[^-o'''&nbsp;'''/file/]]    [Write the updating actions to the specified file instead of running them.] ]    [ [[^-q]]    [Quit quickly (as if an interrupt was received) as soon as *any* target fails.] ]    [ [[^-s'''&nbsp;'''/var/=/value/]]    [Set the variable /var/ to /value/, overriding both internal variables and variables imported from the environment.] ]    [ [[^-t'''&nbsp;'''/target/]]    [Rebuild /target/ and everything that depends on it, even if it is up-to-date.] ]    [ [[^--'''&nbsp;'''/value/]]    [The option and /value/ is ignored, but is available from the =$(ARGV)= variable. ]]    [ [[^-v]]    [Print the version of =bjam= and exit.] ]][section Command-line and Environment Variable Quoting]Classic Jam had an odd behavior with respect to command-line variable (=-s...=) and environment variable settings which made it impossible to define an arbitrary variable with spaces in the value. Boost Jam remedies that by treating all such settings as a single string if they are surrounded by double-quotes. Uses of this feature can look interesting, since shells require quotes to keep characters separated by whitespace from being treated as separate arguments:[prejam -sMSVCNT="\\"\\"C:\\Program Files\\Microsoft Visual C++\\VC98\\"\\"" ...]The outer quote is for the shell. The middle quote is for Jam, to tell it to take everything within those quotes literally, and the inner quotes are for the shell again when paths are passed as arguments to build actions. Under NT, it looks a lot more sane to use environment variables before invoking jam when you have to do this sort of quoting:[preset MSVCNT=""C:\\Program Files\\Microsoft Visual C++\\VC98\\""][endsect][endsect][section:operation Operation]BJam has four phases of operation: start-up, parsing, binding, and updating.[section:startup Start-up]Upon start-up, =bjam= imports environment variable settings into =bjam= variables. Environment variables are split at blanks with each word becoming an element in the variable's list of values. Environment variables whose names end in =PATH= are split at =$(SPLITPATH)= characters (e.g., =":"= for Unix).To set a variable's value on the command line, overriding the variable's environment value, use the =-s= option. To see variable assignments made during bjam's execution, use the =-d+7= option.The Boost.Build v2 initialization behavior has been implemented. This behavior only applies when the executable being invoked is called "=bjam=" or, for backward-compatibility, when the =BOOST_ROOT= variable is set.#   We attempt to load "=boost-build.jam=" by searching from the current invocation directory up to the root of the file system. This file is expected to invoke the =boost-build= rule to indicate where the Boost.Build system files are, and to load them.#   If =boost-build.jam= is not found we error and exit, giving brief instructions on possible errors. As a backward-compatibility measure for older versions of Boost.Build, when the =BOOST_ROOT= variable is set, we first search for =boost-build.jam= in =$(BOOST_ROOT)/tools/build= and =$(BOOST_BUILD_PATH)=. If found, it is loaded and initialization is complete. #   The =boost-build= rule adds its (optional) argument to the front of =BOOST_BUILD_PATH=, and attempts to load =bootstrap.jam= from those directories. If a relative path is specified as an argument, it is treated as though it was relative to the =boost-build.jam= file.#   If the =bootstrap.jam= file was not found, we print a likely error message and exit.[endsect][section:parsing Parsing]In the parsing phase, =bjam= reads and parses the =Jambase= file, by default the built-in one. It is written in the [link jam.language jam language]. The last action of the =Jambase= is to read (via the "include" rule) a user-provided file called "=Jamfile=".Collectively, the purpose of the =Jambase= and the =Jamfile= is to name build targets and source files, construct the dependency graph among them, and associate build actions with targets. The =Jambase= defines boilerplate rules and variable assignments, and the =Jamfile= uses these to specify the actual relationship among the target and source files.[endsect][section:binding Binding]After parsing, =bjam= recursively descends the dependency graph and binds every file target with a location in the filesystem. If =bjam= detects a circular dependency in the graph, it issues a warning.File target names are given as absolute or relative path names in the filesystem. If the path name is absolute, it is bound as is. If the path name is relative, it is normally bound as is, and thus relative to the current directory. This can be modified by the settings of the =$(SEARCH)= and =$(LOCATE)= variables, which enable jam to find and build targets spread across a directory tree. See [link jam.language.variables.builtins.search SEARCH and LOCATE Variables] below.[section:fate Update Determination]After binding each target, =bjam= determines whether the target needs updating, and if so marks the target for the updating phase. A target is normally so marked if it is missing, it is older than any of its sources, or any of its sources are marked for updating. This behavior can be modified by the application of special built-in rules, =ALWAYS=, =LEAVES=, =NOCARE=, =NOTFILE=, =NOUPDATE=, and =TEMPORARY=. See [link jam.language.rules.builtins.modifying_binding Modifying Binding] below.[endsect][section:headerscan Header File Scanning]During the binding phase, =bjam= also performs header file scanning, where it looks inside source files for the implicit dependencies on other files caused by C's #include syntax. This is controlled by the special variables $(HDRSCAN) and $(HDRRULE). The result of the scan is formed into a rule invocation, with the scanned file as the target and the found included file names as the sources. Note that this is the only case where rules are invoked outside the parsing phase. See [link jam.language.variables.builtins.hdrscan HDRSCAN and HDRRULE Variables] below.[endsect][endsect][section:updating Updating]After binding, =bjam= again recursively descends the dependency graph, this time executing the update actions for each target marked for update during the binding phase. If a target's updating actions fail, then all other targets which depend on that target are skipped.The =-j= flag instructs =bjam= to build more than one target at a time. If there are multiple actions on a single target, they are run sequentially.[endsect][endsect][endsect][section:language Language]=BJam= has an interpreted, procedural language. Statements in =bjam= are rule (procedure) definitions, rule invocations, flow-of-control structures, variable assignments, and sundry language support.[section:lexical Lexical Features]=BJam= treats its input files as whitespace-separated tokens, with two exceptions: double quotes (") can enclose whitespace to embed it into a token, and everything between the matching curly braces ({}) in the definition of a rule action is treated as a single string. A backslash (\\) can escape a double quote, or any single whitespace character.=BJam= requires whitespace (blanks, tabs, or newlines) to surround all tokens, including the colon (:) and semicolon (;) tokens.=BJam= keywords (an mentioned in this document) are reserved and generallymust be quoted with double quotes (") to be used as arbitrary tokens, such asvariable or target names. Comments start with the [^#] character and extend until the end of line.[endsect][section:target Targets]The essential =bjam= data entity is a target. Build targets are files to be updated. Source targets are the files used in updating built targets. Built targets and source targets are collectively referred to as file targets, and frequently built targets are source targets for other built targets. Pseudotargets are symbols which represent dependencies on other targets, but which are not themselves associated with any real file.A file target's identifier is generally the file's name, which can be absolutely rooted, relative to the directory of =bjam='s invocation, or simply local (no directory). Most often it is the last case, and the actual file path is bound using the =$(SEARCH)= and =$(LOCATE)= special variables. See [link jam.language.variables.builtins.search SEARCH and LOCATE Variables] below. A local filename is optionally qualified with grist, a string value used to assure uniqueness. A file target with an identifier of the form /file(member)/ is a library member (usually an =ar=(1) archive on Unix).[section Binding Detection]Whenever a target is bound to a location in the filesystem, Boost Jam will look for a variable called =BINDRULE= (first "on" the target being bound, then in the global module). If non-empty, =$(BINDRULE[1])= names a rule which is called with the name of the target and the path it is being bound to. The signature of the rule named by =$(BINDRULE[1])= should match the following:[prerule /bind-rule/ ( /target/ : /path/ )]This facility is useful for correct header file scanning, since many compilers will search for `#include` files first in the directory containing the file doing the `#include` directive. =$(BINDRULE)= can be used to make a record of that directory.[endsect][endsect][section:rules Rules]The basic =bjam= language entity is called a rule. A rule is defined in two parts: the procedure and the actions. The procedure is a body of jam statements to be run when the rule is invoked; the actions are the OS shell commands to execute when updating the built targets of the rule.Rules can return values, which can be expanded into a list with "[ /rule/ /args/ ... ]". A rule's value is the value of its last statement, though only the following statements have values: 'if' (value of the leg chosen), 'switch' (value of the case chosen), set (value of the resulting variable), and 'return' (value of its arguments). Note that 'return' doesn't actually cause a return, i.e., is a no-op unless it is the last statement of the last block executed within rule body.The =bjam= statements for defining and invoking rules are as follows:Define a rule's procedure, replacing any previous definition.[prerule /rulename/ { /statements/ }]Define a rule's updating actions, replacing any previous definition.[preactions \[ /modifiers/ \] /rulename/ { /commands/ }]Invoke a rule.[pre/rulename/ /field1/ : /field2/ : /.../ : /fieldN/ ;]Invoke a rule under the influence of target's specific variables..[preon /target/ /rulename/ /field1/ : /field2/ : /.../ : /fieldN/ ;]Used as an argument, expands to the return value of the rule invoked.[pre\[ /rulename/ /field1/ : /field2/ : /.../ : /fieldN/ \]\[ on /target/ /rulename/ /field1/ : /field2/ : /.../ : /fieldN/ \]]A rule is invoked with values in /field1/ through /fieldN/. They may be referenced in the procedure's statements as [^$(1)] through [^$(['N])] (9 max), and the first two only may be referenced in the action's /commands/ as [^$(1)] and [^$(2)]. [^$(<)] and [^$(>)] are synonymous with [^$(1)] and [^$(2)].Rules fall into two categories: updating rules (with actions), and pure procedure rules (without actions). Updating rules treat arguments [^$(1)] and [^$(2)] as built targets and sources, respectively, while pure procedure rules can take arbitrary arguments.When an updating rule is invoked, its updating actions are added to those associated with its built targets ([^$(1)]) before the rule's procedure is run. Later, to build the targets in the updating phase, /commands/ are passed to the OS command shell, with [^$(1)] and [^$(2)] replaced by bound versions of the target names. See Binding above.Rule invocation may be indirected through a variable:[pre