The Jam/MR Language

This document describes the Jam/MR language, used to defines rules and dependencies for jam, the Jam/MR executable program. For additional information, please see:

• The Jam/MR Executable Program
• Using Jamfiles and Jambase
• Jambase Reference

Also, the Jambase file provided in the Jam/MR distribution is an excellent source of Jam/MR language examples. Documentation and source are available from www.perforce.com/jam/jam.html

Lexical Features

Jam/MR 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.

Jam/MR requires whitespace (blanks, tabs, or newlines) to surround all tokens, including the colon (:) and semicolon (;) tokens. This is because jam runs on many platforms and no characters, save whitespace, are uncommon in the file names on all of those platforms.

Targets

The essential Jam/MR data entity is a target. Built targets are files to be updated. Source targets are the files used in updating those targets. Pseudotargets are symbols which represent dependencies on other targets. Built targets and source targets are collectively referred to as file targets; pseudotargets are not file targets.

Each target has a unique identifier, which, in the case of file targets, is its filename optionally qualified with grist (a string value used to assure uniqueness) and/or a pathname, either rooted or relative to the directory of jam's invocation. A file target with an identifier of the form file(member) is an an ar(1) library member.

Rules

Jam/MR's basic language entity is called a rule, which is used primarily to relate built targets to their source targets. A rule is defined in two parts: the Jam/MR statements to execute when the rule invocation is parsed, and the actions (shell commands) to execute when updating the built targets of the rule. A rule may have a procedure definition, an action definition, or both.

The Jam/MR statements for defining and invoking rules are as follows:

	rule rulename { statements }

	actions [ modifiers ] rulename { commands }

	rulename field1 : field2 : ... : fieldN ;
	

The first form defines a rule's procedure; the second defines the rule's updating actions; the third invokes the rule. Redefining a rule's procedure or actions replaces the previous definition.

A rule is invoked with values in field1 through fieldN, which are referenced in the procedure definition statements as variables named $(1) through $(N). A rule defined with a procedure definition and no action definition is just a procedure call.

When a rule is invoked, its action definition, if any, is automatically the first updating action to be associated with targets. Any other actions invoked from a rule's procedure definition statements will be executing during updating in the order in which they were invoked. Updating actions are associated with the targets in field1.

Built targets and source targets are passed to an updating action through field1 and field2, and are refenced in the action's commands as $(1) and $(2) respectively. $(1) and $(2) may also be referenced as $(<) and $(>) in action commands and procedure definition statements. During updating, commands are passed to the OS, with $(1) and $(2) replaced by bound targets. (See "Binding" in the The Jam/MR Executable Program.)

Action Modifiers

The following action modifiers are understood:

              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.

Built-in Rules

Jam/MR has ten built-in rules, none of which have updating actions:

              ALWAYS targets ;
                     Rebuilds  targets, even if they are up-to-date.

              DEPENDS targets1 : targets2 ;
                     Makes targets1 dependencies of targets2.

              ECHO args ;
                     Blurts out the message args to stdout.

              EXIT args ;
                     Blurts out the message args to stdout  and
                     then exits with a failure status.

              INCLUDES targets1 : targets2 ;
                     Makes  targets2 dependencies of anything of which 
		     targets1 are dependencies.

              LEAVES targets ;
                     Makes each of targets depend only  on  its leaf  
		     sources,  and  not on any intermediate targets. Its leaf 
		     sources are those  source targets without any 
		     dependencies themselves.

              NOCARE targets ;
                     Marks targets as possibly being not needed. If a 
		     target is present, its timestamp is used to compute 
		     dependencies; if it is not present, it is not considered a
		     dependency.

              NOTFILE targets ;
                     Marks targets as pseudotargets, not files.

              NOUPDATE targets ;
                     Causes the timestamps  of  targets  to  be ignored: 
		     either  target exists  or it doesn't. If it  exists,
		     it is  considered eternally old.

              TEMPORARY targets ;
                     Marks targets as temporary; causes targets to be removed 
		     when all their dependencies have been updated.

The ALWAYS, LEAVES, NOCARE, NOTFILE, NOUPDATE, and TEMPORARY affect only the binding phase (q.v.).

Flow-of-Control

Jam/MR has several simple flow-of-control statements:

	      local vars [ = values ] ;

              include file ;

              for var in list { statements }

              switch value 
			{ case pattern1 : statements ; 
			  case pattern2 : statements ; 
			  ... 
			}

              if  cond 
			{ statements } 
	 	 [ else { statements } ]

• The local statement instantiates new vars inside the current {} block. Variables of the same name outside of the {} block or before the local statement are unaffected and inaccessible. local may appear anywhere in a block. The vars are initialized to values, if present.

• The include statement causes jam to read the named file. The file is bound like regular targets (see Binding, below), but unlike regular targets the include file cannot be built.

  The include file is inserted into the input stream during the parsing phase. The primary input file and all the included file(s) are treated as a single file; that is, jam infers no scope boundaries from included files.

• The for loop executes statements for each element in list, setting the variable var to the element value.

• The switch statement executes zero or one of the enclosed statements, depending on which, if any, is the first case whose pattern matches value. The pattern values are not variable-expanded. The pattern values may include the following wildcards:

  ?	match any single character
  *	match zero or more characters
  [chars]	match any single character in chars

• The if statement does the obvious; the else clause is optional. cond is built of:

  a	true if any a element is a non-zero-length string
  a = b	list a matches list b string-for-string
  a != b	list a does not match list b
  a < b	a[i] string is less than b[i] string, where i is first mismatched element in lists a and b
  a <= b	every a string is less than or equal to its b counterpart
  a > b	a[i] string is greater than b[i] string, where i is first mismatched element
  a >= b	every a string is greater than or equal to its b counterpart
  a in b	true if all elements of a can be found in b, or if a has no elements
  ! cond	condition not true
  cond && cond	conjunction
  cond || cond	disjunction
  ( cond )	precedence grouping

Variables

Jam/MR 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.

Variables are either global or target-specific. All variables are referenced as $(VARIABLE).

A variable is defined with:

              variable = elements ;

              variable += elements ;

              variable on targets = elements ;

              variable on targets += elements ;

              variable default = elements ;
              variable        ?= elements ;

The first two forms set variable globally. The third and forth forms set a target-specific variable, where variable takes on a value only during the binding and updating targets. The = operator replaces any previous elements of variable with elements; the += operation adds elements to variable's list of elements. The final two forms do the same thing, set variable globally, but only if it was previously unset.

On program start-up, jam imports environment variable settings into Jam/MR 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). Environment variable values can be overridden on the command line with the -s flag. Jam/MR variables are not re-exported to the shell that executes the updating actions, but the updating actions can reference Jam/MR variables with $(variable).

Variables referenced in updating commands will be replaced with their values; target-specific values take precedence over global values. Variables passed as arguments 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.

Variable Expansion

During parsing, Jam/MR performs variable expansion on each token that is not a keyword or rule name. Such tokens with embedded variable references are replaced with zero or more tokens. Variable references are of the form $(v) or $(vm), where v is the variable name, and m are optional modifiers.

Variable expansion in a rule's actions is similar to variable expansion in statements, except that the action string is tokenized at whitespace regardless of quoting.

The result of a token after variable expansion is the product of the components of the token, where each component is a literal substring or a list substituting a variable reference. For example:

              $(X)      -> a b c
              t$(X)     -> ta tb tc
              $(X)z     -> az bz cz
              $(X)-$(X) -> a-a a-b a-c b-a b-b b-c c-a c-b c-c

The variable name and modifiers can themselves contain a variable reference, and this partakes of the product as well:

              $(X)      -> a b c
              $(Y)      -> 1 2
              $(Z)      -> X Y
              $($(Z))   -> a b c 1 2

Because of this product expansion, if any variable reference in a token is undefined, the result of the expansion is an empty list. If any variable element is a null string, the result propagates the non-null elements:

              $(X)        -> a ""
              $(Y)        -> "" 1
	      $(Z)	  -> 
	      *$(X)$(Y)*  -> *a* *a1* ** *1*
	      *$(X)$(Z)*  ->

A variable element's string value can be parsed into grist and filename-related components. Modifiers to a variable are used to select elements, select components, and replace components. The modifiers are:

On VMS, $(var:P) is the parent directory of $(var:D); on Unix and NT, $(var:P) and $(var:D) are the same.

Built-in Rules and Variables

DEPENDS, INCLUDES Rules

              DEPENDS foo.o : foo.c ;
              INCLUDES foo.c : foo.h ;

ALWAYS, LEAVES, NOCARE, NOTFILE, NOUPDATE, TEMPORARY Rules

The ALWAYS rule causes its targets to be always updated. 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.

The NOCARE rule causes jam to ignore its targets if they can't be found and have no updating actions. Normally, jam issues a warning about a target that can't be built and then refuses to build anything that depends on that target. 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.

The NOTFILE rule marks its targets as being pseudotargets, that is, targets that aren't really files. 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.

The NOUPDATE rule causes jam to ignore the modification time of the target. 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.

The TEMPORARY rule allows for targets to be deleted after they are generated. If jam sees that a temporary target is missing, it will use the target's parent's time when determining if the target needs updating. 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 LEAVES rule makes each of the targets depend only on its "leaf" dependencies. 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.

ECHO, EXIT Rules

SEARCH, LOCATE Variables

$(SEARCH) provides a list of directories along which jam scans looking for a target. $(LOCATE) overrides $(SEARCH), indicating the directory where the target must be. Normally, $(SEARCH) is set for existing targets while $(LOCATE) is set for the targets which jam must build. Only the first element in $(LOCATE) is used for binding. If neither $(SEARCH) nor $(LOCATE) are set, or if the name of the target is a rooted file name (e.g., on UNIX beginning with "/"), then the file name is assumed to be the target name.

Both $(SEARCH) and $(LOCATE) should be set target-specific and not globally. If they were set globally, jam would use the same paths for all file binding, which is not likely to produce sane results. When writing your own rules, especially ones not built upon those in Jambase, you may need to set $(SEARCH) or $(LOCATE) directly. Almost all of the rules defined in Jambase set $(SEARCH) and $(LOCATE) to sensible values for sources they are looking for and targets they create, respectively.

HDRSCAN, HDRRULE 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 robustness (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 and isn't needed during compilation, jam doesn't skip its dependencies.

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/MR language itself does).

Platform Identifier Variables

A number of Jam/MR built-in variables can be used to identify runtime platform:

JAMDATE Variable

JAMSHELL Variable

              JAMSHELL = /bin/sh -c % ;

jam can build targets in parallel, as long as the dependencies among files are properly spelled out and actions don't create fixed named files in the current directory. (If either of those two provisions are violated, jam can trip over itself when building in parallel things which just happen to build OK sequentially.) When building in parallel, jam simply forks off more than one shell at a time.

jam does not directly support building in parallel across multiple hosts, since that is heavily dependent on the local environment. To build in parallel across multiple hosts, you need to write your own shell that provides access to the multiple hosts. You then reset $(JAMSHELL) to reference it.

Just as jam expands a % to be the text of the rule's action block, it expands a ! to be the multi-process slot number. The slot number varies between 1 and the number of concurrent jobs permitted by the -j flag given on the command line. Armed with this, it is possible to write a multiple host shell. For example:

	  #!/bin/sh

	  # This sample JAMSHELL uses the SunOS on(1) command to execute
	  # a command string with an identical environment on another host.
	  #
	  # Set JAMSHELL = jamshell ! %
	  #
	  # where jamshell is the name of this shell file.
	  #
	  # This version handles up to -j6; after that they get executed
	  # locally.

	  case $1 in
	  1|4) on winken sh -c "$2";;
	  2|5) on blinken sh -c "$2";;
	  3|6) on nod sh -c "$2";;
	  *)   eval "$2";;
	  esac

Copyright 1997 Perforce Software, Inc.
Comments to info@perforce.com
Last updated: Oct 19, 1997