Read Me

Contents: Changes to Jam 2.5rc3.
Author:   Ingo Weinhold (bonefish@users.sf.net)

This version of Jam is NOT the original one distributed by Perforce
(www.perforce.com). This file lists its differences to the original version
2.5rc3. The patches have originally been applied to version 2.4 and had to be
adjusted more or less to work with 2.5rc3.

* Jamfile tree processing

  Changes to Jambase, compile.{c,h}, scan.c, jamgram.yy. Jam does now always
  read the whole project Jamfile tree, not only the subtree starting in the
  subdirectory it has been invoked from. If not supplied with a target on the
  command line, however, only the targets in that subtree are built and those
  the former ones depend on.


* Header Caching

  Taken from `//guest/matt_armstrong/jam/patched_version/...' from the
  public Perforce depot (`public.perforce.com:1666'). Originally implemented
  by Craig McPheeters, and improved by Matt Armstrong. The following text
  stems from the file LOCAL_DIFFERENCES.txt in Matt's version.

  <quote>
    This code is taken from //guest/craig_mcpheeters/jam/src/ on the
    Perforce public depot.  Many thanks to Craig McPheeters for making his
    code available.  It is delimited by the OPT_HEADER_CACHE_EXT #define
    within the code.

    Jam has a facility to scan source files for other files they might
    include.  This code implements a cache of these scans, so the entire
    source tree need not be scanned each time jam is run.  This brings the
    following benefits:

	- If a file would otherwise be scanned multiple times in a
	  single jam run (because the same file is represented by
	  multiple targets, perhaps each with a different grist), it
	  will now be scanned only once.  In this way, things are
	  faster even if the cache file is not present when Jam is
	  run.

	- If a cache entry is present in the cache file when Jam
	  starts, and the file has not changed since the last time it
	  was scanned, Jam will not bother to re-scan it.  This
	  markedly increaces Jam startup times for large projects.

    This code has improvements over Craig McPheeters' original
    version.  I've described all of these changes to Craig and he
    intends to incorporate them back into his version.  The changes
    are:

	- The actual name of the cache file is controlled by the
	  HCACHEFILE Jam variable.  If HCACHEFILE is left unset (the
	  default), reading and writing of a cache file is not
	  performed.  The cache is always used internally regardless
	  of HCACHEFILE, which helps when HDRGRIST causes the same
	  file to be scanned multiple times.

	  Setting LOCATE and SEARCH on the the HCACHEFILE works as
	  well, so you can place anywhere on disk you like or even
	  search for it in several directories.  You may also set it
	  in your environment to share it amongst all your projects.

	- The .jamdeps file is in a new format that allows binary data
	  to be in any of the fields, in particular the file names.
	  The original code would break if a file name contained the
	  '@' or '\n' characters.  The format is also versioned,
	  allowing upgrades to automatically ignore old .jamdeps
	  files.  The format remains human readable.  In addition,
	  care has been taken to not add the entry into the header
	  cache until the entire record has been successfully read from
	  the file.

	- The cache stores the value of HDRPATTERN with each cache
	  entry, and it is compared along with the file's date to
	  determine if there is a cache hit.  If the HDRPATTERN does
	  not match, it is treated as a cache miss.  This allows
	  HDRPATTERN to change without worrying about stale cache
	  entries.  It also allows the same file to be scanned
	  multiple times with different HDRPATTERN values.

	- Each cache entry is given an "age" which is the maximum
	  number of times a given header cache entry can go unused
	  before it is purged from the cache.  This helps clean up old
	  entries in the .jamdeps file when files move around or are
	  removed from your project.

	  You control the maximum age with the HCACHEMAXAGE variable.
	  If set to 0, no cache aging is performed.  Otherwise it is
	  the number of times a jam must be run before an unused cache
	  entry is purged.  The default for HCACHEMAXAGE if left unset
	  is 100.

	- Jambase itself is changed.

	  SubDir now always sets HDRGRIST to $(SOURCE_GRIST) so header
	  scanning can deal with multiple header files of the same
	  name in different directories.  With the header cache, this
	  does no longer incurs a performance penalty -- a given file
	  will still only be scanned once.

	  The FGristSourceFiles rule is now just an alias for
	  FGristFiles.  Header files do not necessarily have global
	  visibility, and the header cache eliminates any performance
	  penalty this might otherwise incur.

    Because of all these improvements, the following claims can be
    made about this header cache implementation that can not be made
    about Craig McPheeters' original version.

	- The semantics of a Jam run will never be different because of
	  the header cache (the HDRPATTERN check ensures this).

	- It will never be necessary to delete .jamdeps to fix obscure
	  jam problems or purge old entries.
  </quote>


* Jamfile Caching

  As large build systems may consist of a huge number of Jamfiles, the
  mere reading of these files may take considerable time. This version
  implements a cache for them. Since the time stamps of the files still
  need to retrieved to check whether the cached entries are still up to
  date, the benefits to be expected are not that big though.

  The name of the cache file is controlled by the JCACHEFILE Jam variable.
  If JCACHEFILE is left unset (the default), reading and writing of a cache
  file is not performed. Setting the SEARCH and LOCATE variables does work
  as expected.


* Stat Data and Directory Caching Server (BeOS only)

  Also an optimization for large build systems. Since the BeOS FS cache
  is terrible, stat()ing targets to get their timestamp or see if they exist
  at all, and reading directories usually happens on disk, since the data
  from the previous run are already out of the cache, if the build system
  is large enough.

  This change externalizes all stat()ing and directory reading into a
  dedicated server process which caches the data, so that they can be
  served from memory the next time they are requested. The server uses
  the BeOS node monitoring to keep the data up to date.

  The feature particularly leverages the header and jamfile caching, since
  after the first run the timestamps of the jamfiles and headers are
  cached too, so that reading the jamfiles and performing the header
  scanning doesn't require any disk accesses at all (besides reading the
  cache files, of course).

  Drawbacks are that the first run of jam will be slower, mainly due to
  the communication overhead with the server, and that the server consumes
  memory to store the cached data. The server's memory footprint is quite
  reasonable, though.