- Table of Contents
- 1. Overview
- 2. Lexical Features
- 3. Datatype
- 4. Rules
- 5. Updating Actions
- 6. Statements
- 7. Variables
- 8. Variable expansion
- 9. Built-in Rules
- 10. Built-in Variables
- List of Tables
- 10-1. Values of $(OS)
- List of Examples
- 3-1. One-dimensional list
- 4-1. Rule example
Chapter 1. Overview
Jam has a interpreted, procedural language with a few select features to effect program construction. Statements in jam are rule (procedure) definitions, rule invocations, updating action definitions, flow-of-control structures, variable assignments, and sundry language support.
Chapter 2. Lexical Features
Jam treats its input files as whitespace-separated tokens, with two exceptions:
double quotes (") can enclose whitespace to embed it into a token
everything between the matching curly braces ({}) in the definition of a updating actions is treated as a single string
A backslash (\) can escape a double quote, or any single whitespace character.
Jam requires whitespace (blanks, tabs, or newlines) to surround all tokens, including the colon (:) and semicolon (;) tokens.
Jam keywords (as mentioned in this document) are reserved and generally must be quoted with double quotes (") to be used as arbitrary tokens, such as variable or target names.
Chapter 3. Datatype
Jam's only data type is a one-dimensional list of arbitrary strings. They arise as literal (whitespace-separated) tokens in the Jambase or included files, as the result of variable expansion of those tokens, or as the return value from a rule invocation.
Chapter 4. Rules
The basic jam language entity is called a rule. A rule is simply a procedure definition, with a body of jam statements to be run when the rule is invoked. The syntax of rule invocation make it possible to write Jamfiles that look a bit like Makefiles.
Rules take up to 9 arguments ($(1) through $(9), each a list) and can have a return value (a single list). A rule's return value can be expanded in a list by enclosing the rule invocation with [ and ]
Chapter 5. Updating Actions
A rule may have updating actions associated with it, in which case arguments $(1) and $(2) are treated as built targets and sources, respectively. Updating actions are the OS shell commands to execute when updating the built targets of the rule.
When an rule with updating actions is invoked, those 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, the actions are passed to the OS command shell, with $(1) and $(2) replaced by bound versions of the target names. See Binding operation in Jam's documentation .
Chapter 7. Variables
Jam variables are lists of zero or more elements, with each element being a string value. An undefined variable is indistinguishable from a variable with an empty list, however, a defined variable may have one more elements which are null strings. All variables are referenced as $(variable).
Variables are either global or target-specific. In the latter case, the variable takes on the given value only during the target's binding, header file scanning, and updating; and during the "on target statement" statement.
A variable is defined with:
variable = elements ; variable += elements ; variable ?= elements ; variable on targets = elements ; variable on targets += elements ; variable on targets ?= elements ; The first three forms set variable globally.
The last three forms set a target-specific variable.
= operator replaces any previous elements of variable with elements;
+= operator adds elements to variable's list of elements;
?= operator sets variable only if it was previously unset.
The last form, "variable on targets ?= elements, checks to see if the target-specific, not the global, variable is set. (The ?= operator also has an old form "default =".)
Variables referenced in updating commands will be replaced with their values;
target-specific values take precedence over global values.
Variables passed as arguments ($(1) and $(2)) to actions are replaced with their bound values;
the "bind" modifier can be used on actions to cause other variables to be replaced with bound values. See Action Modifiers above.
Jam variables are not re-exported to the environment of the shell that executes the updating actions, but the updating actions can reference jam variables with $(variable).
Chapter 10. Built-in Variables
This section discusses variables that have special meaning to jam
$(SEARCH) and $(LOCATE) Variables
These two variables control the binding of file target names to locations in the file system.
Generally, $(SEARCH) is used to find existing sources.
while $(LOCATE) is used to fix the location for built targets.
Rooted (absolute path) file targets are bound as is.
Unrooted file target names are also normally bound as is, and thus relative to the current directory, but the settings of $(LOCATE) and $(SEARCH) alter this:
If $(LOCATE) is set, then the target is bound relative to the first directory in $(LOCATE). Only the first element is used for binding.
If $(SEARCH) is set, then the target is bound to the first directory in $(SEARCH) where the target file already exists.
If searching in $(SEARCH) fails, the target is bound relative to the current directory anyhow.
When writing your own rules, especially ones not built upon those in Jambase, you may need to set $(SEARCH) or $(LOCATE) directly.
$(HDRSCAN) and $(HDRRULE) Variables
These two variable control header file scanning.
$(HDRSCAN) is an egrep(1) pattern, with ()'s surrounding the file name, used to find file inclusion statements in source files. Jambase uses $(HDRPATTERN) as the pattern for $(HDRSCAN).
$(HDRRULE) is the name of a rule to invoke with the results of the scan: the scanned file is the target, the found files are the sources. $(HDRRULE) is run under the influence of the scanned file's target-specific variables.
Both $(HDRSCAN) and $(HDRRULE) must be set for header file scanning to take place, and they should be set target-specific and not globally. If they were set globally, all files, including executables and libraries, would be scanned for header file include statements.
The scanning for header file inclusions is not exact, but it is at least dynamic, so there is no need to run something like makedepend(GNU) to create a static dependency file. The scanning mechanism errs on the side of inclusion (i.e., it is more likely to return filenames that are not actually used by the compiler than to miss include files) because it can't tell if #include lines are inside #ifdefs or other conditional logic. In Jambase, HdrRule applies the NOCARE rule to each header file found during scanning so that if the file isn't present yet doesn't cause the compilation to fail, jam won't care.
Also, scanning for regular expressions only works where the included file name is literally in the source file. It can't handle languages that allow including files using variable names (as the Jam language itself does).
Platform Identifier Variables
Jam built-in variables that can be used to identify the runtime platform:
$(OS) : OS identifier string ( e.g. if( $(OS) = LINUX ) { Echo "Building on Linux" })
Valid values of $(OS) are :
$(OSPLAT) : Underlying architecture, when applicable(wtf does that mean?)
$(MAC) : true on MAC platform
$(NT) : true on NT platform
$(OS2) : true on OS2 platform
$(UNIX) : true on Unix platforms
$(VMS) : true on VMS platform
$(CWD) : Current working directory
Other Jam Variables
$(JAMDATE) : Time and date at jam start-up.(what is the format of the date?)
$(JAMUNAME) : Ouput of uname -a command (Unix only)
i686 #2 Mon May 22 23:10:59 UTC 2006 2.6.16-2-686 cucu Linux
$(JAMVERSION) : jam version, as reported by jam -v.
Echo $(JAMVERSION) ; -> 2.5