doc/Jamfile.html

   1 <HTML>
   2 <TITLE>
   3 Jamfiles and Jambase
   4 </TITLE>
   5 <BODY>
   6 <CENTER>
   7 <A HREF=http://www.perforce.com/jam/jam.html>
   8 Jam
   9 </a>
  10 <A NAME="TOP">
  11 <H2>
  12 Using Jamfiles and Jambase
  13 </H2>
  14 </A>
  15 </CENTER>
  16 <P>
  17 This document describes how to write Jamfiles using the Jam Jambase
  18 rules to build software products.
  19 Related documents of interest are:
  20 <UL>
  21 <LI>
  22   <a href="Jam.html">The Jam Executable Program</A>,
  23   which describes using the <b>jam</b> command and the
  24   langauge used in Jambase
  25 <LI>
  26   <A href="Jambase.html">Jambase Reference</A>,
  27   which summarizes the Jambase rules and variables
  28 </UL>
  29 <HR>
  30 <P>
  31 <H2>
  32 Overview
  33 </H2>
  34 <P><B>jam,</B> the Jam executable program,
  35 recursively  builds  target files  from source files
  36 using dependency and build specifications defined
  37 in Jam rules files.
  38 <B>jam</B> parses the rules files to identify targets
  39 and sources,
  40 examines the filesystem to determine which
  41 targets need updating, and issues OS commands to update
  42 targets.
  43 <P>A base rules file called "Jambase" is provided with the
  44 Jam distribution.
  45 The Jambase file defines rules and variables which support
  46 standard software build operations, like compiling, linking,
  47 etc.
  48 <P>
  49   When the Jambase rules are used,
  50   <B>jam</B> reads Jambase, then reads a file called
  51   "Jamfile" in the current directory.
  52   The Jamfile describes what to do with the source files in
  53   its directory. It may also cause
  54   Jamfiles in other directories to be read.
  55   <P>
  56   Under certain circumstances, the first Jamfile read
  57   also causes a site-specific "Jamrules" file to be read.
  58   The Jamrules file is an optional set of rule and variable
  59   definitions used to define site-specific processing.
  60 <P>
  61 <H4>
  62 The Basic Jamfile
  63 </H4>
  64 <P>
  65 Jamfiles contain rule invocations, which usually look like:
  66 <PRE>
  67   <I>RuleName</I> <I>targets</I> : <I>targets</I> ;
  68 </PRE>
  69 The target(s) to the left of the colon usually indicate
  70 what gets built, and the target(s) to the right of the
  71 colon usually indicate what it is built from.
  72 <P>
  73 <P>
  74 A Jamfile can be as simple as this:
  75 <PRE>
  76   Main myprog : main.c util.c ;
  77 </PRE>
  78 This specifies that there is a main.c and util.c file in the same
  79 directory as the Jamfile, and that those source files should be
  80 compiled and linked into an executable called myprog.
  81 If you cd to the directory where this Jamfile lives,
  82 you can see the exactly how <b>jam</b> would
  83 build myprog with:
  84 <PRE>
  85   jam -n
  86 </PRE>
  87 Or, you can actually build myprog with the command:
  88 <PRE>
  89   jam
  90 </PRE>
  91
  92 <P>
  93 <H4>
  94 Whitespace
  95 </H4>
  96 Jamfile elements are delimited by whitespace (blanks, tabs, or
  97 newlines). Elements to be delimited include rule names, targets,
  98 colons, and semicolons. A common mistake users make is to forget the
  99 whitespace, e.g.,
 100 <PRE>
 101   Main myprog: main.c util.c ; #<I>WRONG!</I>
 102 </PRE>
 103 Jam doesn't distinguish between a typo and a target called "myprog:",
 104 so if you get strange results, the first thing
 105 you should check for in your Jamfile is missing whitespace.
 106 <P>
 107 <H4>
 108 Filenames, Target Identifiers, and Buildable Targets
 109 </H4>
 110 <P>
 111 Consider this Jamfile:
 112 <PRE>
 113   Main myprog : main.c util.c ;
 114   LinkLibraries myprog : libtree ;
 115   Library libtree : treemake.c treetrav.c ;
 116 </PRE>
 117 <P>
 118 The Main rule specifies that an executable called myprog will be built.
 119 The compiled main.c and util.c objects will be linked to produce
 120 myprog.
 121 The LinkLibraries rule specifies that libtree will
 122 be linked into myprog as well.
 123 The Library rule specifies which source files will be compiled and
 124 archived into the libtree library.
 125 <P>
 126 The Jamfile above refers to targets like "myprog" and "libtree".
 127 However, depending on the platform you're building on, the actual
 128 filenames of those targets could be "myprog.exe" and "libtree.lib".
 129 Most Jambase rules supply the actual filenames of targets,
 130 so that Jamfiles themselves need not make any
 131 platform-specific filename references.
 132 <P>
 133 The <b>jam</b> program builds up a list of unique target identifiers.
 134 Unless you are using the SubDir rules (described later),
 135 the default identifier for a file target is its filename. In the above
 136 example, the target identifiers are the filenames: myprog.exe,
 137 libtree.lib, main.obj, etc.
 138 <P>
 139 While all Jambase rules refer to "targets",
 140 not all targets are buildable.
 141 There are two kinds of buildable targets:
 142 file targets and pseudotargets.
 143 File targets are objects that can be found in the filesystem.
 144 Pseudotargets are symbolic, and represent other targets.
 145 <P>
 146 You can use any buildable target on the <b>jam</b> command line to
 147 build a subset of defined targets. For example:
 148 <PRE>
 149         jam libtree.a
 150 </PRE>
 151 on Unix builds the libtree library and all the compiled objects
 152 that go in it.
 153 <P>
 154 <H4>
 155 Pseudotargets
 156 </H4>
 157 <P>
 158 Most Jambase rules that define file targets also define pseudotargets
 159 which are dependent on types of file targets.
 160 For example, Jambase defines a pseudotarget called "lib", which
 161 is dependent on file targets created by the Library rule. So
 162 the command:
 163 <PRE>
 164         jam lib
 165 </PRE>
 166 used with the above example would cause the libtree library to be built.
 167 Also, there is one pseudotarget built into <b>jam</b> itself, called
 168 "all". Jambase sets "all" dependent on (almost) all other targets.
 169 <P>
 170 In the unfortunate case where you have a buildable target whose name
 171 is the same as one of the Jambase pseudotargets, you'll have problems
 172 with the conflicting target name.
 173 Your workaround choices are:
 174 <P>
 175 <ol>
 176 <lI>Change the name of your buildable file or directory that conflicts.
 177 <p>
 178 <li>Modify your Jambase and change the name of the conflicting pseudotarget.
 179 (Pseudotargets are defined in Jambase using the NOTFILE rule.)
 180 <p>
 181 <li>Use grist on the conflicting target name in your Jamfile. E.g., instead
 182     of
 183     <PRE>
 184     File lib : libfoo.a ;
 185     </PRE>
 186     try
 187     <PRE>
 188     File &lt;dir&gt;lib : libfoo.a ;
 189     </PRE>
 190 </ol>
 191 <P>
 192
 193 <H4>
 194 Dependencies
 195 </H4>
 196 <P>
 197 Jambase rules set dependencies on targets, so that if you update a
 198 source file, all the file targets that depend on that source
 199 file, and only the ones that depend on that source file,
 200 will be updated (rebuilt) the next time you run <b>jam</b>.
 201 <P>
 202 Here are some of the dependencies
 203 that get set when <b>jam</b> runs on NT using the example Jamfile above:
 204 <CENTER>
 205 <TABLE>
 206 <TR><TD><B>Target</B><TD>&nbsp;&nbsp;&nbsp;<TD><B>Depends on</B></TD>
 207 <TR><TD>myprog.exe<TD><TD>main.obj, util.obj, libtree.lib
 208 <TR><TD>libtree.lib<TD><TD>treemake.obj, treetrav.obj
 209 <TR><TD>treetrav.obj<TD><TD>treetrav.c
 210 </TABLE>
 211 </CENTER>
 212 <P>
 213 Furthermore, the Main and Library rules set up recursive
 214 header scanning on their source targets.
 215 So after <b>jam</b> has finished parsing the Jamfile and
 216 setting the rule-driven dependencies, it scans the source
 217 files for "#include" lines. All #include files found during
 218 this scan become dependencies of the compiled object.
 219 E.g., all header files used to compile treetrav.c would
 220 be made dependencies of treetrav.obj.
 221 <P>
 222 As a result, when you run <b>jam</b>, it will rebuild targets
 223 if either the source files change or the
 224 header files change. You can't tell by looking at a Jamfile
 225 which header files are dependencies, but you can easily
 226 display those dependencies with:
 227 <PRE>
 228   jam -nd+3
 229 </PRE>
 230 <H4>
 231 Rule Ordering
 232 </H4>
 233 <P>
 234 Rules which specify dependencies, like the Main, Library, and
 235 LinkLibrary rules, can be invoked in any order. <b>jam</b>
 236 figures out the order in which targets are built from
 237 their dependencies.
 238 <P>
 239 Some rules, however, set variables which are used by subsequent
 240 rule invocations, and their ordering is important.
 241 For example, the SubDir* rules (discussed
 242 later) must be invoked in a particular order.
 243
 244 <P>
 245 <H4>
 246 Detailed Jambase Specifications
 247 </H4>
 248 <P>
 249 This document describes how to use various Jambase rules
 250 from a functional point of view.
 251 You can see the summary of available Jambase rules in the
 252 <a href="Jambase.html">Jambase Reference</A>.
 253 The detailed specifications for any Jambase rule
 254 can be found by reading the rule definition itself
 255 in the Jambase file.
 256 <P>
 257
 258 <HR>
 259 <H2>
 260 Handling Directory Trees
 261 </H2>
 262        The SubDir* rules are used to
 263        define source code directory hierarchies.
 264        With SubDir and SubInclude, you can use <b>jam</b>
 265        to build software from source files and Jamfiles spread
 266        across many directories, as is typical for large projects.
 267        The SubDir* rules unify an entire
 268        source code tree so that <b>jam</b> can read in
 269        all the Jamfiles in one pass and
 270        compute dependencies across the entire project.
 271 <P>
 272   To use the SubDir* rules, you must:
 273 <P>
 274 <OL>
 275        <LI>     Preface the Jamfile in each directory with an invocation
 276        of the SubDir rule.
 277 <P>
 278        <LI>     Place  at  the  root  of the tree a file named Jamrules.
 279         This file could be empty,  but  in
 280               practice  it contains user-provided rules and variable
 281         definitions that  are  shared  throughout  the
 282               tree.   Examples  of  such  definitions are library
 283               names,  header  directories,  install  directories,
 284               compiler  flags,  etc.  This file is good candidate
 285               for automatic customizing with autoconf(GNU).
 286 <P>
 287   <LI>  Optionally, set an environment variable pointing
 288     to the root directory of the srouce tree. The
 289     variable's name is left up to you, but in these
 290     examples, we use TOP.
 291 </OL>
 292 <P>
 293 <H4>
 294    SubDir Rule
 295 </H4>
 296 <P>
 297        The  SubDir  rule  must  be  invoked before any rules that
 298        refer to the contents of the directory - it is best to put
 299        it at the top of each Jamfile.  For example:
 300 <PRE>
 301   # Jamfile in $(TOP)/src/util directory.
 302
 303   SubDir TOP src util ;
 304
 305   Main myprog : main.c util.c ;
 306   LinkLibraries myprog : libtree ;
 307   Library libtree : treemake.c treetrav.c ;
 308 </PRE>
 309        This  compiles  four  files  in  $(TOP)/src/util, archives
 310        two of the objects into libtree, and links  the  whole
 311        thing into myprog.
 312        Outputs are placed in the $(TOP)/src/util
 313        directory.
 314        <P>
 315        This doesn't appear to be any different from
 316        the previous example that didn't have a SubDir rule,
 317        but two things are happening behind the scenes:
 318        <OL>
 319        <LI>The SubDir rule causes <b>jam</b> to read
 320      in the $(TOP)/Jamrules file.
 321            (The Jamrules file can alternately be named by  the
 322               variable  $(xxxRULES), where xxx is the name of the
 323               root variable, e.g., $(TOPRULES)).
 324         <P>
 325      The Jamrules file can contain variable definitions
 326      and rule definitions specific to your codeline.
 327      It allows you to completely customize your build
 328      environment without having to rewrite Jambase.
 329      Jamrules is only read
 330      in once, at the first SubDir invocation.
 331      </LI>
 332   <LI>
 333      The SubDir rule initializes a set of variables
 334      that are used by Main and other rules to
 335      uniquely identify the source files in this
 336      directory and assign locations to the targets
 337      built from files in this directory.
 338      <P>
 339      When you have set a root variable, e.g., $(TOP),
 340      SubDir constructs path names rooted with $(TOP),
 341      e.g., $(TOP)/src/util.
 342      Otherwise, SubDir constructs relative pathnames
 343      to the root directory, computed from the number
 344      of arguments to the first SubDir rule, e.g.,
 345      ../../src/util. In either case, the SubDir
 346      rule constructs the path names that locate source
 347      files.
 348      You'll see how this is useful later.
 349   </LI>
 350        </OL>
 351
 352 <P>
 353        The SubDir rule takes  as  its  first  argument  the  root
 354        variable's  name  and  takes  as  subsequent arguments the
 355        directory names leading from the root to the directory  of
 356        the  current Jamfile.  Note that the name of the subdirectory
 357        is given as individual  elements:   the  SubDir  rule
 358        does not use system-specific directory name syntax.
 359 <P>
 360 <P>
 361 <H4>
 362    SubInclude Rule
 363 </H4>
 364   The SubInclude rule is used in a Jamfile to cause another
 365   Jamfile to be read in.
 366        Its arguments are in  the  same  format  as
 367        SubDir's.
 368 <P>
 369        The  recommended  practice is only to include one level of
 370        subdirectories at a time, and let the Jamfile in each subdirectory
 371        include  its own subdirectories.  This allows a
 372        user to sit in any arbitrary directory of the source  tree
 373        and build that subtree.  For example:
 374 <PRE>
 375        # This is $(TOP)/Jamfile, top level Jamfile for mondo project.
 376
 377        SubInclude TOP src ;
 378        SubInclude TOP man ;
 379        SubInclude TOP misc ;
 380        SubInclude TOP util ;
 381 </PRE>
 382        If  a directory has both subdirectories of its own as well
 383        as files that need building,  the  SubIncludes  should  be
 384        either before the SubDir rule or be at the end of the Jamfile
 385        - not between the SubDir and other rule  invocations.
 386        For example:
 387 <PRE>
 388   # This is $(TOP)/src/Jamfile:
 389
 390   SubDir TOP src ;
 391
 392   Main mondo : mondo.c ;
 393   LinkLibraries mondo : libmisc libutil ;
 394
 395   SubInclude TOP src misc ;
 396   SubInclude TOP src util ;
 397 </PRE>
 398 <P>
 399   (<b>jam</b> processes all the Jamfiles it reads as if
 400   it were reading one single, large Jamfile.
 401   Build rules like Main and LinkLibraries rely on the
 402   preceding SubDir rule to set up source file and
 403   output file locations, and SubIncludes rules read in
 404   Jamfiles that contain SubDir rules. So if you put
 405   a SubIncludes rule between a SubDir and a Main
 406   rule, <b>jam</b> will try to find the source files
 407   for the Main rule in the wrong directory.)
 408 <P>
 409 <H4>
 410    Variables Used to Handle Directory Trees
 411 </H4>
 412        The  following  variables are set by the SubDir rule
 413        and used by the Jambase rules that define file targets:
 414 <P>
 415 <CENTER>
 416 <TABLE>
 417 <TR><TD VALIGN=TOP>
 418               SEARCH_SOURCE
 419         <TD><TD>The SubDir targets (e.g., "TOP src util")
 420         are used to construct a pathname (e.g., $(TOP)/src/util),
 421         and that pathname is assigned to $(SEARCH_SOURCE).
 422         Rules like Main and Library use $(SEARCH_SOURCE)
 423         to set search paths on source files.
 424 <TR><TD VALIGN=TOP>
 425               LOCATE_SOURCE
 426         <TD><TD>Initialized by the SubDir rule to the same
 427         value as $(SEARCH_SOURCE), unless ALL_LOCATE_TARGET
 428         is set.
 429         $(LOCATE_SOURCE) is used by rules that build
 430         generated source files (e.g., Yacc and Lex) to
 431         set location of output files.
 432         Thus the default location of built source files
 433         is the directory of the Jamfile that defines them.
 434 <TR><TD VALIGN=TOP>
 435               LOCATE_TARGET
 436         <TD><TD>Initalized by the SubDir rule to the same
 437         value as $(SEARCH_SOURCE), unless ALL_LOCATE_TARGET
 438         is set.
 439         $(LOCATE_TARGET) is used by rules that build
 440         binary objects (e.g., Main and Library) to
 441         set location of output files.
 442         Thus the default location of built binaray files
 443         is the directory of the Jamfile that defines them.
 444 <TR><TD VALIGN=TOP>
 445               ALL_LOCATE_TARGET
 446         <TD><TD>
 447         If $(ALL_LOCATE_TARGET) is set, LOCATE_SOURCE
 448         and and LOCATE_TARGET are set to  $(ALL_LOCATE_TARGET)
 449         instead of to $(SEARCH_SOURCE). This can be used to
 450         direct built files to be written to a location outside
 451         of the source tree, and enables building from read-only
 452         source trees.
 453 <TR><TD VALIGN=TOP>
 454               SOURCE_GRIST
 455         <TD><TD>The SubDir targets are formed into a string
 456         like "src!util" and that string is assigned to
 457         SOURCE_GRIST. Rules that define file targets
 458         use $(SOURCE_GRIST) to set the "grist" attribute
 459         on targets. This is used to assure uniqueness
 460         of target identifiers where filenames themselves
 461         are not unique.
 462         For example, the target identifiers of
 463         $(TOP)/src/client/main.c and $(TOP)/src/server/main.c
 464         would be &lt;src!client&gt;main.c and &lt;src!server&gt;main.c.
 465 </TABLE>
 466 </CENTER>
 467 <P>
 468        The $(LOCATE_TARGET) and  $(SEARCH_SOURCE)  variables are used
 469        extensively by rules in Jambase: most rules that  generate
 470        targets  (like  Main,  Object,  etc.)  set $(LOCATE) to
 471        $(LOCATE_TARGET) for the targets they generate, and  rules
 472        that  use  sources  (most all of them) set $(SEARCH) to be
 473        $(SEARCH_SOURCE) for the sources they use.
 474 <P>
 475        $(LOCATE) and $(SEARCH) are better  explained  in
 476        <A HREF="Jam.html">The Jam Executable Program</A>
 477        but in brief they tell <B>jam</B> where to create new targets and
 478        where to find existing ones, respectively.
 479 <P>
 480        Note that you can reset these variables
 481        after SubDir sets them. For example, this Jamfile builds
 482        a program called gensrc, then runs it to create a source file
 483        called new.c:
 484        <PRE>
 485        SubDir TOP src util ;
 486        Main gensrc : gensrc.c ;
 487        LOCATE_SOURCE = $(NEWSRC) ;
 488        GenFile new.c : gensrc ;
 489        </PRE>
 490        By default, new.c would be written into the
 491        $(TOP)/src/util directory, but resetting LOCATE_SOURCE causes
 492        it to be written to the $(NEWSRC) directory. ($(NEWSRC) is assumed
 493        to have been set elsewhere, e.g., in Jamrules.)
 494 <P>
 495 <H4>
 496    VMS Notes
 497 </H4>
 498        On VMS, the logical name table is not imported as  is  the
 499        environment on UNIX.  To use the SubDir and related rules,
 500        you must set the value of the variable that names the root
 501        directory.  For example:
 502 <PRE>
 503               TOP = USR_DISK:[JONES.SRC] ;
 504
 505               SubInclude TOP util ;
 506 </PRE>
 507        The variable must have a value that looks like a directory
 508        or device.  If you choose, you can use a  concealed  logical.
 509        For example:
 510 <PRE>
 511               TOP = TOP: ;
 512
 513               SubInclude TOP util ;
 514 </PRE>
 515        The  :  at  the  end of TOP makes the value of $(TOP) look
 516        like a device name, which jam respects as a directory name
 517        and  will  use when trying to access files.  TOP must then
 518        be defined from DCL:
 519 <PRE>
 520               $ define/job/translation=concealed TOP DK100:[USERS.JONES.SRC.]
 521 </PRE>
 522        Note three things: the concealed  translation  allows  the
 523        logical  to  be  used as a device name; the device name in
 524        the logical (here DK100) cannot itself be concealed  logical
 525        (VMS  rules, man); and the directory component of the
 526        definition must end in a period (more VMS rules).
 527 <P>
 528 <H2>
 529 Building Executables and Libraries
 530 </H2>
 531 <P>
 532 The rules that build executables and libraries are: Main, Library,
 533 and LinkLibraries.
 534 <H4>
 535    Main Rule
 536 </H4>
 537        The Main rule compiles source files and links the  resulting
 538        objects into an executable.  For example:
 539 <PRE>
 540               Main myprog : main.c util.c ;
 541 </PRE>
 542        This  compiles  main.c  and  util.c  and  links main.o and
 543        util.o into myprog. The object files and resulting
 544        executable are named appropriately for the platform.
 545 <P>
 546   Main can also be used to build shared libraries and/or
 547   dynamic link libraries, since those are also linked
 548   objects. E.g.:
 549   <PRE>
 550     Main driver$(SUFSHR) : driver.c ;
 551   </PRE>
 552   Normally, Main uses $(SUFEXE) to determine the suffix on
 553   the filename of the built target. To override it,
 554   you can supply a suffix explicity.
 555   In this case,
 556   $(SUFSHR) is assumed to be the OS-specific shared library
 557   suffix, defined in Jamrules with something
 558   like:
 559   <PRE>
 560     if $(UNIX)      { SUFSHR = .so ; }
 561     else if $(NT)   { SUFSHR = .dll ; }
 562   </PRE>
 563   <P>
 564   Main uses the Objects rule to compile source targets.
 565
 566 <H4>
 567    Library Rule
 568 </H4>
 569        The Library  rule  compiles  source  files,  archives  the
 570        resulting  object  files  into a library, and then deletes
 571        the object files.  For example:
 572 <PRE>
 573               Library libstring : strcmp.c strcpy.c strlen.c ;
 574               Library libtree : treemake.c treetrav.c ;
 575 </PRE>
 576        This compiles five source files,  archives  three  of  the
 577        object  files into libstring and the other two into libtree.
 578        Actual library filenames are formed with the $(SUFLIB) suffix.
 579        Once the objects are safely in the libraries, the
 580        objects are deleted.
 581        <P>
 582        Library uses the Objects rule to compile source files.
 583 <P>
 584 <H4>
 585    LinkLibraries Rule
 586 </H4>
 587        To link executables with built libraries, use
 588        the LinkLibraries rule.  For example:
 589 <PRE>
 590               Main myprog : main.c util.c ;
 591               LinkLibraries myprog : libstring libtree ;
 592 </PRE>
 593        The LinkLibraries rule  does  two  things:  it  makes  the
 594        libraries dependencies of the executable, so that they get
 595        built first; and it makes the libraries  show  up  on  the
 596        command  line  that links the executable.  The ordering of
 597        the lines above is not important, because <b>jam</b> builds  targets
 598        in the order that they are needed.
 599 <P>
 600        You  can  put multiple libraries on a single invocation of
 601        the LinkLibraries rule, or you can provide them in  multiple
 602        invocations.   In both cases, the libraries appear on
 603        the link command line in the  order  in  which  they  were
 604        encountered.  You can also provide multiple executables to
 605        the LinkLibraries rule, if they need the same libraries,
 606        e.g.:
 607        <PRE>
 608     LinkLibraries prog1 prog2 prog3 : libstring libtree ;
 609        </PRE>
 610 <P>
 611 <H4>
 612    Variables Used in Building Executables and Libraries
 613 </H4>
 614 <CENTER>
 615 <TABLE>
 616 <TR><TD>
 617               AR
 618         <TD><TD>Archive command, used for Library targets.
 619 <TR><TD>
 620               SUFEXE
 621         <TD>*<TD>Suffix on filenames of executables referenced
 622     by Main and LinkLibraries.
 623 <TR><TD>
 624               LINK
 625         <TD><TD>Link command, used for Main targets.
 626 <TR><TD>
 627               LINKFLAGS
 628         <TD><TD>Linker flags.
 629 <TR><TD>
 630               LINKLIBS
 631         <TD><TD>Link libraries that aren't dependencies. (See note
 632     below.)
 633 <TR><TD>
 634               EXEMODE
 635         <TD>*<TD>File permissions on Main targets.
 636 <TR><TD>
 637               MODE
 638         <TD><TD>Target-specific file permissions on Main targets
 639     (set from $(EXEMODE))
 640 <TR><TD>
 641               RANLIB
 642         <TD><TD>Name of ranlib program, if any.
 643 </TABLE>
 644 </CENTER>
 645
 646 <P>
 647   Variables above marked with "*" are used by the Main,
 648   Library, and LinkLibraries rules. Their values at the
 649   time the rules are invoked are used to set target-specific
 650   variables.
 651   <P>
 652   All other variables listed above are globally defined,
 653   and are used in actions that update Main and Library
 654   targets. This means that the global values of those
 655   variables are used, uness target-specific values have
 656   been set.
 657   (For instance, a target-specific MODE value is set by
 658   the Main rule.)
 659   The target-specific values always override
 660   global values.
 661 <P>
 662   Note that there are two ways to specify link libraries for
 663   executables:
 664   <UL>
 665   <LI>Use the LinkLibraries rule
 666   to specify built libraries; i.e., libraries
 667   that are built by Library rules. This assures that
 668   these libraries are built first, and that Main targets are
 669   rebuilt when the libraries are updated.
 670   <P>
 671   <LI>Use the LINKLIBS variable to specify external
 672    libraries; e.g., system libraries or third-party libraries.
 673    The LINKLIBS variable must be set to the the actual
 674    link command flag that specifies the libraries.
 675    <P>
 676    </UL>
 677    <P>
 678    For example:
 679 <PRE>
 680   <I>#In Jamrules:</I>
 681               if $(UNIX) { X11LINKLIBS = -lXext -lX11 ; }
 682               if $(NT)   { X11LINKLIBS = libext.lib libX11.lib ; }
 683
 684   <I>#In Jamfile:</I>
 685               Main xprog : xprog.c ;
 686               LINKLIBS on xprog$(SUFEXE) = $(X11LINKLIBS) ;
 687               LinkLibraries xprog : libxutil ;
 688               Library libxutil : xtop.c xbottom.c xutil.c ;
 689 </PRE>
 690        This  example  uses the Jam syntax "variable on target" to
 691        set a target-specific variable.  In this way,  only  xprog
 692        will  be linked with this special $(X11LINKLIBS),
 693        even if other executables were going to  be  built
 694        by  the  same Jamfile. Note that when you set a variable
 695        on a target, you have to specify the target identifer
 696        exactly, which in this case is the suffixed filename of
 697        the executable.
 698        The actual link command line on Unix, for example, would
 699        look something like this:
 700 <PRE>
 701               cc -o xprog xprog.o libxutil.a -lXext -lX11
 702 </PRE>
 703 <H2>
 704 Compiling
 705 </H2>
 706        Compiling of source files occurs normally as  a  byproduct
 707        of  the Main or Library rules, which call the rules
 708        described here. These rules may also be called explicitly
 709        if the Main and Library behavior doesn't satisfy your
 710        requirements.
 711 <P>
 712 <H4>
 713    Objects Rule
 714 </H4>
 715        The Main and Library rules call the Objects rule on source files.
 716        Compiled object files built by
 717        the Objects rule are a dependency of the <I>obj</i>
 718        pseudotarget, so "jam obj" will build object files used in
 719        Main and Library rules.
 720        <P>
 721        Target identifiers created by the Objects rule have grist
 722        set to $(SOURCE_GRIST). So given this Jamfile:
 723        <PRE>
 724     SubDir TOP src lock ;
 725     Main locker : lock.c ;
 726        </PRE>
 727        the object file created is lock.o (or lock.obj) and
 728        its target identifier is &lt;src!lock&gt;lock.o
 729        (or &lt;src!lock&gt;lock.obj).
 730
 731        <P>
 732        You can also call  Objects  directly.  For example:
 733 <PRE>
 734               Objects a.c b.c c.c ;
 735 </PRE>
 736        This compiles a.c into a.o, b.c into b.o, etc. The object
 737        file suffix is supplied by the Objects rule.
 738 <P>
 739 <H4>
 740    Object Rule
 741 </H4>
 742        Objects  gets  its work done by calling the Object rule on
 743        each of the source files.
 744        You could use the Object rule directly.
 745        For example, on Unix, you could use:
 746 <PRE>
 747               Object foo.o : foo.c ;
 748 </PRE>
 749   However, the Object rule does not provide suffixes, and
 750   it does not provide the grist needed to construct target
 751   identifiers if you are using the SubDir* rules.
 752   A portable and robust Jamfile would need to invoke Object thus:
 753   <PRE>
 754         Object &lt;src!util&gt;foo$(SUFOBJ) : &lt;src!util&gt;foo.c ;
 755   </PRE>
 756   which is inelegant and clearly shows why using Objects
 757   is better than using Object.
 758   <P>
 759   If there's any advantage to the Object rule, it's
 760        that it doesn't require that the object name bear
 761        any relationship to the source.  It is  thus  possible  to
 762        compile  the  same file into different objects.  For example:
 763
 764 <PRE>
 765               Object a.o : foo.c ;
 766               Object b.o : foo.c ;
 767               Object c.o : foo.c ;
 768 </PRE>
 769        This compiles foo.c (three times) into a.o, b.o, and  c.o.
 770        Later examples show how this is useful.
 771 <P>
 772        The Object rule looks at the suffix of the source file and
 773        calls the appropriate rules to do  the  actual  preprocessing
 774        (if any) and compiling needed to produce the output object file.
 775        The Object rule is
 776        capable of the generating of an object file from  any
 777        type of source.  For example:
 778 <PRE>
 779               Object grammar$(SUFOBJ) : grammar.y ;
 780               Object scanner$(SUFOBJ) : scanner.l ;
 781               Object fastf$(SUFOBJ) : fastf.f ;
 782               Object util$(SUFOBJ) : util.c ;
 783 </PRE>
 784   An even more elegant way to get the same result is to let the
 785   Objects rule call Object:
 786   <PRE>
 787               Objects grammar.y scanner.l fastf.f util.c ;
 788   </PRE>
 789   <P>
 790        In  addition to calling the compile rules, Object sets up
 791        a bunch of variables specific to  the  source  and  target
 792        files.  (See Variables Used in Compiling, below.)
 793 <P>
 794 <H4>
 795    Cc, C++, Yacc, Lex, Fortran, As, etc. Rules
 796 </H4>
 797 <P>
 798        The Object rule calls compile rules specific to the suffix of
 799        the source file.  (You can see which suffixes are supported
 800        by looking at the Object rule definition in Jambase.)
 801        Because  the  extra  work  done  by  the
 802        Object rule, it is not always useful to call the compile
 803        rules directly.  But the adventurous  user  might  attempt
 804        it.  For example:
 805 <PRE>
 806               Yacc grammar.c : grammar.y ;
 807               Lex scan.c : scan.l ;
 808               Cc prog.o : prog.c ;
 809 </PRE>
 810        These examples individually run yacc(1), lex(1), and the C
 811        compiler on their sources.
 812 <P>
 813 <H4>
 814    UserObject Rule
 815 </H4>
 816        Any files with suffixes not understood by the Object  rule
 817        are passed to the UserObject rule.  The default definition
 818        of UserObject simply emits a warning that  the  suffix  is
 819        not  understood.   This  Jambase rule definition is intended to be
 820        overridden in Jamrules with one that recognizes the project-specific
 821        source file suffixes. For  example:
 822
 823 <PRE>
 824   #In Jamrules:
 825
 826               rule UserObject
 827               {
 828                   switch $(&gt;)
 829                   {
 830                   case *.rc   : ResourceCompiler $(&lt;) : $(&gt;) ;
 831                   case *      : ECHO "unknown suffix on" $(&gt;) ;
 832                   }
 833               }
 834
 835               rule ResourceCompiler
 836               {
 837                   DEPENDS $(&lt;) : $(&gt;) ;
 838       Clean clean : $(<) ;
 839               }
 840
 841               actions ResourceCompiler
 842               {
 843                   rc /fo $(&lt;) $(RCFLAGS) $(&gt;)
 844               }
 845
 846
 847   #In Jamfile:
 848
 849               Library liblock : lockmgr.c ;
 850         if $(NT) { Library liblock : lock.rc ; }
 851 </PRE>
 852 <P>
 853   In this example, the UserObject definition in Jamrules
 854   allows *.rc files to be handle as regular Main and Library
 855   sources. The lock.rc file is compiled into lock.obj
 856   by the "rc" command, and lock.obj is archived into a library
 857   with other compiled objects.
 858 <H4>
 859    LibraryFromObjects Rule
 860 </H4>
 861        Sometimes the Library rule's straightforward compiling  of
 862        source  into  object modules to be archived isn't flexible
 863        enough.  The LibraryFromObjects rule  does  the  archiving
 864        (and  deleting)  job of the Library rule, but not the compiling.
 865        The user can make use of the  Objects  or  Object
 866        rule for that.  For example:
 867 <PRE>
 868               LibraryFromObjects libfoo.a : max.o min.o ;
 869               Object max.o : maxmin.c ;
 870               Object min.o : maxmin.c ;
 871               ObjectCcFlags max.o : -DUSEMAX ;
 872               ObjectCcFlags min.o : -DUSEMIN ;
 873 </PRE>
 874        This  Unix-specific example compiles  the  same  source  file into
 875        two different
 876        objects, with different compile flags, and archives  them.
 877        (The ObjectCcFlags rule is described shortly.)
 878        Unfortunately, the portable and robust implementation of the
 879        above example is not as pleasant to read:
 880        <PRE>
 881         SubDir TOP foo bar ;
 882               LibraryFromObjects libfoo$(SUFLIB) : &lt;foo!bar&gt;max$(SUFOBJ)
 883                                  &lt;foo!bar&gt;min$(SUFOBJ) ;
 884               Object &lt;foo!bar&gt;min$(SUFOBJ) : &lt;foo!bar&gt;maxmin.c ;
 885               Object &lt;foo!bar&gt;max$(SUFOBJ) : &lt;foo!bar&gt;maxmin.c ;
 886         ObjectCcFlags &lt;foo!bar&gt;min$(SUFOBJ) : -DUSEMIN ;
 887         ObjectCcFlags &lt;foo!bar&gt;max$(SUFOBJ) : -DUSEMAX ;
 888        </PRE>
 889        Note that, among other things, you must supply the library
 890        file suffix when using the LibraryFromObjects rule.
 891 <P>
 892 <H4>
 893    MainFromObjects Rule
 894 </H4>
 895        Similar  to  LibraryFromObjects,  MainFromObjects does the
 896        linking part of the Main rule, but not the compiling.
 897        MainFromObjects  can be used when  there  are no
 898        objects at all,  and  everything  is  to  be  loaded  from
 899        libraries.  For example:
 900 <PRE>
 901               MainFromObjects testprog ;
 902               LinkLibraries testprog : libprog ;
 903               Library libprog : main.c util.c ;
 904 </PRE>
 905        On Unix, say, this generates a link command that looks like:
 906 <PRE>
 907               cc -o testprog libprog.a
 908 </PRE>
 909        Linking  purely  from  libraries is something that doesn't
 910        work everywhere: it depends on  the  symbol  "main"  being
 911        undefined when the linker encounters the library that contains
 912        the definition of "main".
 913 <P>
 914 <H4>
 915    Variables Used in Compiling
 916 </H4>
 917        The following variables control the  compiling  of  source
 918        files:
 919 <P>
 920 <CENTER>
 921 <TABLE>
 922 <TR><TD VALIGN=TOP>
 923               C++
 924         <TD><TD>The C++ compiler command
 925 <TR><TD VALIGN=TOP>
 926               CC
 927         <TD><TD>The C compiler command
 928 <TR><TD VALIGN=TOP>
 929               C++FLAGS
 930         <BR>
 931               CCFLAGS
 932         <TD VALIGN=TOP><TD VALIGN=TOP>Compile flags, used to
 933      create or update compiled objects
 934 <TR><TD>
 935               SUBDIRC++FLAGS
 936         <BR>
 937               SUBDIRCCFLAGS
 938         <TD VALIGN=TOP><TD VALIGN=TOP>Additonal compile flags
 939     for source files in this directory.
 940 <TR><TD VALIGN=TOP>
 941               OPTIM
 942         <TD><TD>Compiler optimization flag. The Cc and C++
 943     actions use this as well as C++FLAGS or CCFLAGS.
 944 <TR><TD VALIGN=TOP>
 945               HDRS
 946         <TD VALIGN=TOP><TD>Non-standard header directories; i.e.,
 947     the directories the compiler will not look in
 948     by default and which therefore must be supplied
 949     to the compile command. These directories are
 950     also used by <b>jam</b> to scan for include files.
 951 <TR><TD VALIGN=TOP>
 952               STDHDRS
 953         <TD VALIGN=TOP><TD>Standard header directories, i.e., the
 954     directories the compiler searches automatically.
 955     These are not passed to the compiler, but they
 956     are used by <b>jam</b> to scan for include files.
 957 <TR><TD>
 958               SUBDIRHDRS
 959         <TD><TD>Additional paths to add to HDRS for source files
 960     in this directory.
 961 <TR><TD>
 962               LEX
 963         <TD><TD>The lex(1) command
 964 <TR><TD>
 965               YACC
 966         <TD><TD>The yacc(1) command
 967 </TABLE>
 968 </CENTER>
 969 <P>
 970        The  Cc rule sets a target-specific $(CCFLAGS) to the current
 971        value of $(CCFLAGS) and $(SUBDIRCCFLAGS).   Similarly
 972        for  the C++ rule.  The Object rule sets a target-specific
 973        $(HDRS) to  the  current  value  of  $(HDRS)  and  $(SUBDDIRHDRS).
 974
 975 <P>
 976        $(CC),  $(C++),  $(CCFLAGS),  $(C++FLAGS),  $(OPTIM),  and
 977        $(HDRS) all affect the  compiling  of  C  and  C++  files.
 978        $(OPTIM)  is  separate  from $(CCFLAGS) and $(C++FLAGS) so
 979        they can be set independently.
 980 <P>
 981        $(HDRS) lists the directories to search for header  files,
 982        and  it  is used in two ways: first, it is passed to the C
 983        compiler (with the flag -I prepended); second, it is  used
 984        by  HdrRule  to  locate  the header files whose names were
 985        found when scanning source files.   $(STDHDRS)  lists  the
 986        header  directories  that  the  C  compiler  already knows
 987        about.  It does not need passing to the C compiler, but is
 988        used by HdrRule.
 989 <P>
 990        Note that these variables, if set as target-specific variables,
 991        must be set on the target,  not  the  source  file.
 992        The target file in this case is the object file to be generated.
 993        For example:
 994 <PRE>
 995               Library libximage : xtiff.c xjpeg.c xgif.c ;
 996
 997               HDRS on xjpeg$(SUFOBJ) = /usr/local/src/jpeg ;
 998               CCFLAGS on xtiff$(SUFOBJ) = -DHAVE_TIFF ;
 999 </PRE>
1000        This can be done more easily with the rules that follow.
1001 <P>
1002 <H4>
1003    ObjectCcFlags, ObjectC++Flags, ObjectHdrs Rules
1004 </H4>
1005        $(CCFLAGS), $(C++FLAGS) and  $(HDRS)  can  be  set on object file
1006        targets
1007        directly, but  there are rules that allow these variables
1008        to be set by referring to the original source  file  name,
1009        rather  than  to  the  derived object file name.  ObjectCcFlags
1010        adds object-specific flags to the $(CCFLAGS)  variable,
1011        ObjectC++Flags  adds  object-specific  flags to the
1012        $(C++FLAGS) variable, and ObjectHdrs  add  object-specific
1013        directories to the $(HDRS) variable.  For example:
1014 <PRE>
1015   #In Jamrules:
1016     if $(NT) { CCFLAGS_X = /DXVERSION ;
1017          HDRS_X = \\\\SPARKY\\X11\\INCLUDE\\X11 ;
1018              }
1019
1020   #In Jamfile:
1021               Main xviewer : viewer.c ;
1022               ObjectCcFlags viewer.c : $(CCFLAGS_X) ;
1023               ObjectHdrs viewer.c : $(HDRS_X) ;
1024 </PRE>
1025   The ObjectCcFlags and ObjectHdrs rules take .c files
1026   as targets, but actually set $(CCFLAGS) and $(HDRS) values
1027   on the .obj (or .o) files. As a result, the action
1028   that updates the target .obj file uses the target-specific
1029   values of $(CCFLAGS) and $(HDRS).
1030 <P>
1031 <H4>
1032    SubDirCcFlags, SubDirC++Flags, SubDirHdrs Rules
1033 </H4>
1034        These rules set the  values  of  $(SUBDIRCCFLAGS),  $(SUBDIRC++FLAGS)
1035        and $(SUBDIRHDRS), which are used by the Cc,
1036        C++, and Object rules  when  setting  the  target-specific
1037        values  for $(CCFLAGS), $(C++FLAGS) and $(HDRS).  The SubDir
1038        rule clears these variables out, and thus they provide
1039        directory-specific  values of $(CCFLAGS), $(C++FLAGS)  and
1040        $(HDRS).  For example:
1041 <PRE>
1042   #In Jamrules:
1043               GZHDRS = $(TOP)/src/gz/include ;
1044         GZFLAG = -DGZ ;
1045
1046   #In Jamfile:
1047               SubDir TOP src gz utils ;
1048
1049               SubDirHdrs $(GZHDRS) ;
1050               SubDirCcFlags $(GZFLAG) ;
1051
1052         Library libgz : gizmo.c ;
1053         Main gizmo : main.c ;
1054         LinkLibraries gizmo : libgz ;
1055 </PRE>
1056   All .c files in this directory files will be compiled with
1057   $(GZFLAG) as well as the default $(CCFLAG), and the include
1058   paths used on the compile command will be $(GZHDRS) as well
1059   as the default $(HDRS).
1060 <H2>
1061 Header File Processing
1062 </H2>
1063        One of the functions of the Object rule is set up
1064        scanning of source
1065        files  for (C style) header file inclusions.  To do so, it
1066        sets the special variables $(HDRSCAN)  and  $(HDRRULE)
1067        as  target-specific  variables  on  the source file.  The
1068        presence of these variables triggers a  special  mechanism
1069        in  <B>jam</B> for scanning a file for header file inclusions and
1070        invoking a  rule  with  the  results  of  the  scan.   The
1071        $(HDRSCAN)  variable  is  set  to an egrep(1) pattern that
1072        matches "#include" statements in C source files,  and  the
1073        $(HDRRULE)  variable  is  set to the name of the rule that
1074        gets invoked as such:
1075 <PRE>
1076               $(HDRRULE) source-file : included-files ;
1077 </PRE>
1078        This rule is supposed to set up the  dependencies  between
1079        the  source  file and the included files.  The Object rule
1080        uses HdrRule  to  do  the  job.   HdrRule  itself  expects
1081        another  variable,  $(HDRSEARCH), to be set to the list of
1082        directories where the included files can be found.  Object
1083        does  this  as  well,  setting $(HDRSEARCH) to $(HDRS) and
1084        $(STDHDRS).
1085 <P>
1086        The header file scanning occurs during the "file  binding"
1087        phase   of  <b>jam</b>,  which  means  that  the  target-specific
1088        variables (for the source file) are in effect.  To accomodate
1089        nested includes, one of the HdrRule's jobs is to pass
1090        the target-specific values of $(HDRRULE), $(HDRSCAN),  and
1091        $(HDRSEARCH) onto the included files, so that they will be
1092        scanned as well.
1093 <P>
1094 <H4>
1095    HdrRule Rule
1096 </H4>
1097   Normally, HdrRule is not invoked directly; the Object rule
1098   (called by Main and Library) invokes it.
1099   <P>
1100   If there are special dependencies that need to be set,
1101   and which are not set by HdrRule itself, you can define
1102   another rule and let it invoke HdrRule.  For example:
1103
1104 <PRE>
1105   #In Jamrules:
1106               rule BuiltHeaders
1107               {
1108                       DEPENDS $(&gt;) : mkhdr$(SUFEXE) ;
1109                       HdrRule $(&lt;) : $(&gt;) ;
1110               }
1111
1112   #In Jamfile:
1113               Main mkhdr : mkhdr.c ;
1114               Main ugly : ugly.c ;
1115
1116               HDRRULE on ugly.c = BuiltHeaders ;
1117
1118 </PRE>
1119        This example just says that the files included by "ugly.c"
1120        are  generated  by the program "mkhdr", which can be built
1121        from "mkhdr.c".  During the binding phase, <b>jam</b> will
1122        scan ugly.c, and if it finds an include file, ughdr.h,
1123        for example, it will automatically invoke the rule:
1124        <PRE>
1125               BuiltHeaders ugly.c : ughdr.h ;
1126        </PRE>
1127        By calling HdrRule at the end  of  BuiltHeaders,
1128        all  the gadgetry of HdrRule takes effect and it
1129        doesn't need to be duplicated.
1130 <P>
1131 <H4>
1132    Variables Used for Header Scanning
1133 </H4>
1134 <CENTER>
1135 <TABLE>
1136 <TR><TD VALIGN=TOP>
1137               HDRPATTERN
1138         <TD><TD>Default scan pattern for "include" lines.
1139 <TR><TD VALIGN=TOP>
1140               HDRSCAN
1141         <TD><TD>Scan pattern to use.
1142     This is a special variable: during binding, if
1143     both HDRSCAN and HDRRULE are set, scanning is activated
1144     on the target being bound.
1145     The HdrRule and Object rules sets this
1146     to $(HDRPATTERN) on their source targets.
1147 <TR><TD VALIGN=TOP>
1148               HDRRULE
1149         <TD><TD>Name of rule to invoked on files found in header
1150     scan. The HdrRule and Object rules set this to "HdrRule"
1151     on their source targets. This is also a special variable;
1152     it's the only <b>jam</b> variable that can hold the
1153     name of a rule to be invoked.
1154 <TR><TD VALIGN=TOP>
1155               HDRSEARCH
1156         <TD><TD>Search paths for files found during header scanning.
1157     This is set from $(HDRS) and $(STDHDRS), which are
1158     described in the Compiling section.
1159     <b>jam</b> will search $(HDRSEARCH) directories for
1160     the files found by header scans.
1161 </TABLE>
1162 </CENTER>
1163 <P>
1164        The  Object rule sets HDRRULE and HDRSCAN specifically for
1165        the source files to be scanned, rather than globally.   If
1166        they  were  set  globally,  jam  would attempt to scan all
1167        files, even library archives and executables,  for  header
1168        file  inclusions.   That  would  be  slow and probably not
1169        yield desirable results.
1170 <P>
1171 <H2>
1172 Copying Files
1173 </H2>
1174 <H4>
1175    File Rule
1176 </H4>
1177        The File rule copies one file to another.  The target name
1178        needn't  be the same as the source name.  For
1179        example:
1180 <PRE>
1181   switch $(OS)
1182   {
1183            case NT*  : File config.h : confignt.h ;
1184      case *    : File config.h : configunix.h ;
1185   }
1186   LOCATE on config.h = $(LOCATE_SOURCE) ;
1187 </PRE>
1188   This creates a config.h file from either confignt.h or
1189   configunix.h, depending on the current build platform.
1190 <P>
1191   The File rule does not
1192   use the LOCATE_SOURCE variable set by the
1193   SubDir rule (although it does use SEARCH_SOURCE), which
1194   means you have to set the copied file's output directory
1195   yourself. That's done by setting the special
1196   LOCATE variable on the target, as shown above,
1197   or with the MakeLocate rule described below.
1198 <H4>
1199    Bulk Rule
1200 </H4>
1201        The Bulk rule is a shorthand for many invocations  of  the
1202        File  rule when all files are going to the same directory.
1203        For example:
1204 <PRE>
1205   #In Jamrules:
1206               DISTRIB_GROB = d:\\distrib\\grob ;
1207
1208   #In Jamfile:
1209               Bulk $(DISTRIB_GROB) : grobvals.txt grobvars.txt ;
1210 </PRE>
1211   This causes gobvals.txt and grobvars.txt to be copied
1212   into the $(DISTRIB_GROB) directory.
1213 <H4>
1214    HardLink Rule
1215 </H4>
1216        The Unix-only HardLink rule makes a hard link (using ln(1)) from the
1217        source  to  the  target,  if there isn't one already.  For
1218        example:
1219 <PRE>
1220               HardLink config.h : configunix.h ;
1221 </PRE>
1222 <H4>
1223    Shell Rule
1224 </H4>
1225        The Shell rule is like the File rule, except that on Unix it makes
1226        sure  the first line of the target is "#!/bin/sh" and sets
1227        the permission to make the file executable.  For example:
1228 <PRE>
1229               Shell /usr/local/bin/add : add.sh ;
1230 </PRE>
1231 <P>
1232   You can also use $(SHELLHEADER) to dictate
1233   what the first line of the copied file will be.
1234        For
1235        example:
1236 <PRE>
1237               Shell /usr/local/bin/add : add.awk ;
1238               SHELLHEADER on /usr/local/bin/add = "#!/bin/awk -f" ;
1239 </PRE>
1240        This installs an awk(1) script.
1241 <P>
1242 <H4>
1243    Variables Used When Copying Files
1244 </H4>
1245 <CENTER>
1246 <TABLE>
1247 <TR><TD VALIGN=TOP>
1248               FILEMODE
1249         <TD><TD>Default file permissions for copied files
1250 <TR><TD VALIGN=TOP>
1251               SHELLMODE
1252         <TD><TD>Default file permissions for Shell rule targets
1253 <TR><TD VALIGN=TOP>
1254               MODE
1255         <TD><TD>File permissions set on files copied by
1256     File, Bulk, and Shell rules.
1257           File and Shell sets a target-specific MODE to the  current
1258           value  of  $(FILEMODE) or $(SHELLMODE), respectively.
1259 <TR><TD VALIGN=TOP>
1260               SHELLHEADER
1261         <TD><TD>String to write in first line of Shell targets
1262         (default is #!/bin/sh).
1263
1264 </TABLE>
1265 </CENTER>
1266 <P>
1267
1268 <H2>
1269 Installing Files
1270 </H2>
1271 Jambase provides a set of Install* rules to copy files
1272 into an destination directory and set permissions on them.
1273 On Unix, the install(1) program is used.
1274 If the destination directory does not exist, <b>jam</b>
1275 creates it first.
1276 <P>
1277 All files copied with the Install* rules are dependencies
1278 of the <i>install</i> pseudotarget, which means that the
1279 command "jam install" will cause the installed copies to
1280 be updated. Also, "jam uninstall" will cause the installed
1281 copies to be removed.
1282 <P>
1283 The Install* rules are:
1284 <CENTER>
1285 <TABLE>
1286 <TR><TD VALIGN=TOP><B>InstallBin</B>
1287     <TD VALIGN=TOP>Copies file and sets its permission to $(EXEMODE).
1288        You must specify the suffixed executable name. E.g.:
1289     <PRE>InstallBin $(BINDIR) : thing$(SUFEXE) ;
1290        </PRE>
1291
1292 <TR><TD VALIGN=TOP><B>InstallFile</B>
1293     <TD VALIGN=TOP>Copies file and sets its permission to $(FILEMODE). E.g.:
1294     <PRE>InstallFile $(DESTDIR) : readme.txt ;
1295        </PRE>
1296
1297 <TR><TD VALIGN=TOP><B>InstallLib</B>
1298     <TD VALIGN=TOP>Copies file and sets its permission to $(FILEMODE).
1299        You must specify the suffixed library name. E.g.:
1300     <PRE>InstallLib $(LIBDIR) : libzoo$(SUFLIB) ;
1301        </PRE>
1302
1303 <TR><TD VALIGN=TOP><B>InstallMan</B>
1304     <TD VALIGN=TOP>Copies file into the man<i>n</i>
1305        subdirectory of the target directory
1306        and sets its permission to $(FILEMODE). E.g.,
1307        this copies foo.5 into the $(DESTDIR)/man5 directory:
1308     <PRE>InstallMan $(DESTDIR) : foo.5 ;
1309        </PRE>
1310
1311 <TR><TD VALIGN=TOP><B>InstallShell</B>
1312     <TD VALIGN=TOP>Copies file and sets its permission to $(SHELLMODE). E.g.:
1313     <PRE>InstallShell $(DESTDIR) : startup ;
1314        </PRE>
1315
1316 </TABLE>
1317 </CENTER>
1318 <P>
1319 <P>
1320 <H4>
1321    Variables
1322 </H4>
1323        The following variables control the installation rules:
1324 <P>
1325 <CENTER>
1326 <TABLE>
1327 <TR><TD>
1328               INSTALL
1329         <TD><TD>The install program (Unix only)
1330 <TR><TD>
1331               FILEMODE
1332         <TD><TD>Default file permissions on readable files.
1333 <TR><TD>
1334               EXEMODE
1335         <TD><TD>Default file permission executable files.
1336 <TR><TD>
1337               SHELLMODE
1338         <TD><TD>Default file permission on shell script files.
1339 <TR><TD>
1340               MODE
1341         <TD><TD>Target-specific file permissions
1342 </TABLE>
1343 </CENTER>
1344 <P>
1345 <P>
1346        The  Install  rules set a target-specific MODE to the current
1347        value of $(FILEMODE),  $(EXEMODE),  or  $(SHELLMODE),
1348        depending on which Install rule was invoked.
1349 <P>
1350        The  directory variables are just defined for convenience:
1351        they must be passed  as  the  target  to  the  appropriate
1352        Install  rule.   The $(INSTALL) and mode variables must be
1353        set (globally) before calling the Install rules  in  order
1354        to take effect.
1355 <P>
1356 <H2>
1357 Miscellaneous Rules
1358 </H2>
1359 <H4>
1360 Clean Rule
1361 </H4>
1362 <P>
1363 The Clean rule defines files to be removed when you run "jam clean".
1364 Any site-specific build rules defined in your Jamrules should invoke
1365 Clean so that outputs can be removed. E.g.,
1366 <PRE>
1367   rule ResourceCompiler
1368   {
1369      DEPENDS $(<) : $(>) ;
1370      Clean clean : $(<) ;
1371   }
1372 </PRE>
1373 <P>
1374 <P>
1375 Most Jambase rules invoke the Clean rule on their built targets,
1376 so "jam clean" will remove all compiled objects, libraries,
1377 executables, etc.
1378 <P>
1379 <H4>
1380 MakeLocate Rule
1381 </H4>
1382       MakeLocate is a single convenient rule that creates a directory,
1383       sets LOCATE on a target to that directory, and makes the directory
1384       a dependency of the target. It is used by many Jambase rules,
1385       and can be invoked directly, e.g.:
1386       <PRE>
1387     GenFile data.tbl : hxtract data.h ;
1388     MakeLocate data.tbl : $(TABLEDIR) ;
1389       </PRE>
1390       In this example, the File rule creates data.tbl from data.h.
1391       The MakeLocate causes data.tbl to be written into the $(TABLEDIR)
1392       directory; and if the directory doesn't exist, it is created first.
1393       <P>
1394       The MakeLocate rule invokes another Jambase rule, MkDir,
1395       to (recursively) create
1396       directories. MkDir uses the $(MKDIR) variable to determine the
1397       platform-specific command that creates directories.
1398 <P>
1399 <H4>
1400 RmTemps Rule
1401 </H4>
1402   Some intermediate files are meant to be temporary.
1403   The RmTemps rule can be used to cause
1404   <b>jam</b> to delete them after they are used.
1405   <P>
1406   RmTemps must be:
1407   <UL>
1408   <LI>
1409   the last rule
1410   invoked on the permanent file that uses
1411   the temporary file(s)
1412   <LI>
1413   invoked with the permanent file as the output
1414   target and the temporary file(s) as the input target
1415   <LI>
1416   invoked with the exact target identifiers of
1417   the permanent file and the temporary file(s)
1418   </UL>
1419   For
1420   example:
1421   <PRE>
1422     SubDir TOP src big ;
1423     GenFile big.y : joinfiles part1.y part2.y part3.y ;
1424     Main bigworld : main.c big.y ;
1425     RmTemps bigworld$(SUFEXE) : &lt;src!big&gt;big.y ;
1426   </PRE>
1427   This causes big.y to be deleted after it has been used to create
1428   the bigworld executable.
1429   The exact target identifier of big.y is  &lt;src!big&gt;big.y
1430   (the GenFile and Main rules tack on the grist automatically);
1431   the exact target identifier of the bigworld executable
1432   is bigworld$(SUFEXE).
1433 <P>
1434 <HR>
1435 <A HREF="#TOP">Back to top.</A>
1436 <P>
1437  Copyright 1997, 2000 Perforce Software, Inc.
1438  <BR>
1439  Changes and additions by Ketmar // Invisible Vector
1440 </BODY>
1441 </HTML>