$(/var/) /field1/ : /field2/ : /.../ : /fieldN/ ;on /target/ $(/var/) /field1/ : /field2/ : /.../ : /fieldN/ ;\[ $(/var/) /field1/ : /field2/ : /.../ : /fieldN/ \]\[ on /target/ $(/var/) /field1/ : /field2/ : /.../ : /fieldN/ \]]The variable's value names the rule (or rules) to be invoked. A rule isinvoked for each element in the list of [^$(/var/)]'s values. The fields[^/field1/ : /field2/ : /.../] are passed as arguments for eachinvokation. For the [ ... ] forms, the return value is the concatenation ofthe return values for all of the invocations.[section Action Modifiers]The following action modifiers are understood:[variablelist[[[^actions bind /vars/]] [[^$(/vars/)] will be replaced with bound values.]][[[^actions existing]] [[^$(>)] includes only source targets currently existing.]][[[^actions ignore]] [The return status of the commands is ignored.]][[[^actions piecemeal]] [commands are repeatedly invoked with a subset of [^$(>)] small enough to fit in the command buffer on this OS.]][[[^actions quietly]] [The action is not echoed to the standard output.]][[[^actions together]] [The [^$(>)] from multiple invocations of the same action on the same built target are glommed together.]][[[^actions updated]] [[^$(>)] includes only source targets themselves marked for updating.]]][endsect][section Argument lists]You can describe the arguments accepted by a rule, and refer to them by name within the rule. For example, the following prints "I'm sorry, Dave" to the console:[prerule report ( pronoun index ? : state : names + ){    local he.suffix she.suffix it.suffix = s ;    local I.suffix = m ;    local they.suffix you.suffix = re ;    ECHO $(pronoun)'$($(pronoun).suffix) $(state), $(names\[$(index)\]) ;}report I 2 : sorry : Joe Dave Pete ;]Each name in a list of formal arguments (separated by "=:=" in the rule declaration) is bound to a single element of the corresponding actual argument unless followed by one of these modifiers:[table[[Symbol] [Semantics of preceding symbol]][[=?=] [optional]][[=*=] [Bind to zero or more unbound elements of the actual argument. When =*= appears where an argument name is expected, any number of additional arguments are accepted. This feature can be used to implement "varargs" rules.]][[=+=] [Bind to one or more unbound elements of the actual argument.]]]The actual and formal arguments are checked for inconsistencies, which cause Jam to exit with an error code:[pre### argument error# rule report ( pronoun index ?  : state  : names + )# called with: ( I 2 foo  : sorry  : Joe Dave Pete )# extra argument foo### argument error# rule report ( pronoun index ?  : state  : names + )# called with: ( I 2  : sorry )# missing argument names]If you omit the list of formal arguments, all checking is bypassed as in "classic" Jam. Argument lists drastically improve the reliability and readability of your rules, however, and are *strongly recommended* for any new Jam code you write.[endsect][section:builtins Built-in Rules]=BJam= has a growing set of built-in rules, all of which are pure procedure rules without updating actions. They are in three groups: the first builds the dependency graph; the second modifies it; and the third are just utility rules.[section Dependency Building][section =DEPENDS= ][prerule DEPENDS ( /targets1/ * : /targets2/ * )]Builds a direct dependency: makes each of /targets1/ depend on each of /targets2/. Generally, /targets1/ will be rebuilt if /targets2/ are themselves rebuilt are or are newer than /targets1/.[endsect][section =INCLUDES= ][prerule INCLUDES ( /targets1/ * : /targets2/ * )]Builds a sibling dependency: makes any target that depends on any of /targets1/ also depend on each of /targets2/. This reflects the dependencies that arise when one source file includes another: the object built from the source file depends both on the original and included source file, but the two sources files don't depend on each other. For example:[preDEPENDS foo.o : foo.c ;INCLUDES foo.c : foo.h ;]"=foo.o=" depends on "=foo.c=" and "=foo.h=" in this example.[endsect][endsect][section Modifying Binding]The six rules =ALWAYS=, =LEAVES=, =NOCARE=, =NOTFILE=, =NOUPDATE=, and =TEMPORARY= modify the dependency graph so that =bjam= treats the targets differently during its target binding phase. See Binding above. Normally, =bjam= updates a target if it is missing, if its filesystem modification time is older than any of its dependencies (recursively), or if any of its dependencies are being updated. This basic behavior can be changed by invoking the following rules:[section =ALWAYS= ][prerule ALWAYS ( /targets/ * )]Causes /targets/ to be rebuilt regardless of whether they are up-to-date (they must still be in the dependency graph). This is used for the clean and uninstall targets, as they have no dependencies and would otherwise appear never to need building. It is best applied to targets that are also =NOTFILE= targets, but it can also be used to force a real file to be updated as well.[endsect][section =LEAVES= ][prerule LEAVES ( /targets/ * )]Makes each of /targets/ depend only on its leaf sources, and not on any intermediate targets. This makes it immune to its dependencies being updated, as the "leaf" dependencies are those without their own dependencies and without updating actions. This allows a target to be updated only if original source files change.[endsect][section =NOCARE= ][prerule NOCARE ( /targets/ * )]Causes =bjam= to ignore /targets/ that neither can be found nor have updating actions to build them. Normally for such targets =bjam= issues a warning and then skips other targets that depend on these missing targets. The =HdrRule= in =Jambase= uses =NOCARE= on the header file names found during header file scanning, to let =bjam= know that the included files may not exist. For example, if an `#include` is within an `#ifdef`, the included file may not actually be around.[warning For targets with build actions: if their build actions exit with a nonzero return code, dependent targets will still be built.][endsect][section =NOTFILE= ][prerule NOTFILE ( /targets/ * )]Marks /targets/ as pseudotargets and not real files. No timestamp is checked, and so the actions on such a target are only executed if the target's dependencies are updated, or if the target is also marked with =ALWAYS=. The default =bjam= target "=all=" is a pseudotarget. In =Jambase=, =NOTFILE= is used to define several addition convenient pseudotargets.[endsect][section =NOUPDATE= ][prerule NOUPDATE ( /targets/ * )]Causes the timestamps on /targets/ to be ignored. This has two effects: first, once the target has been created it will never be updated; second, manually updating target will not cause other targets to be updated. In =Jambase=, for example, this rule is applied to directories by the =MkDir= rule, because =MkDir= only cares that the target directory exists, not when it has last been updated.[endsect][section =TEMPORARY= ][prerule TEMPORARY ( /targets/ * )]Marks /targets/ as temporary, allowing them to be removed after other targets that depend upon them have been updated. If a =TEMPORARY= target is missing, =bjam= uses the timestamp of the target's parent. =Jambase= uses =TEMPORARY= to mark object files that are archived in a library after they are built, so that they can be deleted after they are archived.[endsect][section =FAIL_EXPECTED= ][prerule FAIL_EXPECTED ( /targets/ * )]For handling targets whose build actions are expected to fail (e.g. when testing that assertions or compile-time type checkin work properly), Boost Jam supplies the =FAIL_EXPECTED= rule in the same style as =NOCARE=, et. al. During target updating, the return code of the build actions for arguments to =FAIL_EXPECTED= is inverted: if it fails, building of dependent targets continues as though it succeeded. If it succeeds, dependent targets are skipped.[endsect][section =RMOLD= ][prerule RMOLD ( /targets/ * )]=BJam= removes any target files that may exist on disk when the rule used to build those targets fails. However, targets whose dependencies fail to build are not removed by default. The =RMOLD= rule causes its arguments to be removed if any of their dependencies fail to build.[endsect][section =ISFILE= ][prerule ISFILE ( /targets/ * )]=ISFILE= marks targets as required to be files. This changes the way =bjam= searches for the target such that it ignores mathes for file system items that are not file, like directories. This makes it possible to avoid `#include "exception"` matching if one happens to have a directory named exception in the header search path.[warning This is currently not fully implemented.][endsect][endsect][section Utility]The two rules =ECHO= and =EXIT= are utility rules, used only in =bjam='s parsing phase.[section =ECHO= ][prerule ECHO ( /args/ * )]Blurts out the message /args/ to stdout.[endsect][section =EXIT= ][prerule EXIT ( /message/ * : /result-value/ ? )]Blurts out the /message/ to stdout and then exits with a failure status if no /result-value/ is given, otherwise it exits with the given /result-value/."=Echo=", "=echo=", "=Exit=", and "=exit=" are accepted as aliases for =ECHO= and =EXIT=, since it is hard to tell that these are built-in rules and not part of the language, like "=include=". [endsect][section =GLOB= ]The =GLOB= rule does filename globbing.[prerule GLOB ( /directories/ * : /patterns/ * : /downcase-opt/ ? )]Using the same wildcards as for the patterns in the switch statement. It is invoked by being used as an argument to a rule invocation inside of "=[ ]=". For example: "[^FILES = \[ GLOB dir1 dir2 : *.c *.h \]]" sets =FILES= to the list of C source and header files in =dir1= and =dir2=. The resulting filenames are the full pathnames, including the directory, but the pattern is applied only to the file name without the directory.If /downcase-opt/ is supplied, filenames are converted to all-lowercase before matching against the pattern; you can use this to do case-insensitive matching using lowercase patterns. The paths returned will still have mixed case if the OS supplies them. On Windows NT and Cygwin, filenames are always downcased before matching. [endsect][section =MATCH= ]The =MATCH= rule does pattern matching.[prerule MATCH ( /regexps/ + : /list/ * )]Matches the =egrep=(1) style regular expressions /regexps/ against the strings in /list/. The result is the concatenation of matching =()= subexpressions for each string in /list/, and for each regular expression in /regexps/. Only useful within the "=[ ]=" construct, to change the result into a list.[endsect][section =BACKTRACE= ][prerule BACKTRACE ( )]Returns a list of quadruples: /filename/ /line/ /module/ /rulename/..., describing each shallower level of the call stack. This rule can be used to generate useful diagnostic messages from Jam rules.[endsect][section =UPDATE= ][prerule UPDATE ( /targets/ * )]Classic jam treats any non-option element of command line as a name of target to be updated. This prevented more sophisticated handling of command line. This is now enabled again but with additional changes to the =UPDATE= rule to allow for the flexibility of changing the list of targets to update. The UPDATE rule has two effects:# It clears the list of targets to update, and# Causes the specified targets to be updated.If no target was specified with the =UPDATE= rule, no targets will be updated. To support changing of the update list in more usefull ways, the rule also returns the targets previously in the update list. This makes it possible to add targets as such:[prelocal previous-updates = \[ UPDATE \] ;UPDATE $(previous-updates) a-new-target ;][endsect][section =W32_GETREG= ][prerule W32_GETREG ( /path/ : /data/ ? )]Defined only for win32 platform. It reads the registry of Windows. '/path/' is the location of the information, and '/data/' is the name of the value which we want to get. If '/data/' is omitted, the default value of '/path/' will be returned. The '/path/' value must conform to MS key path format and must be prefixed with one of the predefined root keys. As usual,* '=HKLM=' is equivalent to '=HKEY_LOCAL_MACHINE='.* '=HKCU=' is equivalent to '=HKEY_CURRENT_USER='.* '=HKCR=' is equivalent to '=HKEY_CLASSES_ROOT='.Other predefined root keys are not supported.Currently supported data types : '=REG_DWORD=', '=REG_SZ=', '=REG_EXPAND_SZ=', '=REG_MULTI_SZ='. The data with '=REG_DWORD=' type will be turned into a string, '=REG_MULTI_SZ=' into a list of strings, and for those with '=REG_EXPAND_SZ=' type environment variables in it will be replaced with their defined values. The data with '=REG_SZ=' type and other unsupported types will be put into a string without modification. If it can't receive the value of the data, it just return an empty list. For example,[prelocal PSDK-location =  \[ W32_GETREG HKEY_LOCAL_MACHINE\\\\SOFTWARE\\\\Microsoft\\\\MicrosoftSDK\\\\Directories : "Install Dir" \] ;][endsect][section =W32_GETREGNAMES= ][prerule W32_GETREGNAMES ( /path/ : /result-type/ )]