From 56337453f0f3fbe34255e636d5d65974f4d17681 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Frings-F=C3=BCrst?= Date: Mon, 7 Oct 2019 17:50:28 +0200 Subject: New upstream version 3.1.1 --- doc/man/scons-time.xml | 4 ++-- doc/man/scons.xml | 4 ++-- doc/man/sconsign.xml | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) (limited to 'doc/man') diff --git a/doc/man/scons-time.xml b/doc/man/scons-time.xml index 7251c9f..2632e41 100644 --- a/doc/man/scons-time.xml +++ b/doc/man/scons-time.xml @@ -32,8 +32,8 @@ SCONS-TIME 1 -SCons 3.1.0 -SCons 3.1.0 +SCons 3.1.1 +SCons 3.1.1 scons-time diff --git a/doc/man/scons.xml b/doc/man/scons.xml index dd9fbdd..87344cc 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -75,8 +75,8 @@ SCONS 1 -SCons 3.1.0 -SCons 3.1.0 +SCons 3.1.1 +SCons 3.1.1 scons diff --git a/doc/man/sconsign.xml b/doc/man/sconsign.xml index f70bb62..daaa260 100644 --- a/doc/man/sconsign.xml +++ b/doc/man/sconsign.xml @@ -32,8 +32,8 @@ SCONSIGN 1 -SCons 3.1.0 -SCons 3.1.0 +SCons 3.1.1 +SCons 3.1.1 sconsign -- cgit v1.2.3 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/man/scons-time.xml | 57 +--- doc/man/scons.xml | 699 +++++++++++++++++++++++++++---------------------- doc/man/sconsign.xml | 4 +- 3 files changed, 395 insertions(+), 365 deletions(-) (limited to 'doc/man') diff --git a/doc/man/scons-time.xml b/doc/man/scons-time.xml index 2632e41..b973dba 100644 --- a/doc/man/scons-time.xml +++ b/doc/man/scons-time.xml @@ -32,8 +32,8 @@ SCONS-TIME 1 -SCons 3.1.1 -SCons 3.1.1 +SCons 3.1.2 +SCons 3.1.2 scons-time @@ -53,7 +53,6 @@ Generating Timing Information scons-time run [] -[PROJECT] [FILE] [NUMBER] [OUTDIR] @@ -644,7 +643,6 @@ files. The run Subcommand scons-time run [] -[PROJECT] [FILE] [NUMBER] [OUTDIR] @@ -727,31 +725,6 @@ this should be an up-to-date, "do nothing" rebuild. scons-time run subcommand supports the following options: - - --aegis=PROJECT - -Specifies the Aegis -PROJECT -from which the -version(s) of -scons -being timed will be extracted. -When - -is specified, the -NUMBER -option specifies delta numbers -that will be tested. -Output from each invocation run will be placed in file -names that match the Aegis delta numbers. -If the - -option is not specified, -then the default behavior is to time the -tip of the specified -PROJECT. - - -f FILE, --file=FILE @@ -798,14 +771,6 @@ the log files and profile outputs generated by this run. -When used in conjunction with the -PROJECT -option, -NUMBER -specifies one or more comma-separated Aegis delta numbers -that will be retrieved automatically from the specified Aegis -PROJECT. - When used in conjunction with the URL option, @@ -1056,24 +1021,6 @@ and provides a handy way to "shrink-wrap" the necessary information for producing (and reporting) consistent timing runs for a given configuration. - - aegis - -The Aegis executable for extracting deltas. -The default is simply -aegis. - - - - aegis_project - -The Aegis project from which deltas should be extracted. -The default is whatever is specified -with the - -command-line option. - - archive_list diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 87344cc..20e9d84 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -75,8 +75,8 @@ SCONS 1 -SCons 3.1.1 -SCons 3.1.1 +SCons 3.1.2 +SCons 3.1.2 scons @@ -209,12 +209,12 @@ that you want to use to build your target files are not in standard system locations, scons will not find them unless -you explicitly set the PATH +you explicitly set the PATH to include those locations. Whenever you create an scons construction environment, -you can propagate the value of PATH +you can propagate the value of PATH from your external environment as follows: @@ -223,13 +223,20 @@ env = Environment(ENV = {'PATH' : os.environ['PATH']}) Similarly, if the commands use external environment variables -like $PATH, $HOME, $JAVA_HOME, $LANG, $SHELL, $TERM, etc., +like +PATH, +HOME, +JAVA_HOME, +LANG, +SHELL, +TERM, +etc., these variables can also be explicitly propagated: import os -env = Environment(ENV = {'PATH' : os.environ['PATH'], - 'HOME' : os.environ['HOME']}) +env = Environment(ENV = {'PATH': os.environ['PATH'], + 'HOME': os.environ['HOME']}) Or you may explicitly propagate the invoking user's @@ -679,19 +686,32 @@ option except for the way default targets are handled. When this option is used and no targets are specified on the command line, all default targets are built, whether or not they are below the current directory. - + - --debug=type + --debug=type[,type...] Debug the build process. -type[,type...] -specifies what type of debugging. Multiple types may be specified, -separated by commas. The following types are valid: +type +specifies the kind of debugging info to emit. +Multiple types may be specified, separated by commas. +The following entries show the recognized types: + + + + --debug=action-timestamps + +Prints additional time profiling information. For +each command, shows the absolute start and end times. +This may be useful in debugging parallel builds. +Implies the option. + +Since &scons; 3.1. + --debug=count @@ -717,17 +737,6 @@ files). its source file. Includes debugging info for unlinking stale variant files, as well as unlinking old targets before building them. - - - - --debug=dtree - -A synonym for the newer - -option. -This will be deprecated in some future release -and ultimately removed. - @@ -783,13 +792,6 @@ instead of recomputing them each time they're needed. before and after reading the SConscript files and before and after building targets. - - - - --debug=nomemoizer - -A deprecated option preserved for backwards compatibility. - @@ -846,17 +848,6 @@ Building myprog.o with action(s): Prints an internal Python stack trace when encountering an otherwise unexplained error. - - - - --debug=stree - -A synonym for the newer - -option. -This will be deprecated in some future release -and ultimately removed. - @@ -912,20 +903,9 @@ since multiple build commands and intervening SCons processing should take place in parallel.) - - - --debug=tree - -A synonym for the newer - -option. -This will be deprecated in some future release -and ultimately removed. - - --diskcheck=types @@ -1113,6 +1093,18 @@ This implies + + + --install-sandbox=path + + +When using the &Install; functions, prepend path +to the installation paths such that all installed files will be placed +underneath path. + + + + --interactive @@ -1803,41 +1795,6 @@ Warnings for some specific deprecated features may be enabled or disabled individually; see below. -
- - - --warn=deprecated-copy, --warn=no-deprecated-copy - -Enables or disables warnings about use of the deprecated -env.Copy() -method. - - - - - --warn=deprecated-source-signatures, --warn=no-deprecated-source-signatures - -Enables or disables warnings about use of the deprecated -SourceSignatures() -function or -env.SourceSignatures() -method. - - - - - --warn=deprecated-target-signatures, --warn=no-deprecated-target-signatures - -Enables or disables warnings about use of the deprecated -TargetSignatures() -function or -env.TargetSignatures() -method. - - - -
- @@ -1914,7 +1871,7 @@ These warnings are enabled by default. feature not working when scons -is run with the python +is run with the Python option or from optimized Python (.pyo) modules. @@ -2041,7 +1998,7 @@ env['BAR'] = 'bar' As a convenience, construction variables may also be set or modified by the -parse_flags +parse_flags keyword argument, which applies the &f-link-env-MergeFlags; method (described below) to the argument value @@ -2112,36 +2069,59 @@ env = Environment(platform = my_platform) Additionally, a specific set of tools with which to initialize the environment -may be specified as an optional keyword argument: +may be specified using the optional keyword argument +tools: -env = Environment(tools = ['msvc', 'lex']) +env = Environment(tools=['msvc', 'lex']) -Non-built-in tools may be specified using the toolpath argument: + +The tools argument overrides +the tool list, it does not add to it, so be +sure to include all the tools you need. +For example if you are building a c/c++ program +you must add a tool for both compiler and linker, +as in tools=['clang', 'link']. +The tool name 'default' can +be used to retain the default list. + + +Non-built-in tools may be specified using the +optional toolpath keyword argument: -env = Environment(tools = ['default', 'foo'], toolpath = ['tools']) +env = Environment(tools=['default', 'foo'], toolpath=['tools']) -This looks for a tool specification in tools/foo.py (as well as -using the ordinary default tools for the platform). foo.py should -have two functions: generate(env, **kw) and exists(env). + +This looks for a tool specification in tools/foo.py +as well as using the ordinary default tools for the platform. + + + +A tool specification must include two functions: +generate(env, **kw) +and exists(env). The -generate() +generate function -modifies the passed-in environment +modifies the environment referenced by env to set up variables so that the tool can be executed; it may use any keyword arguments -that the user supplies (see below) +that the user supplies in kw (see below) to vary its initialization. The -exists() +exists function should return a true value if the tool is available. + + + Tools in the toolpath are used before -any of the built-in ones. For example, adding gcc.py to the toolpath +any of the built-in ones. For example, adding +gcc.py to the toolpath would override the built-in gcc tool. Also note that the toolpath is stored in the environment for use @@ -2149,7 +2129,8 @@ by later calls to Clone() and Tool() -methods: +methods: + base = Environment(toolpath=['custom_path']) @@ -2192,11 +2173,12 @@ or otherwise changing its initialization. def generate(env, **kw): # Sets MY_TOOL to the value of keyword argument 'arg1' or 1. env['MY_TOOL'] = kw.get('arg1', '1') + def exists(env): - return 1 + return True # in SConstruct: -env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})], +env = Environment(tools=['default', ('my_tool', {'arg1': 'abc'})], toolpath=['tools']) @@ -2215,7 +2197,7 @@ With a nested tool name the dot represents a directory seperator # namespaced builder -env = Environment(ENV = os.environ, tools = ['SubDir1.SubDir2.SomeTool']) +env = Environment(ENV=os.environ, tools=['SubDir1.SubDir2.SomeTool']) env.SomeTool(targets, sources) # Search Paths @@ -2257,90 +2239,108 @@ env.SomeTool(targets, sources) -Additionally, there is a "tool" named -default -which configures the -environment with a default set of tools for the current platform. - -On posix and cygwin platforms -the GNU tools (e.g. gcc) are preferred by SCons, -on Windows the Microsoft tools (e.g. msvc) -followed by MinGW are preferred by SCons, -and in OS/2 the IBM tools (e.g. icc) are preferred by SCons. - Builder Methods -Build rules are specified by calling a construction -environment's builder methods. -The arguments to the builder methods are -target -(a list of targets to be built, -usually file names) +You tell scons what to build +by calling Builders, functions which know to take a +particular action when given files of a particular type +to produce a particular result type. scons +defines a number of builders, and you can also write your own. +Builders are attached to a &consenv; as methods, +and the available builder methods are listed as +key-value pairs in the +BUILDERS attribute of the &consenv;. +The available builders can be displayed like this +for debugging purposes: + + + +print("Builders:", list(env['BUILDERS'])) + + + +Builder methods always take two arguments: +target +(a target or a list of targets to be built) and -source -(a list of sources to be built, -usually file names). +source +(a source or list of sources to be used as input +when building), +although in some circumstances, +the target argument can actually be omitted (see below). +Builder methods also take a variety of +keyword arguments, described below. + Because long lists of file names can lead to a lot of quoting, scons -supplies a -Split() +supplies a &Split; global function and a same-named environment method that split a single string into a list, separated on strings of white-space characters. -(These are similar to the split() member function of Python strings -but work even if the input isn't a string.) +(These are similar to the Python string split +method, but work even if the input isn't a string.) -Like all Python arguments, -the target and source arguments to a builder method -can be specified either with or without -the "target" and "source" keywords. -When the keywords are omitted, -the target is first, -followed by the source. -The following are equivalent examples of calling the Program builder method: + +The target and source arguments to a builder method +can be specified either as positional arguments, +in which case the target comes first, or as +keyword arguments, using target= +and source=. +The following are equivalent examples of calling the +&Program; builder method: + env.Program('bar', ['bar.c', 'foo.c']) env.Program('bar', Split('bar.c foo.c')) env.Program('bar', env.Split('bar.c foo.c')) -env.Program(source = ['bar.c', 'foo.c'], target = 'bar') -env.Program(target = 'bar', Split('bar.c foo.c')) -env.Program(target = 'bar', env.Split('bar.c foo.c')) -env.Program('bar', source = 'bar.c foo.c'.split()) +env.Program(source=['bar.c', 'foo.c'], target='bar') +env.Program(target='bar', source=Split('bar.c foo.c')) +env.Program(target='bar', source=env.Split('bar.c foo.c')) +env.Program('bar', source='bar.c foo.c'.split()) -Target and source file names -that are not absolute path names -(that is, do not begin with -/ -on POSIX systems -or -\ -on Windows systems, -with or without -an optional drive letter) -are interpreted relative to the directory containing the -SConscript -file being read. -An initial -# -(hash mark) -on a path name means that the rest of the file name -is interpreted relative to -the directory containing -the top-level -SConstruct -file, -even if the -# -is followed by a directory separator character -(slash or backslash). + +Python follows the POSIX pathname convention for path +strings: if a string begins with the operating system pathname separator +(on Windows both the slash and backslash separator work, +and any leading drive specifier is ignored for +the determination) it is considered an absolute path, +otherwise it is a relative path. +If the path string contains no separator characters, +it is searched for as a file in the current directory. If it +contains separator characters, the search follows down +from the starting point, which is the top of the directory tree for +an absolute path and the current directory for a relative path. + + +scons recognizes a third way to specify +path strings: if the string begins with +the # character it is +top-relative - it works like a relative path but the +search follows down from the directory containing the top-level +SConstruct rather than +from the current directory (the # is allowed +to be followed by a pathname separator, which is ignored if +found in that position). +Top-relative paths only work in places where &scons; will +interpret the path (see some examples below). To be +used in other contexts the string will need to be converted +to a relative or absolute path first. + + + +Target and source pathnames can be absolute, relative, or +top-relative. Relative pathnames are searched considering the +directory of the SConscript +file currently being processed as the "current directory". + Examples: @@ -2382,12 +2382,12 @@ executable program or bar.exe (on Windows systems) -from the bar.c source file: +from the bar.c source file: -env.Program(target = 'bar', source = 'bar.c') -env.Program('bar', source = 'bar.c') -env.Program(source = 'bar.c') +env.Program(target='bar', source='bar.c') +env.Program('bar', source='bar.c') +env.Program(source='bar.c') env.Program('bar.c') @@ -2397,28 +2397,31 @@ keyword argument may be specified when calling a Builder. When specified, all source file strings that are not absolute paths +or top-relative paths will be interpreted relative to the specified srcdir. The following example will build the -build/prog +build/prog (or -build/prog.exe +build/prog.exe on Windows) program from the files -src/f1.c +src/f1.c and -src/f2.c: +src/f2.c: + env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src') -It is possible to override or add construction variables when calling a -builder method by passing additional keyword arguments. -These overridden or added -variables will only be in effect when building the target, so they will not -affect other parts of the build. For example, if you want to add additional -libraries for just one program: +It is possible to override (replace or add) +construction variables when calling a +builder method by passing them as keyword arguments. +These overrides +will only be in effect when building that target, and will not +affect other parts of the build. For example, if you want to specify +some libraries needed by just one program: env.Program('hello', 'hello.c', LIBS=['gl', 'glut']) @@ -2438,7 +2441,7 @@ for dependencies on the non-standard library names; see the descriptions of these variables, below, for more information.) It is also possible to use the -parse_flags +parse_flags keyword argument in an override, to merge command-line style arguments into the appropriate construction variables @@ -2483,8 +2486,7 @@ from SCons.Script import * All builder methods return a list-like object -containing Nodes that -represent the target or targets that will be built. +containing Nodes that will be built. A Node is an internal SCons object @@ -2496,9 +2498,8 @@ can be passed to other builder methods as source(s) or passed to any SCons function or method where a filename would normally be accepted. For example, if it were necessary -to add a specific - -flag when compiling one specific object file: +to add a specific preprocessor define +when compiling one specific object file: bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR') @@ -2509,14 +2510,14 @@ env.Program(source = ['foo.c', bar_obj_list, 'main.c']) makes for a more portable build by avoiding having to specify a platform-specific object suffix -when calling the Program() builder method. +when calling the &Program; builder method. -Note that Builder calls will automatically "flatten" +Note that builder calls will automatically "flatten" the source and target file lists, -so it's all right to have the bar_obj list -return by the StaticObject() call +so it's all right to have the bar_obj_list +returned by the &StaticObject; call in the middle of the source file list. -If you need to manipulate a list of lists returned by Builders +If you need to manipulate a list of lists returned by builders directly using Python, you can either build the list by hand: @@ -2528,8 +2529,7 @@ for object in objects: print(str(object)) -Or you can use the -Flatten() +Or you can use the &Flatten; function supplied by scons to create a list containing just the Nodes, which may be more convenient: @@ -2542,23 +2542,23 @@ for object in objects: print(str(object)) -Note also that because Builder calls return +Note also that because builder calls return a list-like object, not an actual Python list, you should not -use the Python -+= -operator to append Builder results to a Python list. +use the Python add +operator (+ or +=) +to append builder results to a Python list. Because the list and the object are different types, Python will not update the original list in place, but will instead create a new Node-list object containing the concatenation of the list -elements and the Builder results. +elements and the builder results. This will cause problems for any other Python variables in your SCons configuration that still hold on to a reference to the original list. -Instead, use the Python -.extend() +Instead, use the Python list +extend method to make sure the list is updated in-place. Example: @@ -2571,14 +2571,14 @@ object_files = [] # # It will not update the object_files list in place. # -# Instead, use the .extend() method: +# Instead, use the list extend method: object_files.extend(Object('bar.c')) The path name for a Node's file may be used -by passing the Node to the Python-builtin -str() +by passing the Node to Python's builtin +str function: @@ -2588,7 +2588,7 @@ print("The path to bar_obj is:", str(bar_obj_list[0])) Note again that because the Builder call returns a list, we have to access the first element in the list -(bar_obj_list[0]) +((bar_obj_list[0])) to get at the Node that actually represents the object file. @@ -2651,7 +2651,12 @@ to use just the filename portion of the targets and source. scons -provides the following builder methods: +predefined the following builder methods. +Depending on the setup of a particular +&consenv; and on the type and software +installation status of the underlying system, +not all builders may be available to that +&consenv;. @@ -3119,11 +3124,12 @@ defined construction variables: method of the construction environment: -dict = env.Dictionary() -dict["CC"] = "cc" +cvars = env.Dictionary() +cvars["CC"] = "cc" -or using the [] operator: +or using the key lookup operator [] +directly on the construction environment: env["CC"] = "cc" @@ -4387,7 +4393,7 @@ functions return and Dir Nodes, respectively. -python objects, respectively. +Python objects, respectively. Those objects have several user-visible attributes and methods that are often useful: @@ -4544,7 +4550,7 @@ incl = Dir('include') f = incl.File('header.h') # Get a Node for a subdirectory within a directory -dist = Dir('project-3.2.1) +dist = Dir('project-3.2.1') src = dist.Dir('src') # Get a Node for a file in the same directory @@ -4919,7 +4925,8 @@ the same target file(s). The default is 0, which means the builder can not be called multiple times for the same target file(s). Calling a builder multiple times for the same target simply adds additional source files to the target; it is not allowed to change the environment associated -with the target, specify addition environment overrides, or associate a different +with the target, specify additional environment overrides, +or associate a different builder with the target. @@ -5404,17 +5411,15 @@ a = Action(build_it, varlist=['XXX']) The -Action() +&Action; global function can be passed the following optional keyword arguments to modify the Action object's behavior: - -chdir -The -chdir -keyword argument specifies that + +chdir +specifies that scons will execute the action after changing to the specified directory. If the @@ -5459,15 +5464,9 @@ a = Action("build < ${SOURCE.file} > ${TARGET.file}", chdir=1) - -exitstatfunc -The -Action() -global function -also takes an -exitstatfunc -keyword argument -which specifies a function + +exitstatfunc +specifies a function that is passed the exit status (or return value) from the specified action @@ -5489,11 +5488,9 @@ a = Action("build < ${SOURCE.file} > ${TARGET.file}", -batch_key -The -batch_key -keyword argument can be used -to specify that the Action can create multiple target files + +batch_key +specifies that the Action can create multiple target files by processing multiple independent source files simultaneously. (The canonical example is "batch compilation" of multiple object files @@ -5502,7 +5499,7 @@ to a single invocation of a compiler such as Microsoft's Visual C / C++ compiler.) If the batch_key -argument is any non-False, non-callable Python value, +argument evaluates True and is not a callable object, the configured Action object will cause scons to collect all targets built with the Action object @@ -5534,7 +5531,7 @@ will be used to identify different for batch building. A batch_key -function must take the following arguments: +function must accept the following arguments: @@ -5666,7 +5663,7 @@ sequences of file manipulation without relying on platform-specific external commands: -that + env = Environment(TMPBUILD = '/tmp/builddir') env.Command('foo.out', 'foo.in', @@ -5689,11 +5686,11 @@ which can be octal or string, similar to the bash command. Examples: -Execute(Chmod('file', 0755)) +Execute(Chmod('file', 0o755)) env.Command('foo.out', 'foo.in', [Copy('$TARGET', '$SOURCE'), - Chmod('$TARGET', 0755)]) + Chmod('$TARGET', 0o755)]) Execute(Chmod('file', "ugo+w")) @@ -5826,13 +5823,13 @@ env.Command('marker', 'input_file', Before executing a command, scons -performs construction variable interpolation on the strings that make up -the command line of builders. -Variables are introduced by a -$ +performs construction variable interpolation on the string that makes up +the command line of the builder. +Variables are introduced in such strings by a +$ prefix. -Besides construction variables, scons provides the following -variables for each command execution: +Besides regular construction variables, scons provides the following +special variables for each command execution: @@ -5901,15 +5898,19 @@ from sources that have not changed since the target was last built. -(Note that the above variables are reserved -and may not be set in a construction environment.) - -For example, given the construction variable CC='cc', targets=['foo'], and -sources=['foo.c', 'bar.c']: +Note that the above variables are reserved +and may not be set in a construction environment. + +For example, given the construction variables +CC='cc', +targets=['foo'] +and +sources=['foo.c', 'bar.c']: + action='$CC -c -o $TARGET $SOURCES' @@ -5921,8 +5922,10 @@ action='$CC -c -o $TARGET $SOURCES' cc -c -o foo foo.c bar.c -Variable names may be surrounded by curly braces ({}) -to separate the name from the trailing characters. +Variable names may be surrounded by curly braces +{ } +to separate the name from surrounding characters which +are not part of the name. Within the curly braces, a variable name may have a Python slice subscript appended to select one or more items from a list. @@ -6085,20 +6088,42 @@ may be a callable Python function associated with a construction variable in the environment. The function should -take four arguments: -target -- a list of target nodes, -source -- a list of source nodes, -env -- the construction environment, -for_signature -- a Boolean value that specifies +accept four arguments: + + + + target + +a list of target nodes + + + + source + +a list of source nodes + + + + env + +the construction environment + + + + for_signature + +a Boolean value that specifies whether the function is being called -for generating a build signature. +for generating a build signature. + + + + + SCons will insert whatever the called function returns -into the expanded string: +into the expanded string: + def foo(target, source, env, for_signature): @@ -6179,9 +6204,12 @@ echo Last build occurred . > $TARGET Python Code Substitution -Any python code within -${-} -pairs gets evaluated by python 'eval', with the python globals set to + +Any Python code within curly braces +{ } +and introduced by the variable prefix $ +gets evaluated by the Python eval statement, +with the Python globals set to the current environment's set of construction variables. So in the following case: @@ -6197,14 +6225,20 @@ echo FOO > foo.out echo BAR > foo.out -according to the current value of env['COND'] when the command is -executed. The evaluation occurs when the target is being -built, not when the SConscript is being read. So if env['COND'] is changed +according to the current value of env['COND'] +when the command is executed. +The evaluation takes place when the target is being +built, not when the SConscript is being read. So if +env['COND'] is changed later in the SConscript, the final value will be used. -Here's a more interesting example. Note that all of COND, FOO, and -BAR are environment variables, and their values are substituted into -the final command. FOO is a list, so its elements are interpolated +Here's a more interesting example. Note that all of +COND, +FOO, +and +BAR are construction variables, +and their values are substituted into the final command. +FOO is a list, so its elements are interpolated separated by spaces. @@ -6315,7 +6349,8 @@ might not exist argument is the construction environment for the scan. Fetch values from it using the env.Dictionary() -method. +method or using the key lookup operator +directly on the construction environment. The path @@ -6551,9 +6586,10 @@ do this, in part, by sharing an ability to interpret UNIX-like path names. For example, the Cygwin tools will internally translate a Cygwin path name -like /cygdrive/c/mydir +like /cygdrive/c/mydir to an equivalent Windows pathname -of C:/mydir (equivalent to C:\mydir). +of C:/mydir (equivalent to C:\mydir). + Versions of Python that are built for native Windows execution, @@ -6561,7 +6597,8 @@ such as the python.org and ActiveState versions, do not have the Cygwin path name semantics. This means that using a native Windows version of Python to build compiled programs using Cygwin tools -(such as gcc, bison, and flex) +(such as gcc, bison, +and flex) may yield unpredictable results. "Mixing and matching" in this way can be made to work, @@ -6771,7 +6808,7 @@ env['BUILDERS]['PDFBuilder'] = bld Defining Your Own Scanner Object -The following example shows an extremely simple scanner (the +The following example shows adding an extremely simple scanner (the kfile_scan() function) that doesn't use a search path at all @@ -6796,8 +6833,10 @@ kscan = Scanner(name = 'kfile', function = kfile_scan, argument = None, skeys = ['.k']) -scanners = Environment().Dictionary('SCANNERS') -env = Environment(SCANNERS = scanners + [kscan]) + +scanners = DefaultEnvironment()['SCANNERS'] +scanners.append(kscan) +env = Environment(SCANNERS=scanners) env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET') @@ -6814,7 +6853,8 @@ you can use the function of your current Environment in order to create nodes on the fly from a sequence of file names with relative paths. -Here is a similar but more complete example that searches +Here is a similar but more complete example that adds +a scanner which searches a path of directories (specified as the MYPATH @@ -6840,15 +6880,16 @@ def my_scan(node, env, path, arg): break return env.File(results) -scanner = Scanner(name = 'myscanner', - function = my_scan, - argument = None, - skeys = ['.x'], - path_function = FindPathDirs('MYPATH') +scanner = Scanner(name='myscanner', + function=my_scan, + argument=None, + skeys=['.x'], + path_function=FindPathDirs('MYPATH') ) -scanners = Environment().Dictionary('SCANNERS') -env = Environment(SCANNERS = scanners + [scanner], - MYPATH = ['incs']) + +scanners = DefaultEnvironment()['SCANNERS'] +scanners.append(scanner) +env = Environment(SCANNERS=scanners, MYPATH=['incs']) env.Command('foo', 'foo.x', 'xprocess < $SOURCES > $TARGET') @@ -6861,8 +6902,8 @@ that will return a list of directories specified in the $MYPATH construction variable. It lets SCons detect the file -incs/foo.inc -, even if +incs/foo.inc, +even if foo.x contains the line include foo.inc @@ -6883,17 +6924,18 @@ def pf(env, dir, target, source, arg): results.append(top_dir + os.sep + p) return results -scanner = Scanner(name = 'myscanner', - function = my_scan, - argument = None, - skeys = ['.x'], - path_function = pf +scanner = Scanner(name='myscanner', + function=my_scan, + argument=None, + skeys=['.x'], + path_function=pf ) -Creating a Hierarchical Build + +Creating a Hierarchical Build Notice that the file names specified in a subdirectory's SConscript @@ -6982,7 +7024,7 @@ value each time we call the SConscript function. SConstruct: - env = Environment(LIBPATH = ['#libA', '#libB']) + env = Environment(LIBPATH=['#libA', '#libB']) Export('env') SConscript('libA/SConscript') SConscript('libB/SConscript') @@ -7001,7 +7043,7 @@ libB/SConscript: Main/SConscript: Import('env') - e = env.Copy(LIBS = ['a', 'b']) + e = env.Clone(LIBS=['a', 'b']) e.Program('foo', Split('m1.c m2.c m3.c')) @@ -7126,22 +7168,62 @@ env.Program('MyApp', ['Foo.cpp', 'Bar.cpp']) ENVIRONMENT + +In general, &scons; is not controlled by environment +variables set in the shell used to invoke it, leaving it +up to the SConscript file author to import those if desired. +However the following variables are imported by +&scons; itself if set: + + - SCONS_LIB_DIR - -Specifies the directory that contains the SCons Python module directory -(e.g. /home/aroach/scons-src-0.01/src/engine). + SCONS_LIB_DIR + +Specifies the directory that contains the &scons; +Python module directory (for example, +/home/aroach/scons-src-0.01/src/engine). + + - + + SCONSFLAGS + +A string of options that will be used by &scons; +in addition to those passed on the command line. + + - SCONSFLAGS - -A string of options that will be used by scons in addition to those passed -on the command line. + SCONS_CACHE_MSVC_CONFIG + +(Windows only). If set, save the shell environment variables +generated when setting up the Microsoft Visual C++ compiler +(and/or Build Tools) to a file to give these settings, +which are expensive to generate, persistence +across &scons; invocations. +Use of this option is primarily intended to aid performance +in tightly controlled Continuous Integration setups. + +If set to a True-like value ("1", +"true" or +"True") will cache to a file named +.scons_msvc_cache in the user's home directory. +If set to a pathname, will use that pathname for the cache. + +Note: use this cache with caution as it +might be somewhat fragile: while each major toolset version +(e.g. Visual Studio 2017 vs 2019) and architecture pair will get separate +cache entries, if toolset updates cause a change +to settings within a given release series, &scons; will not +detect the change and will reuse old settings. +Remove the cache file in case of problems with this. +&scons; will ignore failures reading or writing the file +and will silently revert to non-cached behavior in such cases. + +Since &scons; 3.1. - + @@ -7157,8 +7239,9 @@ source code. AUTHORS -Originally: Steven Knight <knight@baldmt.com> and Anthony Roach <aroach@electriceyeball.com> -Since 2010: The SCons Development Team <scons-dev@scons.org> +Originally: Steven Knight knight@baldmt.com +and Anthony Roach aroach@electriceyeball.com. +Since 2010: The SCons Development Team scons-dev@scons.org. diff --git a/doc/man/sconsign.xml b/doc/man/sconsign.xml index daaa260..a1308ea 100644 --- a/doc/man/sconsign.xml +++ b/doc/man/sconsign.xml @@ -32,8 +32,8 @@ SCONSIGN 1 -SCons 3.1.1 -SCons 3.1.1 +SCons 3.1.2 +SCons 3.1.2 sconsign -- cgit v1.2.3