Helix SwarmHelix Swarm
Loading...

README.header_scan_cache

  • //
  • guest/
  • craig_mcpheeters/
  • jam/
  • src/
  • README.header_scan_cache #1
  • View
  • Commits
  • Open Download .zip Download (5 KB)
  1. The header scan was originally implemented by Craig McPheeters. Extensions
  2. to the initial implementation were done by Matt Armstrong. One of the
  3. extensions is the documentation in this file, which other than this
  4. comment, is left un-altered from Matt's version.
  5.  
  6. The comment about changes in the Jambase are not true in this branch. See
  7. //guest/matt_armstrong/jam/hdrscan_cache/...
  8. for details.
  9.  
  10. Craig McPheeters, Jan, 2002.
  11.  
  12. ---
  13.  
  14. This code is taken from //guest/craig_mcpheeters/jam/src/ on the
  15. Perforce public depot. Many thanks to Craig McPheeters for making his
  16. code available. It is delimited by the OPT_HEADER_CACHE_EXT #define
  17. within the code.
  18.  
  19. Jam has a facility to scan source files for other files they might
  20. include. This code implements a cache of these scans, so the entire
  21. source tree need not be scanned each time jam is run. This brings the
  22. following benefits:
  23.  
  24. - If a file would otherwise be scanned multiple times in a
  25. single jam run (because the same file is represented by
  26. multiple targets, perhaps each with a different grist), it
  27. will now be scanned only once. In this way, things are
  28. faster even if the cache file is not present when Jam is
  29. run.
  30.  
  31. - If a cache entry is present in the cache file when Jam
  32. starts, and the file has not changed since the last time it
  33. was scanned, Jam will not bother to re-scan it. This
  34. markedly increaces Jam startup times for large projects.
  35.  
  36. This code has improvements over Craig McPheeters' original
  37. version. I've described all of these changes to Craig and he
  38. intends to incorporate them back into his version. The changes
  39. are:
  40.  
  41. - The actual name of the cache file is controlled by the
  42. HCACHEFILE Jam variable. If HCACHEFILE is left unset (the
  43. default), reading and writing of a cache file is not
  44. performed. The cache is always used internally regardless
  45. of HCACHEFILE, which helps when HDRGRIST causes the same
  46. file to be scanned multiple times.
  47.  
  48. Setting LOCATE and SEARCH on the the HCACHEFILE works as
  49. well, so you can place anywhere on disk you like or even
  50. search for it in several directories. You may also set it
  51. in your environment to share it amongst all your projects.
  52.  
  53. - The .jamdeps file is in a new format that allows binary data
  54. to be in any of the fields, in particular the file names.
  55. The original code would break if a file name contained the
  56. '@' or '\n' characters. The format is also versioned,
  57. allowing upgrades to automatically ignore old .jamdeps
  58. files. The format remains human readable. In addition,
  59. care has been taken to not add the entry into the header
  60. cache until the entire record has been successfully read from
  61. the file.
  62.  
  63. - The cache stores the value of HDRPATTERN with each cache
  64. entry, and it is compared along with the file's date to
  65. determine if there is a cache hit. If the HDRPATTERN does
  66. not match, it is treated as a cache miss. This allows
  67. HDRPATTERN to change without worrying about stale cache
  68. entries. It also allows the same file to be scanned
  69. multiple times with different HDRPATTERN values.
  70.  
  71. - Each cache entry is given an "age" which is the maximum
  72. number of times a given header cache entry can go unused
  73. before it is purged from the cache. This helps clean up old
  74. entries in the .jamdeps file when files move around or are
  75. removed from your project.
  76.  
  77. You control the maximum age with the HCACHEMAXAGE variable.
  78. If set to 0, no cache aging is performed. Otherwise it is
  79. the number of times a jam must be run before an unused cache
  80. entry is purged. The default for HCACHEMAXAGE if left unset
  81. is 100.
  82.  
  83. - Jambase itself is changed.
  84.  
  85. SubDir now always sets HDRGRIST to $(SOURCE_GRIST) so header
  86. scanning can deal with multiple header files of the same
  87. name in different directories. With the header cache, this
  88. does no longer incurs a performance penalty -- a given file
  89. will still only be scanned once.
  90.  
  91. The FGristSourceFiles rule is now just an alias for
  92. FGristFiles. Header files do not necessarily have global
  93. visibility, and the header cache eliminates any performance
  94. penalty this might otherwise incur.
  95.  
  96. Because of all these improvements, the following claims can be
  97. made about this header cache implementation that can not be made
  98. about Craig McPheeters' original version.
  99.  
  100. - The semantics of a Jam run will never be different because of
  101. the header cache (the HDRPATTERN check ensures this).
  102.  
  103. - It will never be necessary to delete .jamdeps to fix obscure
  104. jam problems or purge old entries.
# Change User Description Committed
#1 1251 Craig Mcpheeters This return integrates a modified version of Matt Armstrong's
  extension to my head...er cache code.  Matt documented his extensions
  in the file README.header_scan_cache, read that file for details.
  The modifications to his extensions are recorded in the integration
  history of this return.  My modifications retain all of the new
  properties Matt added in his extension, but it is implemented in
  a slightly different way.  He has reviewed my changes to his changes
  and approves of them
«
24 years ago
//guest/craig_mcpheeters/mattsChanges/src/README.header_scan_cache
#1 1227 Craig Mcpheeters These are the enhancements that Matt Armstrong made to the header
   cache code....  See their original copies in:
     //guest/matt_armstrong/jam/hdrscan_cache
The file headers.c has been modified to incorporate the other extensions
  from my branch, the other three files are unaltered in this return.
«
24 years ago