diff options
Diffstat (limited to 'scons.1')
| -rw-r--r-- | scons.1 | 1154 |
1 files changed, 553 insertions, 601 deletions
@@ -3,11 +3,11 @@ .\" Author: Steven Knight .\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/> .\" Date: <pubdate>2004 - 2019</pubdate> -.\" Manual: SCons 3.1.1 -.\" Source: SCons 3.1.1 version 3.1.1 +.\" Manual: SCons 3.1.2 +.\" Source: SCons 3.1.2 version 3.1.2 .\" Language: English .\" -.TH "SCONS" "1" "<pubdate>2004 - 2019</pubdate>" "SCons 3\&.1\&.1 version 3.1.1" "SCons 3\&.1\&.1" +.TH "SCONS" "1" "<pubdate>2004 - 2019</pubdate>" "SCons 3\&.1\&.2 version 3.1.2" "SCons 3\&.1\&.2" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -116,9 +116,13 @@ to the commands used to build target files\&. This is so that builds will be gua \fBscons\fR is invoked\&. This also means that if the compiler or other commands that you want to use to build your target files are not in standard system locations, \fBscons\fR -will not find them unless you explicitly set the PATH to include those locations\&. Whenever you create an +will not find them unless you explicitly set the +\fBPATH\fR +to include those locations\&. Whenever you create an \fBscons\fR -construction environment, you can propagate the value of PATH from your external environment as follows: +construction environment, you can propagate the value of +\fBPATH\fR +from your external environment as follows: .sp .if n \{\ .RS 4 @@ -131,15 +135,21 @@ env = Environment(ENV = {\*(AqPATH\*(Aq : os\&.environ[\*(AqPATH\*(Aq]}) .RE .\} .PP -Similarly, if the commands use external environment variables like $PATH, $HOME, $JAVA_HOME, $LANG, $SHELL, $TERM, etc\&., these variables can also be explicitly propagated: +Similarly, if the commands use external environment variables like +\fBPATH\fR, +\fBHOME\fR, +\fBJAVA_HOME\fR, +\fBLANG\fR, +\fBSHELL\fR, +\fBTERM\fR, etc\&., these variables can also be explicitly propagated: .sp .if n \{\ .RS 4 .\} .nf import os -env = Environment(ENV = {\*(AqPATH\*(Aq : os\&.environ[\*(AqPATH\*(Aq], - \*(AqHOME\*(Aq : os\&.environ[\*(AqHOME\*(Aq]}) +env = Environment(ENV = {\*(AqPATH\*(Aq: os\&.environ[\*(AqPATH\*(Aq], + \*(AqHOME\*(Aq: os\&.environ[\*(AqHOME\*(Aq]}) .fi .if n \{\ .RE @@ -495,11 +505,22 @@ Works exactly the same way as the 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\&. .RE .PP -\-\-debug=\fItype\fR +\-\-debug=\fItype\fR[\fI,type\fR\&.\&.\&.] .RS 4 Debug the build process\&. -\fItype[,type\&.\&.\&.]\fR -specifies what type of debugging\&. Multiple types may be specified, separated by commas\&. The following types are valid: +\fItype\fR +specifies the kind of debugging info to emit\&. Multiple types may be specified, separated by commas\&. The following entries show the recognized types: +.RE +.PP +\-\-debug=action\-timestamps +.RS 4 +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 +\fB\-\-debug=time\fR +option\&. +.sp +Since +scons +3\&.1\&. .RE .PP \-\-debug=count @@ -516,13 +537,6 @@ files)\&. Print a line for each unlink/relink (or copy) of a variant file from its source file\&. Includes debugging info for unlinking stale variant files, as well as unlinking old targets before building them\&. .RE .PP -\-\-debug=dtree -.RS 4 -A synonym for the newer -\fB\-\-tree=derived\fR -option\&. This will be deprecated in some future release and ultimately removed\&. -.RE -.PP \-\-debug=explain .RS 4 Print an explanation of precisely why @@ -562,11 +576,6 @@ Prints a summary of hits and misses using the Memoizer, an internal subsystem th Prints how much memory SCons uses before and after reading the SConscript files and before and after building targets\&. .RE .PP -\-\-debug=nomemoizer -.RS 4 -A deprecated option preserved for backwards compatibility\&. -.RE -.PP \-\-debug=objects .RS 4 Prints a list of the various objects of the various classes used internally by SCons\&. @@ -609,13 +618,6 @@ Building myprog\&.o with action(s): Prints an internal Python stack trace when encountering an otherwise unexplained error\&. .RE .PP -\-\-debug=stree -.RS 4 -A synonym for the newer -\fB\-\-tree=all,status\fR -option\&. This will be deprecated in some future release and ultimately removed\&. -.RE -.PP \-\-debug=time .RS 4 Prints various time profiling information: @@ -712,13 +714,6 @@ the option, and your build configuration allows good parallelization, the elapsed wall\-clock time should be significantly smaller than the total time spent executing all the build commands, since multiple build commands and intervening SCons processing should take place in parallel\&.) .RE .PP -\-\-debug=tree -.RS 4 -A synonym for the newer -\fB\-\-tree=all\fR -option\&. This will be deprecated in some future release and ultimately removed\&. -.RE -.PP \-\-diskcheck=\fItypes\fR .RS 4 Enable specific checks for whether or not there is a file on disk where the SCons configuration expects a directory (or vice versa), and whether or not RCS or SCCS sources exist when searching for source and include files\&. The @@ -823,6 +818,16 @@ Force SCons to ignore changes in the implicit dependencies\&. This causes cached \fB\-\-implicit\-cache\fR\&. .RE .PP +\-\-install\-sandbox=\fIpath\fR +.RS 4 +When using the +\fBInstall\fR +functions, prepend +\fIpath\fR +to the installation paths such that all installed files will be placed underneath +\fIpath\fR\&. +.RE +.PP \-\-interactive .RS 4 Starts SCons in interactive mode\&. The SConscript files are read once and a @@ -1257,31 +1262,6 @@ Enables or disables warnings about dependencies\&. These warnings are disabled b Enables or disables all warnings about use of currently deprecated features\&. These warnings are enabled by default\&. Note that the \fB\-\-warn=no\-deprecated\fR option does not disable warnings about absolutely all deprecated features\&. Warnings for some deprecated features that have already been through several releases with deprecation warnings may be mandatory for a release or two before they are officially no longer supported by SCons\&. Warnings for some specific deprecated features may be enabled or disabled individually; see below\&. -.PP -\-\-warn=deprecated\-copy, \-\-warn=no\-deprecated\-copy -.RS 4 -Enables or disables warnings about use of the deprecated -\fBenv\&.Copy()\fR -method\&. -.RE -.PP -\-\-warn=deprecated\-source\-signatures, \-\-warn=no\-deprecated\-source\-signatures -.RS 4 -Enables or disables warnings about use of the deprecated -\fBSourceSignatures()\fR -function or -\fBenv\&.SourceSignatures()\fR -method\&. -.RE -.PP -\-\-warn=deprecated\-target\-signatures, \-\-warn=no\-deprecated\-target\-signatures -.RS 4 -Enables or disables warnings about use of the deprecated -\fBTargetSignatures()\fR -function or -\fBenv\&.TargetSignatures()\fR -method\&. -.RE .RE .PP \-\-warn=duplicate\-environment, \-\-warn=no\-duplicate\-environment @@ -1330,7 +1310,7 @@ Enables or disables warnings about the \fB\-\-debug=object\fR feature not working when \fBscons\fR -is run with the python +is run with the Python \fB\-O\fR option or from optimized Python (\&.pyo) modules\&. .RE @@ -1411,7 +1391,7 @@ env[\*(AqBAR\*(Aq] = \*(Aqbar\*(Aq .\} .PP As a convenience, construction variables may also be set or modified by the -\fIparse_flags\fR +\fBparse_flags\fR keyword argument, which applies the \fBenv\&.MergeFlags\fR method (described below) to the argument value after all other processing is completed\&. This is useful either if the exact content of the flags is unknown (for example, read from a control file) or if the flags are distributed to a number of construction variables\&. @@ -1474,35 +1454,60 @@ env = Environment(platform = my_platform) .RE .\} .PP -Additionally, a specific set of tools with which to initialize the environment may be specified as an optional keyword argument: +Additionally, a specific set of tools with which to initialize the environment may be specified using the optional keyword argument +\fItools\fR: .sp .if n \{\ .RS 4 .\} .nf -env = Environment(tools = [\*(Aqmsvc\*(Aq, \*(Aqlex\*(Aq]) +env = Environment(tools=[\*(Aqmsvc\*(Aq, \*(Aqlex\*(Aq]) .fi .if n \{\ .RE .\} .PP -Non\-built\-in tools may be specified using the toolpath argument: +The +\fItools\fR +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=[\*(Aqclang\*(Aq, \*(Aqlink\*(Aq]\&. The tool name +\*(Aqdefault\*(Aq +can be used to retain the default list\&. +.PP +Non\-built\-in tools may be specified using the optional +\fItoolpath\fR +keyword argument: .sp .if n \{\ .RS 4 .\} .nf -env = Environment(tools = [\*(Aqdefault\*(Aq, \*(Aqfoo\*(Aq], toolpath = [\*(Aqtools\*(Aq]) +env = Environment(tools=[\*(Aqdefault\*(Aq, \*(Aqfoo\*(Aq], toolpath=[\*(Aqtools\*(Aq]) .fi .if n \{\ .RE .\} .PP -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)\&. The -\fBgenerate()\fR -function modifies the passed\-in environment to set up variables so that the tool can be executed; it may use any keyword arguments that the user supplies (see below) to vary its initialization\&. The -\fBexists()\fR -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 would override the built\-in gcc tool\&. Also note that the toolpath is stored in the environment for use by later calls to +This looks for a tool specification in +tools/foo\&.py +as well as using the ordinary default tools for the platform\&. +.PP +A tool specification must include two functions: +\fBgenerate(env, **kw)\fR +and +\fBexists(env)\fR\&. The +\fBgenerate\fR +function modifies the environment referenced by +\fIenv\fR +to set up variables so that the tool can be executed; it may use any keyword arguments that the user supplies in +\fIkw\fR +(see below) to vary its initialization\&. The +\fBexists\fR +function should return a true value if the tool is available\&. +.PP +Tools in the toolpath are used before 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 by later calls to \fBClone\fR() and \fBTool\fR() methods: .sp @@ -1551,11 +1556,12 @@ function can use the arguments to modify the tool\*(Aqs behavior by setting up t def generate(env, **kw): # Sets MY_TOOL to the value of keyword argument \*(Aqarg1\*(Aq or 1\&. env[\*(AqMY_TOOL\*(Aq] = kw\&.get(\*(Aqarg1\*(Aq, \*(Aq1\*(Aq) + def exists(env): - return 1 + return True # in SConstruct: -env = Environment(tools = [\*(Aqdefault\*(Aq, (\*(Aqmy_tool\*(Aq, {\*(Aqarg1\*(Aq: \*(Aqabc\*(Aq})], +env = Environment(tools=[\*(Aqdefault\*(Aq, (\*(Aqmy_tool\*(Aq, {\*(Aqarg1\*(Aq: \*(Aqabc\*(Aq})], toolpath=[\*(Aqtools\*(Aq]) .fi .if n \{\ @@ -1573,7 +1579,7 @@ One feature now present within Scons is the ability to have nested tools\&. Tool .\} .nf # namespaced builder -env = Environment(ENV = os\&.environ, tools = [\*(AqSubDir1\&.SubDir2\&.SomeTool\*(Aq]) +env = Environment(ENV=os\&.environ, tools=[\*(AqSubDir1\&.SubDir2\&.SomeTool\*(Aq]) env\&.SomeTool(targets, sources) # Search Paths @@ -1736,7 +1742,7 @@ Uses: .PP cc .RS 4 -Sets construction variables for generic POSIX C copmilers\&. +Sets construction variables for generic POSIX C compilers\&. .sp Sets: \fB$CC\fR, @@ -1851,7 +1857,33 @@ Sets: .PP default .RS 4 -Sets variables by calling a default list of Tool modules for the platform on which SCons is running\&. +Sets +construction variables +for a default list of Tool modules\&. Use +\fBdefault\fR +in the tools list to retain the original defaults, since the +\fItools\fR +parameter is treated as a literal statement of the tools to be made available in that +construction environment, not an addition\&. +.sp +The list of tools selected by default is not static, but is dependent both on the platform and on the software installed on the platform\&. Some tools will not initialize if an underlying command is not found, and some tools are selected from a list of choices on a first\-found basis\&. The finished tool list can be examined by inspecting the +\fBTOOLS\fR +construction variable +in the +construction environment\&. +.sp +On all platforms, all tools from the following list are selected whose respective conditions are met: filesystem, wix, lex, yacc, rpcgen, swig, jar, javac, javah, rmic, dvipdf, dvips, gs, tex, latex, pdflatex, pdftex, tar, zip, textfile\&. +.sp +On Linux systems, the default tools list selects (first\-found): a C compiler from gcc, intelc, icc, cc; a C++ compiler from g++, intelc, icc, cxx; an assembler from gas, nasm, masm; a linker from gnulink, ilink; a Fortran compiler from gfortran, g77, ifort, ifl, f95, f90, f77; and a static archiver \*(Aqar\*(Aq\&. It also selects all found from the list m4, rpm\&. +.sp +On Windows systems, the default tools list selects (first\-found): a C compiler from msvc, mingw, gcc, intelc, icl, icc, cc, bcc32; a C++ compiler from msvc, intelc, icc, g++, cxx, bcc32; an assembler from masm, nasm, gas, 386asm; a linker from mslink, gnulink, ilink, linkloc, ilink32; a Fortran compiler from gfortran, g77, ifl, cvf, f95, f90, fortran; and a static archiver from mslib, ar, tlib; It also selects all found from the list msvs, midl\&. +.sp +On MacOS systems, the default tools list selects (first\-found): a C compiler from gcc, cc; a C++ compiler from g++, cxx; an assembler \*(Aqas\*(Aq; a linker from applelink, gnulink; a Fortran compiler from gfortran, f95, f90, g77; and a static archiver ar\&. It also selects all found from the list m4, rpm\&. +.sp +Default lists for other platforms can be found by examining the +scons +source code (see +SCons/Tool/__init__\&.py)\&. .RE .PP dmd @@ -2877,7 +2909,7 @@ Uses: .PP link .RS 4 -Sets construction variables for generic POSIX linkers\&. +Sets construction variables for generic POSIX linkers\&. This is a "smart" linker tool which selects a compiler to complete the linking based on the types of source files\&. .sp Sets: \fB$LDMODULE\fR, @@ -3719,27 +3751,49 @@ Sets: Uses: \fB$ZIPCOMSTR\fR\&. .RE -.PP -Additionally, there is a "tool" named -\fBdefault\fR -which configures the environment with a default set of tools for the current platform\&. -.PP -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\&. .SS "Builder Methods" .PP -Build rules are specified by calling a construction environment\*(Aqs builder methods\&. The arguments to the builder methods are -\fBtarget\fR -(a list of targets to be built, usually file names) and -\fBsource\fR -(a list of sources to be built, usually file names)\&. +You tell +\fBscons\fR +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\&. +\fBscons\fR +defines a number of builders, and you can also write your own\&. Builders are attached to a +construction environment +as methods, and the available builder methods are listed as key\-value pairs in the +\fBBUILDERS\fR +attribute of the +construction environment\&. The available builders can be displayed like this for debugging purposes: +.sp +.if n \{\ +.RS 4 +.\} +.nf +print("Builders:", list(env[\*(AqBUILDERS\*(Aq])) +.fi +.if n \{\ +.RE +.\} +.PP +Builder methods always take two arguments: +\fItarget\fR +(a target or a list of targets to be built) and +\fIsource\fR +(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\&. .PP Because long lists of file names can lead to a lot of quoting, \fBscons\fR supplies a -\fBSplit()\fR -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\*(Aqt a string\&.) +\fBSplit\fR +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 Python string +\fBsplit\fR +method, but work even if the input isn\*(Aqt a string\&.) .PP -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 +\fItarget=\fR +and +\fIsource=\fR\&. The following are equivalent examples of calling the +\fBProgram\fR +builder method: .sp .if n \{\ .RS 4 @@ -3748,28 +3802,30 @@ Like all Python arguments, the target and source arguments to a builder method c env\&.Program(\*(Aqbar\*(Aq, [\*(Aqbar\&.c\*(Aq, \*(Aqfoo\&.c\*(Aq]) env\&.Program(\*(Aqbar\*(Aq, Split(\*(Aqbar\&.c foo\&.c\*(Aq)) env\&.Program(\*(Aqbar\*(Aq, env\&.Split(\*(Aqbar\&.c foo\&.c\*(Aq)) -env\&.Program(source = [\*(Aqbar\&.c\*(Aq, \*(Aqfoo\&.c\*(Aq], target = \*(Aqbar\*(Aq) -env\&.Program(target = \*(Aqbar\*(Aq, Split(\*(Aqbar\&.c foo\&.c\*(Aq)) -env\&.Program(target = \*(Aqbar\*(Aq, env\&.Split(\*(Aqbar\&.c foo\&.c\*(Aq)) -env\&.Program(\*(Aqbar\*(Aq, source = \*(Aqbar\&.c foo\&.c\*(Aq\&.split()) +env\&.Program(source=[\*(Aqbar\&.c\*(Aq, \*(Aqfoo\&.c\*(Aq], target=\*(Aqbar\*(Aq) +env\&.Program(target=\*(Aqbar\*(Aq, source=Split(\*(Aqbar\&.c foo\&.c\*(Aq)) +env\&.Program(target=\*(Aqbar\*(Aq, source=env\&.Split(\*(Aqbar\&.c foo\&.c\*(Aq)) +env\&.Program(\*(Aqbar\*(Aq, source=\*(Aqbar\&.c foo\&.c\*(Aq\&.split()) .fi .if n \{\ .RE .\} .PP -Target and source file names that are not absolute path names (that is, do not begin with -\fB/\fR -on POSIX systems or -\fB\e\fR -on Windows systems, with or without an optional drive letter) are interpreted relative to the directory containing the -\fBSConscript\fR -file being read\&. An initial +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\&. +.PP + +\fBscons\fR +recognizes a third way to specify path strings: if the string begins with the \fB#\fR -(hash mark) on a path name means that the rest of the file name is interpreted relative to the directory containing the top\-level +character it is top\-relative \- it works like a relative path but the search follows down from the directory containing the top\-level \fBSConstruct\fR -file, even if the -\fB#\fR -is followed by a directory separator character (slash or backslash)\&. +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\&. +.PP +Target and source pathnames can be absolute, relative, or top\-relative\&. Relative pathnames are searched considering the directory of the +\fBSConscript\fR +file currently being processed as the "current directory"\&. .PP Examples: .sp @@ -3808,15 +3864,17 @@ will deduce the target file name from the source file name\&. The following exam \fBbar\fR (on POSIX systems) or \fBbar\&.exe\fR -(on Windows systems) from the bar\&.c source file: +(on Windows systems) from the +bar\&.c +source file: .sp .if n \{\ .RS 4 .\} .nf -env\&.Program(target = \*(Aqbar\*(Aq, source = \*(Aqbar\&.c\*(Aq) -env\&.Program(\*(Aqbar\*(Aq, source = \*(Aqbar\&.c\*(Aq) -env\&.Program(source = \*(Aqbar\&.c\*(Aq) +env\&.Program(target=\*(Aqbar\*(Aq, source=\*(Aqbar\&.c\*(Aq) +env\&.Program(\*(Aqbar\*(Aq, source=\*(Aqbar\&.c\*(Aq) +env\&.Program(source=\*(Aqbar\&.c\*(Aq) env\&.Program(\*(Aqbar\&.c\*(Aq) .fi .if n \{\ @@ -3825,15 +3883,15 @@ env\&.Program(\*(Aqbar\&.c\*(Aq) .PP As a convenience, a \fBsrcdir\fR -keyword argument may be specified when calling a Builder\&. When specified, all source file strings that are not absolute paths will be interpreted relative to the specified +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 \fBsrcdir\fR\&. The following example will build the -\fBbuild/prog\fR +build/prog (or -\fBbuild/prog\&.exe\fR +build/prog\&.exe on Windows) program from the files -\fBsrc/f1\&.c\fR +src/f1\&.c and -\fBsrc/f2\&.c\fR: +src/f2\&.c: .sp .if n \{\ .RS 4 @@ -3845,7 +3903,9 @@ env\&.Program(\*(Aqbuild/prog\*(Aq, [\*(Aqf1\&.c\*(Aq, \*(Aqf2\&.c\*(Aq], srcdir .RE .\} .PP -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 +\fIoverride\fR +(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: .sp .if n \{\ .RS 4 @@ -3874,7 +3934,7 @@ env\&.SharedLibrary(\*(Aqword\*(Aq, \*(Aqword\&.cpp\*(Aq, (Note that both the $SHLIBSUFFIX and $LIBSUFFIXES variables must be set if you want SCons to search automatically for dependencies on the non\-standard library names; see the descriptions of these variables, below, for more information\&.) .PP It is also possible to use the -\fIparse_flags\fR +\fBparse_flags\fR keyword argument in an override, to merge command\-line style arguments into the appropriate construction variables (see \fBenv\&.MergeFlags\fR)\&. .sp @@ -3924,13 +3984,11 @@ from SCons\&.Script import * .RE .\} .PP -All builder methods return a list\-like object containing Nodes that represent the target or targets that will be built\&. A +All builder methods return a list\-like object containing Nodes that will be built\&. A \fINode\fR is an internal SCons object which represents build targets or sources\&. .PP -The returned Node\-list object 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 -\fB\-D\fR -flag when compiling one specific object file: +The returned Node\-list object 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 preprocessor define when compiling one specific object file: .sp .if n \{\ .RS 4 @@ -3943,9 +4001,15 @@ env\&.Program(source = [\*(Aqfoo\&.c\*(Aq, bar_obj_list, \*(Aqmain\&.c\*(Aq]) .RE .\} .PP -Using a Node in this way makes for a more portable build by avoiding having to specify a platform\-specific object suffix when calling the Program() builder method\&. +Using a Node in this way makes for a more portable build by avoiding having to specify a platform\-specific object suffix when calling the +\fBProgram\fR +builder method\&. .PP -Note that Builder calls will automatically "flatten" the source and target file lists, so it\*(Aqs all right to have the bar_obj list return by the StaticObject() call in the middle of the source file list\&. If you need to manipulate a list of lists returned by Builders directly using Python, you can either build the list by hand: +Note that builder calls will automatically "flatten" the source and target file lists, so it\*(Aqs all right to have the +bar_obj_list +returned by the +\fBStaticObject\fR +call in the middle of the source file list\&. If you need to manipulate a list of lists returned by builders directly using Python, you can either build the list by hand: .sp .if n \{\ .RS 4 @@ -3962,7 +4026,8 @@ for object in objects: .\} .PP Or you can use the -\fBFlatten\fR() function supplied by scons to create a list containing just the Nodes, which may be more convenient: +\fBFlatten\fR +function supplied by scons to create a list containing just the Nodes, which may be more convenient: .sp .if n \{\ .RS 4 @@ -3978,12 +4043,12 @@ for object in objects: .RE .\} .PP -Note also that because Builder calls return a list\-like object, not an actual Python list, you should +Note also that because builder calls return a list\-like object, not an actual Python list, you should \fInot\fR -use the Python -\fB+=\fR -operator 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\&. 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 -\fB\&.extend()\fR +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\&. 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 list +\fBextend\fR method to make sure the list is updated in\-place\&. Example: .sp .if n \{\ @@ -3998,7 +4063,7 @@ 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(\*(Aqbar\&.c\*(Aq)) .fi @@ -4006,8 +4071,8 @@ object_files\&.extend(Object(\*(Aqbar\&.c\*(Aq)) .RE .\} .PP -The path name for a Node\*(Aqs file may be used by passing the Node to the Python\-builtin -\fBstr()\fR +The path name for a Node\*(Aqs file may be used by passing the Node to Python\*(Aqs builtin +\fBstr\fR function: .sp .if n \{\ @@ -4021,9 +4086,7 @@ print("The path to bar_obj is:", str(bar_obj_list[0])) .RE .\} .PP -Note again that because the Builder call returns a list, we have to access the first element in the list -\fB(bar_obj_list[0])\fR -to get at the Node that actually represents the object file\&. +Note again that because the Builder call returns a list, we have to access the first element in the list ((bar_obj_list[0])) to get at the Node that actually represents the object file\&. .PP Builder calls support a \fBchdir\fR @@ -4067,7 +4130,10 @@ and to use just the filename portion of the targets and source\&. .PP \fBscons\fR -provides the following builder methods: +predefined the following builder methods\&. Depending on the setup of a particular +construction environment +and on the type and software installation status of the underlying system, not all builders may be available to that +construction environment\&. .PP \fBCFile()\fR, \fBenv\&.CFile()\fR .RS 4 @@ -4094,7 +4160,7 @@ env\&.CFile(target = \*(Aqbar\*(Aq, source = \*(Aqbar\&.y\*(Aq) .RS 4 The \fBCommand\fR -"Builder" is actually implemented as a function that looks like a Builder, but actually takes an additional argument of the action from which the Builder should be made\&. See the +"Builder" is actually a function that looks like a Builder, but takes a required third argument, which is the action to take to construct the target from the source, used for "one\-off" builds where a full builder is not needed\&. Thus it does not follow the builder calling rules described at the start of this section\&. See instead the \fBCommand\fR function description for the calling syntax and details\&. .RE @@ -4555,6 +4621,13 @@ env\&.Install(\*(Aq/usr/local/bin\*(Aq, source = [\*(Aqfoo\*(Aq, \*(Aqbar\*(Aq]) .if n \{\ .RE .\} +.sp +If the +\fB\-\-install\-sandbox\fR +command line option is given, the target directory will be prefixed by the directory path specified\&. This is useful to test installs without installing to a "live" location in the system\&. +.sp +See also +\fBFindInstalledFiles\fR\&. For more thoughts on installation, see the User Guide (particularly the section on Command\-Line Targets and the chapters on Installing Files and on Alias Targets)\&. .RE .PP \fBInstallAs()\fR, \fBenv\&.InstallAs()\fR @@ -6049,52 +6122,14 @@ Builds an executable from D sources without first creating individual objects fo .sp D sources can be compiled file\-by\-file as C and C++ source are, and D is integrated into the scons -Object and Program builders for this model of build\&. D codes can though do whole source meta\-programming (some of the testing frameworks do this)\&. For this it is imperative that all sources are compiled and linked in a single call of the D compiler\&. This builder serves that purpose\&. -.sp -.if n \{\ -.RS 4 -.\} -.nf - env\&.ProgramAllAtOnce(\*(Aqexecutable\*(Aq, [\*(Aqmod_a\&.d, mod_b\&.d\*(Aq, \*(Aqmod_c\&.d\*(Aq]) - -.fi -.if n \{\ -.RE -.\} -.sp -This command will compile the modules mod_a, mod_b, and mod_c in a single compilation process without first creating object files for the modules\&. Some of the D compilers will create executable\&.o others will not\&. -.sp -Builds an executable from D sources without first creating individual objects for each file\&. -.sp -D sources can be compiled file\-by\-file as C and C++ source are, and D is integrated into the -scons -Object and Program builders for this model of build\&. D codes can though do whole source meta\-programming (some of the testing frameworks do this)\&. For this it is imperative that all sources are compiled and linked in a single call of the D compiler\&. This builder serves that purpose\&. -.sp -.if n \{\ -.RS 4 -.\} -.nf - env\&.ProgramAllAtOnce(\*(Aqexecutable\*(Aq, [\*(Aqmod_a\&.d, mod_b\&.d\*(Aq, \*(Aqmod_c\&.d\*(Aq]) - -.fi -.if n \{\ -.RE -.\} -.sp -This command will compile the modules mod_a, mod_b, and mod_c in a single compilation process without first creating object files for the modules\&. Some of the D compilers will create executable\&.o others will not\&. -.sp -Builds an executable from D sources without first creating individual objects for each file\&. -.sp -D sources can be compiled file\-by\-file as C and C++ source are, and D is integrated into the -scons -Object and Program builders for this model of build\&. D codes can though do whole source meta\-programming (some of the testing frameworks do this)\&. For this it is imperative that all sources are compiled and linked in a single call of the D compiler\&. This builder serves that purpose\&. +Object and Program builders for this model of build\&. D codes can though do whole source meta\-programming (some of the testing frameworks do this)\&. For this it is imperative that all sources are compiled and linked in a single call to the D compiler\&. This builder serves that purpose\&. .sp .if n \{\ .RS 4 .\} .nf - env\&.ProgramAllAtOnce(\*(Aqexecutable\*(Aq, [\*(Aqmod_a\&.d, mod_b\&.d\*(Aq, \*(Aqmod_c\&.d\*(Aq]) - + env\&.ProgramAllAtOnce(\*(Aqexecutable\*(Aq, [\*(Aqmod_a\&.d, mod_b\&.d\*(Aq, \*(Aqmod_c\&.d\*(Aq]) + .fi .if n \{\ .RE @@ -7040,7 +7075,7 @@ include: Action(action, [cmd/str/fun, [var, \&.\&.\&.]] [option=value, \&.\&.\&.]), env\&.Action(action, [cmd/str/fun, [var, \&.\&.\&.]] [option=value, \&.\&.\&.]) .RS 4 Creates an Action object for the specified -\fIaction\fR\&. See the section "Action Objects," below, for a complete explanation of the arguments and behavior\&. +\fIaction\fR\&. See the manpage section "Action Objects" for a complete explanation of the arguments and behavior\&. .sp Note that the \fBenv\&.Action\fR() form of the invocation will expand construction variables in any argument strings, including the @@ -7107,9 +7142,11 @@ AddOption(arguments) .RS 4 This function adds a new command\-line option to be recognized\&. The specified \fIarguments\fR -are the same as supported by the standard Python -\fBoptparse\&.add_option\fR() method (with a few additional capabilities noted below); see the documentation for -optparse +are the same as supported by the +\fBadd_option\fR +method in the standard Python library module +\fIoptparse\fR, with a few additional capabilities noted below; see the documentation for +\fIoptparse\fR for a thorough discussion of its option\-processing capabities\&. .sp In addition to the arguments and values supported by the @@ -7135,18 +7172,22 @@ keyword argument is supplied when calling \fBAddOption\fR, the option will have a default value of None\&. .sp +Unlike regular +\fIoptparse\fR, option names added via +\fBAddOption\fR +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 +\fBAddOption\fR +call\&. +.sp Once a new command\-line option has been added with \fBAddOption\fR, the option value may be accessed using \fBGetOption\fR or -\fBenv\&.GetOption\fR()\&. The value may also be set, using +\fBenv\&.GetOption\fR()\&. + \fBSetOption\fR -or -\fBenv\&.SetOption\fR(), if conditions in a -SConscript -require overriding any default value\&. Note, however, that a value specified on the command line will -\fIalways\fR -override a value set by any SConscript file\&. +is not currently supported for options added with +\fBAddOption\fR\&. .sp Any specified help= @@ -7179,6 +7220,32 @@ env = Environment(PREFIX = GetOption(\*(Aqprefix\*(Aq)) .if n \{\ .RE .\} +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +While +\fBAddOption\fR +behaves like +\fBadd_option\fR, from the +\fIoptparse\fR +module, the behavior of options added by +\fBAddOption\fR +which take arguments is underfined in +\fBscons\fR +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\&. +.sp .5v +.RE .RE .PP AddPostAction(target, action), env\&.AddPostAction(target, action) @@ -7187,7 +7254,7 @@ Arranges for the specified \fIaction\fR to be performed after the specified \fItarget\fR -has been built\&. The specified action(s) may be an Action object, or anything that can be converted into an Action object (see below)\&. +has been built\&. The specified action(s) may be an Action object, or anything that can be converted into an Action object See the manpage section "Action Objects" for a complete explanation\&. .sp When multiple targets are supplied, the action may be called multiple times, once after each action that generates one or more targets in the list\&. .RE @@ -7198,7 +7265,7 @@ Arranges for the specified \fIaction\fR to be performed before the specified \fItarget\fR -is built\&. The specified action(s) may be an Action object, or anything that can be converted into an Action object (see below)\&. +is built\&. The specified action(s) may be an Action object, or anything that can be converted into an Action object See the manpage section "Action Objects" for a complete explanation\&. .sp When multiple targets are specified, the action(s) may be called multiple times, once before each action that generates one or more targets in the list\&. .sp @@ -7303,7 +7370,9 @@ be built if so specified\&. Multiple targets can be passed in to a single call t .PP env\&.Append(key=val, [\&.\&.\&.]) .RS 4 -Appends the specified keyword arguments to the end of construction variables in the environment\&. If the Environment does not have the specified construction variable, it is simply added to the environment\&. If the values of the construction variable and the keyword argument are the same type, then the two values will be simply added together\&. 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\&.) +Appends the specified keyword arguments to the end of construction variables in the environment\&. If the Environment does not have the specified construction variable, it is simply added to the environment\&. If the values of the construction variable and the keyword argument are the same type, then the two values will be simply added together\&. 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 +\fBPrepend\fR +method)\&. .sp Example: .sp @@ -7369,25 +7438,10 @@ env\&.AppendUnique(CCFLAGS = \*(Aq\-g\*(Aq, FOO = [\*(Aqfoo\&.yyy\*(Aq]) .\} .RE .PP -BuildDir(build_dir, src_dir, [duplicate]), env\&.BuildDir(build_dir, src_dir, [duplicate]) -.RS 4 -Deprecated synonyms for -\fBVariantDir\fR -and -\fBenv\&.VariantDir\fR()\&. The -\fIbuild_dir\fR -argument becomes the -\fIvariant_dir\fR -argument of -\fBVariantDir\fR -or -\fBenv\&.VariantDir\fR()\&. -.RE -.PP Builder(action, [arguments]), env\&.Builder(action, [arguments]) .RS 4 Creates a Builder object for the specified -\fIaction\fR\&. See the section "Builder Objects," below, for a complete explanation of the arguments and behavior\&. +\fIaction\fR\&. See the manpage section "Builder Objects" for a complete explanation of the arguments and behavior\&. .sp Note that the \fBenv\&.Builder\fR() form of the invocation will expand construction variables in any arguments strings, including the @@ -7568,15 +7622,20 @@ Command(target, source, action, [key=val, \&.\&.\&.]), env\&.Command(target, sou .RS 4 Executes a specific action (or list of actions) to build a target file or files\&. This is more convenient than defining a separate Builder object for a single special\-case build\&. .sp -As a special case, the -\fIsource_scanner\fR -keyword argument can be used to specify a Scanner object that will be used to scan the sources\&. (The global + +\fBCommand\fR +builder accepts +\fIsource_scanner\fR, +\fItarget_scanner\fR, +\fIsource_factory\fR, and +\fItarget_factory\fR +keyword arguments\&. The *_scanner args can be used to specify a Scanner object 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\*(Aqt already specified in other Builder of function calls\&.) +object can be used if any of the sources will be directories that must be scanned on\-disk for changes to files that aren\*(Aqt 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\&. .sp Any other keyword arguments specified override any same\-named existing construction variables\&. .sp -An action can be an external command, specified as a string, or a callable Python object; see "Action Objects," below, for more complete information\&. Also note that a string specifying an external command may be preceded by an +An action can be an external command, specified as a string, 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) to suppress printing the command in question, or by a \- @@ -7594,7 +7653,7 @@ env\&.Command(\*(Aqfoo\&.out\*(Aq, \*(Aqfoo\&.in\*(Aq, env\&.Command(\*(Aqbar\&.out\*(Aq, \*(Aqbar\&.in\*(Aq, ["rm \-f $TARGET", "$BAR_BUILD < $SOURCES > $TARGET"], - ENV = {\*(AqPATH\*(Aq : \*(Aq/usr/local/bin/\*(Aq}) + ENV={\*(AqPATH\*(Aq: \*(Aq/usr/local/bin/\*(Aq}) def rename(env, target, source): import os @@ -7602,7 +7661,7 @@ def rename(env, target, source): env\&.Command(\*(Aqbaz\&.out\*(Aq, \*(Aqbaz\&.in\*(Aq, ["$BAZ_BUILD < $SOURCES > \&.tmp", - rename ]) + rename]) .fi .if n \{\ .RE @@ -7610,10 +7669,11 @@ env\&.Command(\*(Aqbaz\&.out\*(Aq, \*(Aqbaz\&.in\*(Aq, .sp Note that the \fBCommand\fR -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\&. If necessary, you can explicitly specify that targets or source nodes should be treated as directoriese by using 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 entries they are\&. If necessary, you can explicitly specify that targets or source nodes should be treated as directories by using the \fBDir\fR or -\fBenv\&.Dir\fR() functions\&. +\fBenv\&.Dir\fR +functions\&. .sp Examples: .sp @@ -7630,12 +7690,12 @@ env\&.Command(env\&.Dir(\*(Aq$DISTDIR\*(Aq)), None, make_distdir) .RE .\} .sp -(Also note that SCons will usually automatically create any directory necessary to hold a target file, so you normally don\*(Aqt need to create directories by hand\&.) +Also note that SCons will usually automatically create any directory necessary to hold a target file, so you normally don\*(Aqt need to create directories by hand\&. .RE .PP Configure(env, [custom_tests, conf_dir, log_file, config_h]), env\&.Configure([custom_tests, conf_dir, log_file, config_h]) .RS 4 -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\&. +Creates a Configure object for integrated functionality similar to GNU autoconf\&. See the manpage section "Configure Contexts" for a complete explanation of the arguments and behavior\&. .RE .PP env\&.Copy([key=val, \&.\&.\&.]) @@ -7814,9 +7874,15 @@ DEFAULT_TARGETS list; see below\&. .RE .PP -DefaultEnvironment([args]) +DefaultEnvironment([**kwargs]) .RS 4 -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 from source code management systems\&. +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\&. .RE .PP Depends(target, dependency), env\&.Depends(target, dependency) @@ -7858,7 +7924,12 @@ env\&.Depends(bar, installed_lib) .PP env\&.Dictionary([vars]) .RS 4 -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\&. +Returns a dictionary object 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\&. .sp Example: .sp @@ -7866,8 +7937,8 @@ Example: .RS 4 .\} .nf -dict = env\&.Dictionary() -cc_dict = env\&.Dictionary(\*(AqCC\*(Aq, \*(AqCCFLAGS\*(Aq, \*(AqCCCOM\*(Aq) +cvars = env\&.Dictionary() +cc_values = env\&.Dictionary(\*(AqCC\*(Aq, \*(AqCCFLAGS\*(Aq, \*(AqCCCOM\*(Aq) .fi .if n \{\ .RE @@ -7890,7 +7961,7 @@ If is a list, SCons returns a list of Dir nodes\&. Construction variables are expanded in \fIname\fR\&. .sp -Directory Nodes can be used anywhere you 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\&. +Directory Nodes can be used anywhere you 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 manpage section "File and Directory Nodes" for more information\&. .RE .PP env\&.Dump([key]) @@ -7906,7 +7977,7 @@ This SConstruct: .\} .nf env=Environment() -print env\&.Dump(\*(AqCCCOM\*(Aq) +print(env\&.Dump(\*(AqCCCOM\*(Aq)) .fi .if n \{\ .RE @@ -7931,7 +8002,7 @@ While this SConstruct: .\} .nf env=Environment() -print env\&.Dump() +print(env\&.Dump()) .fi .if n \{\ .RE @@ -8008,7 +8079,7 @@ Execute(action, [strfunction, varlist]), env\&.Execute(action, [strfunction, var .RS 4 Executes an Action object\&. The specified \fIaction\fR -may be an Action object (see the section "Action Objects," below, for a complete explanation of the arguments and 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\&. The exit value of the command or return value of the Python function will be returned\&. +may be an Action object (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, each of which will be converted into an Action object and then executed\&. The exit value of the command or return value of the Python function will be returned\&. .sp Note that scons @@ -8108,7 +8179,7 @@ If is a list, SCons returns a list of File nodes\&. Construction variables are expanded in \fIname\fR\&. .sp -File Nodes can be used anywhere you 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\&. +File Nodes can be used anywhere you 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 manpage section "File and Directory Nodes" for more information\&. .RE .PP FindFile(file, dirs), env\&.FindFile(file, dirs) @@ -8842,7 +8913,7 @@ to allow duplicate values to be added\&. .sp Interpreted options and the construction variables they affect are as specified for the \fBenv\&.ParseFlags\fR -method (which this method calls)\&. See that method\*(Aqs description, below, for a table of options and construction variables\&. +method (which this method calls)\&. See that method\*(Aqs description for a table of options and construction variables\&. .RE .PP ParseDepends(filename, [must_exist, only_one]), env\&.ParseDepends(filename, [must_exist, only_one]) @@ -8902,6 +8973,7 @@ Flag values are translated accordig to the prefix found, and added to the follow \-fmerge\-all\-constants CCFLAGS, LINKFLAGS \-fopenmp CCFLAGS, LINKFLAGS \-include CCFLAGS +\-imacros CCFLAGS \-isysroot CCFLAGS, LINKFLAGS \-isystem CCFLAGS \-iquote CCFLAGS @@ -9309,7 +9381,7 @@ Return(\*(Aqval1 val2\*(Aq) Scanner(function, [argument, keys, path_function, node_class, node_factory, scan_check, recursive]), env\&.Scanner(function, [argument, keys, path_function, node_class, node_factory, scan_check, recursive]) .RS 4 Creates a Scanner object for the specified -\fIfunction\fR\&. See the section "Scanner Objects," below, for a complete explanation of the arguments and behavior\&. +\fIfunction\fR\&. See manpage section "Scanner Objects" for a complete explanation of the arguments and behavior\&. .RE .PP SConscript(scripts, [exports, variant_dir, duplicate, must_exist]), env\&.SConscript(scripts, [exports, variant_dir, duplicate, must_exist]), SConscript(dirs=subdirs, [name=script, exports, variant_dir, duplicate, must_exist]), env\&.SConscript(dirs=subdirs, [name=script, exports, variant_dir, duplicate, must_exist]) @@ -9819,59 +9891,6 @@ env\&.SourceCode(\*(Aqno_source\&.c\*(Aq, None) .RE .PP -SourceSignatures(type), env\&.SourceSignatures(type) -.RS 4 -Note: Although it is not yet officially deprecated, use of this function is discouraged\&. See the -\fBDecider\fR -function for a more flexible and straightforward way to configure SCons\*(Aq decision\-making\&. -.sp -The -\fBSourceSignatures\fR -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\&. -.sp -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\&. -.sp - -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\&. -.sp - -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 -\fIolder\fR -than the last time it was used to rebuild the target file\&.) -.sp -There is no different between the two behaviors for Python -\fBValue\fR -node objects\&. -.sp - -MD5 -signatures take longer to compute, but are more accurate than -timestamp -signatures\&. The default value is -MD5\&. -.sp -Note that the default -\fBTargetSignatures\fR -setting (see below) is to use this -\fBSourceSignatures\fR -setting for any target files that are used to build other target files\&. Consequently, changing the value of -\fBSourceSignatures\fR -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 -\fBenv\&.SourceSignatures\fR -is used)\&. -.RE -.PP Split(arg), env\&.Split(arg) .RS 4 Returns a list of file names or other objects\&. 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, the list will be returned untouched\&. If arg is any other type of object, it will be returned as a list containing just the object\&. @@ -9946,7 +9965,7 @@ Example: .RS 4 .\} .nf -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}", @@ -9973,9 +9992,9 @@ Examples: .RS 4 .\} .nf -# 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( \*(Aqlib\&.c\*(Aq ), UNIX_ATTR="0644" ) +Tag( Library( \*(Aqlib\&.c\*(Aq ), UNIX_ATTR="0o644" ) # marks file2\&.txt to be a documentation file Tag( \*(Aqfile2\&.txt\*(Aq, DOC ) @@ -9985,86 +10004,6 @@ Tag( \*(Aqfile2\&.txt\*(Aq, DOC ) .\} .RE .PP -TargetSignatures(type), env\&.TargetSignatures(type) -.RS 4 -Note: Although it is not yet officially deprecated, use of this function is discouraged\&. See the -\fBDecider\fR -function for a more flexible and straightforward way to configure SCons\*(Aq decision\-making\&. -.sp -The -\fBTargetSignatures\fR -function tells -scons -how to decide if a target file (a file that -\fIis\fR -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"\&. -.sp -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\*(Aqt have an explicit target signature type specified for their environments\&. -.sp - -"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\*(Aqre 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\&. -.sp - -"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 -\fIolder\fR -than the last time it was used to rebuild the target file\&.) -.sp - -"source" -means -scons -decides that a target file has changed as specified by the corresponding -\fBSourceSignatures\fR -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\&. -.sp - -"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 -\fBSourceSignatures\fR -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\&. -.sp - -"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"\&. -.sp -Because the default setting is -"source", using -\fBSourceSignatures\fR -is generally preferable to -\fBTargetSignatures\fR, so that the up\-to\-date decision will be consistent for all files (or all files built with a specific construction environment)\&. Use of -\fBTargetSignatures\fR -provides specific control for how built target files affect their "downstream" dependencies\&. -.RE -.PP Tool(string, [toolpath, **kw]), env\&.Tool(string, [toolpath, **kw]) .RS 4 The @@ -10280,11 +10219,65 @@ SConscript(dirs=\*(Aqdoc\*(Aq, variant_dir=\*(Aqbuild/doc\*(Aq, duplicate=0) WhereIs(program, [path, pathext, reject]), env\&.WhereIs(program, [path, pathext, reject]) .RS 4 Searches for the specified executable -\fIprogram\fR, returning the full path name to the program if it is found, and returning None if not\&. Searches the specified -\fIpath\fR, the value of the calling environment\*(Aqs PATH (env[\*(AqENV\*(Aq][\*(AqPATH\*(Aq]), or the user\*(Aqs current external PATH (os\&.environ[\*(AqPATH\*(Aq]) by default\&. On Windows systems, searches for executable programs with any of the file extensions listed in the specified -\fIpathext\fR, the calling environment\*(Aqs PATHEXT (env[\*(AqENV\*(Aq][\*(AqPATHEXT\*(Aq]) or the user\*(Aqs current PATHEXT (os\&.environ[\*(AqPATHEXT\*(Aq]) by default\&. Will not select any path name or names in the specified +\fIprogram\fR, returning the full path name to the program if it is found, else +None\&. Searches the value of the +\fIpath\fR +keyword argument, or if +None +(the default) the value of the calling environment\*(Aqs +\fBPATH\fR +(env[\*(AqENV\*(Aq][\*(AqPATH\*(Aq])\&. If +\fIpath\fR +is +None +and the +env[\*(AqENV\*(Aq][\*(AqPATH\*(Aq] +key does not exist, the user\*(Aqs current external +\fBPATH\fR +(os\&.environ[\*(AqPATH\*(Aq]) is used as fallback\&. +.sp +On Windows systems, searches for executable programs with any of the file extensions listed in the +\fIpathext\fR +keyword argument, or if +None +(the default) the calling environment\*(Aqs +\fBPATHEXT\fR +(env[\*(AqENV\*(Aq][\*(AqPATHEXT\*(Aq])\&. The user\*(Aqs current external +\fBPATHEXT\fR +(os\&.environ[\*(AqPATHEXT\*(Aq]) is used as a fallback if +\fIpathext\fR +is +None +and the key +env[\*(AqENV\*(Aq][\*(AqPATHEXT\*(Aq] +does not exist\&. +.sp +Will not select any path name or names in the specified \fIreject\fR list, if any\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +If you would prefer to search the user\*(Aqs current external +\fBPATH\fR +(os\&.environ[\*(AqPATH\*(Aq]) 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)\&. +.sp .5v +.RE .RE .SS "SConscript Variables" .PP @@ -10865,12 +10858,12 @@ for MSI)\&. If set, the function will be called after the SCons template for the .PP CHANGED_SOURCES .RS 4 -A reserved variable name that may not be set or used in a construction environment\&. (See "Variable Substitution," below\&.) +A reserved variable name that may not be set or used in a construction environment\&. (See the manpage section "Variable Substitution" for more information)\&. .RE .PP CHANGED_TARGETS .RS 4 -A reserved variable name that may not be set or used in a construction environment\&. (See "Variable Substitution," below\&.) +A reserved variable name that may not be set or used in a construction environment\&. (See the manpage section "Variable Substitution" for more information)\&. .RE .PP CHANGELOG @@ -11188,10 +11181,6 @@ The version number of the C++ compiler\&. This may or may not be set, depending DC .RS 4 The D compiler to use\&. -.sp -The D compiler to use\&. -.sp -The D compiler to use\&. .RE .PP DCOM @@ -11199,41 +11188,21 @@ DCOM The command line used to compile a D file to an object file\&. Any options specified in the \fB$DFLAGS\fR construction variable is included on this command line\&. -.sp -The command line used to compile a D file to an object file\&. Any options specified in the -\fB$DFLAGS\fR -construction variable is included on this command line\&. -.sp -The command line used to compile a D file to an object file\&. Any options specified in the -\fB$DFLAGS\fR -construction variable is included on this command line\&. .RE .PP DDEBUG .RS 4 List of debug tags to enable when compiling\&. -.sp -List of debug tags to enable when compiling\&. -.sp -List of debug tags to enable when compiling\&. .RE .PP DDEBUGPREFIX .RS 4 DDEBUGPREFIX\&. -.sp -DDEBUGPREFIX\&. -.sp -DDEBUGPREFIX\&. .RE .PP DDEBUGSUFFIX .RS 4 DDEBUGSUFFIX\&. -.sp -DDEBUGSUFFIX\&. -.sp -DDEBUGSUFFIX\&. .RE .PP DESCRIPTION @@ -11254,55 +11223,31 @@ file\&. DFILESUFFIX .RS 4 DFILESUFFIX\&. -.sp -DFILESUFFIX\&. -.sp -DFILESUFFIX\&. .RE .PP DFLAGPREFIX .RS 4 DFLAGPREFIX\&. -.sp -DFLAGPREFIX\&. -.sp -DFLAGPREFIX\&. .RE .PP DFLAGS .RS 4 General options that are passed to the D compiler\&. -.sp -General options that are passed to the D compiler\&. -.sp -General options that are passed to the D compiler\&. .RE .PP DFLAGSUFFIX .RS 4 DFLAGSUFFIX\&. -.sp -DFLAGSUFFIX\&. -.sp -DFLAGSUFFIX\&. .RE .PP DINCPREFIX .RS 4 DINCPREFIX\&. -.sp -DINCPREFIX\&. -.sp -DINCPREFIX\&. .RE .PP DINCSUFFIX .RS 4 DLIBFLAGSUFFIX\&. -.sp -DLIBFLAGSUFFIX\&. -.sp -DLIBFLAGSUFFIX\&. .RE .PP Dir @@ -11320,118 +11265,66 @@ A function that converts a list of strings into a list of Dir instances relative DLIB .RS 4 Name of the lib tool to use for D codes\&. -.sp -Name of the lib tool to use for D codes\&. -.sp -Name of the lib tool to use for D codes\&. .RE .PP DLIBCOM .RS 4 The command line to use when creating libraries\&. -.sp -The command line to use when creating libraries\&. -.sp -The command line to use when creating libraries\&. .RE .PP DLIBDIRPREFIX .RS 4 DLIBLINKPREFIX\&. -.sp -DLIBLINKPREFIX\&. -.sp -DLIBLINKPREFIX\&. .RE .PP DLIBDIRSUFFIX .RS 4 DLIBLINKSUFFIX\&. -.sp -DLIBLINKSUFFIX\&. -.sp -DLIBLINKSUFFIX\&. .RE .PP DLIBFLAGPREFIX .RS 4 DLIBFLAGPREFIX\&. -.sp -DLIBFLAGPREFIX\&. -.sp -DLIBFLAGPREFIX\&. .RE .PP DLIBFLAGSUFFIX .RS 4 DLIBFLAGSUFFIX\&. -.sp -DLIBFLAGSUFFIX\&. -.sp -DLIBFLAGSUFFIX\&. .RE .PP DLIBLINKPREFIX .RS 4 DLIBLINKPREFIX\&. -.sp -DLIBLINKPREFIX\&. -.sp -DLIBLINKPREFIX\&. .RE .PP DLIBLINKSUFFIX .RS 4 DLIBLINKSUFFIX\&. -.sp -DLIBLINKSUFFIX\&. -.sp -DLIBLINKSUFFIX\&. .RE .PP DLINK .RS 4 Name of the linker to use for linking systems including D sources\&. -.sp -Name of the linker to use for linking systems including D sources\&. -.sp -Name of the linker to use for linking systems including D sources\&. .RE .PP DLINKCOM .RS 4 The command line to use when linking systems including D sources\&. -.sp -The command line to use when linking systems including D sources\&. -.sp -The command line to use when linking systems including D sources\&. .RE .PP DLINKFLAGPREFIX .RS 4 DLINKFLAGPREFIX\&. -.sp -DLINKFLAGPREFIX\&. -.sp -DLINKFLAGPREFIX\&. .RE .PP DLINKFLAGS .RS 4 List of linker flags\&. -.sp -List of linker flags\&. -.sp -List of linker flags\&. .RE .PP DLINKFLAGSUFFIX .RS 4 DLINKFLAGSUFFIX\&. -.sp -DLINKFLAGSUFFIX\&. -.sp -DLINKFLAGSUFFIX\&. .RE .PP DOCBOOK_DEFAULT_XSL_EPUB @@ -11594,10 +11487,6 @@ saxon\-xslt, respectively\&. DPATH .RS 4 List of paths to search for import modules\&. -.sp -List of paths to search for import modules\&. -.sp -List of paths to search for import modules\&. .RE .PP DRPATHPREFIX @@ -11633,28 +11522,16 @@ The list of suffixes of files that will be scanned for imported D package files\ DVERPREFIX .RS 4 DVERPREFIX\&. -.sp -DVERPREFIX\&. -.sp -DVERPREFIX\&. .RE .PP DVERSIONS .RS 4 List of version tags to enable when compiling\&. -.sp -List of version tags to enable when compiling\&. -.sp -List of version tags to enable when compiling\&. .RE .PP DVERSUFFIX .RS 4 DVERSUFFIX\&. -.sp -DVERSUFFIX\&. -.sp -DVERSUFFIX\&. .RE .PP DVIPDF @@ -13295,6 +13172,13 @@ The string displayed when building loadable modules\&. If this is not set, then (the command line) is displayed\&. .RE .PP +LDMODULEEMITTER +.RS 4 +Contains the emitter specification for the +\fBLoadableModule\fR +builder\&. The manpage section "Builder Objects" contains general information on specifying emitters\&. +.RE +.PP LDMODULEFLAGS .RS 4 General user options passed to the linker for building loadable modules\&. @@ -13436,7 +13320,9 @@ variable is automatically generated\&. .PP LIBEMITTER .RS 4 -TODO +Contains the emitter specification for the +\fBStaticLibrary\fR +builder\&. The manpage section "Builder Objects" contains general information on specifying emitters\&. .RE .PP _LIBFLAGS @@ -13733,7 +13619,7 @@ The command line used to pass files to the Microsoft IDL compiler\&. .PP MIDLCOMSTR .RS 4 -The string displayed when the Microsoft IDL copmiler is called\&. If this is not set, then +The string displayed when the Microsoft IDL compiler is called\&. If this is not set, then \fB$MIDLCOM\fR (the command line) is displayed\&. .RE @@ -14659,7 +14545,9 @@ from .PP PROGEMITTER .RS 4 -TODO +Contains the emitter specification for the +\fBProgram\fR +builder\&. The manpage section "Builder Objects" contains general information on specifying emitters\&. .RE .PP PROGPREFIX @@ -15115,7 +15003,7 @@ construction variable\&. .PP SCANNERS .RS 4 -A list of the available implicit dependency scanners\&. New file scanners may be added by appending to this list, although the more flexible approach is to associate scanners with a specific Builder\&. See the sections "Builder Objects" and "Scanner Objects," below, for more information\&. +A list of the available implicit dependency scanners\&. New file scanners may be added by appending to this list, although the more flexible approach is to associate scanners with a specific Builder\&. See the manpage sections "Builder Objects" and "Scanner Objects" for more information\&. .RE .PP SCONS_HOME @@ -15206,19 +15094,11 @@ Options that are passed to the C++ compiler to generate shared\-library objects\ SHDC .RS 4 The name of the compiler to use when compiling D source destined to be in a shared objects\&. -.sp -The name of the compiler to use when compiling D source destined to be in a shared objects\&. -.sp -The name of the compiler to use when compiling D source destined to be in a shared objects\&. .RE .PP SHDCOM .RS 4 The command line to use when compiling code to be part of shared objects\&. -.sp -The command line to use when compiling code to be part of shared objects\&. -.sp -The command line to use when compiling code to be part of shared objects\&. .RE .PP SHDLIBVERSION @@ -15234,28 +15114,16 @@ SHDLIBVERSIONFLAGS\&. SHDLINK .RS 4 The linker to use when creating shared objects for code bases include D sources\&. -.sp -The linker to use when creating shared objects for code bases include D sources\&. -.sp -The linker to use when creating shared objects for code bases include D sources\&. .RE .PP SHDLINKCOM .RS 4 The command line to use when generating shared objects\&. -.sp -The command line to use when generating shared objects\&. -.sp -The command line to use when generating shared objects\&. .RE .PP SHDLINKFLAGS .RS 4 The list of flags to use when generating a shared object\&. -.sp -The list of flags to use when generating a shared object\&. -.sp -The list of flags to use when generating a shared object\&. .RE .PP SHELL @@ -15597,7 +15465,9 @@ The string displayed when a Fortran source file is compiled to a shared\-library .PP SHLIBEMITTER .RS 4 -TODO +Contains the emitter specification for the +\fBSharedLibrary\fR +builder\&. The manpage section "Builder Objects" contains general information on specifying emitters\&. .RE .PP SHLIBNOVERSIONSYMLINKS @@ -15627,7 +15497,7 @@ The suffix used for shared library file names\&. .PP SHLIBVERSION .RS 4 -When this construction variable is defined, a versioned shared library is created by +When this construction variable is defined, a versioned shared library is created by the \fBSharedLibrary\fR builder\&. This activates the \fB$_SHLIBVERSIONFLAGS\fR @@ -15640,16 +15510,6 @@ versions should exist as alpha\-numeric, decimal\-delimited values as defined by values include \*(Aq1\*(Aq, \*(Aq1\&.2\&.3\*(Aq, and \*(Aq1\&.2\&.gitaa412c8b\*(Aq\&. .RE .PP -SHLIBVERSIONFLAGS -.RS 4 -Extra flags added to -\fB$SHLINKCOM\fR -when building versioned -\fBSharedLibrary\fR\&. These flags are only used when -\fB$SHLIBVERSION\fR -is set\&. -.RE -.PP _SHLIBVERSIONFLAGS .RS 4 This macro automatically introduces extra flags to @@ -15666,6 +15526,16 @@ and some extra dynamically generated options (such as \-Wl,\-soname=$_SHLIBSONAME\&. It is unused by "plain" (unversioned) shared libraries\&. .RE .PP +SHLIBVERSIONFLAGS +.RS 4 +Extra flags added to +\fB$SHLINKCOM\fR +when building versioned +\fBSharedLibrary\fR\&. These flags are only used when +\fB$SHLIBVERSION\fR +is set\&. +.RE +.PP SHLINK .RS 4 The linker for programs that use shared libraries\&. @@ -15741,7 +15611,7 @@ linker tool\&. .PP SOURCE .RS 4 -A reserved variable name that may not be set or used in a construction environment\&. (See "Variable Substitution," below\&.) +A reserved variable name that may not be set or used in a construction environment\&. (See the manpage section "Variable Substitution" for more information)\&. .RE .PP SOURCE_URL @@ -15753,7 +15623,7 @@ field in the controlling information for Ipkg and RPM packages\&. .PP SOURCES .RS 4 -A reserved variable name that may not be set or used in a construction environment\&. (See "Variable Substitution," below\&.) +A reserved variable name that may not be set or used in a construction environment\&. (See the manpage section "Variable Substitution" for more information)\&. .RE .PP SPAWN @@ -16010,7 +15880,7 @@ General options passed to the tar archiver\&. .PP TARGET .RS 4 -A reserved variable name that may not be set or used in a construction environment\&. (See "Variable Substitution," below\&.) +A reserved variable name that may not be set or used in a construction environment\&. (See the manpage section "Variable Substitution" for more information)\&. .RE .PP TARGET_ARCH @@ -16043,7 +15913,7 @@ The name of the target operating system for the compiled objects created by this .PP TARGETS .RS 4 -A reserved variable name that may not be set or used in a construction environment\&. (See "Variable Substitution," below\&.) +A reserved variable name that may not be set or used in a construction environment\&. (See the manpage section "Variable Substitution" for more information)\&. .RE .PP TARSUFFIX @@ -16127,12 +15997,12 @@ A list of the names of the Tool specifications that are part of this constructio .PP UNCHANGED_SOURCES .RS 4 -A reserved variable name that may not be set or used in a construction environment\&. (See "Variable Substitution," below\&.) +A reserved variable name that may not be set or used in a construction environment\&. (See the manpage section "Variable Substitution" for more information)\&. .RE .PP UNCHANGED_TARGETS .RS 4 -A reserved variable name that may not be set or used in a construction environment\&. (See "Variable Substitution," below\&.) +A reserved variable name that may not be set or used in a construction environment\&. (See the manpage section "Variable Substitution" for more information)\&. .RE .PP VENDOR @@ -16847,14 +16717,16 @@ method of the construction environment: .RS 4 .\} .nf -dict = env\&.Dictionary() -dict["CC"] = "cc" +cvars = env\&.Dictionary() +cvars["CC"] = "cc" .fi .if n \{\ .RE .\} .PP -or using the [] operator: +or using the key lookup operator +[] +directly on the construction environment: .sp .if n \{\ .RS 4 @@ -17789,7 +17661,7 @@ The \fIFile\fR and \fIDir\fR -Nodes, respectively\&. python objects, respectively\&. Those objects have several user\-visible attributes and methods that are often useful: +Nodes, respectively\&. Python objects, respectively\&. Those objects have several user\-visible attributes and methods that are often useful: .PP path .RS 4 @@ -17917,7 +17789,7 @@ incl = Dir(\*(Aqinclude\*(Aq) f = incl\&.File(\*(Aqheader\&.h\*(Aq) # Get a Node for a subdirectory within a directory -dist = Dir(\*(Aqproject\-3\&.2\&.1) +dist = Dir(\*(Aqproject\-3\&.2\&.1\*(Aq) src = dist\&.Dir(\*(Aqsrc\*(Aq) # Get a Node for a file in the same directory @@ -18187,7 +18059,7 @@ b = Builder("my_build < $TARGET > $SOURCE", .PP multi .RS 4 -Specifies whether this builder is allowed to be called multiple times for 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 builder with the target\&. +Specifies whether this builder is allowed to be called multiple times for 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 additional environment overrides, or associate a different builder with the target\&. .RE .PP env @@ -18534,12 +18406,12 @@ a = Action(build_it, varlist=[\*(AqXXX\*(Aq]) .\} .PP The -\fBAction\fR() global function can be passed the following optional keyword arguments to modify the Action object\*(Aqs behavior: +Action +global function can be passed the following optional keyword arguments to modify the Action object\*(Aqs behavior: .PP -\fBchdir\fR -The -\fBchdir\fR -keyword argument specifies that scons will execute the action after changing to the specified directory\&. If the + +\fIchdir\fR +specifies that scons will execute the action after changing to the specified directory\&. If the \fBchdir\fR argument is a string or a directory Node, scons will change to the specified directory\&. If the \fBchdir\fR @@ -18568,11 +18440,9 @@ a = Action("build < ${SOURCE\&.file} > ${TARGET\&.file}", .RE .\} .PP -\fBexitstatfunc\fR -The -\fBAction\fR() global function also takes an -\fBexitstatfunc\fR -keyword argument which specifies a function that is passed the exit status (or return value) from the specified action and can return an arbitrary or modified value\&. This can be used, for example, to specify that an Action object\*(Aqs return value should be ignored under special conditions and SCons should, therefore, consider that the action always suceeds: + +\fIexitstatfunc\fR +specifies a function that is passed the exit status (or return value) from the specified action and can return an arbitrary or modified value\&. This can be used, for example, to specify that an Action object\*(Aqs return value should be ignored under special conditions and SCons should, therefore, consider that the action always suceeds: .sp .if n \{\ .RS 4 @@ -18588,12 +18458,11 @@ a = Action("build < ${SOURCE\&.file} > ${TARGET\&.file}", .RE .\} .PP + +\fIbatch_key\fR +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 by passing multiple source files to a single invocation of a compiler such as Microsoft\*(Aqs Visual C / C++ compiler\&.) If the \fBbatch_key\fR -The -\fBbatch_key\fR -keyword argument can be used to specify 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 by passing multiple source files to a single invocation of a compiler such as Microsoft\*(Aqs Visual C / C++ compiler\&.) If the -\fBbatch_key\fR -argument is any non\-False, non\-callable Python value, the configured Action object will cause +argument evaluates True and is not a callable object, the configured Action object will cause \fBscons\fR to collect all targets built with the Action object and configured with the same construction environment into single invocations of the Action object\*(Aqs command line or function\&. Command lines will typically want to use the \fBCHANGED_SOURCES\fR @@ -18617,7 +18486,7 @@ The \fBbatch_key\fR argument may also be a callable function that returns a key that will be used to identify different "batches" of target files to be collected for batch building\&. A \fBbatch_key\fR -function must take the following arguments: +function must accept the following arguments: .PP action .RS 4 @@ -18695,7 +18564,7 @@ Execute(Touch(\*(Aqfile\*(Aq)) .PP Second, you can use these functions to supply Actions in a list for use by the \fBCommand\fR -method\&. This can allow you to perform more complicated sequences of file manipulation without relying on platform\-specific external commands: that +method\&. This can allow you to perform more complicated sequences of file manipulation without relying on platform\-specific external commands: .sp .if n \{\ .RS 4 @@ -18724,11 +18593,11 @@ which can be octal or string, similar to the bash command\&. Examples: .RS 4 .\} .nf -Execute(Chmod(\*(Aqfile\*(Aq, 0755)) +Execute(Chmod(\*(Aqfile\*(Aq, 0o755)) env\&.Command(\*(Aqfoo\&.out\*(Aq, \*(Aqfoo\&.in\*(Aq, [Copy(\*(Aq$TARGET\*(Aq, \*(Aq$SOURCE\*(Aq), - Chmod(\*(Aq$TARGET\*(Aq, 0755)]) + Chmod(\*(Aq$TARGET\*(Aq, 0o755)]) Execute(Chmod(\*(Aqfile\*(Aq, "ugo+w")) @@ -18857,9 +18726,9 @@ env\&.Command(\*(Aqmarker\*(Aq, \*(Aqinput_file\*(Aq, .PP Before executing a command, \fBscons\fR -performs construction variable interpolation on the strings that make up the command line of builders\&. Variables are introduced by a -\fB$\fR -prefix\&. Besides construction variables, scons provides the following variables for each command execution: +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 regular construction variables, scons provides the following special variables for each command execution: .PP CHANGED_SOURCES .RS 4 @@ -18903,11 +18772,15 @@ UNCHANGED_TARGETS The file names of all targets that would be built from sources that have \fInot\fR changed since the target was last built\&. -.sp -(Note that the above variables are reserved and may not be set in a construction environment\&.) .RE .PP -For example, given the construction variable CC=\*(Aqcc\*(Aq, targets=[\*(Aqfoo\*(Aq], and sources=[\*(Aqfoo\&.c\*(Aq, \*(Aqbar\&.c\*(Aq]: +Note that the above variables are reserved and may not be set in a construction environment\&. +.PP +For example, given the construction variables +CC=\*(Aqcc\*(Aq, +targets=[\*(Aqfoo\*(Aq] +and +sources=[\*(Aqfoo\&.c\*(Aq, \*(Aqbar\&.c\*(Aq]: .sp .if n \{\ .RS 4 @@ -18931,7 +18804,9 @@ cc \-c \-o foo foo\&.c bar\&.c .RE .\} .PP -Variable names may be surrounded by curly braces ({}) to separate the name from the trailing characters\&. Within the curly braces, a variable name may have a Python slice subscript appended to select one or more items from a list\&. In the previous example, the string: +Variable names may be surrounded by curly braces +\fB{ }\fR +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\&. In the previous example, the string: .sp .if n \{\ .RS 4 @@ -19048,15 +18923,29 @@ ${SOURCE\&.rsrcdir} => /usr/repository/src .PP Note that curly braces braces may also be used to enclose arbitrary Python code to be evaluated\&. (In fact, this is how the above modifiers are substituted, they are simply attributes of the Python objects that represent TARGET, SOURCES, etc\&.) See the section "Python Code Substitution" below, for more thorough examples of how this can be used\&. .PP -Lastly, a variable name may be a callable Python function associated with a construction variable in the environment\&. The function should take four arguments: +Lastly, a variable name may be a callable Python function associated with a construction variable in the environment\&. The function should accept four arguments: +.PP \fItarget\fR -\- a list of target nodes, +.RS 4 +a list of target nodes +.RE +.PP \fIsource\fR -\- a list of source nodes, +.RS 4 +a list of source nodes +.RE +.PP \fIenv\fR -\- the construction environment, +.RS 4 +the construction environment +.RE +.PP \fIfor_signature\fR -\- a Boolean value that specifies whether the function is being called for generating a build signature\&. SCons will insert whatever the called function returns into the expanded string: +.RS 4 +a Boolean value that specifies whether the function is being called for generating a build signature\&. +.RE +.PP +SCons will insert whatever the called function returns into the expanded string: .sp .if n \{\ .RS 4 @@ -19145,9 +19034,13 @@ echo Last build occurred \&. > $TARGET .\} .SS "Python Code Substitution" .PP -Any python code within -\fB${\fR\-\fB}\fR -pairs gets evaluated by python \*(Aqeval\*(Aq, with the python globals set to the current environment\*(Aqs set of construction variables\&. So in the following case: +Any Python code within curly braces +\fB{ }\fR +and introduced by the variable prefix +\fB$\fR +gets evaluated by the Python +\fBeval\fR +statement, with the Python globals set to the current environment\*(Aqs set of construction variables\&. So in the following case: .sp .if n \{\ .RS 4 @@ -19185,9 +19078,19 @@ echo BAR > foo\&.out .RE .\} .PP -according to the current value of env[\*(AqCOND\*(Aq] when the command is executed\&. The evaluation occurs when the target is being built, not when the SConscript is being read\&. So if env[\*(AqCOND\*(Aq] is changed later in the SConscript, the final value will be used\&. +according to the current value of +env[\*(AqCOND\*(Aq] +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[\*(AqCOND\*(Aq] +is changed later in the SConscript, the final value will be used\&. .PP -Here\*(Aqs 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 separated by spaces\&. +Here\*(Aqs a more interesting example\&. Note that all of +\fBCOND\fR, +\fBFOO\fR, and +\fBBAR\fR +are construction variables, and their values are substituted into the final command\&. +\fBFOO\fR +is a list, so its elements are interpolated separated by spaces\&. .sp .if n \{\ .RS 4 @@ -19260,7 +19163,7 @@ The \fBenv\fR argument is the construction environment for the scan\&. Fetch values from it using the \fBenv\&.Dictionary()\fR -method\&. +method or using the key lookup operator directly on the construction environment\&. .sp The \fBpath\fR @@ -19376,9 +19279,17 @@ suffix as a Fortran source file that should be run through the C preprocessor\&. .SS "Windows: Cygwin Tools and Cygwin Python vs\&. Windows Pythons" .PP -Cygwin supplies a set of tools and utilities that let users work on a Windows system using a more POSIX\-like environment\&. The Cygwin tools, including Cygwin Python, 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 to an equivalent Windows pathname of C:/mydir (equivalent to C:\emydir)\&. +Cygwin supplies a set of tools and utilities that let users work on a Windows system using a more POSIX\-like environment\&. The Cygwin tools, including Cygwin Python, 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 +to an equivalent Windows pathname of +C:/mydir +(equivalent to +C:\emydir)\&. .PP -Versions of Python that are built for native Windows execution, 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) may yield unpredictable results\&. "Mixing and matching" in this way can be made to work, but it requires careful attention to the use of path names in your SConscript files\&. +Versions of Python that are built for native Windows execution, 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 +\fBgcc\fR, +\fBbison\fR, and +\fBflex\fR) may yield unpredictable results\&. "Mixing and matching" in this way can be made to work, but it requires careful attention to the use of path names in your SConscript files\&. .PP In practice, users can sidestep the issue by adopting the following rules: When using gcc, use the Cygwin\-supplied Python interpreter to run SCons; when using Microsoft Visual C/C++ (or some other Windows compiler) use the python\&.org or ActiveState version of Python to run SCons\&. .SS "Windows: scons\&.bat file" @@ -19582,7 +19493,7 @@ env[\*(AqBUILDERS][\*(AqPDFBuilder\*(Aq] = bld .\} .SS "Defining Your Own Scanner Object" .PP -The following example shows an extremely simple scanner (the +The following example shows adding an extremely simple scanner (the \fBkfile_scan\fR() function) that doesn\*(Aqt use a search path at all and simply returns the file names present on any \fBinclude\fR lines in the scanned file\&. This would implicitly assume that all included files live in the top\-level directory: @@ -19604,8 +19515,10 @@ kscan = Scanner(name = \*(Aqkfile\*(Aq, function = kfile_scan, argument = None, skeys = [\*(Aq\&.k\*(Aq]) -scanners = Environment()\&.Dictionary(\*(AqSCANNERS\*(Aq) -env = Environment(SCANNERS = scanners + [kscan]) + +scanners = DefaultEnvironment()[\*(AqSCANNERS\*(Aq] +scanners\&.append(kscan) +env = Environment(SCANNERS=scanners) env\&.Command(\*(Aqfoo\*(Aq, \*(Aqfoo\&.k\*(Aq, \*(Aqkprocess < $SOURCES > $TARGET\*(Aq) @@ -19621,7 +19534,7 @@ It is important to note that you have to return a list of File nodes from the sc \fBFile()\fR function of your current Environment in order to create nodes on the fly from a sequence of file names with relative paths\&. .PP -Here is a similar but more complete example that searches a path of directories (specified as the +Here is a similar but more complete example that adds a scanner which searches a path of directories (specified as the \fBMYPATH\fR construction variable) for files that actually exist: .sp @@ -19647,15 +19560,16 @@ def my_scan(node, env, path, arg): break return env\&.File(results) -scanner = Scanner(name = \*(Aqmyscanner\*(Aq, - function = my_scan, - argument = None, - skeys = [\*(Aq\&.x\*(Aq], - path_function = FindPathDirs(\*(AqMYPATH\*(Aq) +scanner = Scanner(name=\*(Aqmyscanner\*(Aq, + function=my_scan, + argument=None, + skeys=[\*(Aq\&.x\*(Aq], + path_function=FindPathDirs(\*(AqMYPATH\*(Aq) ) -scanners = Environment()\&.Dictionary(\*(AqSCANNERS\*(Aq) -env = Environment(SCANNERS = scanners + [scanner], - MYPATH = [\*(Aqincs\*(Aq]) + +scanners = DefaultEnvironment()[\*(AqSCANNERS\*(Aq] +scanners\&.append(scanner) +env = Environment(SCANNERS=scanners, MYPATH=[\*(Aqincs\*(Aq]) env\&.Command(\*(Aqfoo\*(Aq, \*(Aqfoo\&.x\*(Aq, \*(Aqxprocess < $SOURCES > $TARGET\*(Aq) .fi @@ -19667,8 +19581,7 @@ The \fBFindPathDirs\fR() function used in the previous example returns a function (actually a callable Python object) that will return a list of directories specified in the \fB$MYPATH\fR construction variable\&. It lets SCons detect the file -\fBincs/foo\&.inc\fR -, even if +\fBincs/foo\&.inc\fR, even if \fBfoo\&.x\fR contains the line \fBinclude foo\&.inc\fR @@ -19689,11 +19602,11 @@ def pf(env, dir, target, source, arg): results\&.append(top_dir + os\&.sep + p) return results -scanner = Scanner(name = \*(Aqmyscanner\*(Aq, - function = my_scan, - argument = None, - skeys = [\*(Aq\&.x\*(Aq], - path_function = pf +scanner = Scanner(name=\*(Aqmyscanner\*(Aq, + function=my_scan, + argument=None, + skeys=[\*(Aq\&.x\*(Aq], + path_function=pf ) .fi .if n \{\ @@ -19792,7 +19705,7 @@ Note the use of the Export() method to set the "cppdefines" variable to a differ .nf SConstruct: - env = Environment(LIBPATH = [\*(Aq#libA\*(Aq, \*(Aq#libB\*(Aq]) + env = Environment(LIBPATH=[\*(Aq#libA\*(Aq, \*(Aq#libB\*(Aq]) Export(\*(Aqenv\*(Aq) SConscript(\*(AqlibA/SConscript\*(Aq) SConscript(\*(AqlibB/SConscript\*(Aq) @@ -19811,7 +19724,7 @@ libB/SConscript: Main/SConscript: Import(\*(Aqenv\*(Aq) - e = env\&.Copy(LIBS = [\*(Aqa\*(Aq, \*(Aqb\*(Aq]) + e = env\&.Clone(LIBS=[\*(Aqa\*(Aq, \*(Aqb\*(Aq]) e\&.Program(\*(Aqfoo\*(Aq, Split(\*(Aqm1\&.c m2\&.c m3\&.c\*(Aq)) .fi .if n \{\ @@ -19972,14 +19885,49 @@ env\&.Program(\*(AqMyApp\*(Aq, [\*(AqFoo\&.cpp\*(Aq, \*(AqBar\&.cpp\*(Aq]) For more information see the document for the PDB construction variable\&. .SH "ENVIRONMENT" .PP +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: +.PP SCONS_LIB_DIR .RS 4 -Specifies the directory that contains the SCons Python module directory (e\&.g\&. /home/aroach/scons\-src\-0\&.01/src/engine)\&. +Specifies the directory that contains the +scons +Python module directory (for example, +/home/aroach/scons\-src\-0\&.01/src/engine)\&. .RE .PP SCONSFLAGS .RS 4 -A string of options that will be used by scons in addition to those passed on the command line\&. +A string of options that will be used by +scons +in addition to those passed on the command line\&. +.RE +.PP +SCONS_CACHE_MSVC_CONFIG +.RS 4 +(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\&. +.sp +If set to a True\-like value ("1", +"true" +or +"True") will cache to a file named +\&.scons_msvc_cache +in the user\*(Aqs home directory\&. If set to a pathname, will use that pathname for the cache\&. +.sp +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\&. +.sp +Since +scons +3\&.1\&. .RE .SH "SEE ALSO" .PP @@ -19991,7 +19939,11 @@ Design Document, source code\&. .SH "AUTHORS" .PP -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\&. .SH "AUTHORS" .PP \fBSteven Knight\fR |