jamfile.html

jam源码

<P>
       The header file scanning occurs during the "file  binding"
       phase   of  <b>jam</b>,  which  means  that  the  target-specific
       variables (for the source file) are in effect.  To accomodate 
       nested includes, one of the HdrRule's jobs is to pass
       the target-specific values of $(HDRRULE), $(HDRSCAN),  and
       $(HDRSEARCH) onto the included files, so that they will be
       scanned as well.
<P>
<H4>
   HdrRule Rule
</H4>
	Normally, HdrRule is not invoked directly; the Object rule
	(called by Main and Library) invokes it.
	<P>
	If there are special dependencies that need to be set,
	and which are not set by HdrRule itself, you can define
	another rule and let it invoke HdrRule.  For example:

<PRE>
	#In Jamrules:
              rule BuiltHeaders
              {
                      DEPENDS $(&gt;) : mkhdr$(SUFEXE) ;
                      HdrRule $(&lt;) : $(&gt;) ;
              }

	#In Jamfile:
              Main mkhdr : mkhdr.c ;
              Main ugly : ugly.c ;

              HDRRULE on ugly.c = BuiltHeaders ;

</PRE>
       This example just says that the files included by "ugly.c"
       are  generated  by the program "mkhdr", which can be built
       from "mkhdr.c".  During the binding phase, <b>jam</b> will
       scan ugly.c, and if it finds an include file, ughdr.h,
       for example, it will automatically invoke the rule:
       <PRE>
              BuiltHeaders ugly.c : ughdr.h ;
       </PRE>
       By calling HdrRule at the end  of  BuiltHeaders,  
       all  the gadgetry of HdrRule takes effect and it
       doesn't need to be duplicated.
<P>
<H4>
   Variables Used for Header Scanning
</H4>
<CENTER>
<TABLE>
<TR><TD VALIGN=TOP>
              HDRPATTERN    
	      <TD><TD>Default scan pattern for "include" lines.
<TR><TD VALIGN=TOP>
              HDRSCAN         
	      <TD><TD>Scan pattern to use. 
		This is a special variable: during binding, if
		both HDRSCAN and HDRRULE are set, scanning is activated
		on the target being bound.
		The HdrRule and Object rules sets this
		to $(HDRPATTERN) on their source targets.
<TR><TD VALIGN=TOP>
              HDRRULE         
	      <TD><TD>Name of rule to invoked on files found in header
		scan. The HdrRule and Object rules set this to "HdrRule"
		on their source targets. This is also a special variable;
		it's the only <b>jam</b> variable that can hold the
		name of a rule to be invoked.
<TR><TD VALIGN=TOP>
              HDRSEARCH       
	      <TD><TD>Search paths for files found during header scanning.
		This is set from $(HDRS) and $(STDHDRS), which are 
		described in the Compiling section.
		<b>jam</b> will search $(HDRSEARCH) directories for
		the files found by header scans. 
</TABLE>
</CENTER>
<P>
       The  Object rule sets HDRRULE and HDRSCAN specifically for
       the source files to be scanned, rather than globally.   If
       they  were  set  globally,  jam  would attempt to scan all
       files, even library archives and executables,  for  header
       file  inclusions.   That  would  be  slow and probably not
       yield desirable results.
<P>
<H2>
Copying Files
</H2>
<H4>
   File Rule
</H4>
       The File rule copies one file to another.  The target name
       needn't  be the same as the source name.  For
       example:
<PRE>
	switch $(OS)
	{
           case NT*  : File config.h : confignt.h ;
	   case *    : File config.h : configunix.h ;
	}
	LOCATE on config.h = $(LOCATE_SOURCE) ;
</PRE>
	This creates a config.h file from either confignt.h or
	configunix.h, depending on the current build platform.
<P>
	The File rule does not
	use the LOCATE_SOURCE variable set by the
	SubDir rule (although it does use SEARCH_SOURCE), which
	means you have to set the copied file's output directory
	yourself. That's done by setting the special
	LOCATE variable on the target, as shown above,
	or with the MakeLocate rule described below.
<H4>
   Bulk Rule
</H4>
       The Bulk rule is a shorthand for many invocations  of  the
       File  rule when all files are going to the same directory.
       For example:
<PRE>
	#In Jamrules:
              DISTRIB_GROB = d:\\distrib\\grob ;

	#In Jamfile:
              Bulk $(DISTRIB_GROB) : grobvals.txt grobvars.txt ;
</PRE>
	This causes gobvals.txt and grobvars.txt to be copied
	into the $(DISTRIB_GROB) directory.
<H4>
   HardLink Rule
</H4>
       The Unix-only HardLink rule makes a hard link (using ln(1)) from the
       source  to  the  target,  if there isn't one already.  For
       example:
<PRE>
              HardLink config.h : configunix.h ;
</PRE>
<H4>
   Shell Rule
</H4>
       The Shell rule is like the File rule, except that on Unix it makes
       sure  the first line of the target is "#!/bin/sh" and sets
       the permission to make the file executable.  For example:
<PRE>
              Shell /usr/local/bin/add : add.sh ;
</PRE>
<P>
	You can also use $(SHELLHEADER) to dictate
	what the first line of the copied file will be.
       For
       example:
<PRE>
              Shell /usr/local/bin/add : add.awk ;
              SHELLHEADER on /usr/local/bin/add = "#!/bin/awk -f" ;
</PRE>
       This installs an awk(1) script.
<P>
<H4>
   Variables Used When Copying Files
</H4>
<CENTER>
<TABLE>
<TR><TD VALIGN=TOP>
              FILEMODE      
	      <TD><TD>Default file permissions for copied files
<TR><TD VALIGN=TOP>
              SHELLMODE     
	      <TD><TD>Default file permissions for Shell rule targets
<TR><TD VALIGN=TOP>
              MODE            
	      <TD><TD>File permissions set on files copied by
		File, Bulk, and Shell rules. 
       		File and Shell sets a target-specific MODE to the  current
       		value  of  $(FILEMODE) or $(SHELLMODE), respectively.  
<TR><TD VALIGN=TOP>
              SHELLHEADER     
	      <TD><TD>String to write in first line of Shell targets 
	      (default is #!/bin/sh).

</TABLE>
</CENTER>
<P>

<H2>
Installing Files
</H2>
Jambase provides a set of Install* rules to copy files
into an destination directory and set permissions on them.
On Unix, the install(1) program is used.
If the destination directory does not exist, <b>jam</b>
creates it first.
<P>
All files copied with the Install* rules are dependencies
of the <i>install</i> pseudotarget, which means that the
command "jam install" will cause the installed copies to
be updated. Also, "jam uninstall" will cause the installed
copies to be removed.
<P>
The Install* rules are:
<CENTER>
<TABLE>
<TR><TD VALIGN=TOP><B>InstallBin</B>
    <TD VALIGN=TOP>Copies file and sets its permission to $(EXEMODE).
		   You must specify the suffixed executable name. E.g.:
    <PRE>InstallBin $(BINDIR) : thing$(SUFEXE) ;
		   </PRE>

<TR><TD VALIGN=TOP><B>InstallFile</B>
    <TD VALIGN=TOP>Copies file and sets its permission to $(FILEMODE). E.g.:
    <PRE>InstallFile $(DESTDIR) : readme.txt ;
		   </PRE>

<TR><TD VALIGN=TOP><B>InstallLib</B>
    <TD VALIGN=TOP>Copies file and sets its permission to $(FILEMODE).
		   You must specify the suffixed library name. E.g.:
    <PRE>InstallLib $(LIBDIR) : libzoo$(SUFLIB) ;
		   </PRE>

<TR><TD VALIGN=TOP><B>InstallMan</B>
    <TD VALIGN=TOP>Copies file into the man<i>n</i>
		   subdirectory of the target directory
		   and sets its permission to $(FILEMODE). E.g.,
		   this copies foo.5 into the $(DESTDIR)/man5 directory:
    <PRE>InstallMan $(DESTDIR) : foo.5 ;
		   </PRE>

<TR><TD VALIGN=TOP><B>InstallShell</B>
    <TD VALIGN=TOP>Copies file and sets its permission to $(SHELLMODE). E.g.:
    <PRE>InstallShell $(DESTDIR) : startup ;
		   </PRE>

</TABLE>
</CENTER>
<P>
<P>
<H4>
   Variables
</H4>
       The following variables control the installation rules:
<P>
<CENTER>
<TABLE>
<TR><TD>
              INSTALL        
	      <TD><TD>The install program (Unix only)
<TR><TD>
              FILEMODE     
	      <TD><TD>Default file permissions on readable files. 
<TR><TD>
              EXEMODE      
	      <TD><TD>Default file permission executable files.
<TR><TD>
              SHELLMODE    
	      <TD><TD>Default file permission on shell script files.
<TR><TD>
              MODE           
	      <TD><TD>Target-specific file permissions
</TABLE>
</CENTER>
<P>
<P>
       The  Install  rules set a target-specific MODE to the current 
       value of $(FILEMODE),  $(EXEMODE),  or  $(SHELLMODE),
       depending on which Install rule was invoked.
<P>
       The  directory variables are just defined for convenience:
       they must be passed  as  the  target  to  the  appropriate
       Install  rule.   The $(INSTALL) and mode variables must be
       set (globally) before calling the Install rules  in  order
       to take effect.
<P>
<H2>
Miscellaneous Rules
</H2>
<H4>
Clean Rule
</H4>
<P>
The Clean rule defines files to be removed when you run "jam clean".
Any site-specific build rules defined in your Jamrules should invoke
Clean so that outputs can be removed. E.g.,
<PRE>
	rule ResourceCompiler
	{
	   DEPENDS $(<) : $(>) ;
	   Clean clean : $(<) ;
	}
</PRE>
<P>
<P>
Most Jambase rules invoke the Clean rule on their built targets,
so "jam clean" will remove all compiled objects, libraries,
executables, etc.
<P>
<H4>
MakeLocate Rule
</H4>
      MakeLocate is a single convenient rule that creates a directory,
      sets LOCATE on a target to that directory, and makes the directory
      a dependency of the target. It is used by many Jambase rules,
      and can be invoked directly, e.g.:
      <PRE>
		GenFile data.tbl : hxtract data.h ;
		MakeLocate data.tbl : $(TABLEDIR) ;
      </PRE>
      In this example, the File rule creates data.tbl from data.h.
      The MakeLocate causes data.tbl to be written into the $(TABLEDIR)
      directory; and if the directory doesn't exist, it is created first.
      <P>
      The MakeLocate rule invokes another Jambase rule, MkDir,
      to (recursively) create
      directories. MkDir uses the $(MKDIR) variable to determine the
      platform-specific command that creates directories.
<P>
<H4>
RmTemps Rule
</H4>
	Some intermediate files are meant to be temporary. 
	The RmTemps rule can be used to cause 
	<b>jam</b> to delete them after they are used. 
	<P>
	RmTemps must be:
	<UL>
	<LI>
	the last rule 
	invoked on the permanent file that uses
	the temporary file(s) 
	<LI>
	invoked with the permanent file as the output
	target and the temporary file(s) as the input target
	<LI>
	invoked with the exact target identifiers of
	the permanent file and the temporary file(s)
	</UL>
	For
	example: 
	<PRE>
		SubDir TOP src big ;
		GenFile big.y : joinfiles part1.y part2.y part3.y ;
		Main bigworld : main.c big.y ;
		RmTemps bigworld$(SUFEXE) : &lt;src!big&gt;big.y ;
	</PRE>
	This causes big.y to be deleted after it has been used to create
	the bigworld executable. 
	The exact target identifier of big.y is  &lt;src!big&gt;big.y
	(the GenFile and Main rules tack on the grist automatically);
	the exact target identifier of the bigworld executable
	is bigworld$(SUFEXE).
<P>
<HR>   
<A HREF="#TOP">Back to top.</A>
<P>
        Copyright 1997, 2000 Perforce Software, Inc.
        <BR>
        Comments to <A HREF="mailto:[e-mail]">[e-mail]</A>
        <BR>
        Last updated: Dec 31, 2000
	<BR>
	$Id: //public/jam/src/Jamfile.html#6 $
</BODY> 
</HTML>