From a81a838085a35ddfeb12d9bbcdb4cf514b5744da Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Mon, 1 Jun 2020 19:16:49 -0600 Subject: User Guide: update markup for cmdline section [ci skip] Update the markup in the cmdline chapter. Also checked in two generated docs which were changed by a couple of earlier changesets. Signed-off-by: Mats Wichmann --- doc/generated/functions.gen | 889 +++++++++++++++++++++++--------------------- doc/generated/functions.mod | 4 - doc/user/command-line.xml | 172 +++++---- 3 files changed, 567 insertions(+), 498 deletions(-) diff --git a/doc/generated/functions.gen b/doc/generated/functions.gen index c0b325e..bfe63e8 100644 --- a/doc/generated/functions.gen +++ b/doc/generated/functions.gen @@ -16,28 +16,25 @@ Action(action, [cmd/str/fun, [var, ...]] [option=value, ...]) env.Action(action, [cmd/str/fun, [var, ...]] [option=value, ...]) -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 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() +env.Action was called. +The Action global function form delays all variable expansion until the Action object is actually used. @@ -51,27 +48,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 +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. @@ -104,59 +100,59 @@ env.other_method_name('another arg') AddOption(arguments) -This function adds a new command-line option to be recognized. -The specified -arguments -are the same as supported by the add_option -method in the standard Python library module optparse, -with a few additional capabilities noted below; -see the documentation for +Adds a local (project-specific) command-line option. +arguments +are the same as those supported by the add_option +method in the standard Python library module optparse, +with a few additional capabilities noted below. +See the documentation for optparse for a thorough discussion of its option-processing capabities. In addition to the arguments and values supported by the -optparse.add_option() -method, -the SCons -AddOption -function allows you to set the -nargs +optparse +add_option +method, AddOption +allows setting the +nargs keyword value to -'?' -(a string with just the question mark) -to indicate that the specified long option(s) take(s) an -optional -argument. -When -nargs = '?' -is passed to the -AddOption -function, the -const -keyword argument -may be used to supply the "default" -value that should be used when the -option is specified on the command line -without an explicit argument. - - - -If no -default= -keyword argument is supplied when calling -AddOption, -the option will have a default value of -None. - - - -Unlike regular optparse, option names -added via AddOption must be matched -exactly, the automatic matching of abbreviations on the -command line for long options is not supported. -To allow specific abbreviations, +a string consisting of a question mark +('?') +to indicate that the option argument for +that option string is optional. +If the option string is present on the +command line but has no matching option +argument, the value of the +const +keyword argument is produced as the value +of the option. +If the option string is omitted from +the command line, the value of the +default +keyword argument is produced, as usual; +if there is no +default +keyword argument in the AddOption call, +None is produced. + + + +optparse recognizes +abbreviations of long option names, +as long as they can be unambiguously resolved. +For example, if +add_option is called to +define a option, +it will recognize , + +and so forth as long as there is no other option +which could also match to the same abbreviation. +Options added via +AddOption do not support +the automatic recognition of abbreviations. +Instead, to allow specific abbreviations, include them in the AddOption call. @@ -164,45 +160,40 @@ include them in the AddOption call. Once a new command-line option has been added with AddOption, the option value may be accessed using -GetOption +GetOption or -env.GetOption(). - -SetOption is not currently supported for -options added with 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 -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 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 AddOption calls occur. @@ -212,27 +203,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 Help function has been called, +see the 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. @@ -243,10 +257,10 @@ Such usage should be avoided. env.AddPostAction(target, action) 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 @@ -268,10 +282,10 @@ one or more targets in the list. env.AddPreAction(target, action) 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 @@ -324,7 +338,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 @@ -405,7 +419,7 @@ AllowSubstExceptions(IndexError, NameError, ZeroDivisionError) env.AlwaysBuild(target, ...) 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 @@ -471,7 +485,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. @@ -525,7 +539,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. @@ -536,14 +550,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. +env.Builder was called. The Builder form delays all variable expansion @@ -555,68 +568,79 @@ until after the Builder object is actually called. CacheDir(cache_dir) env.CacheDir(cache_dir) -Specifies that +Direct scons -will maintain a cache of derived files in -cache_dir. +to maintain a derived-file cache in +cache_dir. The derived files in the cache will be shared -among all the builds using the same -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 +env.CacheDir +limits the effect to targets built through the specified construction environment. -Calling -CacheDir +Calling the global function +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 env.CacheDir. -When a -CacheDir() +When derived-file caching 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, +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. scons -will retrieve the file from the cache. +will report +Retrieved `file' from cache +instead of the normal build message. 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 -CacheDir +The +Retrieved `file' from cache +messages are useful for human consumption, +but less so when comparing log files between +scons runs which will show differences that are +noisy and not actually significant. +To disable, +use the option. +With this option, scons +will print the action that would +have been used to build the file without +considering cache retrieval. + + + +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 +. @@ -630,36 +654,14 @@ 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 -CacheDir -is added to a build, -or after using the - -option. - - - -When using -CacheDir, -scons -will report, -"Retrieved `file' from cache," -unless the - -option is being used. -When 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. -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. +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. @@ -764,7 +766,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 env.MergeFlags). @@ -780,21 +782,23 @@ wx_env = env.Clone(parse_flags='!wx-config --cflags --cxxflags') Command(target, source, action, [key=val, ...]) env.Command(target, source, action, [key=val, ...]) -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. -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 @@ -806,12 +810,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. @@ -826,13 +830,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. @@ -841,21 +843,30 @@ 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], +) @@ -871,7 +882,7 @@ be treated as directories by using the Dir or -env.Dir +env.Dir functions. @@ -904,14 +915,6 @@ for a complete explanation of the arguments and behavior. - - env.Copy([key=val, ...]) - -A now-deprecated synonym for -env.Clone(). - - - Decider(function) env.Decider(function) @@ -919,18 +922,17 @@ 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 -can be one of the following strings -that specify the type of decision function -to be performed: +function. +function can be the name of +a function or one of the following strings +that specify the predefined decision function +that will be applied: -timestamp-newer +"timestamp-newer" Specifies that a target shall be considered out of date and rebuilt @@ -944,7 +946,7 @@ can be used a synonym for -timestamp-match +"timestamp-match" Specifies that a target shall be considered out of date and rebuilt @@ -961,7 +963,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 @@ -978,7 +980,7 @@ can be used as a synonym for -MD5-timestamp +"MD5-timestamp" Specifies that a target shall be considered out of date and rebuilt @@ -1025,7 +1027,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: @@ -1038,10 +1040,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. @@ -1054,7 +1056,7 @@ The Node (file) being built. In the normal case, this is what should get rebuilt if the -dependency +dependency has "changed." @@ -1064,9 +1066,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 @@ -1080,11 +1082,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. @@ -1096,14 +1098,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 @@ -1197,20 +1199,25 @@ see below. DefaultEnvironment([**kwargs]) -Creates and returns the default construction environment object. -The default construction environment is used internally by SCons +Instantiates and returns the default construction environment object. +The default environment 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 -construction environment), 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 construction environment). +It is not mandatory to call DefaultEnvironment: +the default environment 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 default environment. + + +The default environment 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 construction environment. -Modifying the default environment has no effect on the environment -constructed by a subsequent Environment call. +any keyword arguments are silently ignored. +The default environment can be modified after instantiation +in the same way as any construction environment. +Modifying the default environment has no effect on the construction environment +constructed by an Environment or Clone call. @@ -1220,15 +1227,15 @@ constructed by a subsequent Environment call. 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, @@ -1269,9 +1276,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. env.Detect is a wrapper around env.WhereIs. @@ -1304,24 +1311,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. @@ -1336,13 +1343,37 @@ for more information. - env.Dump([key]) + env.Dump([key], [format]) -Returns a pretty printable representation of the environment. -key, -if not -None, -should be a string containing the name of the variable of interest. +Serializes construction variables to a string. +The method supports the following formats specified by +format: + + +pretty + + +Returns a pretty printed representation of the environment (if +format +is not specified, this is the default). + + + + +json + + +Returns a JSON-formatted string representation of the environment. + + + + + +If key is +None (the default) the entire +dictionary of construction variables is serialized. +If supplied, it is taken as the name of a construction variable +whose value is serialized. @@ -1438,7 +1469,7 @@ EnsureSConsVersion(0,96,90) Return a new construction environment initialized with the specified -key=value +key=value pairs. @@ -1449,16 +1480,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 Execute +(strfunction, varlist) +are passed on to the 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. @@ -1468,7 +1503,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 @@ -1477,7 +1512,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 Execute @@ -1572,24 +1607,24 @@ See the description below. 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. @@ -1608,10 +1643,10 @@ for more information. env.FindFile(file, dirs) 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 @@ -1729,9 +1764,9 @@ scanner = Scanner(name = 'myscanner', 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. @@ -1797,7 +1832,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)) @@ -1931,10 +1966,10 @@ atexit.register(print_build_failures) Returns the scons path name (or names) for the specified -file +file (or files). The specified -file +file or files may be scons @@ -2233,21 +2268,20 @@ option. env.Glob(pattern, [ondisk, source, strings, exclude]) 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 (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: @@ -2281,14 +2315,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, @@ -2301,7 +2335,7 @@ for any on-disk matches found. The -source +source argument may be set to a value which evaluates True to specify that, @@ -2314,7 +2348,7 @@ not the local directory. The -strings +strings argument may be set to a value which evaluates True to have the @@ -2340,7 +2374,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. @@ -2364,22 +2398,24 @@ sources = Glob("*.cpp", exclude=["os_*_specific_*.cpp"]) + \ Help(text, append=False) env.Help(text, append=False) -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 -Help -is called multiple times, the text is appended together in the order that -Help -is called. With append set to False, any +Subsequent calls to Help -text generated with -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 Help only, +if append is False +(the default) +any local help message generated through +AddOption calls is replaced. +If append is True, +text is appended to +the existing help text. @@ -2458,7 +2494,7 @@ Import("*") env.Literal(string) The specified -string +string will be preserved as-is and not have construction variables expanded. @@ -2469,7 +2505,7 @@ and not have construction variables expanded. env.Local(targets) The specified -targets +targets will have copies made in the local tree, even if an already up-to-date copy exists in a repository. @@ -2481,17 +2517,17 @@ Returns a list of the target Node or Nodes. env.MergeFlags(arg, [unique]) 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 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, @@ -2633,11 +2669,11 @@ NoClean(env.Program('hello', 'hello.c')) env.ParseConfig(command, [function, unique]) Calls the specified -function +function to modify the environment as specified by the output of -command. +command. The default -function +function is env.MergeFlags, which expects the output of a typical @@ -2672,7 +2708,7 @@ for a table of options and construction variables. env.ParseDepends(filename, [must_exist, only_one]) Parses the contents of the specified -filename +filename as a list of dependencies in the style of Make or @@ -2684,10 +2720,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 @@ -2698,7 +2734,7 @@ or is otherwise inaccessible. The optional -only_one +only_one argument may be set to a non-zero value to have scons @@ -2720,7 +2756,7 @@ file. The -filename +filename and all of the files listed therein will be interpreted relative to the directory of the @@ -2841,7 +2877,7 @@ env = Environment(platform = Platform('win32')) The env.Platform form applies the callable object for the specified platform -string +string to the environment through which the method was called. @@ -2932,7 +2968,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. @@ -2999,22 +3035,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.) @@ -3025,7 +3060,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) @@ -3043,8 +3078,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 @@ -3054,18 +3088,28 @@ Progress(ProgressCounter(), interval=100) -If the first argument -Progress -is a string, -the string will be displayed -every +If the first argument to +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: @@ -3078,7 +3122,7 @@ Progress('.', interval=100, file=sys.stderr) If the string contains the verbatim substring -$TARGET, +$TARGET;, it will be replaced with the Node. Note that, for performance reasons, this is not @@ -3087,12 +3131,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: @@ -3102,15 +3147,9 @@ Progress('$TARGET\r', overwrite=True) -If the first argument to -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: @@ -3142,16 +3181,16 @@ Multiple targets can be passed in to a single call to 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. @@ -3176,7 +3215,7 @@ env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx') env.Repository(directory) Specifies that -directory +directory is a repository to be searched for files. Multiple calls to Repository @@ -3307,7 +3346,7 @@ Return('val1 val2') Creates a Scanner object for the specified -function. +function. See manpage section "Scanner Objects" for a complete explanation of the arguments and behavior. @@ -3604,18 +3643,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 @@ -3624,9 +3663,9 @@ file. If -file +file is -None, +None, then scons will store file signatures @@ -3640,7 +3679,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 @@ -3817,13 +3856,13 @@ SetOption('max_drift', 1) env.SideEffect(side_effect, target) 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. @@ -3845,23 +3884,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 @@ -3877,13 +3916,13 @@ function. env.Split(arg) 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. @@ -3908,7 +3947,7 @@ files = Split(""" Performs construction variable interpolation on the specified string or sequence argument -input. +input. @@ -3923,14 +3962,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 @@ -3953,9 +3992,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, @@ -3977,7 +4016,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 @@ -4076,7 +4115,7 @@ as part of the tools keyword argument, or it can be called directly, passing a construction environment to update as the argument. Either approach will also update the -TOOLS construction variable. +$TOOLS construction variable. @@ -4101,17 +4140,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. @@ -4121,7 +4160,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 @@ -4178,11 +4217,11 @@ Use the 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. @@ -4191,15 +4230,15 @@ within the variant tree. 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. - &SetOption; is not currently supported for - options added with &AddOption;. @@ -634,15 +667,17 @@ foo.in -AddOption('--prefix', - dest='prefix', - type='string', - nargs=1, - action='store', - metavar='DIR', - help='installation prefix') +AddOption( + '--prefix', + dest='prefix', + type='string', + nargs=1, + action='store', + metavar='DIR', + help='installation prefix', +) -env = Environment(PREFIX = GetOption('prefix')) +env = Environment(PREFIX=GetOption('prefix')) installed_foo = env.Install('$PREFIX/usr/bin', 'foo.in') Default(installed_foo) @@ -655,14 +690,14 @@ foo.in The above code uses the &GetOption; function - to set the $PREFIX + to set the $PREFIX construction variable to any value that the user specifies with a command-line - option of --prefix. - Because $PREFIX + option of . + Because $PREFIX will expand to a null string if it's not initialized, running &SCons; without the - option of --prefix + option of will install the file in the /usr/bin/ directory: @@ -674,7 +709,7 @@ foo.in - But specifying --prefix=/tmp/install + But specifying on the command line causes the file to be installed in the /tmp/install/usr/bin/ directory: @@ -688,13 +723,13 @@ foo.in Option-arguments separated from long options by whitespace, rather than by an =, cannot be correctly - resolved by scons. - While --input=ARG - is clearly opt followed by arg, for --input ARG + resolved by &SCons;. + While + is clearly opt followed by arg, for it is not possible to tell without instructions whether ARG is an argument belonging to the input option or a positional argument. - scons treats positional arguments as either + &SCons; treats positional arguments as either command-line build options or command-line targets which are made available for use in an &SConscript; (see the immediately following sections for details). @@ -702,21 +737,21 @@ foo.in takes place. Since &AddOption; calls, which provide the processing instructions to resolve any ambiguity, happen in an &SConscript;, - scons does not know in time + &SCons; does not know in time for options added this way, and unexpected things will happen, such as option-arguments assigned as targets and/or exceptions due to missing option-arguments. As a result, this usage style should be avoided when invoking - scons. For single-argument - options, use the --input=ARG form on the + &scons;. For single-argument + options, use the form on the command line. For multiple-argument options (nargs greater than one), set nargs to one in &AddOption; calls and either: combine the option-arguments into one word with a separator, and parse the result in your own code - (see the built-in --debug option, which + (see the built-in option, which allows specifying multiple arguments as a single comma-separated word, for an example of such usage); or allow the option to be specified multiple times by setting @@ -730,13 +765,13 @@ foo.in
- Command-Line <varname>variable</varname>=<varname>value</varname> Build Variables + Command-Line <varname>variable</varname>=<replaceable>value</replaceable> Build Variables You may want to control various aspects of your build by allowing the user - to specify variable=value + to specify variable=value values on the command line. For example, suppose you want users to be able to @@ -753,7 +788,7 @@ foo.in &SCons; provides an &ARGUMENTS; dictionary that stores all of the - variable=value + variable=value assignments from the command line. This allows you to modify aspects of your build in response @@ -762,8 +797,7 @@ foo.in that users always specify a variable, you probably want to use - the Python - ARGUMENTS.get() function, + the Python dictionary get method, which allows you to specify a default value to be used if there is no specification on the command line.) @@ -845,7 +879,7 @@ prog.c To accomodate these requirements, &SCons; provides an &ARGLIST; variable that gives you direct access to - variable=value + variable=value settings on the command line, in the exact order they were specified, and without removing any duplicate settings. @@ -898,7 +932,7 @@ prog.c variables do not interfere with each other, but merely provide slightly different views into how the user specified - variable=value + variable=value settings on the command line. You can use both variables in the same &SCons; configuration. @@ -1056,7 +1090,7 @@ Help(vars.GenerateHelpText(env)) &SCons; will now display some useful text - when the -h option is used: + when the option is used: @@ -2292,7 +2326,7 @@ prog1.c &DEFAULT_TARGETS; list takes place during the first phase when &SCons; is reading up the &SConscript; files, which is obvious if - we leave off the -Q flag when we run &SCons;:) + we leave off the flag when we run &SCons;:) -- cgit v0.12 From c47ec6035ba472880ff3a9aead3a82baae3004c4 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Wed, 3 Jun 2020 06:23:35 -0600 Subject: [PR #3682] drop one more env var $ introducer [ci skip] Signed-off-by: Mats Wichmann --- doc/user/command-line.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/user/command-line.xml b/doc/user/command-line.xml index 9114273..c230fea 100644 --- a/doc/user/command-line.xml +++ b/doc/user/command-line.xml @@ -342,7 +342,7 @@ foo.in The above snippet of code sets the value of the option to the value specified in the - $NUM_CPU environment variable. + NUM_CPU environment variable. (This is one of the exception cases where the string is spelled differently from the from command-line option. -- cgit v0.12