From 502fa36ca74899cf200c455f844d3cc9721fc585 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Sun, 31 May 2020 12:26:18 -0600 Subject: Update manpage Options section [ci skip] OPTIONS: add/change markup. A few comments modified on CacheDir usage, and on Help. Dropped a reference to SCCS/RCS retrieval. Signed-off-by: Mats Wichmann --- doc/man/scons.xml | 129 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 71 insertions(+), 58 deletions(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index b58e14f..f9372bb 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -266,11 +266,6 @@ supports the ability to define new scanners for unknown input file types. &scons; -knows how to fetch files automatically from -SCCS or RCS subdirectories -using SCCS, RCS or BitKeeper. - -&scons; is normally executed in a top-level directory containing an &SConstruct; file. When &scons; is invoked, @@ -295,7 +290,7 @@ the build in any way: if ARGUMENTS.get('debug', 0): - env = Environment(CCFLAGS = '-g') + env = Environment(CCFLAGS='-g') else: env = Environment() @@ -521,18 +516,17 @@ Will not remove any targets specified by the &NoClean; function. - -Print debug information about the &CacheDir; +Write debug information about derived-file caching to the specified file. If file -is -- -(a hyphen), +is a hyphen +(-), the debug information is printed to the standard output. The printed messages describe what signature-file names are being looked for in, retrieved from, or written to the -&CacheDir; directory tree. +derived-file cache specified by &f-link-CacheDir;. @@ -542,11 +536,13 @@ are being looked for in, retrieved from, or written to the -Disable the derived-file caching specified by -&CacheDir;. +Disable derived-file caching. &scons; will neither retrieve files from the cache -nor copy files to the cache. +nor copy files to the cache. This option can +be used to temporarily disable the cache without +modifying the build scripts. + @@ -556,9 +552,9 @@ nor copy files to the cache. -When using &CacheDir;, -populate a cache by copying any already-existing, up-to-date -derived files to the cache, +When using &f-link-CacheDir;, +populate a derived-file 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, @@ -572,8 +568,9 @@ option. -Use the cache (if enabled) for reading, but do not not update the -cache with changed files. +Use the derived-file cache, if enabled, to retrieve files, +but do not not update the cache with any files actually +built during this invocation. @@ -581,13 +578,13 @@ cache with changed files. -When using &CacheDir; -and retrieving a derived file from the cache, +When using a derived-file cache +and retrieving a file from it, 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, +that would have been executed to build the file. +Without this option, &scons; reports +"Retrieved `file' from cache.". +This allows producing consistent output for build logs, regardless of whether a target file was rebuilt or retrieved from the cache. @@ -722,7 +719,7 @@ each command, shows the absolute start and end times. This may be useful in debugging parallel builds. Implies the option. -Since &scons; 3.1. +Available since &scons; 3.1. @@ -739,7 +736,7 @@ This is not supported when SCons is executed with the Python or when the SCons modules have been compiled with optimization (that is, when executing from -*.pyo +*.pyo files). @@ -1054,12 +1051,20 @@ will read all of the specified files. -Print a local help message for this build, if one is defined in -the SConscript files, plus a line that describes the - -option for command-line option help. If no local help message -is defined, prints the standard help message about command-line -options. Exits after displaying the appropriate message. +Print a local help message for this project, +if one is defined in the SConscript files +(see the &f-link-Help; function), +plus a line that refers to the standard &SCons; help message. +If no local help message is defined, +prints the standard &SCons; help message +(as for the option) +plus help for any local options defined through &f-link-AddOption;. +Exits after displaying the appropriate message. + +Note that use of this option requires &SCons; to process +the SConscript files, so syntax errors may cause +the help message not to be displayed. + @@ -1069,8 +1074,8 @@ options. Exits after displaying the appropriate message. -Print the standard help message about command-line options and -exit. +Print the standard help message about &SCons; +command-line options and exit. @@ -1172,7 +1177,7 @@ underneath path. Starts SCons in interactive mode. The SConscript files are read once and a -scons>>> +scons>>> prompt is printed. Targets may now be rebuilt by typing commands at interactive prompt without having to re-read the SConscript files @@ -1182,7 +1187,7 @@ and re-initialize the dependency graph from scratch. - build[OPTIONS] [TARGETS] ... + build [OPTIONS] [TARGETS] ... Builds the specified TARGETS @@ -1229,7 +1234,7 @@ which only happens once at the beginning of interactive mode). - clean[OPTIONS] [TARGETS] ... + clean [OPTIONS] [TARGETS] ... Cleans the specified TARGETS @@ -1244,17 +1249,25 @@ This command is itself a synonym for - exit + exit Exits SCons interactive mode. You can also exit by terminating input -(CTRL+D on UNIX or Linux systems, -CTRL+Z on Windows systems). +( +Ctrl +D + +UNIX or Linux systems, +( +Ctrl +Z + +on Windows systems). - help[COMMAND] + help [COMMAND] Provides a help message about the commands available in SCons interactive mode. @@ -1269,13 +1282,13 @@ are synonyms. - shell[COMMANDLINE] + shell [COMMANDLINE] Executes the specified -COMMANDLINE +COMMANDLINE in a subshell. If no -COMMANDLINE +COMMANDLINE is specified, executes the interactive command interpreter specified in the @@ -1283,7 +1296,7 @@ specified in the environment variable (on UNIX and Linux systems) or the -COMSPEC +COMSPEC environment variable (on Windows systems). sh @@ -1294,7 +1307,7 @@ are synonyms. - version + version Prints SCons version information. @@ -1721,7 +1734,7 @@ specified alone, without any type, it behaves as if all had been specified. -Since &scons; 4.0. +Available since &scons; 4.0. @@ -1845,9 +1858,9 @@ specifies the type of warnings to be enabled or disabled: cache-version -Warnings about the cache directory not using -the latest configuration information -CacheDir(). +Warnings about the derived-file cache directory +specified by &f-link-CacheDir; not using +the latest configuration information. These warnings are enabled by default. @@ -1857,7 +1870,7 @@ These warnings are enabled by default. Warnings about errors trying to write a copy of a built file to a specified -CacheDir(). +derived-file cache specified by &f-link-CacheDir;. These warnings are disabled by default. @@ -1866,7 +1879,7 @@ These warnings are disabled by default. corrupt-sconsign Warnings about unfamiliar signature data in -.sconsign +.sconsign files. These warnings are enabled by default. @@ -1943,14 +1956,14 @@ that may require changes to the configuration. Warnings about the use of two commonly misspelled keywords -targets +targets and -sources -to &Builder; calls. The correct spelling is the +sources +to &f-link-Builder; calls. The correct spelling is the singular form, even though -target +target and -source +source can themselves refer to lists of names or nodes. -- cgit v0.12