Start-up

Upon start-up, jam performs the following steps:

1. Imports environment variable settings into jam variables.

   1. Environment variables are split at blanks with each word becoming an element in the variable's list of values.

   2. Environment variables whose names end in PATH are split at $(SPLITPATH) characters (e.g., ":" for Unix).

2. To set a variable's value on the command line, overriding the variable's environment value, use the -s option.

   To see variable assignments made during jam's execution, use the -d+7 option.

Parsing

In the parsing phase, jam will:

1. Read and execute the Jambase file. The default Jambase is built into jam executable, and is written using jam language

2. The last action of the Jambase is to read (via the include rule) a user-provided file called "Jamfile".

   The Jambase defines boilerplate rules and variable assignments, and the Jamfile uses these to specify the actual relationship among the target and source files. Collectively, the purpose of the Jambase and the Jamfile is :

   1. To name build target and source files.

   2. Construct the dependency graph among them.

   3. Associate build actions with targets.

Binding

In this phase, jam recursively descends the dependency graph and binds every file target with a location in the filesystem.

1. Any string value in jam can represent a target, and it does so if the DEPENDS or INCLUDES rules make it part of the dependency graph. Build targets are files to be updated. Source targets are the files used in updating build targets. Build targets and source targets are collectively referred to as file targets, and frequently build targets are source targets for other build targets. Pseudotargets are symbols which represent dependencies on other targets, but which are not themselves associated with any real file.

2. A file target's identifier is generally the file's name, which can be absolutely rooted, relative to the directory of jam's invocation, or simply local (no directory). Most often it is the last case, and the actual file path is bound using the $(SEARCH) and $(LOCATE) special variables. See SEARCH and LOCATE Variables below. A local filename is optionally qualified with "grist," a string value used to assure uniqueness. A file target with an identifier of the form file(member) is a library member (usually an ar(1) archive on UNIX). The use of $(SEARCH) and $(LOCATE) allows jam to separate the the location of files from their names, so that Jamfiles can refer to files locally (i.e. relative to the Jamfile's directory), yet still be usable when jam is invoked from a distant directory. The use of grist allows files with the same name to be identified uniquely, so that jam can read a whole directory tree of Jamfiles and not mix up same-named targets.

3. Update Determination. After binding each target, jam determines whether the target needs updating, and if so marks the target for the updating phase. A target is normally so marked if it is missing, it is older than any of its sources, or any of its sources are marked for updating. This behavior can be modified by the application of special built-in rules. See Modifying Binding below.

4. Header File Scanning. During the binding phase, jam also performs header file scanning, where it looks inside source files for the implicit dependencies on other files caused by C #include syntax. This is controlled by the special variables $(HDRSCAN) and $(HDRRULE). The result of the scan is formed into a rule invocation, with the scanned file as the target and the found included file names as the sources. Note that this is the only case where rules are invoked outside the parsing phase. See HDRSCAN and HDRRULE Variables below.

Updading

jam again recursively descends the dependency graph, this time executing the update actions for each target marked for update during the binding phase. If a target's updating actions fail, then all other targets which depend on that target are skipped.

1. The -j flag instructs jam to build more than one target at a time. If there are multiple actions on a single target, they are run sequentially. The -g flag reorders builds so that targets with newest sources are built first. Normally, they are built in the order of appearance in the Jamfiles.