diff options
Diffstat (limited to 'doc/man/scons.1')
| -rw-r--r-- | doc/man/scons.1 | 169 |
1 files changed, 136 insertions, 33 deletions
diff --git a/doc/man/scons.1 b/doc/man/scons.1 index a1eac4c..7eac0e8 100644 --- a/doc/man/scons.1 +++ b/doc/man/scons.1 @@ -297,28 +297,40 @@ command is specified. Also remove any files or directories associated to the construction command using the Clean() function. -.\" .TP -.\" --cache-disable, --no-cache -.\" Disable caching. Will neither retrieve files from cache nor flush -.\" files to cache. Has no effect if use of caching is not specified -.\" in an SConscript file. -.\" -.\" .TP -.\" --cache-force, --cache-populate -.\" Populate a cache by forcing any already-existing up-to-date -.\" target files to the cache, in addition to files built by this -.\" invocation. This is useful to populate a new cache with -.\" appropriate target files, or to make available in the cache -.\" any target files recently built with caching disabled via the -.\" .B --cache-disable -.\" option. -.\" -.\" .TP -.\" --cache-show -.\" When retrieving a target file from a cache, show the command -.\" that would have been executed to build the file. This produces -.\" consistent output for build logs, regardless of whether a target -.\" file was rebuilt or retrieved from cache. +.TP +--cache-disable, --no-cache +Disable the derived-file caching specified by +.BR CacheDir (). +.B scons +will neither retrieve files from the cache +nor copy files to the cache. + +.TP +--cache-force, --cache-populate +When using +.BR CacheDir (), +populate a cache by copying any already-existing, up-to-date +derived files to the cache, +in addition to files built by this invocation. +This is useful to populate a new cache with +all the current derived files, +or to add to the cache any derived files +recently built with caching disabled via the +.B --cache-disable +option. + +.TP +--cache-show +When using +.BR CacheDir () +and retrieving a derived file from the cache, +show the command +that would have been executed to build the file, +instead of the usual report, +"Retrieved `file' from cache." +This will produce consistent output for build logs, +regardless of whether a target +file was rebuilt or retrieved from the cache. .TP .RI "-C" " directory" ", --directory=" directory @@ -2311,6 +2323,32 @@ also provides various additional functions, not associated with a construction environment, that SConscript files can use: +.TP +.RI AddPostAction ( target, action ) +Arranges for the specified +.I action +to be performed +after the specified +.I target +has been built. +The specified action(s) may be +an Action object, or anything that +can be converted into an Action object +(see below). + +.TP +.RI AddPreAction ( target, action ) +Arranges for the specified +.I action +to be performed +before the specified +.I target +is built. +The specified action(s) may be +an Action object, or anything that +can be converted into an Action object +(see below). + .TP .RI BuildDir( build_dir ", " src_dir ", [" duplicate ]) This specifies a build directory to use for all derived files. @@ -2356,17 +2394,82 @@ can be converted into an Action object (see below). .TP -.RI AddPreAction ( target, action ) -Arranges for the specified -.I action -to be performed -before the specified -.I target -is built. -The specified action(s) may be -an Action object, or anything that -can be converted into an Action object -(see below). +.RI CacheDir ( cache_dir ) +Specifies that +.B scons +will maintain a cache of derived files in +.I cache_dir . +The derived files in the cache will be shared +among all the builds using the same +.BR CacheDir () +call. + +When a +.BR CacheDir () +is being used and +.B scons +finds a derived file that needs to be rebuilt, +it will first look in the cache to see if a +derived file has already been built +from identical input files and an identical build action +(as incorporated into the MD5 build signature). +If so, +.B scons +will retrieve the file from the cache. +If the derived file is not present in the cache, +.B scons +will rebuild it and +then place a copy of the built file in the cache +(identified by its MD5 build signature), +so that it may be retrieved by other +builds that need to build the same derived file +from identical inputs. + +Use of a specified +.BR CacheDir() +may be disabled for any invocation +by using the +.B --cache-disable +option. + +If the +.B --cache-force +option is used, +.B scons +will place a copy of +.I all +derived files in the cache, +even if they already existed +and were not built by this invocation. +This is useful to populate a cache +the first time +.BR CacheDir () +is added to a build, +or after using the +.B --cache-disable +option. + +When using +.BR CacheDir (), +.B scons +will report, +"Retrieved `file' from cache," +unless the +.B --cache-show +option is being used. +When the +.B --cache-show +option is used, +.B scons +will print the action that +.I would +have been used to build the file, +without any indication that +the file was actually retrieved from the cache. +This is useful to generate build logs +that are equivalent regardless of whether +a given derived file has been built in-place +or retrieved from the cache. .TP .RI Clean ( target, files_or_dirs ) |