From 56597a6a68e741355b301f91d5913d59cfb34eaa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Frings-F=C3=BCrst?= Date: Sat, 28 Dec 2019 17:12:41 +0100 Subject: New upstream version 3.1.2 --- doc/generated/functions.gen | 489 +++++++++++++------------------------------- 1 file changed, 140 insertions(+), 349 deletions(-) (limited to 'doc/generated/functions.gen') diff --git a/doc/generated/functions.gen b/doc/generated/functions.gen index 9bed358..d71387e 100644 --- a/doc/generated/functions.gen +++ b/doc/generated/functions.gen @@ -25,8 +25,8 @@ Creates an Action object for the specified action. -See the section "Action Objects," -below, for a complete explanation of the arguments and behavior. +See the manpage section "Action Objects" +for a complete explanation of the arguments and behavior. @@ -121,11 +121,11 @@ env.other_method_name('another arg') This function adds a new command-line option to be recognized. The specified arguments -are the same as supported by the standard Python -optparse.add_option() -method (with a few additional capabilities noted below); +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 -optparse +optparse for a thorough discussion of its option-processing capabities. @@ -165,6 +165,15 @@ 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, +include them in the AddOption call. + + Once a new command-line option has been added with AddOption, @@ -172,17 +181,21 @@ the option value may be accessed using GetOption or env.GetOption(). + +SetOption is not currently supported for +options added with AddOption. @@ -221,6 +234,22 @@ AddOption('--prefix', help='installation prefix') env = Environment(PREFIX = GetOption('prefix')) + + + +While AddOption behaves like +add_option, +from the optparse module, +the behavior of options added by AddOption +which take arguments is underfined in +scons 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. + + + @@ -241,7 +270,8 @@ has been built. The specified action(s) may be an Action object, or anything that can be converted into an Action object -(see below). +See the manpage section "Action Objects" +for a complete explanation. @@ -270,7 +300,8 @@ is built. The specified action(s) may be an Action object, or anything that can be converted into an Action object -(see below). +See the manpage section "Action Objects" +for a complete explanation. @@ -444,7 +475,7 @@ Otherwise, the construction variable and the value of the keyword argument are both coerced to lists, and the lists are added together. -(See also the Prepend method, below.) +(See also the Prepend method). @@ -530,30 +561,6 @@ Example: env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy']) - - - - - BuildDir(build_dir, src_dir, [duplicate]) - - - env.BuildDir(build_dir, src_dir, [duplicate]) - - - -Deprecated synonyms for -VariantDir -and -env.VariantDir(). -The -build_dir -argument becomes the -variant_dir -argument of -VariantDir -or -env.VariantDir(). - @@ -568,8 +575,8 @@ or Creates a Builder object for the specified action. -See the section "Builder Objects," -below, for a complete explanation of the arguments and behavior. +See the manpage section "Builder Objects" +for a complete explanation of the arguments and behavior. @@ -849,19 +856,29 @@ for a single special-case build. -As a special case, the -source_scanner -keyword argument can +Command builder accepts +source_scanner, +target_scanner, +source_factory, and +target_factory +keyword arguments. The *_scanner args can be used to specify a Scanner object -that will be used to scan the sources. -(The global +that will be used to apply a custom +scanner for a source or target. +For example, the global DirScanner object can be used 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.) +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 +specified as strings into SCons Nodes. +See the sections "Builder Objects" +below, for more information about how these +args work in a Builder. @@ -873,7 +890,7 @@ same-named existing construction variables. An action can be an external command, specified as a string, or a callable Python object; -see "Action Objects," below, +see the manpage section "Action Objects" for more complete information. Also note that a string specifying an external command may be preceded by an @@ -897,7 +914,7 @@ env.Command('foo.out', 'foo.in', env.Command('bar.out', 'bar.in', ["rm -f $TARGET", "$BAR_BUILD < $SOURCES > $TARGET"], - ENV = {'PATH' : '/usr/local/bin/'}) + ENV={'PATH': '/usr/local/bin/'}) def rename(env, target, source): import os @@ -905,7 +922,7 @@ def rename(env, target, source): env.Command('baz.out', 'baz.in', ["$BAZ_BUILD < $SOURCES > .tmp", - rename ]) + rename]) @@ -914,14 +931,14 @@ Note that the function will usually assume, by default, that the specified targets and/or sources are Files, if no other part of the configuration -identifies what type of entry it is. +identifies what type of entries they are. If necessary, you can explicitly specify that targets or source nodes should -be treated as directoriese +be treated as directories by using the Dir or -env.Dir() +env.Dir functions. @@ -937,9 +954,9 @@ env.Command(env.Dir('$DISTDIR')), None, make_distdir) -(Also note that SCons will usually +Also note that SCons will usually automatically create any directory necessary to hold a target file, -so you normally don't need to create directories by hand.) +so you normally don't need to create directories by hand. @@ -954,8 +971,8 @@ so you normally don't need to create directories by hand.) Creates a Configure object for integrated functionality similar to GNU autoconf. -See the section "Configure Contexts," -below, for a complete explanation of the arguments and behavior. +See the manpage section "Configure Contexts" +for a complete explanation of the arguments and behavior. @@ -1262,15 +1279,21 @@ see below. - DefaultEnvironment([args]) + DefaultEnvironment([**kwargs]) -Creates and returns a default construction environment object. -This construction environment is used internally by SCons -in order to execute many of the global functions in this list, -and to fetch source files transparently +Creates and returns the default construction environment object. +The default construction 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 +arguments affect it only on the first call, on subsequent +calls the already-constructed object is returned. +The default environment can be modified in the same way +as any construction environment. @@ -1333,11 +1356,11 @@ env.Depends(bar, installed_lib) Returns a dictionary object -containing copies of all of the -construction variables in the environment. -If there are any variable names specified, -only the specified construction -variables are returned in the dictionary. +containing the construction variables in the construction environment. +If there are any arguments specified, +the values of the specified construction variables +are returned as a string (if one +argument) or as a list of strings. @@ -1345,8 +1368,8 @@ Example: -dict = env.Dictionary() -cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM') +cvars = env.Dictionary() +cc_values = env.Dictionary('CC', 'CCFLAGS', 'CCCOM') @@ -1385,7 +1408,8 @@ would supply a string as a directory name to a Builder method or function. Directory Nodes have attributes and methods that are useful in many situations; -see "File and Directory Nodes," below. +see manpage section "File and Directory Nodes" +for more information. @@ -1408,7 +1432,7 @@ This SConstruct: env=Environment() -print env.Dump('CCCOM') +print(env.Dump('CCCOM')) @@ -1425,7 +1449,7 @@ While this SConstruct: env=Environment() -print env.Dump() +print(env.Dump()) @@ -1528,8 +1552,8 @@ Executes an Action object. The specified action may be an Action object -(see the section "Action Objects," -below, for a complete explanation of the arguments and behavior), +(see manpage section "Action Objects" +for a complete explanation of the arguments and behavior), or it may be a command-line string, list of commands, or executable Python function, @@ -1686,7 +1710,8 @@ would supply a string as a file name to a Builder method or function. File Nodes have attributes and methods that are useful in many situations; -see "File and Directory Nodes," below. +see manpage section "File and Directory Nodes" +for more information. @@ -2836,7 +2861,7 @@ and the construction variables they affect are as specified for the env.ParseFlags method (which this method calls). -See that method's description, below, +See that method's description for a table of options and construction variables. @@ -2955,6 +2980,7 @@ and added to the following construction variables: -fmerge-all-constants CCFLAGS, LINKFLAGS -fopenmp CCFLAGS, LINKFLAGS -include CCFLAGS +-imacros CCFLAGS -isysroot CCFLAGS, LINKFLAGS -isystem CCFLAGS -iquote CCFLAGS @@ -3539,8 +3565,8 @@ Return('val1 val2') Creates a Scanner object for the specified function. -See the section "Scanner Objects," -below, for a complete explanation of the arguments and behavior. +See manpage section "Scanner Objects" +for a complete explanation of the arguments and behavior. @@ -4227,107 +4253,6 @@ env.SourceCode('no_source.c', None) - - - - - SourceSignatures(type) - - - env.SourceSignatures(type) - - - -Note: Although it is not yet officially deprecated, -use of this function is discouraged. -See the -Decider -function for a more flexible and straightforward way -to configure SCons' decision-making. - - - -The -SourceSignatures -function tells -scons -how to decide if a source file -(a file that is not built from any other files) -has changed since the last time it -was used to build a particular target file. -Legal values are -MD5 -or -timestamp. - - - -If the environment method is used, -the specified type of source signature -is only used when deciding whether targets -built with that environment are up-to-date or must be rebuilt. -If the global function is used, -the specified type of source signature becomes the default -used for all decisions -about whether targets are up-to-date. - - - -MD5 -means -scons -decides that a source file has changed -if the MD5 checksum of its contents has changed since -the last time it was used to rebuild a particular target file. - - - -timestamp -means -scons -decides that a source file has changed -if its timestamp (modification time) has changed since -the last time it was used to rebuild a particular target file. -(Note that although this is similar to the behavior of Make, -by default it will also rebuild if the dependency is -older -than the last time it was used to rebuild the target file.) - - - -There is no different between the two behaviors -for Python -Value -node objects. - - - -MD5 -signatures take longer to compute, -but are more accurate than -timestamp -signatures. -The default value is -MD5. - - - -Note that the default -TargetSignatures -setting (see below) -is to use this -SourceSignatures -setting for any target files that are used -to build other target files. -Consequently, changing the value of -SourceSignatures -will, by default, -affect the up-to-date decision for all files in the build -(or all files built with a specific construction environment -when -env.SourceSignatures -is used). - @@ -4462,7 +4387,7 @@ Example: -print env.subst("The C compiler is: $CC") +print(env.subst("The C compiler is: $CC")) def compile(target, source, env): sourceDir = env.subst("${SOURCE.srcdir}", @@ -4492,168 +4417,13 @@ Examples: -# makes sure the built library will be installed with 0644 file +# makes sure the built library will be installed with 0o644 file # access mode -Tag( Library( 'lib.c' ), UNIX_ATTR="0644" ) +Tag( Library( 'lib.c' ), UNIX_ATTR="0o644" ) # marks file2.txt to be a documentation file Tag( 'file2.txt', DOC ) - - - - - TargetSignatures(type) - - - env.TargetSignatures(type) - - - -Note: Although it is not yet officially deprecated, -use of this function is discouraged. -See the -Decider -function for a more flexible and straightforward way -to configure SCons' decision-making. - - - -The -TargetSignatures -function tells -scons -how to decide if a target file -(a file that -is -built from any other files) -has changed since the last time it -was used to build some other target file. -Legal values are -"build"; -"content" -(or its synonym -"MD5"); -"timestamp"; -or -"source". - - - -If the environment method is used, -the specified type of target signature is only used -for targets built with that environment. -If the global function is used, -the specified type of signature becomes the default -used for all target files that -don't have an explicit target signature type -specified for their environments. - - - -"content" -(or its synonym -"MD5") -means -scons -decides that a target file has changed -if the MD5 checksum of its contents has changed since -the last time it was used to rebuild some other target file. -This means -scons -will open up -MD5 sum the contents -of target files after they're built, -and may decide that it does not need to rebuild -"downstream" target files if a file was -rebuilt with exactly the same contents as the last time. - - - -"timestamp" -means -scons -decides that a target file has changed -if its timestamp (modification time) has changed since -the last time it was used to rebuild some other target file. -(Note that although this is similar to the behavior of Make, -by default it will also rebuild if the dependency is -older -than the last time it was used to rebuild the target file.) - - - -"source" -means -scons -decides that a target file has changed -as specified by the corresponding -SourceSignatures -setting -("MD5" -or -"timestamp"). -This means that -scons -will treat all input files to a target the same way, -regardless of whether they are source files -or have been built from other files. - - - -"build" -means -scons -decides that a target file has changed -if it has been rebuilt in this invocation -or if its content or timestamp have changed -as specified by the corresponding -SourceSignatures -setting. -This "propagates" the status of a rebuilt file -so that other "downstream" target files -will always be rebuilt, -even if the contents or the timestamp -have not changed. - - - -"build" -signatures are fastest because -"content" -(or -"MD5") -signatures take longer to compute, -but are more accurate than -"timestamp" -signatures, -and can prevent unnecessary "downstream" rebuilds -when a target file is rebuilt to the exact same contents -as the previous build. -The -"source" -setting provides the most consistent behavior -when other target files may be rebuilt from -both source and target input files. -The default value is -"source". - - - -Because the default setting is -"source", -using -SourceSignatures -is generally preferable to -TargetSignatures, -so that the up-to-date decision -will be consistent for all files -(or all files built with a specific construction environment). -Use of -TargetSignatures -provides specific control for how built target files -affect their "downstream" dependencies. - @@ -4949,30 +4719,51 @@ SConscript(dirs='doc', variant_dir='build/doc', duplicate=0) Searches for the specified executable program, returning the full path name to the program -if it is found, -and returning None if not. -Searches the specified -path, -the value of the calling environment's PATH -(env['ENV']['PATH']), -or the user's current external PATH -(os.environ['PATH']) -by default. +if it is found, else None. +Searches the value of the +path keyword argument, +or if None (the default) +the value of the calling environment's PATH +(env['ENV']['PATH']). +If path is None and +the env['ENV']['PATH'] key does not exist, +the user's current external PATH +(os.environ['PATH']) is used as fallback. + + On Windows systems, searches for executable -programs with any of the file extensions -listed in the specified -pathext, -the calling environment's PATHEXT -(env['ENV']['PATHEXT']) -or the user's current PATHEXT +programs with any of the file extensions listed in the +pathext keyword argument, +or if None (the default) +the calling environment's PATHEXT +(env['ENV']['PATHEXT']). +The user's current external PATHEXT (os.environ['PATHEXT']) -by default. +is used as a fallback if pathext is +None +and the key env['ENV']['PATHEXT'] +does not exist. + + Will not select any path name or names in the specified reject list, if any. + + +If you would prefer to search +the user's current external PATH +(os.environ['PATH']) +by default, +consider using the function SCons.Util.WhereIs instead. +Note that SCons.Util.WhereIs +does not expand environment variables automatically +(no implicit env.subst for its arguments). + + + -- cgit v1.2.3