From 306b34fa44d175730f9fbc191c9a63aed313aeec Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Fri, 11 Feb 2022 12:34:23 -0700 Subject: Updates to User Guide: 22/Caching [skip appveyor] Use entities. Adopt the "derived-file cache" terminology used elsewhere instead of the former wording "shared cache". Also added entity references for content/build sigs to manpage, as well as some other entity fiddling. CacheDir entry now mentions SCons doesn't do cache maintenance. Signed-off-by: Mats Wichmann --- SCons/Environment.xml | 20 ++++--- doc/man/scons.xml | 60 +++++++++---------- doc/user/caching.xml | 155 +++++++++++++++++++++++++++++--------------------- 3 files changed, 133 insertions(+), 102 deletions(-) diff --git a/SCons/Environment.xml b/SCons/Environment.xml index f471866..d314711 100644 --- a/SCons/Environment.xml +++ b/SCons/Environment.xml @@ -107,8 +107,7 @@ to the commands executed to build target files, you must do so explicitly. A common example is -the system -PATH +the system &PATH; environment variable, so that &scons; @@ -547,7 +546,7 @@ and/or suffix, so the contents are treated as a list of strings, that is, adding a string will result in a separate string entry, not a combined string. For &cv-CPPDEFINES; as well as -for &cv-link-LIBS;, and the various *PATH +for &cv-link-LIBS;, and the various *PATH; variables, &SCons; will supply the compiler-specific syntax (e.g. adding a -D or /D prefix for &cv-CPPDEFINES;), so this syntax should be omitted when @@ -625,7 +624,7 @@ do not make sense and a &Python; exception will be raised. When using &f-env-Append; to modify &consvars; which are path specifications (conventionally, -the names of such end in PATH), +the names of such end in PATH), it is recommended to add the values as a list of strings, even if there is only a single string to add. The same goes for adding library names to &cv-LIBS;. @@ -812,7 +811,7 @@ is being used and &scons; finds a derived file that needs to be rebuilt, it will first look in the cache to see if a -file with matching build signature exists +file with matching &buildsig; exists (indicating the input file(s) and build action(s) were identical to those for the current target), and if so, will retrieve the file from the cache. @@ -824,7 +823,7 @@ If the derived file is not present in the cache, &scons; will build it and then place a copy of the built file in the cache, -identified by its build signature, for future use. +identified by its &buildsig;, for future use. @@ -881,6 +880,13 @@ method can be used to disable caching of specific files. This can be useful if inputs and/or outputs of some tool are impossible to predict or prohibitively large. + + +Note that (at this time) &SCons; provides no facilities +for managing the derived-file cache. It is up to the developer +to arrange for cache pruning, expiry, etc. if needed. + + @@ -1324,7 +1330,7 @@ was built. This can be consulted to match various file characteristics such as the timestamp, -size, or content signature. +size, or &contentsig;. diff --git a/doc/man/scons.xml b/doc/man/scons.xml index fc2e24d..047f230 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -1165,7 +1165,7 @@ the help message not to be displayed. -Set the block size used when computing content signatures to +Set the block size used when computing &contentsigs; to KILOBYTES. This value determines the size of the chunks which are read in at once when computing signature hashes. Files below that size are fully stored in memory @@ -1187,8 +1187,8 @@ be appropriate for most uses. Set the hashing algorithm used by SCons to ALGORITHM. -This value determines the hashing algorithm used in generating content -signatures or &f-link-CacheDir; keys. +This value determines the hashing algorithm used in generating +&contentsigs; or &CacheDir; keys. The supported list of values are: md5, sha1, and sha256. However, the Python interpreter used to run SCons must have the corresponding @@ -1272,8 +1272,7 @@ but with the following limitations: &scons; will not detect changes to implicit dependency search paths -(e.g. -CPPPATH, LIBPATH) +(e.g. &cv-link-CPPPATH;, &cv-link-LIBPATH;) that would ordinarily cause different versions of same-named files to be used. @@ -1281,8 +1280,7 @@ cause different versions of same-named files to be used. will miss changes in the implicit dependencies in cases where a new implicit dependency is added earlier in the implicit dependency search path -(e.g. -CPPPATH, LIBPATH) +(e.g. &cv-link-CPPPATH;, &cv-link-LIBPATH;) than a current implicit dependency with the same name. @@ -1551,16 +1549,16 @@ targets specified on the command line will still be processed. Set the maximum expected drift in the modification time of files to SECONDS. This value determines how long a file must be unmodified -before its cached content signature +before its cached &contentsig; will be used instead of -calculating a new content signature (hash) +calculating a new &contentsig; (hash) of the file's contents. The default value is 2 days, which means a file must have a modification time of at least two days ago in order to have its -cached content signature used. -A negative value means to never cache the content -signature and to ignore the cached value if there already is one. A value -of 0 means to always use the cached signature, +cached &contentsig; used. +A negative value means to never cache the +&contentsig; and to ignore the cached value if there already is one. +A value of 0 means to always use the cached signature, no matter how old the file is. @@ -2408,11 +2406,11 @@ env = Environment(parse_flags='-Iinclude -DEBUG -lm') This example adds 'include' to -the CPPPATH &consvar;, +the &cv-link-CPPPATH; &consvar;, 'EBUG' to -CPPDEFINES, +&cv-link-CPPDEFINES;, and 'm' to -LIBS. +&cv-link-LIBS;. @@ -2574,7 +2572,7 @@ or if tools includes 'default', then &scons; will auto-detect usable tools, using the execution environment value of PATH (that is, env['ENV']['PATH'] - -the external evironment PATH from os.environ +the external evironment &PATH; from os.environ is not used) for looking up any backing programs, and the platform name in effect to determine the default tools for that platform. @@ -2856,11 +2854,12 @@ env.Program('hello', 'hello.c', parse_flags='-Iinclude -DEBUG -lm') This example adds 'include' to -CPPPATH, +the &cv-link-CPPPATH; &consvar;, 'EBUG' to -CPPDEFINES, +&cv-link-CPPDEFINES;, and 'm' to -LIBS. +&cv-link-LIBS;. + Although the builder methods defined by &scons; @@ -5546,9 +5545,9 @@ must accept four arguments: env is the &consenv; to use for context, and for_signature is a Boolean value that tells the function -if it is being called for the purpose of generating a build signature +if it is being called for the purpose of generating a &buildsig; (as opposed to actually executing the command). -Since the build signature is used for rebuild determination, +Since the &buildsig; is used for rebuild determination, the function should omit those elements that do not affect whether a rebuild should be triggered if for_signature is true. @@ -5974,6 +5973,7 @@ l = Action(build_it, '$STRINGIT') Any additional positional arguments, if present, may either be &consvars; or lists of &consvars; whose values will be included in the signature of the Action +(the &buildsig;) when deciding whether a target should be rebuilt because the action changed. Such variables may also be specified using the varlist @@ -6637,14 +6637,14 @@ may be used to surround parts of a command line that may change without causing a rebuild--that is, -which are not included in the signature +which are not included in the &buildsig; of target files built with this command. All text between $( and $) will be removed from the command line -before it is added to the build action signature, +before it is added to the &buildsig; and the $( and @@ -6662,7 +6662,9 @@ echo Last build occurred $( $TODAY $). > $TARGET echo Last build occurred $TODAY. > $TARGET -but the command signature added to any target files would be: +but the command portion of the +the &buildsig; computed for any target files built +by this action would be: echo Last build occurred . > $TARGET @@ -6682,8 +6684,8 @@ Such a function must accept four arguments: env is the &consenv; to use for context, and for_signature is a Boolean value that tells the function -if it is being called for the purpose of generating a build signature. -Since the build signature is used for rebuild determination, +if it is being called for the purpose of generating a &buildsig;. +Since the &buildsig; is used for rebuild determination, the function should omit variable elements that do not affect whether a rebuild should be triggered (see $( @@ -6921,7 +6923,7 @@ directories when generating the dependency Nodes. To illustrate this, a C language source file may contain a line like #include "foo.h". However, there is no guarantee that foo.h exists in the current directory: -the contents of &cv-CPPPATH; is passed to the C preprocessor which +the contents of &cv-link-CPPPATH; is passed to the C preprocessor which will look in those places for the header, so the scanner function needs to look in those places as well in order to build Nodes with correct paths. @@ -7201,7 +7203,7 @@ to vary its initialization. Returns True if the tool can be called in the context of env. Usually this means looking up one or more -known programs using the PATH from the +known programs using the PATH from the supplied env, but the tool can make the "exists" decision in any way it chooses. diff --git a/doc/user/caching.xml b/doc/user/caching.xml index c7b3842..69368d7 100644 --- a/doc/user/caching.xml +++ b/doc/user/caching.xml @@ -22,7 +22,9 @@