📄 jam.html
字号:
<HTML><TITLE> Jam - Make(1) Redux </TITLE><BODY><CENTER><H1> Jam - Make(1) Redux </H1><P> The <a href=http://www.perforce.com/jam/jam.html>Jam</a> Executable</CENTER><DL><DT> <P> <H2> USAGE </H2> <DD><PRE>jam [ -a ] [ -g ] [ -n ] [ -q ] [ -v ] [ -d <I>debug</I> ] [ -f <I>jambase</I> ] [ -j <I>jobs</I> ] [ -o <I>actionsfile</I> ] [ -s <I>var</I>=<I>value</I> ] [ -t <I>target</I> ] [ <I>target</I> ... ]</PRE><DT> <P> <H2> DESCRIPTION </H2> <DD> <P> <B>Jam</B> is a program construction tool, like <B>make</B>(1). <P> <B>Jam</B> recursively builds target files from source files, using dependency information and updating actions expressed in the Jambase file, which is written in <B>jam</B>'s own interpreted language. The default Jambase is compiled into <B>jam</B> and provides a boilerplate for common use, relying on a user-provide file "Jamfile" to enumerate actual targets and sources. <P> The Jambase is described in the <a href="Jambase.html">Jambase Reference</a> and the document <a href="Jamfile.html">Using Jamfiles and Jambase</A>.<DT> <P> <H2> OPTIONS </H2> <DD> <P> If <I>target</I> is provided on the command line, <B>jam</B> builds <I>target;</I> otherwise <B>jam</B> builds the target 'all'. <P> <B>Jam</b> may be invoked with the following options: <P> <TABLE WIDTH=85% ALIGN=CENTER BORDER=1 CELLPADDING=2> <TR><TD VALIGN=TOP WIDTH=20%><CODE> -a </CODE> <TD> Build all targets anyway, even if they are up-to-date. <TR><TD VALIGN=TOP><CODE> -d <I>c</I> </CODE> <TD> Turn on display option <I>c</I> and off the default display (summary info and actions): <DL COMPACT> <DT> a <DD> Show summary info, actions, quiet actions, and the use of temporary targets <DT> c <DD> Show the names of files that cause rebuilds, i.e. new sources, missing targets, etc. <DT> d <DD> Display a dependency graph (in <B>jam</B> syntax). <DT> m <DD> Display the dependency analysis, and target/source timestamps and paths <DT> x <DD> Show shell arguments </DL> <TR><TD VALIGN=TOP><CODE> -d <I>n</I> </CODE> <TD> Enable cummulative debugging levels from 1 to <I>n</I>. Interesting values are: <DL COMPACT> <DT> 1 <DD> Show actions and summary info (the default) <DT> 3 <DD> Old name for -dm (described above) <DT> 5 <DD> Show rule invocations and variable expansions <DT> 6 <DD> Show directory/header file/archive scans <DT> 7 <DD> Show variable settings <DT> 8 <DD> Show variable fetches <DT> 9 <DD> Show variable manipulation, scanner tokens </DL> <TR><TD VALIGN=TOP><CODE> -d +<I>n</I> </CODE> <TD> Enable debugging level <I>n</I>. <TR><TD VALIGN=TOP><CODE> -d 0 </CODE> <TD> Turn off all debugging levels. Only errors are emitted. <TR><TD VALIGN=TOP><CODE> -f <I>jambase</I></CODE> <TD>Read <I>jambase</I> instead of using the built-in Jambase. Multiple -f flags are permitted. <TR><TD VALIGN=TOP><CODE> -g </CODE> <TD> Build targets with the newest sources first, rather than in the order of appearance in the Jambase/Jamfiles. <TR><TD VALIGN=TOP><CODE> -j <I>n</I></CODE> <TD> Run up to <I>n</I> shell commands concurrently (UNIX and NT only). The default is 1. <TR><TD VALIGN=TOP><CODE> -n</CODE> <TD> Don't actually execute the updating actions, but do everything else. This changes the debug level to -dax. <TR><TD VALIGN=TOP><CODE> -o <I>file</I></CODE> <TD> Write the updating actions to the specified file instead of running them (or outputting them, as on the Mac). <TR><TD VALIGN=TOP><CODE> -q </CODE> <TD> Quit quickly (as if an interrupt was received) as soon as any target build fails. <TR><TD VALIGN=TOP><CODE> -s <I>var</I>=<I>value</I></CODE> <TD> Set the variable <I>var</I> to <I>value</I>, overriding both internal variables and variables imported from the environment. <TR><TD VALIGN=TOP><CODE> -t <I>target</I></CODE> <TD> Rebuild <I>target</I> and everything that depends on it, even if it is up-to-date. <TR><TD VALIGN=TOP><CODE> -v</CODE> <TD> Print the version of <B>jam</B> and exit. </TABLE><DT> <P> <H2> OPERATION </H2> <DD> <P> <b>Jam</b> has four phases of operation: start-up, parsing, binding, and updating.<DT> <P> <H3> Start-up </H3> <DD> <P> Upon start-up, <b>jam</b> imports environment variable settings into <b>jam</b> 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). <P> 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 <b>jam</b>'s execution, use the -d+7 option.<DT> <P> <H3> Parsing </H3> <DD> <P> In the parsing phase, <b>jam</b> reads and executes the Jambase file, by default the built-in one. It is written in the <b>jam</b> language. See <a href="#language"> Language</a> below. The last action of the Jambase is to read (via the "include" rule) a user-provided file called "Jamfile". <P> Collectively, the purpose of the Jambase and the Jamfile is to name built target and source files, construct the dependency graph among them, and associate build actions with targets. The Jambase defines boilerplate rules and variable assignments, and the Jamfile uses these to specify the actual relationship among the target and source files. See the <a href="Jambase.html">Jambase Reference</a> and the document <a href="Jamfile.html">Using Jamfiles and Jambase</A> for information.<A NAME="binding"><DT> <P> <H3> Binding </H3> <DD></A> <P> <H5> Binding </H5> After parsing, <B>jam</B> recursively descends the dependency graph and binds every file target with a location in the filesystem. <P> <H5> Targets </H5> <DD> Any string value in <b>jam</b> 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. <P> A file target's identifier is generally the file's name, which can be absolutely rooted, relative to the directory of <b>jam</b>'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 <A HREF="#search"> SEARCH and LOCATE Variables</A> 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 <I>file(member)</I> is a library member (usually an ar(1) archive on UNIX). <P> The use of $(SEARCH) and $(LOCATE) allows <b>jam</b> 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 <b>jam</b> is invoked from a distant directory. The use of grist allows files with the same name to be identified uniquely, so that <b>jam</b> can read a whole directory tree of Jamfiles and not mix up same-named targets. <P> <H5> Update Determination </H5> After binding each target, <B>jam</B> 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 <A HREF="#bindingmods">Modifying Binding</A> below. <P> <H5> Header File Scanning </H5> During the binding phase, <b>jam</b> also performs header file scanning, where it looks inside source files for the implicit dependencies on other files caused by C's #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 <A HREF="#hdrscan">HDRSCAN and HDRRULE Variables</A> below.<DT> <P> <H3> Updating </H3> <DD> <P> After binding, <B>jam</B> 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. <P> The -j flag instructs <B>jam</B> 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.<A NAME="language"><DT> <P> <H2> LANGUAGE </H2> <DD></A><DT> <P> <H3> Overview </H3> <DD> <B>Jam</b> has a interpreted, procedural language with a few select features to effect program construction. Statements in <b>jam</b> are rule (procedure) definitions, rule invocations, updating action definitions, flow-of-control structures, variable assignments, and sundry language support.<DT> <P> <H3> Lexical Features </H3> <DD> <P> <B>Jam</b> 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 updating actions is treated as a single string. A backslash (\) can escape a double quote, or any single whitespace character. <P> <B>Jam</b> requires whitespace (blanks, tabs, or newlines) to surround all tokens, <b>including the colon (:) and semicolon (;) tokens</b>. <P> <B>Jam</b> 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.<DT> <P> <H3> Datatype </H3> <DD> <P> <B>Jam</B>'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.<DT> <P> <H3> Rules </H3> <DD> <P> The basic <B>jam</b> language entity is called a rule. A rule is simply a procedure definition, with a body of <b>jam</b> 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. <P> 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 <tt>[</tt> and <tt>]</tt>.<DT> <P> <H3> Updating Actions </H3> <DD> <P> 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. <P> 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 <A HREF="#binding"> Binding</A> above.<DT> <P> <H3> Statements </H3> <DD> <P> <b>Jam</b>'s langauge has the following statements: <P><TABLE WIDTH=75% ALIGN=CENTER><TR><TD><DL> <P> <DT> <CODE> <I>rulename field1</I> : <I>field2</I> : <I>...</I> : <I>fieldN</I> ; </CODE> <P><DD> Invoke a rule. A rule is invoked with values in <I>field1</I> through <I>fieldN</I> (9 max). They may be referenced in the procedure's <I>statements</I> as $(1) through $(<9>N</I>). $(<) and $(>) are synonymous with $(1) and $(2). <P> <i>rulename</i> undergoes <A HREF="#varexp"> variable expansion</A>. If the resulting list is more than one value, each rule is invoked with the same arguments, and the result of the invocation is the concatenation of all the results. <P> <DT> <CODE> actions [ <I>modifiers</I> ] <I>rulename</I> { <I>commands</I> } </CODE> <P><DD> Define a rule's updating actions, replacing any previous definition. The first two arguments may be referenced in the action's <I>commands</I> as $(1) and $(2) or $(<) and $(>). <P> The following action <i>modifiers</i> are understood: <P><TABLE BORDER=1> <TR><TD WIDTH=30%><CODE> actions bind <I>vars</I> </CODE></TD> <TD> $(vars) will be replaced with bound values.</TD> </TR> <TR><TD><CODE> actions existing </CODE></TD> <TD> $(>) includes only source targets currently existing.</TD> </TR> <TR><TD><CODE> actions ignore </CODE></TD> <TD> The return status of the <I>commands</I> is ignored.</TD> </TR> <TR><TD><CODE> actions piecemeal </CODE></TD> <TD> <I>commands</I> are repeatedly invoked with a subset of $(>) small enough to fit in the command buffer on this OS.</TD> </TR> <TR><TD><CODE> actions quietly </CODE></TD> <TD> The action is not echoed to the standard output.</TD> </TR> <TR><TD><CODE> actions together </CODE></TD> <TD> The $(>) from multiple invocations of the same action on the same built target are glommed together.</TD> </TR> <TR><TD><CODE> actions updated </CODE></TD> <TD> $(>) includes only source targets themselves marked for updating.</TD> </TR> </TABLE> <P><DT><CODE> break </CODE> <P><DD> Breaks out of the closest enclosing <I>for</I> or <I>while</I> loop. <P><DT><CODE> continue </CODE> <P><DD> Jumps to the end of the closest enclosing <I>for</I> or <I>while</I> loop.⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -