jam.html

jam源码

	    <P><DT><CODE> 

		for <I>var</I> in <I>list</I> { <I>statements</I> }

	    </CODE>

	    <P><DD> Executes <i>statements</i> for each element in
	    <i>list</i>, setting the variable <i>var</i> to the element
	    value.

	    <A name=if>
	    <P><DT><CODE>
	    </A>

		if <I>cond</I> { <I>statements</I> } [ else <I>statement</I> ]

	    </CODE>

	    <P><DD> Does the obvious;  the else clause is optional.
	    <i>cond</i> is built of:

	    <TABLE BORDER=1> 

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

	    </TABLE>

	    <P><DT> <CODE>

		include <I>file</I> ;

	    </CODE>

	    <P><DD> Causes <b>jam</b> to read the named <i>file</i>.
	    The file is bound like a regular target (see <A
	    HREF="#binding"> Binding</A> above) but unlike a regular
	    target the include file cannot be built.  Marking an include
	    file target with the <b>NOCARE</b> rule makes it optional:
	    if it is missing, it causes no error.

	    <P>

	    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, <b>jam</b>
	    infers no scope boundaries from included files.

	    <P><DT> <CODE>

		local <i>vars</I> [ = <i>values</i> ] ;

	    </CODE>

	    <P><DD> Creates new <i>vars</i> inside to the enclosing {}
	    block, obscuring any previous values they might have.  The
	    previous values for <i>vars</i> are restored when the current
	    block ends.  Any rule called or file included will see the
	    local and not the previous value (this is sometimes called
	    Dynamic Scoping).  The local statement may appear anywhere,
	    even outside of a block (in which case the previous value
	    is restored when the input ends).  The <i>vars</i> are
	    initialized to <i>values</i> if present, or left uninitialized
	    otherwise.

	    <P> <DT> <CODE>
	    
		on <I>target</I> <I>statement</I> ;

	    </CODE>

	    <P><DD> Run <I>statement</I> under the influence of
	    <I>target</I>'s target-specific variables.  These variables
	    become local copies during <I>statement</I>'s run, but they
	    may be updated as target-specific variables using the usual
	    "<I>variable</I> on <I>targets</I> =" syntax.


	    <P><DT> <CODE>

		return <I>values</I> ; 

	    </CODE>

	    <P><DD> Within a rule body, the return statement sets the return
	    value for an invocation of the rule and terminates the rule's
	    execution.

	    <P> <DT> <CODE>
	    
		rule <I>rulename</I> [ : <I>vars</I> ] { <I>statements</I> }

	    </CODE>

	    <P><DD> Define a rule's procedure, replacing any previous
	    definition.  If <I>vars</I> are provided, they are assigned
	    the values of the parameters ($(1) to $(9)) when <I>statements</I>
	    are executed, as with the <B>local</B> statement.

	    <P><DT> <CODE>

		<A NAME="switch">
		switch <I>value</I>
		</A>
		<BR> { 
		<BR> case <I>pattern1</I> : <I>statements</I> ; 
		<BR> case <I>pattern2</I> : <I>statements</I> ; 
		<BR> ... 
		<BR> }

	    </CODE>

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

	    <TABLE>

		<TR><TD><CODE> ? </CODE></TD>
		<TD> match any single character </TD>
		<TR><TD><CODE> * </CODE></TD>
		<TD> match zero or more characters </TD>
		<TR><TD><CODE> [<i>chars</i>] </CODE></TD>
		<TD> match any single character in <i>chars</i> </TD>
		<TR><TD><CODE> [^<i>chars</i>] </CODE></TD>
		<TD> match any single character not in <i>chars</i> </TD>
		<TR><TD><CODE> \<i>x</i> </CODE></TD>
		<TD> match <i>x</i> (escapes the other wildcards)</i> </TD>

	    </TABLE>

	    <P><DT> <CODE>

		while <I>cond</I> { <I>statements</I> }

	    </CODE>

	    <P><DD> Repeatedly execute <I>statements</I> while <I>cond</I>
	    remains true upon entry. (See the description of <I>cond</I>
	    expression syntax under <a href="#if">if</a>, above).
	</DL></TABLE>


<DT> <P> <H3> Variables </H3> <DD>

	<P>

	<B>Jam</b> 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 $(<I>variable</I>).

	<P>

	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 <I>target</I> <I>statement</I>" statement.

	<P>

	A variable is defined with:

	<P> <TABLE WIDTH=75% ALIGN=CENTER> <TR><TD> <DL>

	    <DT><CODE> 
	    <I>variable</I> = <I>elements</I> ; </CODE>
	    <DT><CODE> 
	    <I>variable</I> += <I>elements</I> ; </CODE>
	    <DT><CODE> 
	    <I>variable</I> ?= <I>elements</I> ; </CODE>
	    <DT><CODE> 
	    <I>variable</I> on <I>targets</I> = <I>elements</I> ; </CODE>
	    <DT><CODE> 
	    <I>variable</I> on <I>targets</I> += <I>elements</I> ; </CODE>
	    <DT><CODE> 
	    <I>variable</I> on <I>targets</I> ?= <I>elements</I> ; </CODE>

	</DL></TABLE>

	<P>

	The first three forms set <I>variable</I> globally.  The last
	three forms set a target-specific variable.  The = operator
	replaces any previous elements of <I>variable</I> with
	<I>elements</I>; the += operation adds <I>elements</I> to
	<I>variable</I>'s list of elements; the ?= operator sets
	<I>variable</I> only if it was previously unset.  The last form
	"<I>variable</I> on <I>targets</I> ?= <I>elements</I>" checks
	to see if the target-specific, not the global, variable is set.
	(The ?= operator also has an old form "default =".)  

	<P>

	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 <A HREF="#actionmods">Action Modifiers</A>
	above.

	<P>

	<B>Jam</b> variables are not re-exported to the environment of
	the shell that executes the updating actions, but the updating
	actions can reference <b>jam</b> variables with $(<I>variable</I>).

<A NAME="varexp">
<DT> <P> <H3> Variable Expansion </H3> <DD>
</A>

	<P>

	During parsing, <b>jam</b> 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 $(<I>v</I>) or
	$(<I>vm</I>), where <i>v</i> is the variable name,  and  <I>m</I>
	are optional modifiers.

	<P>

	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.

	<P>

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

	<P> <TABLE WIDTH=75% ALIGN=CENTER><TR><TD><CODE>

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

	</CODE></TABLE>

	<P>

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

	<P> <TABLE WIDTH=75% ALIGN=CENTER><TR><TD><CODE>

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

	</CODE></TABLE>

	<P>

	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:

	<P> <TABLE WIDTH=75% ALIGN=CENTER><TR><TD><CODE>

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

	</CODE></TABLE>

	<P>

	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:

	<P> <TABLE WIDTH=75% BORDER=1 ALIGN=CENTER>

	    <TR><TD><CODE> [<I>n</I>] </CODE>
	    <TD>Select element number <I>n</I> (starting at 1).  If
	    the variable contains fewer than <I>n</I> elements,
	    the result is a zero-element list.

	    <TR><TD><CODE> [<I>n</I>-<I>m</I>] </CODE>
	    <TD>Select elements number <I>n</I> through <I>m</I>.

	    <TR><TD><CODE> [<I>n</I>-] </CODE>
	    <TD>Select elements number <I>n</I> through the last.

	    <TR><TD><CODE> :B </CODE>
	    <TD>Select filename base.

	    <TR><TD><CODE> :S </CODE>
	    <TD>Select (last) filename suffix.

	    <TR><TD><CODE> :M </CODE>
	    <TD>Select archive member name.

	    <TR><TD><CODE> :D </CODE>
	    <TD>Select directory path.

	    <TR><TD><CODE> :P </CODE>
	    <TD>Select parent directory.

	    <TR><TD><CODE> :G </CODE>
	    <TD>Select grist.

	    <TR><TD><CODE> :U </CODE>
	    <TD>Replace lowercase characters with uppercase.

	    <TR><TD><CODE> :L </CODE>
	    <TD>Replace uppercase characters with lowercase.

	    <TR><TD><CODE> :<i>chars</I> </CODE>
	    <TD>Select the components listed in <i>chars</i>.

	    <TR><TD><CODE> :G=<I>grist</I> </CODE>
	    <TD>Replace grist with <I>grist</I>.

	    <TR><TD><CODE> :D=<I>path</I> </CODE>
	    <TD>Replace directory with <I>path</I>.

	    <TR><TD><CODE> :B=<I>base</I> </CODE>
	    <TD>Replace the base part of file name with <I>base</I>.

	    <TR><TD><CODE> :S=<I>suf</I> </CODE>
	    <TD>Replace the suffix of file name with <I>suf</I>.

	    <TR><TD><CODE> :M=<I>mem</I> </CODE>
	    <TD>Replace the archive member name with <I>mem</I>.

	    <TR><TD><CODE> :R=<I>root</I> </CODE>
	    <TD>Prepend <I>root</I> to the whole file name,  if not
	    already rooted.

	    <TR><TD><CODE> :E=<I>value</I> </CODE>
	    <TD>Use <I>value</I> instead if the variable is unset.

	    <TR><TD><CODE> :J=<I>joinval</I> </CODE>
	    <TD>Concatentate list elements into single
            element, separated by <I>joinval</I>.

	</TABLE>

	<P>

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


<DT> <P> <H3> Built-in Rules </H3> <DD>

	<P>
	<B>Jam</b> has twelve built-in rules, all of which are pure
	procedure rules without updating actions.  They are in
	three groups:  the first builds the dependency graph;
	the second modifies it; and the third are just utility
	rules.

	<P> <H5> Dependency Building </H5> 

	<P><TABLE WIDTH=75% ALIGN=CENTER><TR><TD><DL>

	<P><DT><CODE> 
	DEPENDS <I>targets1</I> : <I>targets2</I> ; 
	</CODE>

	<DD> Builds a direct dependency: makes each of <I>targets1</I>
	depend on each of <I>targets2</I>.  Generally, <I>targets1</I>
	will be rebuilt if <I>targets2</I> are themselves rebuilt are
	or are newer than <I>targets1</I>.

	<P><DT><CODE>
	INCLUDES <I>targets1</I> : <I>targets2</I> ;
	</CODE>

	<DD> Builds a sibling dependency: makes any target that depends
	on any of <I>targets1</I> also depend on each of <I>targets2</I>.
	This reflects the dependencies that arise when one source file
	includes another:  the object built from the source file depends
	both on the original and included source file,  but the two
	sources files don't depend on each other.  For example:

	<CODE>
	<P>DEPENDS foo.o : foo.c ;
	<BR>INCLUDES foo.c : foo.h ;
	</CODE>

	<P>

	"foo.o" depends on "foo.c" and "foo.h" in this example.

	</DL></TABLE>

	<A NAME="bindingmods">
	<P> <H5> Modifying Binding </H5> 
	</A>

	<P>

	The six rules ALWAYS, LEAVES, NOCARE, NOTFILE, NOUPDATE, and
	TEMPORARY modify the dependency graph so that <b>jam</b> treats
	the targets differently during its target binding phase.  See
	<A HREF="#binding">Binding</A> above.  Normally, <b>jam</b>