|
JamPlus manual
|
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:
"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, ForceCare, 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.
Causes Jam to care again about targets that neither can be found nor have updating actions to build them. Standard Jam behavior applies here, a warning will be issues and other targets depending on the missing targets will be skipped.
ForceCare is needed to override a NoCare flag applied to a target. Note that once ForceCare has been applied to a given target, that target can never be a NoCare target again.
ForceContentsOnly, JAM_CHECKSUMS must be set to 1.Normally, a target's build checksum accumulates a dependency's build checksum also. This may be undesirable in some situations. Use ForceContentsOnly to use the target's content checksum instead of the build checksum.
See Building with Checksums for more information.
IgnoreContents, JAM_CHECKSUMS must be set to 1.Instead of considering the contents of targets for inclusion into the build checksum, the contents of the targets are ignored.
See Building with Checksums for more information.
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.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 remaining rules are utility rules.
Copies SOURCE to TARGET, potentially modifying its contents during the transfer.
While processing the text lines of SOURCE, text found in the form ${VAR} (or $(VAR) if parens is specified in OPTIONS) are replaced with the current value of the variable within Jam. If the variable doesn't exist, ${VAR} is replaced with an empty string.
ConfigureFileHelper is based on input formats for CMake's configure_file function. As such, input lines containing:
will be replaced with the following if VAR is defined:
or if VAR is not defined, a line of this format will be output:
| TARGET | The destination target for the expansion copy. |
| SOURCE | The source file target to expansion copy from. |
| OPTIONS | (optional) May be noexpand, in which case no variable expansion is performed when copying from SOURCE to TARGET. Can also specify parens to use $(VAR) as the replacement format instead of ${VAR}. |
DebugSuppressMakeText makes Jam be more quiet by turning DEBUG_MAKE, DEBUG_MAKE0, and DEBUG_EXEC off.
DependsList takes the list of PARENT_TARGETS and returns all of the direct child dependency target names.
| PARENT_TARGETS | A list of parent targets to derive child dependencies from. There is generally only one parent in this list. |
Prints out the message ARGS to stdout.
Prints out the message ARGS to stdout and then exits with a failure status.
ExpandFileList takes a list of files or including glob-capable wildcards and expands them. The result of the expansion is returned to the user.
If ABSOLUTE is specified, then the result(s) of the wildcard expansion will rooted against SEARCH_SOURCE.
| WILDCARDS | A list of files or Glob-capable wildcards. |
| ABSOLUTE | Whether to root the result of the wildcard expansion against SEARCH_SOURCE. Set to 1 or true to enable it. |
| SEARCH_SOURCE | A directory to root the WILDCARDS against. |
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. |
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. |
Sorts the provided LIST in either a case sensitive or case insensitive fashion.
| LIST | The list of strings to be sorted. |
| CASE_INSENSITIVE | 0 for case insensitive, 1 for case sensitive. Case sensitive is the default. |
Changes INPUT_PATHS into relative paths from START_PATH.
| INPUT_PATHS | The list of input paths to be converted to relative format, if possible. |
| START_PATH | The path to change INPUT_PATHS to relative against. |
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. Alternatively, use a less-than symbol, greater-than symbol, or equals symbol to test the LEFT and RIGHT number relationship. |
| 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.
Calculates the md5sum of all listed files. Only useful within the [ ] construct, to change the resultant md5sum into a list.
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. |
Quickly looks up a single setting from from a TARGET. This is generally much faster than using the syntax:
QuickSettingsLookup can also be achieved by using the expansion modifier :Z=.
| TARGET | The target to look up the SYMBOL within. |
| SYMBOL | The name of the symbol to lookup within TARGET. |
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. |
Determines whether RULE_NAME exists.
| RULE_NAME | The name of the rule whose existence is to be determined. |
true if the rule exists, an empty list otherwise.Determines whether TARGET exists, and, if so, returns the bound filename using all LOCATE and SEARCH and other facilities available.
| TARGET | The target to search for. |
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. |
Splits each of the STRINGS at SPLIT_CHARACTERS. All splits are returned as a string list.
| STRINGS | The list of strings to split at the points specified by SPLIT_CHARACTERS. |
| SPLIT_CHARACTERS | One or more characters to split the list of STRINGS at. |
SPLIT_CHARACTERS.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. |
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.
Returns an escaped version of LITERAL_PATTERN that is suitable to be passed to the Subst rule. That is, any special character used for matching in the Subst rule is escaped with a percent sign.
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.
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.
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. |
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. |
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. |
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: |
Wildcard takes a list of files or including glob-capable wildcards and expands them. The result of the expansion is returned to the user.
If ABSOLUTE is specified, then the result(s) of the wildcard expansion will rooted against SEARCH_SOURCE.
| WILDCARDS | A list of files or Glob-capable wildcards. |
| ABSOLUTE | Whether to root the result of the wildcard expansion against SEARCH_SOURCE. Set to 1 or true to enable it. |
| SEARCH_SOURCE | A directory to root the WILDCARDS against. |