From 615c04fae3b647cd433efa4fb05eb5f62207f462 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Wed, 27 May 2020 07:14:40 -0600 Subject: Updates to shared docs [ci skip] Mostly update markup to more "standard" markup conventions. There are some substantive wording changes to CacheDir descriptions in Environment, and to the AddOption/Help descriptions in Main and SConscript files. Signed-off-by: Mats Wichmann --- SCons/Environment.xml | 539 +++++++++++++++++++++----------------------- SCons/Script/Main.xml | 261 +++++++++++---------- SCons/Script/SConscript.xml | 26 ++- 3 files changed, 418 insertions(+), 408 deletions(-) diff --git a/SCons/Environment.xml b/SCons/Environment.xml index 898dc5d..bc1864f 100644 --- a/SCons/Environment.xml +++ b/SCons/Environment.xml @@ -242,28 +242,25 @@ that are part of this construction environment. -Creates an Action object for +A factory function to create an Action object for the specified -action. +action. See the manpage section "Action Objects" for a complete explanation of the arguments and behavior. -Note that the -env.Action() +Note that the &f-env-Action; form of the invocation will expand construction variables in any argument strings, including the -action +action argument, at the time it is called using the construction variables in the -env +env construction environment through which -env.Action() -was called. -The -Action() +&f-env-Action; was called. +The &f-Action; global function form delays all variable expansion until the Action object is actually used. @@ -283,27 +280,26 @@ When called with the AddMethod() form, adds the specified -function +function to the specified -object +object as the specified method -name. -When called with the -env.AddMethod() -form, +name. +When called using the +&f-env-AddMethod; form, adds the specified -function +function to the construction environment -env +env as the specified method -name. +name. In both cases, if -name +name is omitted or -None, +None, the name of the specified -function +function itself is used for the method name. @@ -341,10 +337,10 @@ env.other_method_name('another arg') Arranges for the specified -action +action to be performed after the specified -target +target has been built. The specified action(s) may be an Action object, or anything that @@ -369,10 +365,10 @@ one or more targets in the list. Arranges for the specified -action +action to be performed before the specified -target +target is built. The specified action(s) may be an Action object, or anything that @@ -428,7 +424,7 @@ file into an object file. Creates one or more phony targets that expand to one or more other targets. An optional -action +action (command) or list of actions can be specified that will be executed @@ -470,7 +466,7 @@ env.Alias('update', ['file1', 'file2'], "update_database $SOURCES") Marks each given -target +target so that it is always assumed to be out of date, and will always be rebuilt if needed. Note, however, that @@ -544,7 +540,7 @@ string, in which case a list will be returned instead of a string. If -delete_existing +delete_existing is 0, then adding a path that already exists will not move it to the end; it will stay where it is in the list. @@ -605,7 +601,7 @@ env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy']) Creates a Builder object for the specified -action. +action. See the manpage section "Builder Objects" for a complete explanation of the arguments and behavior. @@ -616,14 +612,13 @@ Note that the form of the invocation will expand construction variables in any arguments strings, including the -action +action argument, at the time it is called using the construction variables in the -env +env construction environment through which -env.Builder() -was called. +&f-env-Builder; was called. The &f-Builder; form delays all variable expansion @@ -638,68 +633,61 @@ until after the Builder object is actually called. -Specifies that +Direct &scons; -will maintain a cache of derived files in -cache_dir. +to use a derived-file cache in +cache_dir. The derived files in the cache will be shared -among all the builds using the same -&f-CacheDir; -call. +among all the builds specifying the same +cache_dir. Specifying a -cache_dir +cache_dir of -None +None disables derived file caching. -Calling -env.CacheDir() -will only affect targets built +Calling the environment method +&f-link-env-CacheDir; +limits the effect to targets built through the specified construction environment. -Calling -&f-CacheDir; +Calling the global function +&f-link-CacheDir; sets a global default that will be used by all targets built through construction environments -that do -not -have an -env.CacheDir() -specified. +that do not set up environment-specific +caching by calling &f-env-CacheDir;. -When a -CacheDir() +When cachin +cache_dir 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 -derived file has already been built -from identical input files and an identical build action -(as incorporated into the MD5 build signature). -If so, -&scons; -will retrieve the file from the cache. +file with matching build signature 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. If the derived file is not present in the cache, &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. +will build it and +then place a copy of the built file in the cache, +identified by its build signature, for future use. -Use of a specified -&f-CacheDir; +Derived-file caching may be disabled for any invocation -by using the +of &scons; by giving the -option. +command line option. +Cache updating may be disabled, leaving cache +fetching enabled, by giving the +. @@ -713,32 +701,31 @@ 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 -&f-CacheDir; -is added to a build, -or after using the - -option. +the first time a +cache_dir +is used for a build, +or to bring a cache up to date after +a build with cache updating disabled +( +or ) +has been done. When using &f-CacheDir;, &scons; -will report, -"Retrieved `file' from cache," +will report +Retrieved `file' from cache unless the option is being used. -When the +With the -option is used, -&scons; -will print the action that -would -have been used to build the file, -without any indication that -the file was actually retrieved from the cache. +option, &scons; +will print the action that would +have been used to build the file +whether or not it was retreived 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 @@ -854,7 +841,7 @@ env4 = env.Clone(tools = ['msvc', MyTool]) The -parse_flags +parse_flags keyword argument is also recognized to allow merging command-line style arguments into the appropriate construction variables (see &f-link-env-MergeFlags;). @@ -890,21 +877,23 @@ for the calling syntax and details. -Executes a specific action +Executes a specific action (or list of actions) -to build a target file or files. +to build a target file or files +from a source file or files. This is more convenient than defining a separate Builder object for a single special-case build. -&b-Command; builder accepts -source_scanner, -target_scanner, -source_factory, and -target_factory -keyword arguments. The *_scanner args can +The +&Command; function accepts +source_scanner, +target_scanner, +source_factory, and +target_factory +keyword arguments. These arguments can be used to specify a Scanner object that will be used to apply a custom @@ -916,12 +905,12 @@ if any of the sources will be directories that must be scanned on-disk for changes to files that aren't already specified in other Builder of function calls. -The *_factory args take a factory function that the -Command will use to turn any sources or targets +The *_factory arguments take a factory function that +&Command; will use to turn any sources or targets specified as strings into SCons Nodes. -See the sections "Builder Objects" -below, for more information about how these -args work in a Builder. +See the manpage section "Builder Objects" +for more information about how these +arguments work in a Builder. @@ -936,13 +925,11 @@ or a callable Python object; see the manpage section "Action Objects" for more complete information. Also note that a string specifying an external command -may be preceded by an -@ -(at-sign) +may be preceded by an at-sign +(@) to suppress printing the command in question, -or by a -- -(hyphen) +or by a hyphen +(-) to ignore the exit status of the external command. @@ -951,26 +938,35 @@ Examples: -env.Command('foo.out', 'foo.in', - "$FOO_BUILD < $SOURCES > $TARGET") +env.Command( + target='foo.out', + source='foo.in', + action="$FOO_BUILD < $SOURCES > $TARGET" +) + +env.Command( + target='bar.out', + source='bar.in', + action=["rm -f $TARGET", "$BAR_BUILD < $SOURCES > $TARGET"], + ENV={'PATH': '/usr/local/bin/'}, +) -env.Command('bar.out', 'bar.in', - ["rm -f $TARGET", - "$BAR_BUILD < $SOURCES > $TARGET"], - ENV={'PATH': '/usr/local/bin/'}) +import os def rename(env, target, source): - import os os.rename('.tmp', str(target[0])) -env.Command('baz.out', 'baz.in', - ["$BAZ_BUILD < $SOURCES > .tmp", - rename]) + +env.Command( + target='baz.out', + source='baz.in', + action=["$BAZ_BUILD < $SOURCES > .tmp", rename], +) Note that the -&f-Command; +&Command; function will usually assume, by default, that the specified targets and/or sources are Files, if no other part of the configuration @@ -981,7 +977,7 @@ be treated as directories by using the &f-link-Dir; or -env.Dir +&f-link-env-Dir; functions. @@ -1021,18 +1017,6 @@ for a complete explanation of the arguments and behavior. - - -([key=val, ...]) - - - -A now-deprecated synonym for -env.Clone(). - - - - (function) @@ -1042,9 +1026,8 @@ A now-deprecated synonym for Specifies that all up-to-date decisions for targets built through this construction environment will be handled by the specified -function. -The -function +function. +function can be one of the following strings that specify the type of decision function to be performed: @@ -1053,7 +1036,7 @@ to be performed: -timestamp-newer +"timestamp-newer" Specifies that a target shall be considered out of date and rebuilt @@ -1067,7 +1050,7 @@ can be used a synonym for -timestamp-match +"timestamp-match" Specifies that a target shall be considered out of date and rebuilt @@ -1084,7 +1067,7 @@ timestamp, such as can happen when restoring files from backup archives. -MD5 +"MD5" Specifies that a target shall be considered out of date and rebuilt @@ -1101,7 +1084,7 @@ can be used as a synonym for -MD5-timestamp +"MD5-timestamp" Specifies that a target shall be considered out of date and rebuilt @@ -1148,7 +1131,7 @@ env.Decider('content') In addition to the above already-available functions, the -function +function argument may be a Python function you supply. Such a function must accept the following four arguments: @@ -1161,10 +1144,10 @@ Such a function must accept the following four arguments: The Node (file) which should cause the -target +target to be rebuilt if it has "changed" since the last tme -target +target was built. @@ -1177,7 +1160,7 @@ The Node (file) being built. In the normal case, this is what should get rebuilt if the -dependency +dependency has "changed." @@ -1187,9 +1170,9 @@ has "changed." Stored information about the state of the -dependency +dependency the last time the -target +target was built. This can be consulted to match various file characteristics @@ -1203,11 +1186,11 @@ size, or content signature. If set, use this Node instead of the one specified by -dependency +dependency to determine if the dependency has changed. This argument is optional so should be written as a default argument (typically it would be -written as repo_node=None). +written as repo_node=None). A caller will normally only set this if the target only exists in a Repository. @@ -1219,14 +1202,14 @@ target only exists in a Repository. The -function +function should return a value which evaluates True if the -dependency +dependency has "changed" since the last time the -target +target was built (indicating that the target should @@ -1264,15 +1247,15 @@ env.Decider(my_decider) Specifies an explicit dependency; the -target +target will be rebuilt whenever the -dependency +dependency has changed. Both the specified -target +target and -dependency +dependency can be a string (usually the path name of a file or directory) or Node objects, @@ -1317,9 +1300,9 @@ Find an executable from one or more choices: Returns the first value from progs that was found, or None. Executable is searched by checking the paths specified -by env['ENV']['PATH']. +by env['ENV']['PATH']. On Windows systems, additionally applies the filename suffixes found in -env['ENV']['PATHEXT'] +env['ENV']['PATHEXT'] but will not include any such extension in the return value. &f-env-Detect; is a wrapper around &f-link-env-WhereIs;. @@ -1359,24 +1342,24 @@ cc_values = env.Dictionary('CC', 'CCFLAGS', 'CCCOM') Returns Directory Node(s). A Directory Node is an object that represents a directory. -name +name can be a relative or absolute path or a list of such paths. -directory +directory is an optional directory that will be used as the parent directory. If no -directory +directory is specified, the current script's directory is used as the parent. If -name +name is a single pathname, the corresponding node is returned. If -name +name is a list, SCons returns a list of nodes. Construction variables are expanded in -name. +name. @@ -1397,7 +1380,7 @@ for more information. -Serializes the construction variables to a string. +Serializes &cpnsvars; to a string. The method supports the following formats specified by format: @@ -1405,7 +1388,7 @@ The method supports the following formats specified by pretty -Returns a pretty printable representation of the environment (if +Returns a pretty printed representation of the environment (if format is not specified, this is the default). @@ -1421,10 +1404,11 @@ Returns a JSON-formatted string representation of the environment. -key, -if not -None, -should be a string containing the name of the variable of interest. +If key is +None (the default) the entire +dictionary of &consvars; is serialized. +If supplied, it is taken as the name of a &consvar; +whose value is serialized. @@ -1476,7 +1460,7 @@ will print: Return a new construction environment initialized with the specified -key=value +key=value pairs. @@ -1490,16 +1474,20 @@ pairs. Executes an Action object. The specified -action +action may be an Action object (see manpage section "Action Objects" -for a complete explanation of the arguments and behavior), +for an explanation of behavior), or it may be a command-line string, list of commands, or executable Python function, each of which will be converted into an Action object and then executed. +Any additional arguments to &f-Execute; +(strfunction, varlist) +are passed on to the &f-link-Action; factory function +which actually creates the Action object. The exit value of the command or return value of the Python function will be returned. @@ -1509,7 +1497,7 @@ will be returned. Note that &scons; will print an error message if the executed -action +action fails--that is, exits with or returns a non-zero value. &scons; @@ -1518,7 +1506,7 @@ will however, automatically terminate the build if the specified -action +action fails. If you want the build to stop in response to a failed &f-Execute; @@ -1544,24 +1532,24 @@ if Execute("mkdir sub/dir/ectory"): Returns File Node(s). A File Node is an object that represents a file. -name +name can be a relative or absolute path or a list of such paths. -directory +directory is an optional directory that will be used as the parent directory. If no -directory +directory is specified, the current script's directory is used as the parent. If -name +name is a single pathname, the corresponding node is returned. If -name +name is a list, SCons returns a list of nodes. Construction variables are expanded in -name. +name. @@ -1583,10 +1571,10 @@ for more information. Search for -file +file in the path specified by -dirs. -dirs +dirs. +dirs may be a list of directory names or a single directory name. In addition to searching for files that exist in the filesystem, this function also searches for derived files @@ -1650,9 +1638,9 @@ FindInstalledFiles() Returns the list of nodes which serve as the source of the built files. It does so by inspecting the dependency tree starting at the optional argument -node +node which defaults to the '"."'-node. It will then return all leaves of -node. +node. These are all children which have no further children. @@ -1721,7 +1709,7 @@ Program(source = objects) # If you need to manipulate the list directly using Python, you need to # call Flatten() yourself, or otherwise handle nested lists: for object in Flatten(objects): - print str(object) + print(str(object)) @@ -1735,10 +1723,10 @@ for object in Flatten(objects): Returns the &scons; path name (or names) for the specified -file +file (or files). The specified -file +file or files may be &scons; @@ -1754,21 +1742,20 @@ Nodes or strings representing path names. Returns Nodes (or strings) that match the specified -pattern, +pattern, relative to the directory of the current &SConscript; file. -The -env.Glob() -form performs string substition on -pattern +The evironment method form (&f-env-Glob;) +performs string substition on +pattern and returns whatever matches the resulting expanded pattern. The specified -pattern +pattern uses Unix shell style metacharacters for matching: @@ -1802,14 +1789,14 @@ function) and returns a Node (or string, if so configured) in the local (SConscript) directory -if matching Node is found +if a matching Node is found anywhere in a corresponding repository or source directory. The -ondisk +ondisk argument may be set to a value which evaluates False to disable the search for matches on disk, @@ -1822,7 +1809,7 @@ for any on-disk matches found. The -source +source argument may be set to a value which evaluates True to specify that, @@ -1835,7 +1822,7 @@ not the local directory. The -strings +strings argument may be set to a value which evaluates True to have the @@ -1861,7 +1848,7 @@ directory.) The -exclude +exclude argument may be set to a pattern or a list of patterns (following the same Unix shell semantics) which must be filtered out of returned elements. @@ -1890,7 +1877,7 @@ sources = Glob("*.cpp", exclude=["os_*_specific_*.cpp"]) + \ When -flag +flag is non-zero, adds the names of the default builders (Program, Library, etc.) @@ -1898,7 +1885,7 @@ to the global name space so they can be called without an explicit construction environment. (This is the default.) When -flag +flag is zero, the names of the default builders are removed from the global name space @@ -1956,7 +1943,7 @@ env.Ignore('bar','bar/foobar.obj') The specified -string +string will be preserved as-is and not have construction variables expanded. @@ -1970,7 +1957,7 @@ and not have construction variables expanded. The specified -targets +targets will have copies made in the local tree, even if an already up-to-date copy exists in a repository. @@ -1987,14 +1974,14 @@ Returns a list of the target Node or Nodes. Merges the elements of the specified -arg, +arg, which must be a dictionary, to the construction environment's copy of the shell environment in env['ENV']. (This is the environment which is passed to subshells spawned by SCons.) Note that -arg +arg must be a single value, so multiple strings must be passed in as a list, @@ -2011,7 +1998,7 @@ since this function calls or &f-link-PrependENVPath; depending on the -prepend +prepend argument. See those functions for more details. @@ -2036,17 +2023,17 @@ env.MergeShellPaths({'INCLUDE':['c:/inc1', 'c:/inc2']}, prepend=0 ) Merges the specified -arg +arg values to the construction environment's construction variables. If the -arg +arg argument is not a dictionary, it is converted to one by calling &f-link-env-ParseFlags; on the argument before the values are merged. Note that -arg +arg must be a single value, so multiple strings must be passed in as a list, @@ -2198,11 +2185,11 @@ NoClean(env.Program('hello', 'hello.c')) Calls the specified -function +function to modify the environment as specified by the output of -command. +command. The default -function +function is &f-link-env-MergeFlags;, which expects the output of a typical @@ -2240,7 +2227,7 @@ for a table of options and construction variables. Parses the contents of the specified -filename +filename as a list of dependencies in the style of &Make; or @@ -2252,10 +2239,10 @@ and explicitly establishes all of the listed dependencies. By default, it is not an error if the specified -filename +filename does not exist. The optional -must_exist +must_exist argument may be set to a non-zero value to have scons @@ -2266,7 +2253,7 @@ or is otherwise inaccessible. The optional -only_one +only_one argument may be set to a non-zero value to have scons @@ -2288,7 +2275,7 @@ file. The -filename +filename and all of the files listed therein will be interpreted relative to the directory of the @@ -2417,7 +2404,7 @@ env = Environment(platform = Platform('win32')) The &f-env-Platform; form applies the callable object for the specified platform -string +string to the environment through which the method was called. @@ -2502,7 +2489,7 @@ string, in which case a list will be returned instead of a string. If -delete_existing +delete_existing is 0, then adding a path that already exists will not move it to the beginning; it will stay where it is in the list. @@ -2570,16 +2557,16 @@ env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy']) This returns a Directory Node similar to Dir. The python module / package is looked up and if located the directory is returned for the location. -modulename +modulename Is a named python package / module to lookup the directory for it's location. If -modulename +modulename is a list, SCons returns a list of Dir nodes. Construction variables are expanded in -modulename. +modulename. @@ -2611,7 +2598,7 @@ env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx') Specifies that -directory +directory is a repository to be searched for files. Multiple calls to &f-Repository; @@ -2695,7 +2682,7 @@ env.Requires('foo', 'file-that-must-be-built-before-foo') Creates a Scanner object for the specified -function. +function. See manpage section "Scanner Objects" for a complete explanation of the arguments and behavior. @@ -2760,18 +2747,18 @@ This tells &scons; to store all file signatures in the specified database -file. +file. If the -file +file name is omitted, .sconsign is used by default. (The actual file name(s) stored on disk may have an appropriated suffix appended by the - dbm_module.) +dbm_module.) If -file +file is not an absolute path name, the file is placed in the same directory as the top-level &SConstruct; @@ -2780,9 +2767,9 @@ file. If -file +file is -None, +None, then &scons; will store file signatures @@ -2796,7 +2783,7 @@ prior to SCons 0.96.91 and 0.97.) The optional -dbm_module +dbm_module argument can be used to specify which Python database module The default is to use a custom @@ -2856,13 +2843,13 @@ if 'FOO' not in env: env['FOO'] = 'foo' Declares -side_effect +side_effect as a side effect of building -target. +target. Both -side_effect +side_effect and -target +target can be a list, a file name, or a node. A side effect is a target file that is created or updated as a side effect of building other targets. @@ -2884,23 +2871,23 @@ multiple build commands. Because multiple build commands may update the same side effect file, by default the -side_effect +side_effect target is not automatically removed when the -target +target is removed by the option. (Note, however, that the -side_effect +side_effect might be removed as part of cleaning the directory in which it lives.) If you want to make sure the -side_effect +side_effect is cleaned whenever a specific -target +target is cleaned, you must specify this explicitly with the @@ -2917,13 +2904,13 @@ function. Returns a list of file names or other objects. -If arg is a string, +If arg is a string, it will be split on strings of white-space characters within the string, making it easier to write long lists of file names. -If arg is already a list, +If arg is already a list, the list will be returned untouched. -If arg is any other type of object, +If arg is any other type of object, it will be returned as a list containing just the object. @@ -2952,7 +2939,7 @@ files = Split(""" Performs construction variable interpolation on the specified string or sequence argument -input. +input. @@ -2967,14 +2954,14 @@ and $) character sequences will be stripped from the returned string, The optional -raw +raw argument may be set to 1 if you want to preserve white space and $(-$) sequences. The -raw +raw argument may be set to 2 if you want to strip @@ -2997,9 +2984,9 @@ and the results will be returned as a list. The optional -target +target and -source +source keyword arguments must be set to lists of target and source nodes, respectively, @@ -3021,7 +3008,7 @@ as an SCons action. Returned string values or sequence elements are converted to their string representation by default. The optional -conv +conv argument may specify a conversion function that will be used in place of @@ -3100,7 +3087,7 @@ as part of the tools keyword argument, or it can be called directly, passing a &consenv; to update as the argument. Either approach will also update the -TOOLS &consvar;. +&cv-TOOLS; &consvar;. @@ -3128,17 +3115,17 @@ u(env) # adds 'opengl' to the TOOLS variable Returns a Node object representing the specified Python value. Value Nodes can be used as dependencies of targets. If the result of calling -str(value) +str(value) changes between SCons runs, any targets depending on -Value(value) +Value(value) will be rebuilt. (This is true even when using timestamps to decide if files are up-to-date.) When using timestamp source signatures, Value Nodes' timestamps are equal to the system time when the Node is created. -name can be provided as an alternative name +name can be provided as an alternative name for the resulting Value node; this is advised -if the value parameter can't be converted to +if the value parameter can't be converted to a string. @@ -3148,7 +3135,7 @@ The returned Value Node object has a method that can be used to "build" a Value Node by setting a new value. The optional -built_value +built_value argument can be specified when the Value Node is created to indicate the Node should already be considered @@ -3208,11 +3195,11 @@ Use the &f-VariantDir; function to create a copy of your sources in another location: if a name under -variant_dir +variant_dir is not found but exists under -src_dir, +src_dir, the file or directory is copied to -variant_dir. +variant_dir. Target files can be built in a different directory than the original sources by simply refering to the sources (and targets) within the variant tree. @@ -3221,15 +3208,15 @@ within the variant tree. &f-VariantDir; can be called multiple times with the same -src_dir +src_dir to set up multiple builds with different options -(variants). +(variants). The -src_dir +src_dir location must be in or underneath the SConstruct file's directory, and -variant_dir +variant_dir may not be underneath -src_dir. +src_dir. -&f-SetOption; is not currently supported for -options added with &f-AddOption;. -Any specified -help= -strings for the new option(s) -will be displayed by the - -or - -options -(the latter only if no other help text is -specified in the SConscript files). -The help text for the local options specified by -&f-AddOption; -will appear below the SCons options themselves, -under a separate -Local Options -heading. -The options will appear in the help text -in the order in which the +Help text for an option is a combination +of the string supplied in the +help keyword +argument to &f-AddOption; and information +collected from the other keyword arguments. +Such help is displayed if the + command line option +is used (but not with ). +Help for all local options is displayed +under the separate heading +Local Options. +The options are unsorted - they will appear +in the help text in the order in which the &f-AddOption; calls occur. @@ -138,27 +133,50 @@ Example: -AddOption('--prefix', - dest='prefix', - nargs=1, type='string', - action='store', - metavar='DIR', - help='installation prefix') -env = Environment(PREFIX = GetOption('prefix')) +AddOption( + '--prefix', + dest='prefix', + nargs=1, + type='string', + action='store', + metavar='DIR', + help='installation prefix', +) +env = Environment(PREFIX=GetOption('prefix')) +For that example, +the following help text would be produced: + + +Local Options: + --prefix=DIR installation prefix + + + +Help text for local options may be unavailable if +the &f-link-Help; function has been called, +see the &f-Help; documentation for details. + + -While &AddOption; behaves like -add_option, -from the optparse module, +As an artifact of the internal implementation, the behavior of options added by &AddOption; -which take arguments is underfined in -scons if whitespace +which take option arguments is undefined +if whitespace (rather than an = sign) is used as -the separator on the command line when -the option is invoked. -Such usage should be avoided. +the separator on the command line. +Users should avoid such usage; it is recommended +to add a note to this effect to project documentation +if the situation is likely to arise. +In addition, if the nargs +keyword is used to specify more than one following +option argument (that is, with a value of 2 +or greater), such arguments would necessarily +be whitespace separated, triggering the issue. +Developers should not use &AddOption; this way. +Future versions of &SCons; will likely forbid such usage. @@ -582,22 +600,21 @@ evaluating Nodes (e.g. files). If the first specified argument is a Python callable (a function or an object that has a -__call__() -method), +__call__ method), the function will be called once every interval -times a Node is evaluated. +times a Node is evaluated (default 1). The callable will be passed the evaluated Node as its only argument. (For future compatibility, it's a good idea to also add -*args +*args and -**kw -as arguments to your function or method. +**kwargs +as arguments to your function or method signatures. This will prevent the code from breaking -if SCons ever changes the interface +if &SCons; ever changes the interface to call the function with additional arguments in the future.) @@ -608,7 +625,7 @@ every 10 Nodes: -def my_progress_function(node, *args, **kw): +def my_progress_function(node, *args, **kwargs): print('Evaluating node %s!' % node) Progress(my_progress_function, interval=10) @@ -626,8 +643,7 @@ will overwrite itself on a display: import sys - -class ProgressCounter: +class ProgressCounter(object): count = 0 def __call__(self, node, *args, **kw): self.count += 100 @@ -637,18 +653,28 @@ Progress(ProgressCounter(), interval=100) -If the first argument -&f-link-Progress; -is a string, -the string will be displayed -every +If the first argument to +&f-Progress; is a string or list of strings, +it is taken as text to be displayed every +interval +evaluated Nodes. +If the first argument is a list of strings, +then each string in the list will be displayed +in rotating fashion every interval evaluated Nodes. -The default is to print the string on standard output; -an alternate output stream + + + +The default is to print the string on standard output. +An alternate output stream may be specified with the -file= -argument. +file +keyword argument, which the +caller must pass already opened. + + + The following will print a series of dots on the error output, one dot for every 100 evaluated Nodes: @@ -661,7 +687,7 @@ Progress('.', interval=100, file=sys.stderr) If the string contains the verbatim substring -&cv-TARGET;, +$TARGET;, it will be replaced with the Node. Note that, for performance reasons, this is not @@ -670,12 +696,13 @@ so you can not use other variables or use curly braces. The following example will print the name of every evaluated Node, -using a -\r -(carriage return) to cause each line to overwritten by the next line, +using a carriage return) +(\r) +to cause each line to overwritten by the next line, and the -overwrite= -keyword argument to make sure the previously-printed +overwrite +keyword argument (default False) +to make sure the previously-printed file name is overwritten with blank spaces: @@ -685,15 +712,9 @@ Progress('$TARGET\r', overwrite=True) -If the first argument to -&f-Progress; -is a list of strings, -then each string in the list will be displayed -in rotating fashion every -interval -evaluated Nodes. -This can be used to implement a "spinner" -on the user's screen as follows: +A list of strings can be used to implement a "spinner" +on the user's screen as follows, changing every +five evaluated Nodes: diff --git a/SCons/Script/SConscript.xml b/SCons/Script/SConscript.xml index 9c383f8..03efcfb 100644 --- a/SCons/Script/SConscript.xml +++ b/SCons/Script/SConscript.xml @@ -248,22 +248,24 @@ file is found. -This specifies help text to be printed if the +Specifies a local help message to be printed if the argument is given to &scons;. -If -&f-Help; -is called multiple times, the text is appended together in the order that +Subsequent calls to &f-Help; -is called. With append set to False, any -&f-Help; -text generated with -&f-AddOption; -is clobbered. If append is True, the AddOption help is prepended to the help -string, thus preserving the - -message. +append text to the previously +defined local help text. + + +For the first call to &f-Help; only, +if append is False +(the default) +any local help message generated through +&f-link-AddOption; calls is replaced. +If append is True, +text is appended to +the existing help text. -- cgit v0.12 From 77b7f15937bd601fe20f50938be6804ae5ab128b Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Wed, 27 May 2020 07:22:02 -0600 Subject: [PR #3671] fix typo; add missed file [ci skip] Sider detected a misspelled tag Failed to "add" one changed doc file, Defaults.xml. Added. Signed-off-by: Mats Wichmann --- SCons/Defaults.xml | 27 ++++++++++++++++----------- SCons/Environment.xml | 2 +- 2 files changed, 17 insertions(+), 12 deletions(-) diff --git a/SCons/Defaults.xml b/SCons/Defaults.xml index bd41cdf..8f3fe12 100644 --- a/SCons/Defaults.xml +++ b/SCons/Defaults.xml @@ -572,20 +572,25 @@ searching the repositories. -Creates and returns the default &consenv; object. -The default &consenv; is used internally by SCons +Instantiates and returns the default &consenv; object. +The &defenv; is used internally by SCons in order to execute many of the global functions in this list -(i.e. those not called as methods of a specific -&consenv;), and to fetch source files transparently -from source code management systems. -The default environment is a singleton, so the keyword +(that is, those not called as methods of a specific &consenv;). +It is not mandatory to call &f-DefaultEnvironment;: +the &defenv; will be instantiated automatically when the +build phase begins if the function has not been called, +however calling it explicitly gives the opportunity to +affect and examine the contents of the &defenv;. + + +The &defenv; is a singleton, so the keyword arguments affect it only on the first call, on subsequent calls the already-constructed object is returned and -any arguments are ignored. -The default environment can be modified in the same way -as any &consenv;. -Modifying the &defenv; has no effect on the environment -constructed by a subsequent &f-Environment; call. +any keyword arguments are silently ignored. +The &defenv; can be modified after instantiation +in the same way as any &consenv;. +Modifying the &defenv; has no effect on the &consenv; +constructed by an &f-link-Environment; or &f-link-Clone; call. diff --git a/SCons/Environment.xml b/SCons/Environment.xml index bc1864f..fe7841a 100644 --- a/SCons/Environment.xml +++ b/SCons/Environment.xml @@ -905,7 +905,7 @@ if any of the sources will be directories that must be scanned on-disk for changes to files that aren't already specified in other Builder of function calls. -The *_factory arguments take a factory function that +The *_factory arguments take a factory function that &Command; will use to turn any sources or targets specified as strings into SCons Nodes. See the manpage section "Builder Objects" -- cgit v0.12 From 34f3bb7409982f847f14e506133b0290809abd31 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Sat, 30 May 2020 11:09:29 -0600 Subject: [PR #3675] fix doc typo from sider [ci skip] Signed-off-by: Mats Wichmann --- SCons/Environment.xml | 10 +++++----- SCons/Errors.py | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/SCons/Environment.xml b/SCons/Environment.xml index fe7841a..f06fda1 100644 --- a/SCons/Environment.xml +++ b/SCons/Environment.xml @@ -662,7 +662,7 @@ caching by calling &f-env-CacheDir;. -When cachin +When a cache_dir is being used and &scons; @@ -1027,10 +1027,10 @@ Specifies that all up-to-date decisions for targets built through this construction environment will be handled by the specified function. -function -can be one of the following strings -that specify the type of decision function -to be performed: +function can be the name of +a function or one of the following strings +that specify the predefined decision function +that will be applied: diff --git a/SCons/Errors.py b/SCons/Errors.py index a3a891f..1f6c240 100644 --- a/SCons/Errors.py +++ b/SCons/Errors.py @@ -73,7 +73,7 @@ class BuildError(Exception): Information about the cause of the location of the error: --------------------------------------------------------- - node : the error occured while building this target node(s) + node : the error occurred while building this target node(s) executor : the executor that caused the build to fail (might be None if the build failures is not due to the -- cgit v0.12