README.html #1 

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Final//EN">
<HTML>
 <HEAD>
  <TITLE>Abstract multi-directory Jam example</TITLE>
 </HEAD>

 <BODY>

 <p>This is a somewhat abstract example of one way in which you can use
    Jam to build a project whose sources are spread over several
    subdirectories.

 <p>In this example, we introduce the "Jamrules" file, which generally contains
    site or project specific configuration, rules, and actions.  In this
    case, the Jamrules only sets the ALL_LOCATE_TARGET variable, which
    specifies where to put generated files.

 <p>We also demonstrate the use of the SubDir and SubInclude rules to 
    compile the contents of sub directories.

 <p>Note that there's a Jamfile for each directory in which sources reside.
    Each contains only a call to the Library rule specifying that a library
    should be made from the source files in that directory.  The Jamfiles 
    in the sub directories could of course be arbitrarily complex, but it
    is usually best to keep them as simple as possible.

 <p>Things to try:
   <ul>
     <li>Run jam, then touch or edit one of the header files - for example,
         "b.h" in the "b" directory.  Notice that jam knew which source files
         #included "b.h" (see the section called "Header File Processing" in the
         <a href="http://public.perforce.com/public/jam/src/Jamfile.html">
          Jamfiles and Jambase</a> document for information on how this works).
         Then try making one header file #include another, and touch the
         #included file.  Jam understands the new relationship, without
         the need for a "make depends", and it does it fast.
     <li>Do a "jam clean" from the top directory, and then try running jam
         from within one of the source sub directories.  Note that (with this
         particular setup) Jam will only compile the library corresponding
         to that particular sub directory.  This sort of arrangement can be
         helpful in modularizing large and/or multi-platform projects.
     <li>Try adding your own call to "InstallBin" in the top level Jamfile
         (see the <a href="../simple">simple</a> example for an example
         of using InstallBin).  Then, hypothesize that for this project
         you actually want to install one or more of the libraries, and 
         add a call to "InstallLib" to tell jam which libraries to install
         and where.  (Hint:  on a "real" project, the directory into which
         things are installed would probably be specified one way or another
         in the Jamrules.  Try setting a variable containing your install
         path in the Jamrules and then pass that variable to the appropriate
         install rule.)
         See the 
         <a href="http://public.perforce.com/public/jam/src/Jamfile.html">
         Jamfiles and Jambase</a> file for more information on InstallLib and
         other rules.
   </ul>

 </BODY>
</HTML>
# Change User Description Committed
#1 4438 Chris Comparini Sample jam projects.
 "rootless" documentation still needs work.