From 4ed788defaa2fa80c3d17f1e9d582bf2557d9712 Mon Sep 17 00:00:00 2001 From: Ingo Weinhold Date: Sat, 16 Nov 2002 18:48:41 +0000 Subject: [PATCH] Changes to the original Jam version. git-svn-id: file:///srv/svn/repos/haiku/trunk/current@1961 a95241bf-73f2-0310-859d-f6bbb57e9c96 --- src/tools/jam/README.CHANGES | 126 +++++++++++++++++++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 src/tools/jam/README.CHANGES diff --git a/src/tools/jam/README.CHANGES b/src/tools/jam/README.CHANGES new file mode 100644 index 0000000000..790390e437 --- /dev/null +++ b/src/tools/jam/README.CHANGES @@ -0,0 +1,126 @@ +Contents: Changes to Jam 2.4. +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.4. + +* BeOS specifics + + Changes to the system specific variable settings in the BeOS specific + section in Jambase. Several variables were wrong or had weird values. + PPC support was broken (very small fix in jam.h, too). + + These changes will be included in the next version published by Perforce. + + +* 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. + + + 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. + +