当前位置：首页 > news >正文

jam

news 2026/5/11 19:19:05

jam

The Jam/MR Executable Program
Jam/MR 2.2

USAGE

	jam [ -a ] [ -n ] [ -v ] [ -d debug ] [ -f rulesfile ... ] [ -j jobs ] [ -s var=value ... ] [ -t target ... ] [  target ... ]

DESCRIPTION

jam, the Jam/MR executable program,recursively builds target files from source filesusing dependency and build specification rules defined in rulesfile.jam parses rulesfile to identify targetsand sources,examines the filesystem to determine whichtargets need updating, and issues OS commands to updatetargets.

Normally, rulesfile is compiled into jam,allowing jam to be run as a stand-alone program.A base set of build rules is provided in thefile "Jambase", and is described inUsing Jamfiles and Jambaseand theJambase Reference.For general information, refer to theJam/MR Language document.

If target is provided on the command line, jam attempts tobuild target; otherwise jam attempts to build thetarget 'all'.

OPTIONS

jam may be invoked with the following options:

       -a     Build all targets anyway, even if they are up-to-date.-d<n>  Enable cummulative debugging levels from 1 to <n>.  Interesting values are:1 Show actions (the default)2 Show "quiet" actions and display all action text3 Show dependency analysis, and target/source timestamps/paths 4 Show shell arguments5 Show rule invocations and variable expansions6 Show directory/header file/archive scans7 Show variable settings8 Show variable fetches9 Show variable manipulation, scanner tokens-d+<n> Enable debugging level <n>.-d0    Turn off all debugging levels.  Only errors are notsuppressed.-f<rulesfile>Read <rulesfile> instead of Jambase.-j<n>Run  up to <n> shell commands concurrently (UNIXonly).  The default is 1.-k     Continue after build error.  The default behavior is to exit after the first build failure.-n     Don't actually execute the updating actions, but doeverything else.  This changes the debug level default to -d2.-s<var>=<value>Set  the variable <var> to <value>, overriding bothinternal variables and variables imported from  theenvironment.-t<target>Rebuild <target>, even if it is up-to-date, and/or build dependencies of <target> as if <target> were newer.-v     Print the version of jam and exit.

OPERATION

jam has three phases of operation: parsing, binding, andupdating.

Parsing

In the parsing phase, jam reads the rules file(s),evaluates variables, identifies and invokes rules, identifies targets, and builds the dependency graph.

Which rules files get read depends on the site-specific implementation of jam.The normal implementation is this: jam reads the Jambaserules file, the text of which is stored inside the jamexecutable itself. Jambase may "include" other rules files, andthe last rule invoked from Jambase is"include Jamfile", which reads file "Jamfile" from the currentdirectory. Jamfile is expected to specify which targets getbuilt from the source files in the current directory.(All of this is explained in detail inUsing Jamfiles and Jambase.)If there's no Jamfile in the current directory, jamemits a message and exits.

Environment variable settings are imported into Jam/MR variables.To pass a value to a variable on the jam 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.

Rules are defined in rules files using the Jam/MR language,and are invoked in rules files after they are defined.Targets are identified by rule invocations. At the completionof the parsing phase, all targets are uniquely identifiedand a dependency graph is constructed.

Binding

After parsing, jam recursively descends the dependencygraph and binds every file target with a location in the filesystem.The existence and modification times of the bound files are used to determine which targets need updating. If jam detects a circulardependency in the graph, it issues a warning.

A file target is bound with a location as follows:

If $(LOCATE) is set, the target is boundto the path described by the first element in $(LOCATE).
If $(LOCATE) is not set, and the target has any updatingactions associated with it, the target is bound to thecurrent directory of the jam invocation.
If $(LOCATE) is not set, and the target has no updatingactions associated with it, and $(SEARCH) is set,jam searches the directories in the $(SEARCH) list.The first directory in the list in which the target isfound becomes the target's bound path. If the target isnot found, it is bound to the current directory of thejam invocation.
If neither $(SEARCH) nor $(LOCATE) are set, the targetis bound to the current directory of the jam invocation.
If the target's identifier contains a rooted pathname,none of the above applies, and the target's boundlocation is that path.
Unrooted pathnames used in $(SEARCH), $(LOCATE), ortarget identifiers are relative to the current directory where jam was invoked.
Target-specific values of $(SEARCH) and $(LOCATE)always have precedence over global values in binding.

After binding each target, jam determines whether the target needs updating, and marks the target if necessary forthe updating phase. A target is marked for updating forany of these three reasons:

It is missing.
Its filesystem modification time is older than anyof its sources.
Any of its sources are marked for updating.

For targets of the built-in rules ALWAYS, LEAVES,NOCARE, TEMPORARY, NOTFILE, and NOUPDATE, jam's updatingbehavior is slightly different:

ALWAYS
The target is always updated.
LEAVES
The target is only updated if it is missingor if its leaf sources are newer. Leafsources are those dependencies of the targetthat have no dependencies themselves.
NOCARE
The target is ignored if it is missing andhas no updating actions. Normally, jamissues a warning and skips other targetsthat depend on missing targets withoutupdating actions.
TEMPORARY
If the target is missing, then its source'smodification time is used when comparingagainst dependencies.
NOTFILE
The target is only updated if any of itssources are marked for updating.
NOUPDATE
The target is only updated if it is missing.Also, if it exists, it will appear eternallyold; that is, older than anything thatdepends on it.

If $(HDRSCAN) is set on a file target,jam scans the file for header file include lines.It scans the file by matching each line against a regexp(3) pattern that has ()'s surrounding the included filename. The pattern is provided by the user through thespecial variable $(HDRSCAN) (see HDRPATTERN in Jambase foran example). The result of the scan is formed into a ruleinvocation, with the scanned file as the target and thefound included file names as the sources. The ruleinvoked is named by the special variable $(HDRRULE). jamonly scans files if $(HDRSCAN) is set, and $(HDRSCAN) isnormally set target-specific.

Between binding and updating, jam announces the number oftargets to be updated.

Updating

After binding, jam again recursively descends the dependency graph, this time executing the update actions foreach target marked for update during the binding phase.If a target's updating actions fail, then all targetswhich depend on it are skipped.

The -j flag instructs jam to build more thanone target at a time. If there are multiple actions on asingle target, they are run sequentially.

The special variable $(JAMSHELL) gives jam acommand execution shell to be used instead of /bin/sh.This variable's value must be a multi-element list, corresponding to the argument vector for the command shell. Anelement "%" is replaced with the command string to execute. An element "!" is replaced with the multiprocessslot number, which is (inclusively) between 1 and the maximum number of concurrent jobs specified with the -j flag(default 1). If no element of the list is "%", the command string is tacked on as the last argument. Thedefault value is: "/bin/sh -c %".

DIAGNOSTICS

In addition to generic error messages, jam may emit one ofthe following:

       warning: unknown rule XA  rule  was invoked that has not been defined withan "actions" or "rule" statement.using N temp target(s)Targets marked as being temporary (but  nonethelesspresent) have been found.updating N target(s)Targets are out-of-date and will be updated.can't find N target(s)Source  files  can't  be  found  and  there  are noactions to create them.can't make N target(s)Due to sources not being found, other targets  cannot be made.warning: X depends on itselfA  target  depends  on  itself  either  directly orthrough its sources.don't know how to make XA target is not present and no  actions  have  beendefined to create it.X skipped for lack of YA  source failed to build, and thus a target cannotbe built.warning: using independent target XA target that does is not a dependency of any othertarget is being referenced with $(<) or $(>).X removedjam  removed  a  partially built target after beinginterrupted.

BUGS, LIMITATIONS

The -j flag can cause jam to get confused whensingle actions update more thanone target at a time. jam may try to executeactions to build those targets' dependencies beforethe targets themselves have all been built.

With the -j flag, errors from failed commands can getstaggeringly mixed up. Also, because targets tend to getbuilt in a quickest-first ordering, dependency informationmust be quite exact. Finally, beware of parallelizingcommands that drop fixed-named files into the currentdirectory, like yacc(1) does.

A poorly set $(JAMSHELL) is likely to result in silentfailure.