jam.html

jam源码

	updates a target if it is missing, if its filesystem modification
	time is older than any of its dependencies (recursively), or if
	any of its dependencies are being updated.  This basic behavior
	can be changed by invoking the following rules:

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

	<P><DT><CODE>
	ALWAYS <I>targets</I> ;
	</CODE>

	<DD> Causes <I>targets</I> to be rebuilt regardless of whether
	they are up-to-date (they must still be in the dependency graph).
	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.

	<P><DT><CODE>
	LEAVES <I>targets</I> ;
	</CODE>

	<DD> Makes each of <I>targets</I> depend only on its leaf sources,
	and not on any intermediate targets.  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.

	<P><DT><CODE>
	NOCARE <I>targets</I> ;
	</CODE>

	<DD> Causes <b>jam</b> to ignore <I>targets</I> that neither
	can be found nor have updating actions to build them.  Normally
	for such targets <B>jam</B> issues a warning and then skips
	other targets that depend on these missing targets.  The HdrRule
	in Jambase uses NOCARE on the header file names found during
	header file scanning, to let <b>jam</b> 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.

	<P><DT><CODE>
	NOTFILE <I>targets</I> ;
	</CODE>

	<DD> Marks <I>targets</I> as pseudotargets and not real files.
	No timestamp is checked, and so 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 <b>jam</b>
	target "all" is a pseudotarget. In Jambase, NOTFILE is used to
	define several addition convenient pseudotargets.

	<P><DT><CODE>
	NOUPDATE <I>targets</I> ;
	</CODE>

	<DD> Causes the timestamps on <I>targets</I> to be ignored.
	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.

	<P><DT><CODE>
	TEMPORARY <I>targets</I> ;
	</CODE>

	<DD> Marks <I>targets</I> as temporary, allowing them to be
	removed after other targets that depend upon them have been
	updated.  If a TEMPORARY target is missing, <b>jam</b> uses the
	timestamp of the target's parent.  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.

	</DL></TABLE>

	<P> <H5> Utility Rules </H5> 

	The remaining rules are utility rules.

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

	<P><DT><CODE>
	ECHO <i>args</I> ; <br>
	Echo <i>args</I> ; <br>
	echo <i>args</I> ;
	</CODE>

	<DD> Blurts out the message <i>args</I> to stdout.

	<P><DT><CODE>
	EXIT <i>args</I> ; <br>
	Exit <i>args</I> ; <br>
	exit <i>args</I> ;
	</CODE>

	<DD> Blurts out the message <i>args</I> to stdout and then exits
	with a failure status.

	<P><DT><CODE>
	GLOB <i>directories</I> : <I>patterns</I> ;
	</CODE>

	<DD> Scans <i>directories</i> for files matching <i>patterns</i>,
	returning the list of matching files (with directory prepended).
	<i>patterns</i> uses the same syntax as in the <b>switch</b>
	statement.  Only useful within the <tt>[ ]</tt> construct, to
	change the result into a list.

	<P><DT><CODE>
	MATCH <i>regexps</I> : <I>list</I> ;
	</CODE>

	<DD> Matches the <b>egrep</b>(1) style regular expressions
	<I>regexps</I> against the strings in <I>list</I>.  The result
	is the concatenation of matching <tt>()</tt> subexpressions for
	each string in <I>list</I>, and for each regular expression in
	<I>regexps</I>.  Only useful within the <tt>[ ]</tt> construct,
	to change the result into a list.

	</DL></TABLE>

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

	<P>

	This section discusses variables that have special meaning to
	<b>jam</b>.

	<A NAME="search">
	<P> <H4> SEARCH and LOCATE Variables </H4>
	</A>

	<P>

	These two variables control the binding of file target names to
	locations in the file system.  Generally, $(SEARCH) is used to
	find existing sources while $(LOCATE) is used to fix the location
	for built targets.

	<P>

	Rooted (absolute path) file targets are bound as is.  Unrooted
	file target names are also normally bound as is, and thus relative
	to the current directory, but the settings of $(LOCATE) and
	$(SEARCH) alter this:

	<P>

	<UL>

	<LI> If $(LOCATE) is set then the target is bound relative to
	the first directory in $(LOCATE).  Only the first element is
	used for binding.

	<LI> If $(SEARCH) is set then the target is bound to the first
	directory in $(SEARCH) where the target file already exists.

	<LI> If the $(SEARCH) search fails, the target is bound relative
	to the current directory anyhow.

	</UL>

	<P>

	Both $(SEARCH) and $(LOCATE) should be set target-specific and
	not globally.  If they were set globally,  <b>jam</b> 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.

	<A NAME="hdrscan">
	<P> <H4> HDRSCAN and HDRRULE Variables </H4>
	</A>

	<P>

	These two variable control header file scanning.  $(HDRSCAN) is
	an <b>egrep</b>(1) pattern, with ()'s surrounding the file name,
	used to find file inclusion statements in source files.  Jambase
	uses $(HDRPATTERN) as the pattern for $(HDRSCAN).  $(HDRRULE)
	is the name of a rule to invoke with the results of the scan:
	the scanned file is the target, the found files are the sources.
	$(HDRRULE) is run under the influence of the scanned file's
	target-specific variables.

	<P>

	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.

	<P>

	The scanning for header file inclusions is not exact, but it is
	at least dynamic, so there is no need to run something like
	<b>makedepend</b>(GNU) to create a static dependency file. The
	scanning mechanism errs on the side of inclusion (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 yet
	doesn't cause the compilation to fail, <b>jam</b> won't care.

	<P>

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

	<P> <H4> Platform Identifier Variables </H4>

	<P>

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

	<P>

	<TABLE WIDTH=75% ALIGN=CENTER>

	    <TR><TD>OS<TD>OS identifier string 
	    <TR><TD>OSPLAT<TD>Underlying architecture, when applicable
	    <TR><TD>MAC<TD>true on MAC platform
	    <TR><TD>NT<TD>true on NT platform
	    <TR><TD>OS2<TD>true on OS2 platform
	    <TR><TD>UNIX<TD>true on Unix platforms
	    <TR><TD>VMS<TD>true on VMS platform

	</TABLE>

	<P> <H4> Jam Version Variables </H4>

	<P>

	<TABLE WIDTH=75% ALIGN=CENTER>

	    <TR><TD>JAMDATE<TD>Time and date at <b>jam</b> start-up.
	    <TR><TD>JAMUNAME<TD>Ouput of <b>uname</b>(1) command (Unix only)
	    <TR><TD>JAMVERSION<TD><b>jam</b> version, as reported by jam -v.

	</TABLE>

	<P> <H4> JAMSHELL Variable </H4>

	<P>

	When  <b>jam</b>  executes a  rule's action block, it forks and
	execs a shell, passing the action block as an argument to the
	shell.   The invocation of the shell can be controlled by
	$(JAMSHELL).  The default on Unix is, for example:

	<P>

	<CODE>JAMSHELL = /bin/sh -c % ;</CODE>

	<P>

	The % is replaced with the text of the action block.

	<P>

	<B>Jam</b>  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.

	<P>

	Just as <b>jam</b> 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:

	<P>

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

	    <BR>#!/bin/sh
	    <BR>
	    <BR># This sample JAMSHELL uses the SunOS on(1) command to execute a
	    <BR># command string with an identical environment on another host.
	    <BR>
	    <BR># Set JAMSHELL = jamshell ! %
	    <BR>#
	    <BR># where jamshell is the name of this shell file.
	    <BR>#
	    <BR># This version handles up to -j6; after that they get executed
	    <BR># locally.
	    <BR>
	    <BR>case $1 in
	    <BR>1|4) on winken sh -c "$2";;
	    <BR>2|5) on blinken sh -c "$2";;
	    <BR>3|6) on nod sh -c "$2";;
	    <BR>*)   eval "$2";;
	    <BR>esac

	</CODE></TABLE>


<DT> <P> <H2> DIAGNOSTICS </H2>  <DD>

	<P>

       In addition to generic error messages, <B>jam</B> may emit one of
       the following:

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

       <P><DT><CODE> warning: unknown rule X </CODE> <DD>

              A rule was invoked that has not been defined with
              an "actions" or "rule" statement.

       <P><DT><CODE> using N temp target(s) </CODE> <DD>

              Targets marked as being temporary (but nonetheless
              present) have been found.

       <P><DT><CODE> updating N target(s) </CODE> <DD>

              Targets are out-of-date and will be updated.

       <P><DT><CODE> can't find N target(s) </CODE> <DD>

              Source files can't be found and there are no
              actions to create them.

       <P><DT><CODE> can't make N target(s) </CODE> <DD>

              Due to sources not being found, other targets cannot be made.

       <P><DT><CODE> warning: X depends on itself </CODE> <DD>

              A target depends on itself either directly or
              through its sources.

       <P><DT><CODE> don't know how to make X </CODE> <DD>

              A target is not present and no actions have been
              defined to create it.

       <P><DT><CODE> X skipped for lack of Y </CODE> <DD>

              A source failed to build, and thus a target cannot
              be built.

       <P><DT><CODE> warning: using independent target X </CODE> <DD>

              A target that is not a dependency of any other
              target is being referenced with $(&lt;) or $(&gt;).

       <P><DT><CODE> X removed </CODE> <DD>

              <b>Jam</b>  removed a  partially built target after being
              interrupted.

	</DL></TABLE>

<DT> <P> <H2> BUGS, LIMITATIONS </H2> <DD>

	<P>

	The -j flag can cause <B>jam</B> to get confused when single
	actions update more than one target at a time. <B>jam</B> may
	proceed as if the targets were built even though they are still
	under construction.

	<P>

	For parallel building to be successful, the dependencies among
	files must be properly spelled out, as targets tend to get built
	in a quickest-first ordering.  Also, beware of un-parallelizable
	commands that drop fixed-named files into the current directory,
	like <b>yacc</b>(1) does.

	<P>

	With the -j flag, errors from failed commands can get staggeringly
	mixed up.  

	<P>

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

<DT> <P> <H2> SEE ALSO </H2> <DD>

	<P>

	<UL>

	<LI> <a href="Jambase.html">Jambase Reference</a>

	<LI> <a href="Jamfile.html">Using Jamfiles and Jambase</a>

	</UL>

	<P>

	Jam documentation and source are available from the <A
	HREF="http://public.perforce.com/public/index.html">Perforce
	Public Depot</a>.

<DT> <P> <H2> AUTHOR </H2>   <DD>

	<P>
	Jam's author is Christopher Seiwald (<a 
	href="mailto:[e-mail]">[e-mail]</A>).
	Documentation is provided by 
	<A HREF="http://www.perforce.com">Perforce Software, Inc.</A>

</DL>

<P> <HR>   

	<P>

        Copyright 1993-2002 Christopher Seiwald and Perforce Software, Inc.
        <BR>
        Comments to <A HREF="mailto:[e-mail]">[e-mail]</A>
        <BR>
        Last updated: May, 2002
	<BR>
	$Id: //public/jam/src/Jam.html#19 $

</BODY> 
</HTML>