Jam has a number 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.
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.
As a simplification when specifying multi-level dependencies, targets2 depend on the optional targets3, and so on.
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:
Depends foo.o : foo.c ;
Includes foo.c : foo.h ;
"foo.o" depends on "foo.c" and "foo.h" in this example.
As a simplification when specifying multi-level dependencies, targets2 depend on the optional targets3, and so on.
Needs is very similar to rule Depends targets1 : targets2 [ : target3 ... targets9 ] ;. Like Depends, targets1 are dependent on targets2 having been built first. Unlike Depends, if targets2 are updated, targets1 do not build.
As a simplification when specifying multi-level dependencies, targets2 depend on the optional targets3, and so on.
The rules Always, Leaves, MightNotUpdate, NoCare, NotFile, NoUpdate, and Temporary modify the dependency graph so that Jam treats the targets differently during its target binding phase. See Binding Phase above. Normally, Jam 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:
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.
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.
Some targets may or may not update when their action is executed, such as export libraries for a Windows DLL. In order for Jam to process this behavior appropriately, the targets must be marked so their timestamps will be evaluated at the latest possible time during the Updating Phase.
Be aware that the MightNotUpdate calculation happens during the Updating Phase. This results in Jam possibly reporting target counts improperly.
Causes Jam to ignore targets that neither can be found nor have updating actions to build them. Normally for such targets Jam 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 Jam know that the included files may not exist. For example, if a #include is within an #ifdef, the included file may not actually be around.
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 Jam target "all" is a pseudotarget. In Jambase, NotFile is used to define several addition convenient pseudotargets.
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 rule MkDir DIRECTORY only cares that the target directory exists, not when it has last been updated.
ScanContents, the dependency cache must be enabled.Causes the file's contents to be scanned for differences on timestamp change. There are times when a file's timestamp changes, but its contents do not. Normally, a timestamp change will cause all dependent targets to be rebuilt. When ScanContents is applied to targets and one of those targets has a timestamp that changes, Jam will compare the contents of the target against the last build's contents, whose md5sum is stored in the dependency cache. If they are the same, no dependent targets are built. If they differ, the dependent target build occurs as it would have on just a timestamp change.
Be aware that the ScanContents calculation happens during the Updating Phase. This results in Jam possibly reporting target counts improperly.
Example: A build action generates a C++ header. There are three scenarios to make note of here:
ScanContents is applied to the generated header. When Jam builds the header, it checks the contents of the file against the previous build and realizes nothing has changed. Jam will short circuit the build of dependent targets, those that rely on the generated header, as the generated header did not change.ScanContents my_generated_header.h ;
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, Jam 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.
The "command line" of a target, not necessarily the command line sent to a target's action, is compared against the previous build's command line for the same target. If it differs, regardless of timestamps being equal, the target is rebuilt.
| TARGETS | One or more targets to set the COMMANDLINE string to. | |
| COMMANDLINE | A unique string to be compared against the last build. When different, the target is rebuilt. |
Example 1: During the last build, the #defines for somefile.cpp were -DMYDEFINE -DSOMEDEFINE. The user then alters the defines for somefile.cpp to be -DMYDEFINE -DYOURDEFINE. somefile.cpp file will be rebuilt, even if the timestamp hasn't changed.
UseCommandLine somefile.cpp : -DMYDEFINE -DYOURDEFINE ;
Example 2: The file format for .model files changes. It is desirable to cause the .model files to be rebuilt on the next build. This can be done by altering the 'command line' to be version2.
UseCommandLine $(TARGETS) : version2 ;
The remaining rules are utility rules.
Prints out the message ARGS to stdout.
Blurts out the message ARGS to stdout and then exits with a failure status.
Scans DIRECTORIES for files matching PATTERNS, returning the list of matching files (with directory prepended, unless the optional PREPEND is set to 0 or false). PATTERNS uses the same syntax as in the switch statement. Only useful within the [ ] construct, to change the result into a list.
On Windows, the glob matching is performed in a case insensitive manner.
| DIRECTORIES | The list of directories to perform the glob scan within. | |
| PATTERNS | The list of patterns to scan. | |
| PREPEND | (optional) If 1 (default), prepend the directory name. If 0, do not. |
# Returns all files and directories. Directories have a / appended. # Directories . and .. are not returned. Glob bin : * ; # Returns just directories. Glob bin : */ ; # Returns just files without bin/ prepended. Glob bin : *[^/] : 0;
Given a list of targets determined by the TARGETLIST_VARIABLE_NAME, those targets whose COMPARISON_SETTINGS_NAME contents match one another are grouped together and returned to the caller. The remaining targets are assigned back to TARGETLIST_VARIABLE_NAME.
The matched grouping is limited to the maximum number of targets specified via MAX_PER_GROUP.
| TARGETLIST_VARIABLE_NAME | The name of the variable containing the target list to obtain matching groups of targets from. It is not the actual list of targets. | |
| COMPARISON_SETTINGS_NAME | The setting used to obtain matches from COMPARISON_SETTINGS_NAME. | |
| MAX_PER_GROUP | (optional) The maximum number of targets to include in the group. If unspecified, there is no limit. |
files = targeta targetb targetc targetd targete targetf ;
FLAGS on targeta = a b c ;
FLAGS on targetb = a b c d ;
FLAGS on targetc = a b c ;
FLAGS on targetd = a b c e ;
FLAGS on targete = a b c ;
FLAGS on targetf = a b c ;
# Together - targeta targetc targete targetf <- because all FLAGS are: a b c
Echo Together - [ GroupByVar files : FLAGS ] ;
# Together - targetb <- only targetb has FLAGS: a b c d
Echo Together - [ GroupByVar files : FLAGS ] ;
# Together - targetd <- only targetd has FLAGS: a b c e
Echo Together - [ GroupByVar files : FLAGS ] ;
# files is empty at this point.
files = targeta targetb targetc targetd targete targetf ;
# (2 max) - targeta targetc
Echo (2 max) - [ GroupByVar files : FLAGS : 2 ] ;
# (2 max) - targetb
Echo (2 max) - [ GroupByVar files : FLAGS : 2 ] ;
# (2 max) - targetd
Echo (2 max) - [ GroupByVar files : FLAGS : 2 ] ;
# (2 max) - targete targetf
Echo (2 max) - [ GroupByVar files : FLAGS : 2 ] ;
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.
Calculates the result of the simple math equation of the form LEFT OPERATOR RIGHT. Useful only within the [ ] construct, to change the result into a list.
| LEFT | An integer for the left side of the equation. | |
| OPERATOR | + for addition, - for subtraction, * for multiplication, / for division, and % for modulus. | |
| RIGHT | An integer for the right side of the equation. |
Calculates the md5sum of all lists and their respective list elements. Each list element is separated with one NUL character, so that [ MD5 a b ] is different than [ MD5 ab ]. Each list is separated with two NUL characters so that [ MD5 a : b ] is different than [ MD5 a b ]. Only useful within the [ ] construct, to change the resultant md5sum into a list.
# Prints d41d8cd98f00b204e9800998ecf8427e. Echo [ MD5 "" ] ; # Returns c3fcd3d76192e4007dfb496cca67e13b. Echo [ MD5 "abcdefghijklmnopqrstuvwxyz" ] ;
Calculates the md5sum of all listed files. Only useful within the [ ] construct, to change the resultant md5sum into a list.
Echo [ MD5File "myfile.txt" ] ;
If the given generated TARGETS are already built and stored within the file cache CACHE_NAME, they are retrieved via a simple file copy, and no further build steps are initiated. If the TARGETS are not in the file cache, they are first generated locally via the prescribed build steps and then copied to the cache to be used in a future build. If the given target is not actually generated by a build step, it isn't copied to the file cache, and no error occurs.
| TARGETS | One or more targets to use the file cache for. | |
| CACHE_NAME | (optional) If not specified, defaults to generic. |
# Assign image.tga to the 'generic' file cache. OptionalFileCache image.tga ; # Assign image2.tga to the 'weapons' file cache. OptionalFileCache image2.tga : weapons ;
When QueueJamfile is called, another pass on the Jam dependency graph is initiated after the Updating Phase. Further documentation on this can be found on the Multiple Passes page.
Queued Jamfiles are processed in the order they are queued. There may be cases where the queued order does not allow for proper processing of the Jamfiles. In the event the Jamfile order matters for the upcoming pass, PRIORITY may be applied. When a priority isn't given, the default priority is 0. A queued Jamfile with priority of 100 will be parsed before a Jamfile with a priority of 0. Likewise, a queued Jamfile with a priority of -50 will be parsed after a Jamfile with a priority of 0.
| JAMFILE_LIST | A list of one or more Jamfiles to queue for the next pass. | |
| PRIORITY | (optional) A numeric priority. If not specified, the default is 0. |
# Queue Pass2.jam for the second pass. QueueJamfile Pass2.jam ; # Queue me_first.jam with a higher priority than me_second.jam. QueueJamfile me_second.jam ; # Priority of 0. QueueJamfile me_first.jam : 1000 ; # Parse me_first.jam and then me_second.jam.
The Shell rule is used to execute one or more COMMANDS and return the output to the user. Each command specified in the COMMANDS list is executed immediately, one after another. The results of a command execution are returned to the caller.
| COMMANDS | A list of one or more commands, each executed serially. |
# Copy file1.txt to file2.txt, ignoring output. Shell "copy file1.txt file2.txt" ; # Grab a directory listing. dir_listing = [ Shell dir ] ; # Grab two directory listings. dir_listings = [ Shell "dir *.tga" "dir *.png" ] Echo dir *.tga - $(dir_listings[1]) ; Echo dir *.png - $(dir_listings[2]) ;
Returns a copy of LIST in which all occurrences of the PATTERN have been replaced by a replacement string specified by REPL. Only useful within the [ ] construct, to change the result into a list.
The character % works as an escape character: any sequence in repl of the form n, with n between 1 and 9, stands for the value of the n-th captured substring (see below). The sequence 0 stands for the whole match. The sequence %% stands for a single %.
The optional last parameter n limits the maximum number of substitutions to occur. For instance, when n is 1 only the first occurrence of pattern is replaced.
| LIST | The list of strings to apply the regular expression substitution algorithm to. | |
| PATTERN | The regular expression pattern to search for within LIST. If the pattern is found, it is replaced with REPL. | |
| REPL | (optional) If specified, any patterns matched with PATTERN are replaced with the contents of REPL. If not specified, the replacement string is empty. | |
| MAXN | (optional) The maximum number of substitutions to occur. |
# __/__/dir/__/dir2 Echo [ Subst ../../dir/../dir2 : %.%. : __ ] ; # hello hello world world Echo [ Subst "hello world" : "(%w+)" : "%1 %1" ] ; # hello hello world Echo [ Subst "hello world" : "%w+" : "%0 %0" : 1 ] ; # world hello Lua from Echo [ Subst "hello world from Lua" : "(%w+)%s*(%w+)" : "%2 %1" ] ;
A character class is used to represent a set of characters. The following combinations are allowed in describing a character class:
x: (where x is not one of the magic characters
^$()%.[]*+-?) represents the character x itself.
.: (a dot) represents all characters.
a: represents all letters.
c: represents all control characters.
d: represents all digits.
l: represents all lowercase letters.
p: represents all punctuation characters.
s: represents all space characters.
u: represents all uppercase letters.
w: represents all alphanumeric characters.
x: represents all hexadecimal digits.
z: represents the character with representation 0.
%x: (where x is any non-alphanumeric character) represents the character x. This is the standard way to escape the magic characters. Any punctuation character (even the non magic) can be preceded by a '%' when used to represent itself in a pattern.
[set]:
represents the class which is the union of all characters in set. A range of characters may be specified by separating the end characters of the range with a '-'. All classes %x described above may also be used as components in set. All other characters in set represent themselves. For example, [w_] (or [_w]) represents all alphanumeric characters plus the underscore,
[0-7] represents the octal digits, and [0-7l-] represents the octal digits plus the lowercase letters plus the '-' character.
The interaction between ranges and classes is not defined. Therefore, patterns like [a-z] or [a-%%] have no meaning.
[^set]: represents the complement of set, where set is interpreted as above.
For all classes represented by single letters (a, c, etc.), the corresponding uppercase letter represents the complement of the class. For instance, S represents all non-space characters.
The definitions of letter, space, and other character groups depend on the current locale. In particular, the class [a-z] may not be equivalent to l.
A pattern item may be
a single character class, which matches any single character in the class;
a single character class followed by '*', which matches 0 or more repetitions of characters in the class. These repetition items will always match the longest possible sequence;
a single character class followed by '+', which matches 1 or more repetitions of characters in the class. These repetition items will always match the longest possible sequence;
a single character class followed by '-', which also matches 0 or more repetitions of characters in the class. Unlike '*', these repetition items will always match the shortest possible sequence;
a single character class followed by '?', which matches 0 or 1 occurrence of a character in the class;
%n, for n between 1 and 9; such item matches a substring equal to the n-th captured string (see below);
bxy, where x and y are two distinct characters; such item matches strings that start with x, end with y, and where the x and y are balanced. This means that, if one reads the string from left to right, counting +1 for an x and -1 for a y, the ending y is the first y where the count reaches 0. For instance, the item b() matches expressions with balanced parentheses.
A pattern is a sequence of pattern items. A '^' at the beginning of a pattern anchors the match at the beginning of the subject string. A '$' at the end of a pattern anchors the match at the end of the subject string. At other positions, '^' and '$' have no special meaning and represent themselves.
A pattern may contain sub-patterns enclosed in parentheses; they describe captures. When a match succeeds, the substrings of the subject string that match captures are stored (captured) for future use. Captures are numbered according to their left parentheses. For instance, in the pattern "(a*(.)%w(%s*))", the part of the string matching "a*(.)%w(%s*)" is stored as the first capture (and therefore has number 1); the character matching "<code>.</code>" is captured with number 2, and the part matching "<code>%s*</code>" has number 3.
As a special case, the empty capture () captures the current string position (a number). For instance, if we apply the pattern "()aa()" on the string "flaaap", there will be two captures: 3 and 5.
A pattern cannot contain embedded zeros. Use z instead.
Change the active dependency cache for the TARGETS. See Dependency Cache Usage for more information.
| TARGETS | One or more targets to change the active dependency cache on. | |
| CACHE_NAME | (optional) If not specified, the active dependency cache for the target reverts back to the global DEPCACHE. If specified, the TARGETS use CACHE_NAME as their new dependency cache. |
# Use the platform dependency cache. UseDepCache $(TARGETS) : platform ;
If the given generated TARGETS are already built and stored within the file cache CACHE_NAME, they are retrieved via a simple file copy, and no further build steps are initiated. If the TARGETS are not in the file cache, they are first generated locally via the prescribed build steps and then copied to the cache to be used in a future build.
| TARGETS | One or more targets to use the file cache for. | |
| CACHE_NAME | (optional) If not specified, defaults to generic. |
# Assign image.tga to the 'generic' file cache. UseFileCache image.tga ; # Assign image2.tga to the 'weapons' file cache. UseFileCache image2.tga : weapons ;
When a callback is assigned to TARGETS, a Lua function of the name specified in the parameter MD5_CALLBACK is called. It calculates the MD5 of the target and returns it.
| TARGETS | One or more targets to assign an MD5 callback to. | |
| MD5_CALLBACK | The name of a Lua function accepting a single parameter, the bound name of the target, and returning the md5sum. |
# Use the Lua function md5png to calculate the md5 for file1.png. UseMD5Callback file1.png : md5png ;
Returns a registry entry, given a list of KEYS.
| KEYS | A list of keys to look up in the registry. The first key may be one of the following: |
local key = HKEY_LOCAL_MACHINE SOFTWARE Microsoft VisualStudio 9.0 InstallDir ;
MSVCNT = [ W32_GETREG $(key) ] ;