summaryrefslogtreecommitdiff
path: root/scons.1
diff options
context:
space:
mode:
authorLuca Falavigna <dktrkranz@debian.org>2011-09-10 10:58:07 +0200
committerLuca Falavigna <dktrkranz@debian.org>2011-09-10 10:58:07 +0200
commit7d0cf46e8ad5acb1028a391255a9b84d2f6d3cdf (patch)
treebcf7a54e7f8ad198e6d31adf0fffc0e0c74469e4 /scons.1
parentde2237c3cf3dd7dcc0a914f78348fdb6d821c296 (diff)
parent9dc7be6c34e2bda6d0d96a450bb8eee03b277ba3 (diff)
Merge commit 'upstream/2.1.0'
Diffstat (limited to 'scons.1')
-rw-r--r--scons.12268
1 files changed, 1137 insertions, 1131 deletions
diff --git a/scons.1 b/scons.1
index 878980e..ee321d7 100644
--- a/scons.1
+++ b/scons.1
@@ -1,4 +1,4 @@
-.\" Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+.\" Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
.\"
.\" Permission is hereby granted, free of charge, to any person obtaining
.\" a copy of this software and associated documentation files (the
@@ -19,9 +19,9 @@
.\" OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
.\" WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
.\"
-.\" doc/man/scons.1 5134 2010/08/16 23:02:40 bdeegan
+.\" doc/man/scons.1 5357 2011/09/09 21:31:03 bdeegan
.\"
-.TH SCONS 1 "August 2010"
+.TH SCONS 1 "September 2011"
.\" ES - Example Start - indents and turns off line fill
.rm ES
.de ES
@@ -100,17 +100,17 @@ file,
.B scons
looks for a directory named
.I site_scons
-in the directory containing the
+in various system directories (see below) and the directory containing the
.I SConstruct
-file; if it exists,
+file; for each of those dirs which exists,
.I site_scons
-is added to sys.path,
+is prepended to sys.path,
the file
.IR site_scons/site_init.py ,
is evaluated if it exists,
and the directory
.I site_scons/site_tools
-is added to the default toolpath if it exist.
+is prepended to the default toolpath if it exists.
See the
.I --no-site-dir
and
@@ -601,6 +601,12 @@ have been compiled with optimization
files).
.TP
+--debug=duplicate
+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.
+
+.TP
--debug=dtree
A synonym for the newer
.B --tree=derived
@@ -664,6 +670,18 @@ Re-run SCons under the control of the
Python debugger.
.TP
+--debug=prepare
+Print a line each time any target (internal or external)
+is prepared for building.
+.B scons
+prints this for each target it considers, even if that
+target is up to date (see also --debug=explain).
+This can help debug problems with targets that aren't being
+built; it shows whether
+.B scons
+is at least considering them or not.
+
+.TP
--debug=presub
Print the raw command line used to build each target
before the construction environment variables are substituted.
@@ -1095,13 +1113,13 @@ any out-of-date target files, but do not execute the commands.
.RI --no-site-dir
Prevents the automatic addition of the standard
.I site_scons
-dir to
+dirs to
.IR sys.path .
Also prevents loading the
.I site_scons/site_init.py
-module if it exists, and prevents adding
+modules if they exist, and prevents adding their
.I site_scons/site_tools
-to the toolpath.
+dirs to the toolpath.
.\" .TP
.\" .RI -o " file" ", --old-file=" file ", --assume-old=" file
@@ -1182,7 +1200,7 @@ Ignored for compatibility with GNU
.RI --site-dir= dir
Uses the named dir as the site dir rather than the default
.I site_scons
-dir. This dir will get prepended to
+dirs. This dir will get prepended to
.IR sys.path ,
the module
.IR dir /site_init.py
@@ -1190,6 +1208,48 @@ will get loaded if it exists, and
.IR dir /site_tools
will get added to the default toolpath.
+The default set of
+.I site_scons
+dirs used when
+.I --site-dir
+is not specified depends on the system platform, as follows. Note
+that the directories are examined in the order given, from most
+generic to most specific, so the last-executed site_init.py file is
+the most specific one (which gives it the chance to override
+everything else), and the dirs are prepended to the paths, again so
+the last dir examined comes first in the resulting path.
+
+.IP "Windows:"
+.nf
+ %ALLUSERSPROFILE/Application Data/scons/site_scons
+ %USERPROFILE%/Local Settings/Application Data/scons/site_scons
+ %APPDATA%/scons/site_scons
+ %HOME%/.scons/site_scons
+ ./site_scons
+.fi
+.IP "Mac OS X:"
+.nf
+ /Library/Application Support/SCons/site_scons
+ /opt/local/share/scons/site_scons (for MacPorts)
+ /sw/share/scons/site_scons (for Fink)
+ $HOME/Library/Application Support/SCons/site_scons
+ $HOME/.scons/site_scons
+ ./site_scons
+.fi
+.IP "Solaris:"
+.nf
+ /opt/sfw/scons/site_scons
+ /usr/share/scons/site_scons
+ $HOME/.scons/site_scons
+ ./site_scons
+.fi
+.IP "Linux, HPUX, and other Posix-like systems:"
+.nf
+ /usr/share/scons/site_scons
+ $HOME/.scons/site_scons
+ ./site_scons
+.fi
+
.TP
.RI --stack-size= KILOBYTES
Set the size stack used to run threads to
@@ -2214,7 +2274,7 @@ provides the following builder methods:
.IP env.CFile()
Builds a C source file given a lex (\fB.l\fP)
or yacc (\fB.y\fP) input file.
-The suffix specified by the $CFILESUFFIX construction variable
+The suffix specified by the \fB$CFILESUFFIX\fP construction variable
(\fB.c\fP by default)
is automatically added to the target
if it is not already present.
@@ -2228,12 +2288,22 @@ env.CFile(target = 'bar', source = 'bar.y')
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.IP Command()
+.IP env.Command()
+The \fBCommand\fP() "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 \fBCommand\fP() function description
+for the calling syntax and details.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IP CXXFile()
.IP env.CXXFile()
Builds a C++ source file given a lex (\fB.ll\fP)
or yacc (\fB.yy\fP)
input file.
-The suffix specified by the $CXXFILESUFFIX construction variable
+The suffix specified by the \fB$CXXFILESUFFIX\fP construction variable
(\fB.cc\fP by default)
is automatically added to the target
if it is not already present.
@@ -2260,24 +2330,24 @@ if the string
or
.B \\documentstyle
is found, the file is assumed to be a LaTeX file and
-the target is built by invoking the $LATEXCOM command line;
-otherwise, the $TEXCOM command line is used.
+the target is built by invoking the \fB$LATEXCOM\fP command line;
+otherwise, the \fB$TEXCOM\fP command line is used.
If the file is a LaTeX file,
the
.BR DVI ()
builder method will also examine the contents
of the
.B .aux
-file and invoke the $BIBTEX command line
+file and invoke the \fB$BIBTEX\fP command line
if the string
.B bibdata
is found,
-start $MAKEINDEX to generate an index if a
+start \fB$MAKEINDEX\fP to generate an index if a
.B .ind
file is found
and will examine the contents
.B .log
-file and re-run the $LATEXCOM command
+file and re-run the \fB$LATEXCOM\fP command
if the log file says it is necessary.
The suffix \fB.dvi\fP
@@ -2339,12 +2409,12 @@ Any \fB.java\fP files in the source list
will be compiled to \fB.class\fP files
by calling the \fBJava\fP() Builder.
-If the $JARCHDIR value is set, the
+If the \fB$JARCHDIR\fP value is set, the
.B jar
command will change to the specified directory using the
.B \-C
option.
-If $JARCHDIR is not set explicitly,
+If \fB$JARCHDIR\fP is not set explicitly,
&SCons; will use the top of any subdirectory tree
in which Java \fB.class\fP
were built by the \fBJava\fP() Builder.
@@ -2445,7 +2515,7 @@ or the objects returned from the
builder method.
If the construction variable
-$JAVACLASSDIR
+.B $JAVACLASSDIR
is set, either in the environment
or in the call to the
.BR JavaH ()
@@ -2491,7 +2561,7 @@ this creates a loadable module bundle.
.IP M4()
.IP env.M4()
Builds an output file from an M4 input file.
-This uses a default $M4FLAGS value of
+This uses a default \fB$M4FLAGS\fP value of
.BR \-E ,
which considers all warnings to be fatal
and stops on the first warning
@@ -2507,7 +2577,7 @@ env.M4(target = 'foo.c', source = 'foo.c.m4')
.IP env.Moc()
Builds an output file from a moc input file. Moc input files are either
header files or cxx files. This builder is only available after using the
-tool 'qt'. See the $QTDIR variable for more information.
+tool 'qt'. See the \fB$QTDIR\fP variable for more information.
Example:
.ES
@@ -2524,7 +2594,7 @@ and by default builds a solution file as well.
This builds a Visual Studio project file, based on the version of
Visual Studio that is configured (either the latest installed version,
or the version specified by
-$MSVS_VERSION
+.B $MSVS_VERSION
in the Environment constructor).
For Visual Studio 6, it will generate a
.B .dsp
@@ -2563,7 +2633,7 @@ These are currently limited to
and
.BR misc .
These are pretty self-explanatory, but it should be noted that these
-lists are added to the $SOURCES construction variable as strings,
+lists are added to the \fB$SOURCES\fP construction variable as strings,
NOT as SCons File Nodes. This is because they represent file
names to be added to the project file, not the source files used to
build the project file.
@@ -2584,7 +2654,7 @@ file.
The correct
suffix for the version of Visual Studio must be used,
but the
-$MSVSPROJECTSUFFIX
+.B $MSVSPROJECTSUFFIX
construction variable
will be defined to the correct value (see example below).
@@ -2639,7 +2709,7 @@ displayed in the Visual Studio console output window.
This can be remedied by adding the
Visual C/C++
.B /FC
-compiler option to the $CCFLAGS variable
+compiler option to the \fB$CCFLAGS\fP variable
so that the compiler will print
the full path name of any
files that cause compilation errors.
@@ -2675,7 +2745,7 @@ This builds a Visual Studio solution file,
based on the version of Visual Studio that is configured
(either the latest installed version,
or the version specified by
-$MSVS_VERSION
+.B $MSVS_VERSION
in the construction environment).
For Visual Studio 6, it will generate a
.B .dsw
@@ -2690,7 +2760,7 @@ The following values must be specified:
.BR target :
The name of the target .dsw or .sln file. The correct
suffix for the version of Visual Studio must be used, but the value
-$MSVSSOLUTIONSUFFIX
+.B $MSVSSOLUTIONSUFFIX
will be defined to the correct value (see example below).
.BR variant :
@@ -2710,8 +2780,6 @@ environment variable in form of files, but rather as strings. This
is because they represent file names to be added to the solution file,
not the source files used to build the solution file.
-(NOTE: Currently only one project is supported per solution.)
-
Example Usage:
.ES
@@ -2746,7 +2814,7 @@ The mandatory ones will complain if they were not specified.
They vary depending on chosen target packager.
The target packager may be selected with the "PACKAGETYPE" command line
-option or with the $PACKAGETYPE construction variable. Currently
+option or with the \fB$PACKAGETYPE\fP construction variable. Currently
the following packagers available:
* msi - Microsoft Installer
@@ -2802,7 +2870,7 @@ from a \fB.dvi\fP input file
.BR .ltx ,
or
\fB.latex\fP input file).
-The suffix specified by the $PDFSUFFIX construction variable
+The suffix specified by the \fB$PDFSUFFIX\fP construction variable
(\fB.pdf\fP by default)
is added automatically to the target
if it is not already present. Example:
@@ -2823,7 +2891,7 @@ from a \fB.dvi\fP input file
.BR .ltx ,
or
\fB.latex\fP input file).
-The suffix specified by the $PSSUFFIX construction variable
+The suffix specified by the \fB$PSSUFFIX\fP construction variable
(\fB.ps\fP by default)
is added automatically to the target
if it is not already present. Example:
@@ -2849,9 +2917,9 @@ see that builder method's description for
a list of legal source file suffixes
and how they are interpreted.
The target executable file prefix
-(specified by the $PROGPREFIX construction variable; nothing by default)
+(specified by the \fB$PROGPREFIX\fP construction variable; nothing by default)
and suffix
-(specified by the $PROGSUFFIX construction variable;
+(specified by the \fB$PROGSUFFIX\fP construction variable;
by default, \fB.exe\fP on Windows systems,
nothing on POSIX systems)
are automatically added to the target if not already present.
@@ -2894,7 +2962,7 @@ or the objects return from the
builder method.
If the construction variable
-$JAVACLASSDIR
+.B $JAVACLASSDIR
is set, either in the environment
or in the call to the
.BR RMIC ()
@@ -2990,11 +3058,11 @@ compiled to object files.
The static library prefix and suffix (if any)
are automatically added to the target.
The target library file prefix
-(specified by the $SHLIBPREFIX construction variable;
+(specified by the \fB$SHLIBPREFIX\fP construction variable;
by default, \fBlib\fP on POSIX systems,
nothing on Windows systems)
and suffix
-(specified by the $SHLIBSUFFIX construction variable;
+(specified by the \fB$SHLIBSUFFIX\fP construction variable;
by default, \fB.dll\fP on Windows systems,
\fB.so\fP on POSIX systems)
are automatically added to the target if not already present.
@@ -3032,12 +3100,12 @@ On Windows systems, specifying
will cause the \fB.dll\fP to be
registered after it is built using REGSVR32.
The command that is run
-("regsvr32" by default) is determined by $REGSVR construction
-variable, and the flags passed are determined by $REGSVRFLAGS. By
-default, $REGSVRFLAGS includes the \fB/s\fP option,
+("regsvr32" by default) is determined by \fB$REGSVR\fP construction
+variable, and the flags passed are determined by \fB$REGSVRFLAGS\fP. By
+default, \fB$REGSVRFLAGS\fP includes the \fB/s\fP option,
to prevent dialogs from popping
up and requiring user attention when it is run. If you change
-$REGSVRFLAGS, be sure to include the \fB/s\fP option.
+\fB$REGSVRFLAGS\fP, be sure to include the \fB/s\fP option.
For example,
.ES
@@ -3071,10 +3139,10 @@ and shared objects to be linked into a
shared library, and will use the same suffix for shared and normal
(static) objects.
The target object file prefix
-(specified by the $SHOBJPREFIX construction variable;
-by default, the same as $OBJPREFIX)
+(specified by the \fB$SHOBJPREFIX\fP construction variable;
+by default, the same as \fB$OBJPREFIX\fP)
and suffix
-(specified by the $SHOBJSUFFIX construction variable)
+(specified by the \fB$SHOBJSUFFIX\fP construction variable)
are automatically added to the target if not already present.
Examples:
@@ -3102,11 +3170,11 @@ compiled to object files.
The static library prefix and suffix (if any)
are automatically added to the target.
The target library file prefix
-(specified by the $LIBPREFIX construction variable;
+(specified by the \fB$LIBPREFIX\fP construction variable;
by default, \fBlib\fP on POSIX systems,
nothing on Windows systems)
and suffix
-(specified by the $LIBSUFFIX construction variable;
+(specified by the \fB$LIBSUFFIX\fP construction variable;
by default, \fB.lib\fP on Windows systems,
\fB.a\fP on POSIX systems)
are automatically added to the target if not already present.
@@ -3164,9 +3232,9 @@ Source files must have one of the following extensions:
.EE
.IP
The target object file prefix
-(specified by the $OBJPREFIX construction variable; nothing by default)
+(specified by the \fB$OBJPREFIX\fP construction variable; nothing by default)
and suffix
-(specified by the $OBJSUFFIX construction variable;
+(specified by the \fB$OBJSUFFIX\fP construction variable;
\fB.obj\fP on Windows systems,
\fB.o\fP on POSIX systems)
are automatically added to the target if not already present.
@@ -3191,18 +3259,18 @@ below, for more information.
The \fBSubstfile\fP() builder generates a single text file
by concatenating the source files.
Nested lists of sources are flattened.
-$LINESEPARATOR is used to separate the source files;
+\fB$LINESEPARATOR\fP is used to separate the source files;
see the description of \fBTextfile\fP() for details.
If a single source file is present with an \fB.in\fP suffix,
the suffix is stripped and the remainder is used as the default target name.
-The prefix and suffix specified by the $SUBSTFILEPREFIX
-and $SUBSTFILESUFFIX construction variables
+The prefix and suffix specified by the \fB$SUBSTFILEPREFIX\fP
+and \fB$SUBSTFILESUFFIX\fP construction variables
(the null string by default in both cases)
are automatically added to the target if they are not already present.
-If a construction variable named $SUBST_DICT is present,
+If a construction variable named \fB$SUBST_DICT\fP is present,
it may be either a Python dictionary or a sequence of (key,value) tuples.
If the former,
the dictionary is converted into a list of tuples in an arbitrary order,
@@ -3306,14 +3374,14 @@ env.Tar('foo')
The \fBTextfile\fP() builder generates a single text file.
The source strings constitute the lines;
nested lists of sources are flattened.
-$LINESEPARATOR is used to separate the strings.
+\fB$LINESEPARATOR\fP is used to separate the strings.
-If present, the $SUBST_DICT construction variable
+If present, the \fB$SUBST_DICT\fP construction variable
is used to modify the strings before they are written;
see the \fBSubstfile\fP() description for details.
-The prefix and suffix specified by the $TEXTFILEPREFIX
-and $TEXTFILESUFFIX construction variables
+The prefix and suffix specified by the \fB$TEXTFILEPREFIX\fP
+and \fB$TEXTFILESUFFIX\fP construction variables
(the null string and \fB.txt\fP by default, respectively)
are automatically added to the target if they are not already present.
Examples:
@@ -3393,7 +3461,7 @@ files to the \fBProgram\fP(),
without using this builder. Using this builder lets you override the standard
naming conventions (be careful: prefixes are always prepended to names of
built files; if you don't want prefixes, you may set them to ``).
-See the $QTDIR variable for more information.
+See the \fB$QTDIR\fP variable for more information.
Example:
.ES
@@ -3490,7 +3558,7 @@ Builders by adding them
to the
.B SourceFileScanner
object.
-See the section "Scanner Objects,"
+See the section "Scanner Objects"
below, for more information about
defining your own Scanner objects
and using the
@@ -3572,10 +3640,25 @@ and global functions supported by
include:
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+'\" BEGIN GENERATED FUNCTION DESCRIPTIONS
+'\"
+'\" The descriptions below of the various SCons functions are generated
+'\" from the .xml files that live next to the various Python modules in
+'\" the build enginer library. If you're reading this [gnt]roff file
+'\" with an eye towards patching this man page, you can still submit
+'\" a diff against this text, but it will have to be translated to a
+'\" diff against the underlying .xml file before the patch is actually
+'\" accepted. If you do that yourself, it will make it easier to
+'\" integrate the patch.
+'\"
+'\" BEGIN GENERATED FUNCTION DESCRIPTIONS
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI Action( action ", [" cmd/str/fun ", [" var ", ...]] [" option = value ", ...])"
+.RI Action( action ", [" cmd/str/fun ", [" var ", ...]] [option=" value ", ...])"
.TP
-.IR env .Action( action ", [" cmd/str/fun ", [" var ", ...]] [" option = value ", ...])"
+.IR env .Action( action ", [" cmd/str/fun ", [" var ", ...]] [option=" value ", ...])"
Creates an Action object for
the specified
.IR action .
@@ -3601,9 +3684,9 @@ until the Action object is actually used.
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI AddMethod( object, function ", [" name ])
+.RI AddMethod( object ", " function ", [" name ])
.TP
-.RI env.AddMethod( function ", [" name ])
+.IR env .AddMethod( function ", [" name ])
When called with the
.BR AddMethod ()
form,
@@ -3668,7 +3751,7 @@ see the documentation for
for a thorough discussion of its option-processing capabities.
In addition to the arguments and values supported by the
-.B optparse.add_option ()
+.BR optparse.add_option ()
method,
the SCons
.BR AddOption ()
@@ -3705,27 +3788,25 @@ the option value may be accessed using
.BR GetOption ()
or
.BR env.GetOption ().
-\" NOTE: in SCons 1.x or 2.0, user options will be settable, but not yet.
-\" Uncomment this when that works. See tigris issue 2105.
-\" The value may also be set, using
-\" .BR SetOption ()
-\" or
-\" .BR env.SetOption (),
-\" if conditions in a
-\" .B SConscript
-\" require overriding any default value.
-\" Note, however, that a
-\" value specified on the command line will
-\" .I always
-\" override a value set by any SConscript file.
+The value may also be set, using
+.BR SetOption ()
+or
+.BR env.SetOption (),
+if conditions in a
+.B SConscript
+require overriding any default value.
+Note, however, that a
+value specified on the command line will
+.I always
+override a value set by any SConscript file.
Any specified
.B help=
strings for the new option(s)
will be displayed by the
-.B -H
+.B \-H
or
-.B -h
+.B \-h
options
(the latter only if no other help text is
specified in the SConscript files).
@@ -3756,7 +3837,7 @@ env = Environment(PREFIX = GetOption('prefix'))
.TP
.RI AddPostAction( target ", " action )
.TP
-.RI env.AddPostAction( target ", " action )
+.IR env .AddPostAction( target ", " action )
Arranges for the specified
.I action
to be performed
@@ -3777,7 +3858,7 @@ one or more targets in the list.
.TP
.RI AddPreAction( target ", " action )
.TP
-.RI env.AddPreAction( target ", " action )
+.IR env .AddPreAction( target ", " action )
Arranges for the specified
.I action
to be performed
@@ -3807,7 +3888,7 @@ file via an intermediate object file:
foo = Program('foo.c')
AddPreAction(foo, 'pre_action')
.EE
-
+.IP
The specified
.B pre_action
would be executed before
@@ -3823,7 +3904,7 @@ file into an object file.
.TP
.RI Alias( alias ", [" targets ", [" action ]])
.TP
-.RI env.Alias( alias ", [" targets ", [" action ]])
+.IR env .Alias( alias ", [" targets ", [" action ]])
Creates one or more phony targets that
expand to one or more other targets.
An optional
@@ -3837,7 +3918,7 @@ which exists outside of any file system.
This Node object, or the alias name,
may be used as a dependency of any other target,
including another alias.
-.B Alias
+.BR Alias ()
can be called multiple times for the same
alias to add additional targets to the alias,
or additional actions to the list for this alias.
@@ -3864,7 +3945,7 @@ By default,
any construction variable expansions that generate a
.B NameError
or
-.BR IndexError
+.B IndexError
exception will expand to a
.B ''
(a null string) and not cause scons to fail.
@@ -3873,7 +3954,7 @@ will generate an error message
and terminate processing.
If
-.B AllowSubstExceptions
+.BR AllowSubstExceptions ()
is called multiple times,
each call completely overwrites the previous list
of allowed exceptions.
@@ -3895,7 +3976,7 @@ AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
.TP
.RI AlwaysBuild( target ", ...)"
.TP
-.RI env.AlwaysBuild( target ", ...)"
+.IR env .AlwaysBuild( target ", ...)"
Marks each given
.I target
so that it is always assumed to be out of date,
@@ -3914,7 +3995,7 @@ Multiple targets can be passed in to a single call to
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI env.Append( key = val ", [...])"
+.IR env .Append(key= val ", [...])"
Appends the specified keyword arguments
to the end of construction variables in the environment.
If the Environment does not have
@@ -3937,7 +4018,7 @@ env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ", " delete_existing ])
+.IR env .AppendENVPath( name ", " newpath ", [" envname ", " sep ", " delete_existing ])
This appends new path elements to the given path in the
specified external environment
.RB ( ENV
@@ -3974,7 +4055,7 @@ after: /biz:/foo/bar:/foo
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI env.AppendUnique( key = val ", [...], delete_existing=0)"
+.IR env .AppendUnique(key= val ", [...], delete_existing=" 0)
Appends the specified keyword arguments
to the end of construction variables in the environment.
If the Environment does not have
@@ -3997,18 +4078,18 @@ env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-env.BitKeeper()
+.IR env .BitKeeper()
A factory function that
returns a Builder object
to be used to fetch source files
using BitKeeper.
The returned Builder
is intended to be passed to the
-.B SourceCode
+.BR SourceCode ()
function.
This function is deprecated. For details, see the entry for the
-.B SourceCode
+.BR SourceCode ()
function.
Example:
@@ -4021,7 +4102,7 @@ env.SourceCode('.', env.BitKeeper())
.TP
.RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
.TP
-.RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ])
+.IR env .BuildDir( build_dir ", " src_dir ", [" duplicate ])
Deprecated synonyms for
.BR VariantDir ()
and
@@ -4039,7 +4120,7 @@ or
.TP
.RI Builder( action ", [" arguments ])
.TP
-.RI env.Builder( action ", [" arguments ])
+.IR env .Builder( action ", [" arguments ])
Creates a Builder object for
the specified
.IR action .
@@ -4055,7 +4136,7 @@ including the
argument,
at the time it is called
using the construction variables in the
-.B env
+.I env
construction environment through which
.BR env.Builder ()
was called.
@@ -4068,11 +4149,11 @@ until after the Builder object is actually called.
.TP
.RI CacheDir( cache_dir )
.TP
-.RI env.CacheDir( cache_dir )
+.IR env .CacheDir( cache_dir )
Specifies that
.B scons
will maintain a cache of derived files in
-.I cache_dir .
+.IR cache_dir .
The derived files in the cache will be shared
among all the builds using the same
.BR CacheDir ()
@@ -4120,14 +4201,14 @@ builds that need to build the same derived file
from identical inputs.
Use of a specified
-.BR CacheDir()
+.BR CacheDir ()
may be disabled for any invocation
by using the
-.B --cache-disable
+.B \-\-cache-disable
option.
If the
-.B --cache-force
+.B \-\-cache-force
option is used,
.B scons
will place a copy of
@@ -4140,7 +4221,7 @@ the first time
.BR CacheDir ()
is added to a build,
or after using the
-.B --cache-disable
+.B \-\-cache-disable
option.
When using
@@ -4149,10 +4230,10 @@ When using
will report,
"Retrieved `file' from cache,"
unless the
-.B --cache-show
+.B \-\-cache-show
option is being used.
When the
-.B --cache-show
+.B \-\-cache-show
option is used,
.B scons
will print the action that
@@ -4175,10 +4256,10 @@ predict or prohibitively large.
.TP
.RI Clean( targets ", " files_or_dirs )
.TP
-.RI env.Clean( targets ", " files_or_dirs )
+.IR env .Clean( targets ", " files_or_dirs )
This specifies a list of files or directories which should be removed
whenever the targets are specified with the
-.B -c
+.B \-c
command line option.
The specified targets may be a list
or an individual target.
@@ -4205,7 +4286,7 @@ for the same target,
and any targets passed to both functions will
.I not
be removed by the
-.B -c
+.B \-c
option.
Examples:
@@ -4215,7 +4296,7 @@ Clean('foo', ['bar', 'baz'])
Clean('dist', env.Program('hello', 'hello.c'))
Clean(['foo', 'bar'], 'something_else_to_clean')
.EE
-
+.IP
In this example,
installing the project creates a subdirectory for the documentation.
This statement causes the subdirectory to be removed
@@ -4226,9 +4307,42 @@ Clean(docdir, os.path.join(docdir, projectname))
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI Command( target ", " source ", " action ", [" key = val ", ...])"
+.IR env .Clone([key= val ", ...])"
+Returns a separate copy of a construction environment.
+If there are any keyword arguments specified,
+they are added to the returned copy,
+overwriting any existing values
+for the keywords.
+
+Example:
+
+.ES
+env2 = env.Clone()
+env3 = env.Clone(CCFLAGS = '-g')
+.EE
+.IP
+Additionally, a list of tools and a toolpath may be specified, as in
+the Environment constructor:
+
+.ES
+def MyTool(env): env['FOO'] = 'bar'
+env4 = env.Clone(tools = ['msvc', MyTool])
+.EE
+.IP
+The
+.I parse_flags
+keyword argument is also recognized:
+
+.ES
+# create an environment for compiling programs that use wxWidgets
+wx_env = env.Clone(parse_flags = '!wx-config --cflags --cxxflags')
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI Command( target ", " source ", " action ", [key=" val ", ...])"
.TP
-.RI env.Command( target ", " source ", " action ", [" key = val ", ...])"
+.IR env .Command( target ", " source ", " action ", [key=" val ", ...])"
Executes a specific action
(or list of actions)
to build a target file or files.
@@ -4237,7 +4351,7 @@ than defining a separate Builder object
for a single special-case build.
As a special case, the
-.B source_scanner
+.I source_scanner
keyword argument can
be used to specify
a Scanner object
@@ -4287,7 +4401,6 @@ env.Command('baz.out', 'baz.in',
["$BAZ_BUILD < $SOURCES > .tmp",
rename ])
.EE
-
.IP
Note that the
.BR Command ()
@@ -4312,7 +4425,6 @@ env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET')
env['DISTDIR'] = 'destination/directory'
env.Command(env.Dir('$DISTDIR')), None, make_distdir)
.EE
-
.IP
(Also note that SCons will usually
automatically create any directory necessary to hold a target file,
@@ -4322,7 +4434,7 @@ so you normally don't need to create directories by hand.)
.TP
.RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
.TP
-.RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
+.IR env .Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
Creates a Configure object for integrated
functionality similar to GNU autoconf.
See the section "Configure Contexts,"
@@ -4330,46 +4442,13 @@ below, for a complete explanation of the arguments and behavior.
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI env.Clone([ key = val ", ...])"
-Return a separate copy of a construction environment.
-If there are any keyword arguments specified,
-they are added to the returned copy,
-overwriting any existing values
-for the keywords.
-
-Example:
-
-.ES
-env2 = env.Clone()
-env3 = env.Clone(CCFLAGS = '-g')
-.EE
-.IP
-Additionally, a list of tools and a toolpath may be specified, as in
-the Environment constructor:
-
-.ES
-def MyTool(env): env['FOO'] = 'bar'
-env4 = env.Clone(tools = ['msvc', MyTool])
-.EE
-
-The
-.I parse_flags
-keyword argument is also recognized:
-
-.ES
-# create an environment for compiling programs that use wxWidgets
-wx_env = env.Clone(parse_flags = '!wx-config --cflags --cxxflags')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI env.Copy([ key = val ", ...])"
+.IR env .Copy([key= val ", ...])"
A now-deprecated synonym for
-.BR env.Clone() .
+.BR env.Clone ().
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI env.CVS( repository ", " module )
+.IR env .CVS( repository ", " module )
A factory function that
returns a Builder object
to be used to fetch source files
@@ -4378,7 +4457,11 @@ CVS
.IR repository .
The returned Builder
is intended to be passed to the
-.B SourceCode
+.BR SourceCode ()
+function.
+
+This function is deprecated. For details, see the entry for the
+.BR SourceCode ()
function.
The optional specified
@@ -4393,10 +4476,6 @@ replicate part of the repository
directory hierarchy in your
local build directory.
-This function is deprecated. For details, see the entry for the
-.B SourceCode
-function.
-
Examples:
.ES
@@ -4417,7 +4496,7 @@ env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
.TP
.RI Decider( function )
.TP
-.RI env.Decider( function )
+.IR env .Decider( function )
Specifies that all up-to-date decisions for
targets built through this construction environment
will be handled by the specified
@@ -4429,7 +4508,7 @@ that specify the type of decision function
to be performed:
.RS 10
-.HP 6
+.TP 6
.B timestamp-newer
Specifies that a target shall be considered out of date and rebuilt
if the dependency's timestamp is newer than the target file's timestamp.
@@ -4438,8 +4517,7 @@ and
.B make
can be used a synonym for
.BR timestamp-newer .
-
-.HP 6
+.TP 6
.B timestamp-match
Specifies that a target shall be considered out of date and rebuilt
if the dependency's timestamp is different than the
@@ -4451,8 +4529,7 @@ except that the target will also be rebuilt if a
dependency file has been restored to a version with an
.I earlier
timestamp, such as can happen when restoring files from backup archives.
-
-.HP 6
+.TP 6
.B MD5
Specifies that a target shall be considered out of date and rebuilt
if the dependency's content has changed sine the last time
@@ -4464,8 +4541,7 @@ last time the target was built.
.B content
can be used as a synonym for
.BR MD5 .
-
-.HP 6
+.TP 6
.B MD5-timestamp
Specifies that a target shall be considered out of date and rebuilt
if the dependency's content has changed sine the last time
@@ -4492,7 +4568,6 @@ and runs the build again,
all within a single second.
.RE
-.IP
Examples:
.ES
@@ -4503,7 +4578,6 @@ Decider('timestamp-match')
# with the attached construction environment.
env.Decider('content')
.EE
-
.IP
In addition to the above already-available functions,
the
@@ -4518,8 +4592,8 @@ should cause the
.I target
to be rebuilt
if it has "changed" since the last tme
-.I target was built.
-
+.I target
+was built.
.IP target
The Node (file) being built.
In the normal case,
@@ -4527,7 +4601,6 @@ this is what should get rebuilt
if the
.I dependency
has "changed."
-
.IP prev_ni
Stored information about the state of the
.I dependency
@@ -4540,7 +4613,6 @@ such as the timestamp,
size, or content signature.
.RE
-.IP
The
.I function
should return a
@@ -4580,7 +4652,7 @@ env.Decider(my_decider)
.TP
.RI Default( targets )
.TP
-.RI env.Default( targets )
+.IR env .Default( targets )
This specifies a list of default targets,
which will be built by
.B scons
@@ -4638,7 +4710,7 @@ from source code management systems.
.TP
.RI Depends( target ", " dependency )
.TP
-.RI env.Depends( target ", " dependency )
+.IR env .Depends( target ", " dependency )
Specifies an explicit dependency;
the
.I target
@@ -4680,7 +4752,7 @@ env.Depends(bar, installed_lib)
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI env.Dictionary([ vars ])
+.IR env .Dictionary([ vars ])
Returns a dictionary object
containing copies of all of the
construction variables in the environment.
@@ -4699,7 +4771,7 @@ cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
.TP
.RI Dir( name ", [" directory ])
.TP
-.RI env.Dir( name ", [" directory ])
+.IR env .Dir( name ", [" directory ])
This returns a Directory Node,
an object that represents the specified directory
.IR name .
@@ -4726,23 +4798,27 @@ see "File and Directory Nodes," below.
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI env.Dump([ key ])
+.IR env .Dump([ key ])
Returns a pretty printable representation of the environment.
.IR key ,
if not
-.IR None ,
+.BR None ,
should be a string containing the name of the variable of interest.
This SConstruct:
+
.ES
env=Environment()
print env.Dump('CCCOM')
.EE
.IP
will print:
+
.ES
-\&'$CC -c -o $TARGET $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS $SOURCES'
+'$CC -c -o $TARGET $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS $SOURCES'
.EE
+.IP
+While this SConstruct:
.ES
env=Environment()
@@ -4752,7 +4828,7 @@ print env.Dump()
will print:
.ES
{ 'AR': 'ar',
- 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
+ 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\\n$RANLIB $RANLIBFLAGS $TARGET',
'ARFLAGS': ['r'],
'AS': 'as',
'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
@@ -4764,9 +4840,9 @@ will print:
.TP
.RI EnsurePythonVersion( major ", " minor )
.TP
-.RI env.EnsurePythonVersion( major ", " minor )
+.IR env .EnsurePythonVersion( major ", " minor )
Ensure that the Python version is at least
-.IR major . minor .
+.IR major\fP.\fIminor .
This function will
print out an error message and exit SCons with a non-zero exit code if the
actual Python version is not late enough.
@@ -4781,7 +4857,7 @@ EnsurePythonVersion(2,2)
.TP
.RI EnsureSConsVersion( major ", " minor ", [" revision ])
.TP
-.RI env.EnsureSConsVersion( major ", " minor ", [" revision ])
+.IR env .EnsureSConsVersion( major ", " minor ", [" revision ])
Ensure that the SCons version is at least
.IR major.minor ,
or
@@ -4803,9 +4879,9 @@ EnsureSConsVersion(0,96,90)
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI Environment([ key = value ", ...])"
+.RI Environment([key= value ", ...])"
.TP
-.RI env.Environment([ key = value ", ...])"
+.IR env .Environment([key= value ", ...])"
Return a new construction environment
initialized with the specified
.IR key = value
@@ -4815,10 +4891,10 @@ pairs.
.TP
.RI Execute( action ", [" strfunction ", " varlist ])
.TP
-.RI env.Execute( action ", [" strfunction ", " varlist ])
+.IR env .Execute( action ", [" strfunction ", " varlist ])
Executes an Action object.
The specified
-.IR action
+.I action
may be an Action object
(see the section "Action Objects,"
below, for a complete explanation of the arguments and behavior),
@@ -4840,7 +4916,7 @@ fails--that is,
exits with or returns a non-zero value.
.B scons
will
-.I not ,
+.IR not ,
however,
automatically terminate the build
if the specified
@@ -4863,7 +4939,7 @@ if Execute("mkdir sub/dir/ectory"):
.TP
.RI Exit([ value ])
.TP
-.RI env.Exit([ value ])
+.IR env .Exit([ value ])
This tells
.B scons
to exit immediately
@@ -4878,7 +4954,7 @@ is used if no value is specified.
.TP
.RI Export( vars )
.TP
-.RI env.Export( vars )
+.IR env .Export( vars )
This tells
.B scons
to export a list of variables from the current
@@ -4914,7 +4990,6 @@ Export(debug = env)
# Make env available using the name debug:
Export({"debug":env})
.EE
-
.IP
Note that the
.BR SConscript ()
@@ -4930,7 +5005,7 @@ function, below.
.TP
.RI File( name ", [" directory ])
.TP
-.RI env.File( name ", [" directory ])
+.IR env .File( name ", [" directory ])
This returns a
File Node,
an object that represents the specified file
@@ -4957,7 +5032,7 @@ see "File and Directory Nodes," below.
.TP
.RI FindFile( file ", " dirs )
.TP
-.RI env.FindFile( file ", " dirs )
+.IR env .FindFile( file ", " dirs )
Search for
.I file
in the path specified by
@@ -4976,13 +5051,13 @@ foo = env.FindFile('foo', ['dir1', 'dir2'])
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI FindInstalledFiles( )
+.RI FindInstalledFiles()
.TP
-.RI env.FindInstalledFiles( )
+.IR env .FindInstalledFiles()
Returns the list of targets set up by the
-.B Install()
+.BR Install ()
or
-.B InstallAs()
+.BR InstallAs ()
builders.
This function serves as a convenient method to select the contents of
@@ -5006,46 +5081,11 @@ FindInstalledFiles()
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI FindSourceFiles( node = '"."' )
-.TP
-.RI env.FindSourceFiles( node = '"."' )
-
-Returns the list of nodes which serve as the source of the built files.
-It does so by inspecting the dependency tree starting at the optional
-argument
-.B node
-which defaults to the '"."'-node. It will then return all leaves of
-.B node.
-These are all children which have no further children.
-
-This function is a convenient method to select the contents of a Source
-Package.
-
-Example:
-
-.ES
-Program( 'src/main_a.c' )
-Program( 'src/main_b.c' )
-Program( 'main_c.c' )
-
-# returns ['main_c.c', 'src/main_a.c', 'SConstruct', 'src/main_b.c']
-FindSourceFiles()
-
-# returns ['src/main_b.c', 'src/main_a.c' ]
-FindSourceFiles( 'src' )
-.EE
-
-.IP
-As you can see build support files (SConstruct in the above example)
-will also be returned by this function.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
.RI FindPathDirs( variable )
Returns a function
(actually a callable Python object)
intended to be used as the
-.B path_function
+.I path_function
of a Scanner object.
The returned object will look up the specified
.I variable
@@ -5053,15 +5093,15 @@ in a construction environment
and treat the construction variable's value as a list of
directory paths that should be searched
(like
-.BR CPPPATH ,
-.BR LIBPATH ,
+.BR $CPPPATH ,
+.BR $LIBPATH ,
etc.).
Note that use of
.BR FindPathDirs ()
is generally preferable to
writing your own
-.B path_function
+.I path_function
for the following reasons:
1) The returned list will contain all appropriate directories
found in source trees
@@ -5095,9 +5135,42 @@ scanner = Scanner(name = 'myscanner',
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
+.RI FindSourceFiles(node= '"."')
+.TP
+.IR env .FindSourceFiles(node= '"."')
+Returns the list of nodes which serve as the source of the built files.
+It does so by inspecting the dependency tree starting at the optional
+argument
+.I node
+which defaults to the '"."'-node. It will then return all leaves of
+.IR node .
+These are all children which have no further children.
+
+This function is a convenient method to select the contents of a Source
+Package.
+
+Example:
+
+.ES
+Program( 'src/main_a.c' )
+Program( 'src/main_b.c' )
+Program( 'main_c.c' )
+
+# returns ['main_c.c', 'src/main_a.c', 'SConstruct', 'src/main_b.c']
+FindSourceFiles()
+
+# returns ['src/main_b.c', 'src/main_a.c' ]
+FindSourceFiles( 'src' )
+.EE
+.IP
+As you can see build support files (SConstruct in the above example)
+will also be returned by this function.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
.RI Flatten( sequence )
.TP
-.RI env.Flatten( sequence )
+.IR env .Flatten( sequence )
Takes a sequence (that is, a Python list or tuple)
that may contain nested sequences
and returns a flattened list containing
@@ -5136,7 +5209,7 @@ Returns a list of exceptions for the
actions that failed while
attempting to build targets.
Each element in the returned list is a
-.B BuildError
+.I BuildError
object
with the following attributes
that record various aspects
@@ -5236,9 +5309,9 @@ atexit.register(print_build_failures)
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI GetBuildPath( file ", [" ... ])
+.RI GetBuildPath( file ", [...])"
.TP
-.RI env.GetBuildPath( file ", [" ... ])
+.IR env .GetBuildPath( file ", [...])"
Returns the
.B scons
path name (or names) for the specified
@@ -5255,15 +5328,15 @@ Nodes or strings representing path names.
.TP
.RI GetLaunchDir()
.TP
-.RI env.GetLaunchDir()
+.IR env .GetLaunchDir()
Returns the absolute path name of the directory from which
.B scons
was initially invoked.
This can be useful when using the
.BR \-u ,
-.BR \-U
+.B \-U
or
-.BR \-D
+.B \-D
options, which internally
change to the directory in which the
.B SConstruct
@@ -5273,11 +5346,11 @@ file is found.
.TP
.RI GetOption( name )
.TP
-.RI env.GetOption( name )
+.IR env .GetOption( name )
This function provides a way to query the value of
SCons options set on scons command line
(or set using the
-.IR SetOption ()
+.BR SetOption ()
function).
The options supported are:
@@ -5374,7 +5447,6 @@ which corresponds to --taskmastertrace; and
which corresponds to --warn and --warning.
.RE
-.IP
See the documentation for the
corresponding command line object for information about each specific
option.
@@ -5383,7 +5455,7 @@ option.
.TP
.RI Glob( pattern ", [" ondisk ", " source ", " strings ])
.TP
-.RI env.Glob( pattern ", [" ondisk ", " source ", " strings ])
+.IR env .Glob( pattern ", [" ondisk ", " source ", " strings ])
Returns Nodes (or strings) that match the specified
.IR pattern ,
relative to the directory of the current
@@ -5406,7 +5478,6 @@ uses Unix shell style metacharacters for matching:
[seq] matches any character in seq
[!seq] matches any char not in seq
.EE
-
.IP
If the first character of a filename is a dot,
it must be matched explicitly.
@@ -5433,7 +5504,7 @@ anywhere in a corresponding
repository or source directory.
The
-.B ondisk
+.I ondisk
argument may be set to
.B False
(or any other non-true value)
@@ -5445,7 +5516,7 @@ return corresponding Nodes
for any on-disk matches found.
The
-.B source
+.I source
argument may be set to
.B True
(or any equivalent value)
@@ -5457,7 +5528,7 @@ corresponding source directory,
not the local directory.
The
-.B strings
+.I strings
argument may be set to
.B True
(or any equivalent value)
@@ -5489,51 +5560,32 @@ Zip('/tmp/everything', Glob('.??*') + Glob('*'))
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-'\".TP
-'\".RI GlobalBuilders( flag )
-'\"When
-'\".B flag
-'\"is non-zero,
-'\"adds the names of the default builders
-'\"(Program, Library, etc.)
-'\"to the global name space
-'\"so they can be called without an explicit construction environment.
-'\"(This is the default.)
-'\"When
-'\".B
-'\"flag is zero,
-'\"the names of the default builders are removed
-'\"from the global name space
-'\"so that an explicit construction environment is required
-'\"to call all builders.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
.RI Help( text )
.TP
-.RI env.Help( text )
+.IR env .Help( text )
This specifies help text to be printed if the
-.B -h
+.B \-h
argument is given to
.BR scons .
If
-.BR Help
+.BR Help ()
is called multiple times, the text is appended together in the order
that
-.BR Help
+.BR Help ()
is called.
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
.RI Ignore( target ", " dependency )
.TP
-.RI env.Ignore( target ", " dependency )
+.IR env .Ignore( target ", " dependency )
The specified dependency file(s)
will be ignored when deciding if
the target file(s) need to be rebuilt.
You can also use
-.BR Ignore()
+.BR Ignore ()
to remove a target from the default build.
In order to do this you must specify the directory the target will
be built in as the target, and the file you want to skip building
@@ -5557,7 +5609,7 @@ env.Ignore('bar','bar/foobar.obj')
.TP
.RI Import( vars )
.TP
-.RI env.Import( vars )
+.IR env .Import( vars )
This tells
.B scons
to import a list of variables into the current SConscript file. This
@@ -5588,7 +5640,7 @@ Import("*")
.TP
.RI Literal( string )
.TP
-.RI env.Literal( string )
+.IR env .Literal( string )
The specified
.I string
will be preserved as-is
@@ -5598,7 +5650,7 @@ and not have construction variables expanded.
.TP
.RI Local( targets )
.TP
-.RI env.Local( targets )
+.IR env .Local( targets )
The specified
.I targets
will have copies made in the local tree,
@@ -5607,47 +5659,8 @@ exists in a repository.
Returns a list of the target Node or Nodes.
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-\" .TP
-\" .RI env.MergeShellPaths( arg ", [" prepend ])
-\" Merges the elements of the specified
-\" .IR arg ,
-\" which must be a dictionary, to the construction
-\" environment's copy of the shell environment
-\" in env['ENV'].
-\" (This is the environment which is passed
-\" to subshells spawned by SCons.)
-\" Note that
-\" .I arg
-\" must be a single value,
-\" so multiple strings must
-\" be passed in as a list,
-\" not as separate arguments to
-\" .BR env.MergeShellPaths ().
-
-\" New values are prepended to the environment variable by default,
-\" unless prepend=0 is specified.
-\" Duplicate values are always eliminated,
-\" since this function calls
-\" .B AppendENVPath
-\" or
-\" .B PrependENVPath
-\" depending on the
-\" .I prepend
-\" argument. See those functions for more details.
-
-\" Examples:
-
-\" .ES
-\" # Prepend a path to the shell PATH.
-\" env.MergeShellPaths({'PATH':'/usr/local/bin'} )
-\" # Append two dirs to the shell INCLUDE.
-\" env.MergeShellPaths({'INCLUDE':['c:/inc1', 'c:/inc2']}, prepend=0 )
-
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI env.MergeFlags( arg ", [" unique ])
+.IR env .MergeFlags( arg ", [" unique ])
Merges the specified
.I arg
values to the construction environment's construction variables.
@@ -5655,7 +5668,7 @@ If the
.I arg
argument is not a dictionary,
it is converted to one by calling
-.B env.ParseFlags()
+.BR env.ParseFlags ()
on the argument
before the values are merged.
Note that
@@ -5701,7 +5714,7 @@ env.MergeFlags(['-O3',
.TP
.RI NoCache( target ", ...)"
.TP
-.RI env.NoCache( target ", ...)"
+.IR env .NoCache( target ", ...)"
Specifies a list of files which should
.I not
be cached whenever the
@@ -5734,12 +5747,12 @@ NoCache(env.Program('hello', 'hello.c'))
.TP
.RI NoClean( target ", ...)"
.TP
-.RI env.NoClean( target ", ...)"
+.IR env .NoClean( target ", ...)"
Specifies a list of files or directories which should
.I not
be removed whenever the targets (or their dependencies)
are specified with the
-.B -c
+.B \-c
command line option.
The specified targets may be a list
or an individual target.
@@ -5748,7 +5761,7 @@ Multiple calls to
are legal,
and prevent each specified target
from being removed by calls to the
-.B -c
+.B \-c
option.
Multiple files or directories should be specified
@@ -5767,7 +5780,7 @@ for the same target,
and any targets passed to both functions will
.I not
be removed by the
-.B -c
+.B \-c
option.
Examples:
@@ -5779,17 +5792,18 @@ NoClean(env.Program('hello', 'hello.c'))
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI env.ParseConfig( command ", [" function ", " unique ])
+.IR env .ParseConfig( command ", [" function ", " unique ])
Calls the specified
.I function
to modify the environment as specified by the output of
-.I command .
+.IR command .
The default
.I function
is
.BR env.MergeFlags (),
which expects the output of a typical
-.I *-config command
+.B *-config
+command
(for example,
.BR gtk-config )
and adds the options
@@ -5814,11 +5828,11 @@ for a table of options and construction variables.
.TP
.RI ParseDepends( filename ", [" must_exist ", " only_one ])
.TP
-.RI env.ParseDepends( filename ", [" must_exist ", " only_one ])
+.IR env .ParseDepends( filename ", [" must_exist ", " only_one ])
Parses the contents of the specified
.I filename
as a list of dependencies in the style of
-.BR Make
+.B Make
or
.BR mkdep ,
and explicitly establishes all of the listed dependencies.
@@ -5849,7 +5863,7 @@ information for more than one target.
This can provide a small sanity check
for files intended to be generated
by, for example, the
-.B gcc -M
+.B "gcc -M"
flag,
which should typically only
write dependency information for
@@ -5862,14 +5876,14 @@ The
and all of the files listed therein
will be interpreted relative to
the directory of the
-.I SConscript
+.B SConscript
file which calls the
-.B ParseDepends
+.BR ParseDepends ()
function.
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI env.ParseFlags( flags ", ...)"
+.IR env .ParseFlags( flags ", ...)"
Parses one or more strings containing
typical command-line flags for GCC tool chains
and returns a dictionary with the flag values
@@ -5919,12 +5933,11 @@ and added to the following construction variables:
- CCFLAGS
+ CCFLAGS, LINKFLAGS
.EE
-
.IP
Any other strings not associated with options
are assumed to be the names of libraries
and added to the
-.B LIBS
+.B $LIBS
construction variable.
Examples (all of which produce the same result):
@@ -5938,18 +5951,18 @@ dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1')
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-env.Perforce()
+.IR env .Perforce()
A factory function that
returns a Builder object
to be used to fetch source files
from the Perforce source code management system.
The returned Builder
is intended to be passed to the
-.B SourceCode
+.BR SourceCode ()
function.
This function is deprecated. For details, see the entry for the
-.B SourceCode
+.BR SourceCode ()
function.
Example:
@@ -5978,19 +5991,24 @@ USERNAME.
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
.RI Platform( string )
-Returns a callable object
+The
+.BR Platform ()
+form returns a callable object
that can be used to initialize
a construction environment using the
-platform keyword of the Environment() method.
+platform keyword of the
+.BR Environment ()
+function.
Example:
.ES
env = Environment(platform = Platform('win32'))
.EE
-.TP
-.RI env.Platform( string )
-Applies the callable object for the specified platform
+.IP
+The
+.BR env.Platform ()
+form applies the callable object for the specified platform
.I string
to the environment through which the method was called.
@@ -6006,7 +6024,7 @@ and
.B SystemRoot
variables from the user's external environment
to the construction environment's
-.B ENV
+.B $ENV
dictionary.
This is so that any executed commands
that use sockets to connect with other systems
@@ -6017,6 +6035,106 @@ will work on Windows systems.
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
+.RI Precious( target ", ...)"
+.TP
+.IR env .Precious( target ", ...)"
+Marks each given
+.I target
+as precious so it is not deleted before it is rebuilt. Normally
+.B scons
+deletes a target before building it.
+Multiple targets can be passed in to a single call to
+.BR Precious ().
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.IR env .Prepend(key= val ", [...])"
+Appends the specified keyword arguments
+to the beginning 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 Append method, above.)
+
+Example:
+
+.ES
+env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.IR env .PrependENVPath( name ", " newpath ", [" envname ", " sep ", " delete_existing ])
+This appends new path elements to the given path in the
+specified external environment
+.RB ( $ENV
+by default).
+This will only add
+any particular path once (leaving the first one it encounters and
+ignoring the rest, to preserve path order),
+and to help assure this,
+will normalize all paths (using
+.B os.path.normpath
+and
+.BR os.path.normcase ).
+This can also handle the
+case where the given old path variable is a list instead of a
+string, in which case a list will be returned instead of a string.
+
+If
+.I delete_existing
+is 0, then adding a path that already exists
+will not move it to the beginning;
+it will stay where it is in the list.
+
+Example:
+
+.ES
+print 'before:',env['ENV']['INCLUDE']
+include_path = '/foo/bar:/foo'
+env.PrependENVPath('INCLUDE', include_path)
+print 'after:',env['ENV']['INCLUDE']
+.EE
+.IP
+The above example will print:
+
+.ES
+before: /biz:/foo
+after: /foo/bar:/foo:/biz
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.IR env .PrependUnique(key= val ", delete_existing=" "0, [...])"
+Appends the specified keyword arguments
+to the beginning 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 construction variable being appended to is a list,
+then any value(s) that already exist in the
+construction variable will
+.I not
+be added again to the list.
+However, if delete_existing is 1,
+existing matching values are removed first, so
+existing values in the arg list move to the front of the list.
+
+Example:
+
+.ES
+env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
.RI Progress( callable ", [" interval ])
.TP
.RI Progress( string ", [" interval ", " file ", " overwrite ])
@@ -6060,7 +6178,7 @@ A more complicated example of a custom progress display object
that prints a string containing a count
every 100 evaluated Nodes.
Note the use of
-.B \\\\r
+.B \\r
(a carriage return)
at the end so that the string
will overwrite itself on a display:
@@ -6097,7 +6215,7 @@ Progress('.', interval=100, file=sys.stderr)
.EE
.IP
If the string contains the verbatim substring
-.B $TARGET,
+.BR $TARGET ,
it will be replaced with the Node.
Note that, for performance reasons, this is
.I not
@@ -6107,7 +6225,7 @@ or use curly braces.
The following example will print the name of
every evaluated Node,
using a
-.B \\\\r
+.B \\r
(carriage return) to cause each line to overwritten by the next line,
and the
.B overwrite=
@@ -6135,118 +6253,18 @@ Progress(['-\\r', '\\\\\\r', '|\\r', '/\\r'], interval=5)
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI Precious( target ", ...)"
-.TP
-.RI env.Precious( target ", ...)"
-Marks each given
-.I target
-as precious so it is not deleted before it is rebuilt. Normally
-.B scons
-deletes a target before building it.
-Multiple targets can be passed in to a single call to
-.BR Precious ().
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI env.Prepend( key = val ", [...])"
-Appends the specified keyword arguments
-to the beginning 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 Append method, above.)
-
-Example:
-
-.ES
-env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ", " delete_existing ])
-This appends new path elements to the given path in the
-specified external environment
-.RB ( ENV
-by default).
-This will only add
-any particular path once (leaving the first one it encounters and
-ignoring the rest, to preserve path order),
-and to help assure this,
-will normalize all paths (using
-.B os.path.normpath
-and
-.BR os.path.normcase ).
-This can also handle the
-case where the given old path variable is a list instead of a
-string, in which case a list will be returned instead of a string.
-
-If
-.I delete_existing
-is 0, then adding a path that already exists
-will not move it to the beginning;
-it will stay where it is in the list.
-
-Example:
-
-.ES
-print 'before:',env['ENV']['INCLUDE']
-include_path = '/foo/bar:/foo'
-env.PrependENVPath('INCLUDE', include_path)
-print 'after:',env['ENV']['INCLUDE']
-.EE
-
-The above exmaple will print:
-
-.ES
-before: /biz:/foo
-after: /foo/bar:/foo:/biz
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI env.PrependUnique( key = val ", delete_existing=0, [...])"
-Appends the specified keyword arguments
-to the beginning 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 construction variable being appended to is a list,
-then any value(s) that already exist in the
-construction variable will
-.I not
-be added again to the list.
-However, if delete_existing is 1,
-existing matching values are removed first, so
-existing values in the arg list move to the front of the list.
-
-Example:
-
-.ES
-env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-env.RCS()
+.IR env .RCS()
A factory function that
returns a Builder object
to be used to fetch source files
from RCS.
The returned Builder
is intended to be passed to the
-.B SourceCode
+.BR SourceCode ()
function:
This function is deprecated. For details, see the entry for the
-.B SourceCode
+.BR SourceCode ()
function.
Examples:
@@ -6271,7 +6289,7 @@ for a specific subdirectory.
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI env.Replace( key = val ", [...])"
+.IR env .Replace(key= val ", [...])"
Replaces construction variables in the Environment
with the specified keyword arguments.
@@ -6285,7 +6303,7 @@ env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
.TP
.RI Repository( directory )
.TP
-.RI env.Repository( directory )
+.IR env .Repository( directory )
Specifies that
.I directory
is a repository to be searched for files.
@@ -6324,14 +6342,14 @@ make a copy in the local directory tree.
In order to guarantee that a local copy
will be made,
use the
-.B Local()
+.BR Local ()
method.
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
.RI Requires( target ", " prerequisite )
.TP
-.RI env.Requires( target ", " prerequisite )
+.IR env .Requires( target ", " prerequisite )
Specifies an order-only relationship
between the specified target file(s)
and the specified prerequisite file(s).
@@ -6352,7 +6370,7 @@ env.Requires('foo', 'file-that-must-be-built-before-foo')
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI Return([ vars "... , " stop= ])
+.RI Return([ vars "..., stop=" ])
By default,
this stops processing the current SConscript
file and returns to the calling SConscript file
@@ -6398,7 +6416,7 @@ Return('val1 val2')
.TP
.RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
.TP
-.RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
+.IR env .Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
Creates a Scanner object for
the specified
.IR function .
@@ -6407,18 +6425,14 @@ below, for a complete explanation of the arguments and behavior.
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-env.SCCS()
+.IR env .SCCS()
A factory function that
returns a Builder object
to be used to fetch source files
from SCCS.
The returned Builder
is intended to be passed to the
-.B SourceCode
-function.
-
-This function is deprecated. For details, see the entry for the
-.B SourceCode
+.BR SourceCode ()
function.
Example:
@@ -6435,7 +6449,7 @@ so configuring SCCS
as demonstrated in the above example
should only be necessary if
you are fetching from
-.I s.SCCS
+.B s.SCCS
files in the same
directory as the source files,
or if you need to explicitly specify SCCS
@@ -6444,16 +6458,12 @@ for a specific subdirectory.
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
.RI SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ])
-'\" .RI SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ])
.TP
-.RI env.SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ])
-'\" .RI env.SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ])
+.IR env .SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ])
.TP
.RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ])
-'\" .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_dir ", " duplicate ])
.TP
-.RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ])
-'\" .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_dir ", " duplicate ])
+.IR env .SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ])
This tells
.B scons
to execute
@@ -6483,12 +6493,12 @@ SConscript('src/SConscript') # run SConscript in the src directory
SConscript(['src/SConscript', 'doc/SConscript'])
config = SConscript('MyConfig.py')
.EE
-
+.IP
The second way you can call
.BR SConscript ()
is to specify a list of (sub)directory names
as a
-.RI dirs= subdirs
+.BI dirs= subdirs
keyword argument.
In this case,
.B scons
@@ -6499,7 +6509,7 @@ in each of the specified directories.
You may specify a name other than
.B SConscript
by supplying an optional
-.RI name= script
+.BI name= script
keyword argument.
The first three examples below have the same effect
as the first three examples above:
@@ -6509,7 +6519,7 @@ SConscript(dirs='src') # run SConscript in the src directory
SConscript(dirs=['src', 'doc'])
SConscript(dirs=['sub1', 'sub2'], name='MySConscript')
.EE
-
+.IP
The optional
.I exports
argument provides a list of variable names or a dictionary of
@@ -6520,7 +6530,6 @@ These variables are locally exported only to the specified
and do not affect the global pool of variables used by the
.BR Export ()
function.
-'\"If multiple dirs are provided, each script gets a fresh export.
The subsidiary
.I script(s)
must use the
@@ -6533,7 +6542,7 @@ SConscript('dir/SConscript', exports=['env', 'variable'])
SConscript(dirs='subdir', exports='env variable')
SConscript(dirs=['one', 'two', 'three'], exports='shared_info')
.EE
-
+.IP
If the optional
.I variant_dir
argument is present, it causes an effect equivalent to the
@@ -6542,15 +6551,10 @@ method described below.
(If
.I variant_dir
is not present, the
-'\" .IR src_dir and
.I duplicate
-'\" arguments are ignored.)
argument is ignored.)
The
.I variant_dir
-'\" and
-'\" .I src_dir
-'\" arguments are interpreted relative to the directory of the calling
argument is interpreted relative to the directory of the calling
.B SConscript
file.
@@ -6561,8 +6565,6 @@ function below for additional details and restrictions.
If
.I variant_dir
is present,
-'\" but
-'\" .IR src_dir " is not,"
the source directory is the directory in which the
.B SConscript
file resides and the
@@ -6573,46 +6575,29 @@ directory:
.ES
SConscript('src/SConscript', variant_dir = 'build')
.EE
+.IP
is equivalent to
+
.ES
VariantDir('build', 'src')
SConscript('build/SConscript')
.EE
+.IP
This later paradigm is often used when the sources are
in the same directory as the
-.BR SConstruct:
+.BR SConstruct :
+
.ES
SConscript('SConscript', variant_dir = 'build')
.EE
+.IP
is equivalent to
+
.ES
VariantDir('build', '.')
SConscript('build/SConscript')
.EE
-
-'\" If
-'\" .IR variant_dir " and"
-'\" .IR src_dir " are both present,"
-'\" xxxxx everything is in a state of confusion.
-'\" .ES
-'\" SConscript(dirs = 'src', variant_dir = 'build', src_dir = '.')
-'\" runs src/SConscript in build/src, but
-'\" SConscript(dirs = 'lib', variant_dir = 'build', src_dir = 'src')
-'\" runs lib/SConscript (in lib!). However,
-'\" SConscript(dirs = 'src', variant_dir = 'build', src_dir = 'src')
-'\" runs src/SConscript in build. Moreover,
-'\" SConscript(dirs = 'src/lib', variant_dir = 'build', src_dir = 'src')
-'\" runs src/lib/SConscript in build/lib. Moreover,
-'\" SConscript(dirs = 'build/src/lib', variant_dir = 'build', src_dir = 'src')
-'\" can't find build/src/lib/SConscript, even though it ought to exist.
-'\" .EE
-'\" is equivalent to
-'\" .ES
-'\" ????????????????
-'\" .EE
-'\" and what about this alternative?
-'\"TODO??? SConscript('build/SConscript', src_dir='src')
-
+.IP
Here are some composite examples:
.ES
@@ -6649,7 +6634,7 @@ SConscript('src/SConscript', variant_dir='build/ppc', duplicate=0)
.TP
.RI SConscriptChdir( value )
.TP
-.RI env.SConscriptChdir( value )
+.IR env .SConscriptChdir( value )
By default,
.B scons
changes its working directory
@@ -6687,9 +6672,9 @@ SConscript('bar/SConscript') # will chdir to bar
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI SConsignFile([ file , dbm_module ])
+.RI SConsignFile([ file ", " dbm_module ])
.TP
-.RI env.SConsignFile([ file , dbm_module ])
+.IR env .SConsignFile([ file ", " dbm_module ])
This tells
.B scons
to store all file signatures
@@ -6757,7 +6742,7 @@ SConsignFile(None)
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI env.SetDefault(key = val ", [...])"
+.IR env .SetDefault(key= val ", [...])"
Sets construction variables to default values specified with the keyword
arguments if (and only if) the variables are not already set.
The following statements are equivalent:
@@ -6772,7 +6757,7 @@ if 'FOO' not in env: env['FOO'] = 'foo'
.TP
.RI SetOption( name ", " value )
.TP
-.RI env.SetOption( name ", " value )
+.IR env .SetOption( name ", " value )
This function provides a way to set a select subset of the scons command
line options from a SConscript file. The options supported are:
@@ -6806,7 +6791,6 @@ which corresponds to --random; and
which corresponds to --stack-size.
.RE
-.IP
See the documentation for the
corresponding command line object for information about each specific
option.
@@ -6821,7 +6805,7 @@ SetOption('max_drift', 1)
.TP
.RI SideEffect( side_effect ", " target )
.TP
-.RI env.SideEffect( side_effect ", " target )
+.IR env .SideEffect( side_effect ", " target )
Declares
.I side_effect
as a side effect of building
@@ -6856,7 +6840,7 @@ automatically removed
when the
.I target
is removed by the
-.B -c
+.B \-c
option.
(Note, however, that the
.I side_effect
@@ -6878,13 +6862,13 @@ function.
.TP
.RI SourceCode( entries ", " builder )
.TP
-.RI env.SourceCode( entries ", " builder )
+.IR env .SourceCode( entries ", " builder )
This function and its associate factory functions are deprecated.
There is no replacement.
The intended use was to keep a local tree in sync with an archive,
but in actuality the function only causes the archive
to be fetched on the first run.
-Synchronizing with the archive is best done external to SCons.
+Synchronizing with the archive is best done external to &SCons;.
Arrange for non-existent source files to
be fetched from a source code management system
@@ -6901,7 +6885,7 @@ For any non-existent source files,
.B scons
will search up the directory tree
and use the first
-.B SourceCode
+.BR SourceCode ()
builder it finds.
The specified
.I builder
@@ -6913,7 +6897,7 @@ will not use a builder to fetch
source files for the specified
.IR entries ,
even if a
-.B SourceCode
+.BR SourceCode ()
builder has been specified
for a directory higher up the tree.
@@ -6931,7 +6915,6 @@ by disabling these searches as follows:
.ES
env.SourceCode('.', None)
.EE
-
.IP
Note that if the specified
.I builder
@@ -6954,151 +6937,12 @@ env.SourceCode('/', env.RCS())
env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
env.SourceCode('no_source.c', None)
.EE
-'\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI env.subst( input ", [" raw ", " target ", " source ", " conv ])
-Performs construction variable interpolation
-on the specified string or sequence argument
-.IR input .
-
-By default,
-leading or trailing white space will
-be removed from the result.
-and all sequences of white space
-will be compressed to a single space character.
-Additionally, any
-.B $(
-and
-.B $)
-character sequences will be stripped from the returned string,
-The optional
-.I raw
-argument may be set to
-.B 1
-if you want to preserve white space and
-.BR $( - $)
-sequences.
-The
-.I raw
-argument may be set to
-.B 2
-if you want to strip
-all characters between
-any
-.B $(
-and
-.B $)
-pairs
-(as is done for signature calculation).
-
-If the input is a sequence
-(list or tuple),
-the individual elements of
-the sequence will be expanded,
-and the results will be returned as a list.
-
-The optional
-.I target
-and
-.I source
-keyword arguments
-must be set to lists of
-target and source nodes, respectively,
-if you want the
-.BR $TARGET ,
-.BR $TARGETS ,
-.BR $SOURCE
-and
-.BR $SOURCES
-to be available for expansion.
-This is usually necessary if you are
-calling
-.BR env.subst ()
-from within a Python function used
-as an SCons action.
-
-Returned string values or sequence elements
-are converted to their string representation by default.
-The optional
-.I conv
-argument
-may specify a conversion function
-that will be used in place of
-the default.
-For example, if you want Python objects
-(including SCons Nodes)
-to be returned as Python objects,
-you can use the Python
-.B lambda
-idiom to pass in an unnamed function
-that simply returns its unconverted argument.
-
-Example:
-
-.ES
-print env.subst("The C compiler is: $CC")
-
-def compile(target, source, env):
- sourceDir = env.subst("${SOURCE.srcdir}",
- target=target,
- source=source)
-
-source_nodes = env.subst('$EXPAND_TO_NODELIST',
- conv=lambda x: x)
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-'\".TP
-'\".RI Subversion( repository ", " module )
-'\"A factory function that
-'\"returns a Builder object
-'\"to be used to fetch source files
-'\"from the specified Subversion
-'\".IR repository .
-'\"The returned Builder
-'\"is intended to be passed to the
-'\".B SourceCode
-'\"function.
-'\"
-'\"The optional specified
-'\".I module
-'\"will be added to the beginning
-'\"of all repository path names;
-'\"this can be used, in essence,
-'\"to strip initial directory names
-'\"from the repository path names,
-'\"so that you only have to
-'\"replicate part of the repository
-'\"directory hierarchy in your
-'\"local build directory.
-'\"
-'\"This function is deprecated. For details, see the entry for the
-'\".B SourceCode
-'\"function.
-'\"
-'\"Example:
-'\"
-'\".ES
-'\"# Will fetch foo/bar/src.c
-'\"# from /usr/local/Subversion/foo/bar/src.c.
-'\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
-'\"
-'\"# Will fetch bar/src.c
-'\"# from /usr/local/Subversion/foo/bar/src.c.
-'\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo'))
-'\"
-'\"# Will fetch src.c
-'\"# from /usr/local/Subversion/foo/bar/src.c.
-'\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar'))
-'\".EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
.RI SourceSignatures( type )
.TP
-.RI env.SourceSignatures( type )
+.IR env .SourceSignatures( type )
Note: Although it is not yet officially deprecated,
use of this function is discouraged.
See the
@@ -7115,9 +6959,9 @@ how to decide if a source file
has changed since the last time it
was used to build a particular target file.
Legal values are
-.B "MD5"
+.B MD5
or
-.BR "timestamp" .
+.BR timestamp .
If the environment method is used,
the specified type of source signature
@@ -7128,14 +6972,14 @@ the specified type of source signature becomes the default
used for all decisions
about whether targets are up-to-date.
-.B "MD5"
+.B MD5
means
.B 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.
-.B "timestamp"
+.B timestamp
means
.B scons
decides that a source file has changed
@@ -7151,13 +6995,13 @@ for Python
.BR Value ()
node objects.
-.B "MD5"
+.B MD5
signatures take longer to compute,
but are more accurate than
-.B "timestamp"
+.B timestamp
signatures.
The default value is
-.BR "MD5" .
+.BR MD5 .
Note that the default
.BR TargetSignatures ()
@@ -7179,7 +7023,7 @@ is used).
.TP
.RI Split( arg )
.TP
-.RI env.Split( arg )
+.IR env .Split( arg )
Returns a list of file names or other objects.
If arg is a string,
it will be split on strings of white-space characters
@@ -7205,6 +7049,99 @@ files = Split("""
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
+.IR env .subst( input ", [" raw ", " target ", " source ", " conv ])
+Performs construction variable interpolation
+on the specified string or sequence argument
+.IR input .
+
+By default,
+leading or trailing white space will
+be removed from the result.
+and all sequences of white space
+will be compressed to a single space character.
+Additionally, any
+.B $(
+and
+.B $)
+character sequences will be stripped from the returned string,
+The optional
+.I raw
+argument may be set to
+.B 1
+if you want to preserve white space and
+.BR $( - $)
+sequences.
+The
+.I raw
+argument may be set to
+.B 2
+if you want to strip
+all characters between
+any
+.B $(
+and
+.B $)
+pairs
+(as is done for signature calculation).
+
+If the input is a sequence
+(list or tuple),
+the individual elements of
+the sequence will be expanded,
+and the results will be returned as a list.
+
+The optional
+.I target
+and
+.I source
+keyword arguments
+must be set to lists of
+target and source nodes, respectively,
+if you want the
+.BR $TARGET ,
+.BR $TARGETS ,
+.B $SOURCE
+and
+.B $SOURCES
+to be available for expansion.
+This is usually necessary if you are
+calling
+.BR env.subst ()
+from within a Python function used
+as an SCons action.
+
+Returned string values or sequence elements
+are converted to their string representation by default.
+The optional
+.I conv
+argument
+may specify a conversion function
+that will be used in place of
+the default.
+For example, if you want Python objects
+(including SCons Nodes)
+to be returned as Python objects,
+you can use the Python
+.B lambda
+idiom to pass in an unnamed function
+that simply returns its unconverted argument.
+
+Example:
+
+.ES
+print env.subst("The C compiler is: $CC")
+
+def compile(target, source, env):
+ sourceDir = env.subst("${SOURCE.srcdir}",
+ target=target,
+ source=source)
+
+source_nodes = env.subst('$EXPAND_TO_NODELIST',
+ conv=lambda x: x)
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
.RI Tag( node ", " tags )
Annotates file or directory Nodes with
information about how the
@@ -7227,7 +7164,7 @@ Tag( 'file2.txt', DOC )
.TP
.RI TargetSignatures( type )
.TP
-.RI env.TargetSignatures( type )
+.IR env .TargetSignatures( type )
Note: Although it is not yet officially deprecated,
use of this function is discouraged.
See the
@@ -7247,7 +7184,7 @@ has changed since the last time it
was used to build some other target file.
Legal values are
.BR "build" ;
-.BR "content"
+.B "content"
(or its synonym
.BR "MD5" );
.BR "timestamp" ;
@@ -7298,7 +7235,7 @@ decides that a target file has changed
as specified by the corresponding
.BR SourceSignatures ()
setting
-.BR "" ( "MD5"
+.RB ( "MD5"
or
.BR "timestamp" ).
This means that
@@ -7347,7 +7284,7 @@ Because the default setting is
using
.BR SourceSignatures ()
is generally preferable to
-.BR TargetSignatures () ,
+.BR TargetSignatures (),
so that the up-to-date decision
will be consistent for all files
(or all files built with a specific construction environment).
@@ -7358,8 +7295,13 @@ affect their "downstream" dependencies.
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI Tool( string [, toolpath ", " **kw ])
-Returns a callable object
+.RI Tool( string ", [" toolpath ", **" kw ])
+.TP
+.IR env .Tool( string ", [" toolpath ", **" kw ])
+The
+.BR Tool ()
+form of the function
+returns a callable object
that can be used to initialize
a construction environment using the
tools keyword of the Environment() method.
@@ -7373,7 +7315,7 @@ and the name of the tool will be added to the
construction variable.
Additional keyword arguments are passed to the tool's
-.B generate()
+.BR generate ()
method.
Examples:
@@ -7387,14 +7329,16 @@ t(env) # adds 'msvc' to the TOOLS variable
u = Tool('opengl', toolpath = ['tools'])
u(env) # adds 'opengl' to the TOOLS variable
.EE
-.TP
-.RI env.Tool( string [, toolpath ", " **kw ])
-Applies the callable object for the specified tool
+.IP
+The
+.BR env.Tool ()
+form of the function
+applies the callable object for the specified tool
.I string
to the environment through which the method was called.
Additional keyword arguments are passed to the tool's
-.B generate()
+.BR generate ()
method.
.ES
@@ -7406,13 +7350,13 @@ env.Tool('opengl', toolpath = ['build/tools'])
.TP
.RI Value( value ", [" built_value ])
.TP
-.RI env.Value( value ", [" built_value ])
+.IR env .Value( value ", [" built_value ])
Returns a Node object representing the specified Python value. Value
Nodes can be used as dependencies of targets. If the result of
calling
-.BR str( value )
+.BI str( value )
changes between SCons runs, any targets depending on
-.BR Value( value )
+.BI Value( value )
will be rebuilt.
(This is true even when using timestamps to decide if
files are up-to-date.)
@@ -7473,12 +7417,12 @@ env.UpdateValue(target = Value(output), source = Value(input))
.TP
.RI VariantDir( variant_dir ", " src_dir ", [" duplicate ])
.TP
-.RI env.VariantDir( variant_dir ", " src_dir ", [" duplicate ])
+.IR env .VariantDir( variant_dir ", " src_dir ", [" duplicate ])
Use the
.BR VariantDir ()
function to create a copy of your sources in another location:
if a name under
-.IR variant_dir
+.I variant_dir
is not found but exists under
.IR src_dir ,
the file or directory is copied to
@@ -7489,7 +7433,7 @@ within the variant tree.
.BR VariantDir ()
can be called multiple times with the same
-.I src_dir
+.I src_dir
to set up multiple builds with different options
.RI ( variants ).
The
@@ -7498,9 +7442,6 @@ location must be in or underneath the SConstruct file's directory, and
.I variant_dir
may not be underneath
.IR src_dir .
-'\"TODO: Can the above restrictions be clarified or relaxed?
-'\"TODO: The latter restriction is clearly not completely right;
-'\"TODO: src_dir = '.' works fine with a build dir under it.
The default behavior is for
.B scons
@@ -7516,15 +7457,17 @@ to put derived files in the same directory as source files.
If possible on the platform,
the duplication is performed by linking rather than copying;
see also the
-.IR --duplicate
+.B \-\-duplicate
command-line option.
Moreover, only the files needed for the build are duplicated;
files and directories that are not used are not present in
.IR variant_dir .
Duplicating the source tree may be disabled by setting the
-.I duplicate
-argument to 0 (zero).
+.B duplicate
+argument to
+.B 0
+(zero).
This will cause
.B scons
to invoke Builders using the path names of source files in
@@ -7532,7 +7475,7 @@ to invoke Builders using the path names of source files in
and the path names of derived files within
.IR variant_dir .
This is always more efficient than
-.IR duplicate =1,
+.BR duplicate=1 ,
and is usually safe for most builds
(but see above for cases that may cause problems).
@@ -7541,9 +7484,9 @@ Note that
works most naturally with a subsidiary SConscript file.
However, you would then call the subsidiary SConscript file
not in the source directory, but in the
-.I variant_dir ,
+.IR variant_dir ,
regardless of the value of
-.IR duplicate .
+.BR duplicate .
This is how you tell
.B scons
which variant of a source tree to build:
@@ -7555,7 +7498,6 @@ SConscript('build/variant1/SConscript')
VariantDir('build/variant2', 'src')
SConscript('build/variant2/SConscript')
.EE
-
.IP
See also the
.BR SConscript ()
@@ -7585,36 +7527,49 @@ SConscript(dirs='doc', variant_dir='build/doc', duplicate=0)
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI WhereIs( program ", [" path ", " pathext ", " reject ])
+.RI WhereIs( program ", [" path ", " pathext ", " reject ])
.TP
-.RI env.WhereIs( program ", [" path ", " pathext ", " reject ])
-
+.IR env .WhereIs( program ", [" path ", " pathext ", " reject ])
Searches for the specified executable
-.I program,
+.IR program ,
returning the full path name to the program
if it is found,
and returning None if not.
Searches the specified
-.I path,
+.IR path ,
the value of the calling environment's PATH
-(env['ENV']['PATH']),
+.RB ( env['ENV']['PATH'] ),
or the user's current external PATH
-(os.environ['PATH'])
+.RB ( os.environ['PATH'] )
by default.
On Windows systems, searches for executable
programs with any of the file extensions
listed in the specified
-.I pathext,
+.IR pathext ,
the calling environment's PATHEXT
-(env['ENV']['PATHEXT'])
+.RB ( env['ENV']['PATHEXT'] )
or the user's current PATHEXT
-(os.environ['PATHEXT'])
+.RB ( os.environ['PATHEXT'] )
by default.
Will not select any
path name or names
in the specified
.I reject
list, if any.
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+'\" END GENERATED FUNCTION DESCRIPTIONS
+'\"
+'\" The descriptions above of the various SCons functions are generated
+'\" from the .xml files that live next to the various Python modules in
+'\" the build enginer library. If you're reading this [gnt]roff file
+'\" with an eye towards patching this man page, you can still submit
+'\" a diff against this text, but it will have to be translated to a
+'\" diff against the underlying .xml file before the patch is actually
+'\" accepted. If you do that yourself, it will make it easier to
+'\" integrate the patch.
+'\"
+'\" END GENERATED FUNCTION DESCRIPTIONS
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SS SConscript Variables
In addition to the global functions and methods,
@@ -7870,7 +7825,7 @@ The command line used to generate a static library from object files.
.IP ARCOMSTR
The string displayed when an object file
is generated from an assembly-language source file.
-If this is not set, then $ARCOM (the command line) is displayed.
+If this is not set, then \fB$ARCOM\fP (the command line) is displayed.
.ES
env = Environment(ARCOMSTR = "Archiving $TARGET")
@@ -7889,7 +7844,7 @@ from an assembly-language source file.
.IP ASCOMSTR
The string displayed when an object file
is generated from an assembly-language source file.
-If this is not set, then $ASCOM (the command line) is displayed.
+If this is not set, then \fB$ASCOM\fP (the command line) is displayed.
.ES
env = Environment(ASCOMSTR = "Assembling $TARGET")
@@ -7903,14 +7858,14 @@ The command line used to assemble an assembly-language
source file into an object file
after first running the file through the C preprocessor.
Any options specified
-in the $ASFLAGS and $CPPFLAGS construction variables
+in the \fB$ASFLAGS\fP and \fB$CPPFLAGS\fP construction variables
are included on this command line.
.IP ASPPCOMSTR
The string displayed when an object file
is generated from an assembly-language source file
after first running the file through the C preprocessor.
-If this is not set, then $ASPPCOM (the command line) is displayed.
+If this is not set, then \fB$ASPPCOM\fP (the command line) is displayed.
.ES
env = Environment(ASPPCOMSTR = "Assembling $TARGET")
@@ -7920,7 +7875,7 @@ env = Environment(ASPPCOMSTR = "Assembling $TARGET")
General options when an assembling an assembly-language
source file into an object file
after first running the file through the C preprocessor.
-The default is to use the value of $ASFLAGS.
+The default is to use the value of \fB$ASFLAGS\fP.
.IP BIBTEX
The bibliography generator for the TeX formatter and typesetter and the
@@ -7934,7 +7889,7 @@ typesetter.
.IP BIBTEXCOMSTR
The string displayed when generating a bibliography
for TeX or LaTeX.
-If this is not set, then $BIBTEXCOM (the command line) is displayed.
+If this is not set, then \fB$BIBTEXCOM\fP (the command line) is displayed.
.ES
env = Environment(BIBTEXCOMSTR = "Generating bibliography $TARGET")
@@ -7954,11 +7909,11 @@ fetching source files using BitKeeper.
.IP BITKEEPERCOMSTR
The string displayed when fetching
a source file using BitKeeper.
-If this is not set, then $BITKEEPERCOM
+If this is not set, then \fB$BITKEEPERCOM\fP
(the command line) is displayed.
.IP BITKEEPERGET
-The command ($BITKEEPER) and subcommand
+The command (\fB$BITKEEPER\fP) and subcommand
for fetching source files using BitKeeper.
.IP BITKEEPERGETFLAGS
@@ -8001,14 +7956,14 @@ The C compiler.
.IP CCCOM
The command line used to compile a C source file to a (static) object
-file. Any options specified in the $CFLAGS, $CCFLAGS and
-$CPPFLAGS construction variables are included on this command
+file. Any options specified in the \fB$CFLAGS\fP, \fB$CCFLAGS\fP and
+\fB$CPPFLAGS\fP construction variables are included on this command
line.
.IP CCCOMSTR
The string displayed when a C source file
is compiled to a (static) object file.
-If this is not set, then $CCCOM (the command line) is displayed.
+If this is not set, then \fB$CCCOM\fP (the command line) is displayed.
.ES
env = Environment(CCCOMSTR = "Compiling static object $TARGET")
@@ -8022,7 +7977,7 @@ Options added to the compiler command line
to support building with precompiled headers.
The default value expands expands to the appropriate
Microsoft Visual C++ command-line options
-when the $PCH construction variable is set.
+when the \fB$PCH\fP construction variable is set.
.IP CCPDBFLAGS
Options added to the compiler command line
@@ -8030,7 +7985,7 @@ to support storing debugging information in a
Microsoft Visual C++ PDB file.
The default value expands expands to appropriate
Microsoft Visual C++ command-line options
-when the $PDB construction variable is set.
+when the \fB$PDB\fP construction variable is set.
The Visual C++ compiler option that SCons uses by default
to generate PDB information is \fB/Z7\fP.
@@ -8044,7 +7999,7 @@ link-time performance,
although parallel builds will no longer work.
You can generate PDB files with the \fB/Zi\fP
-switch by overriding the default $CCPDBFLAGS variable as follows:
+switch by overriding the default \fB$CCPDBFLAGS\fP variable as follows:
.ES
env['CCPDBFLAGS'] = ['${(PDB and "/Zi /Fd%s" % File(PDB)) or ""}']
@@ -8053,7 +8008,7 @@ env['CCPDBFLAGS'] = ['${(PDB and "/Zi /Fd%s" % File(PDB)) or ""}']
An alternative would be to use the \fB/Zi\fP
to put the debugging information in a separate \fB.pdb\fP
file for each object file by overriding
-the $CCPDBFLAGS variable as follows:
+the \fB$CCPDBFLAGS\fP variable as follows:
.ES
env['CCPDBFLAGS'] = '/Zi /Fd${TARGET}.pdb'
@@ -8108,7 +8063,7 @@ section of the RPM
\fB.spec\fP file.
.IP _concat
-A function used to produce variables like $_CPPINCFLAGS. It takes
+A function used to produce variables like \fB$_CPPINCFLAGS\fP. It takes
four or five
arguments: a prefix to concatenate onto each element, a list of
elements, a suffix to concatenate onto each element, an environment
@@ -8142,22 +8097,22 @@ file.
An automatically-generated construction variable
containing the C preprocessor command-line options
to define values.
-The value of $_CPPDEFFLAGS is created
-by appending $CPPDEFPREFIX and $CPPDEFSUFFIX
+The value of \fB$_CPPDEFFLAGS\fP is created
+by appending \fB$CPPDEFPREFIX\fP and \fB$CPPDEFSUFFIX\fP
to the beginning and end
-of each definition in $CPPDEFINES.
+of each definition in \fB$CPPDEFINES\fP.
.IP CPPDEFINES
A platform independent specification of C preprocessor definitions.
The definitions will be added to command lines
through the automatically-generated
-$_CPPDEFFLAGS construction variable (see above),
+\fB$_CPPDEFFLAGS\fP construction variable (see above),
which is constructed according to
-the type of value of $CPPDEFINES:
+the type of value of \fB$CPPDEFINES\fP:
-If $CPPDEFINES is a string,
+If \fB$CPPDEFINES\fP is a string,
the values of the
-$CPPDEFPREFIX and $CPPDEFSUFFIX
+.BR $CPPDEFPREFIX and $CPPDEFSUFFIX
construction variables
will be added to the beginning and end.
@@ -8167,9 +8122,9 @@ will be added to the beginning and end.
env = Environment(CPPDEFINES='xyz')
.EE
.IP
-If $CPPDEFINES is a list,
+If \fB$CPPDEFINES\fP is a list,
the values of the
-$CPPDEFPREFIX and $CPPDEFSUFFIX
+.BR $CPPDEFPREFIX and $CPPDEFSUFFIX
construction variables
will be appended to the beginning and end
of each element in the list.
@@ -8183,9 +8138,9 @@ defined and the second item is its value:
env = Environment(CPPDEFINES=[('B', 2), 'A'])
.EE
.IP
-If $CPPDEFINES is a dictionary,
+If \fB$CPPDEFINES\fP is a dictionary,
the values of the
-$CPPDEFPREFIX and $CPPDEFSUFFIX
+.BR $CPPDEFPREFIX and $CPPDEFSUFFIX
construction variables
will be appended to the beginning and end
of each item from the dictionary.
@@ -8211,30 +8166,30 @@ env = Environment(CPPDEFINES={'B':2, 'A':None})
The prefix used to specify preprocessor definitions
on the C compiler command line.
This will be appended to the beginning of each definition
-in the $CPPDEFINES construction variable
-when the $_CPPDEFFLAGS variable is automatically generated.
+in the \fB$CPPDEFINES\fP construction variable
+when the \fB$_CPPDEFFLAGS\fP variable is automatically generated.
.IP CPPDEFSUFFIX
The suffix used to specify preprocessor definitions
on the C compiler command line.
This will be appended to the end of each definition
-in the $CPPDEFINES construction variable
-when the $_CPPDEFFLAGS variable is automatically generated.
+in the \fB$CPPDEFINES\fP construction variable
+when the \fB$_CPPDEFFLAGS\fP variable is automatically generated.
.IP CPPFLAGS
User-specified C preprocessor options.
These will be included in any command that uses the C preprocessor,
including not just compilation of C and C++ source files
-via the $CCCOM,
-$SHCCCOM,
-$CXXCOM and
-$SHCXXCOM command lines,
-but also the $FORTRANPPCOM,
-$SHFORTRANPPCOM,
-$F77PPCOM and
-$SHF77PPCOM command lines
+via the \fB$CCCOM\fP,
+.BR $SHCCCOM ,
+\fB$CXXCOM\fP and
+\fB$SHCXXCOM\fP command lines,
+but also the \fB$FORTRANPPCOM\fP,
+.BR $SHFORTRANPPCOM ,
+\fB$F77PPCOM\fP and
+\fB$SHF77PPCOM\fP command lines
used to compile a Fortran source file,
-and the $ASPPCOM command line
+and the \fB$ASPPCOM\fP command line
used to assemble an assembly language source file,
after first running each file through the C preprocessor.
Note that this variable does
@@ -8242,18 +8197,18 @@ Note that this variable does
contain
.B \-I
(or similar) include search path options
-that scons generates automatically from $CPPPATH.
-See $_CPPINCFLAGS, below,
+that scons generates automatically from \fB$CPPPATH\fP.
+See \fB$_CPPINCFLAGS\fP, below,
for the variable that expands to those options.
.IP _CPPINCFLAGS
An automatically-generated construction variable
containing the C preprocessor command-line options
for specifying directories to be searched for include files.
-The value of $_CPPINCFLAGS is created
-by appending $INCPREFIX and $INCSUFFIX
+The value of \fB$_CPPINCFLAGS\fP is created
+by appending \fB$INCPREFIX\fP and \fB$INCSUFFIX\fP
to the beginning and end
-of each directory in $CPPPATH.
+of each directory in \fB$CPPPATH\fP.
.IP CPPPATH
The list of directories that the C preprocessor will search for include
@@ -8281,17 +8236,17 @@ env = Environment(CPPPATH=include)
.IP
The directory list will be added to command lines
through the automatically-generated
-$_CPPINCFLAGS
+.B $_CPPINCFLAGS
construction variable,
which is constructed by
appending the values of the
-$INCPREFIX and $INCSUFFIX
+.BR $INCPREFIX and $INCSUFFIX
construction variables
to the beginning and end
-of each directory in $CPPPATH.
+of each directory in \fB$CPPPATH\fP.
Any command lines you define that need
the CPPPATH directory list should
-include $_CPPINCFLAGS:
+include \fB$_CPPINCFLAGS\fP:
.ES
env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
@@ -8324,7 +8279,7 @@ fetch source files from a CVS repository.
.IP CVSCOMSTR
The string displayed when fetching
a source file from a CVS repository.
-If this is not set, then $CVSCOM
+If this is not set, then \fB$CVSCOM\fP
(the command line) is displayed.
.IP CVSFLAGS
@@ -8336,21 +8291,21 @@ to specify from where the files must be fetched.
.IP CVSREPOSITORY
The path to the CVS repository.
This is referenced in the default
-$CVSFLAGS value.
+\fB$CVSFLAGS\fP value.
.IP CXX
The C++ compiler.
.IP CXXCOM
The command line used to compile a C++ source file to an object file.
-Any options specified in the $CXXFLAGS and
-$CPPFLAGS construction variables
+Any options specified in the \fB$CXXFLAGS\fP and
+\fB$CPPFLAGS\fP construction variables
are included on this command line.
.IP CXXCOMSTR
The string displayed when a C++ source file
is compiled to a (static) object file.
-If this is not set, then $CXXCOM (the command line) is displayed.
+If this is not set, then \fB$CXXCOM\fP (the command line) is displayed.
.ES
env = Environment(CXXCOMSTR = "Compiling static object $TARGET")
@@ -8380,10 +8335,10 @@ as C++ files.
.IP CXXFLAGS
General options that are passed to the C++ compiler.
-By default, this includes the value of $CCFLAGS,
-so that setting $CCFLAGS affects both C and C++ compilation.
+By default, this includes the value of \fB$CCFLAGS\fP,
+so that setting \fB$CCFLAGS\fP affects both C and C++ compilation.
If you want to add C++-specific flags,
-you must set or override the value of $CXXFLAGS.
+you must set or override the value of \fB$CXXFLAGS\fP.
.IP CXXVERSION
The version number of the C++ compiler.
@@ -8429,7 +8384,7 @@ The command line used to convert TeX DVI files into a PDF file.
.IP DVIPDFCOMSTR
The string displayed when a TeX DVI file
is converted into a PDF file.
-If this is not set, then $DVIPDFCOM (the command line) is displayed.
+If this is not set, then \fB$DVIPDFCOM\fP (the command line) is displayed.
.IP DVIPDFFLAGS
General options passed to the TeX DVI file to PDF file converter.
@@ -8443,7 +8398,7 @@ General options passed to the TeX DVI file to PostScript converter.
.IP ENV
A dictionary of environment variables
to use when invoking commands. When
-$ENV is used in a command all list
+\fB$ENV\fP is used in a command all list
values will be joined using the path separator and any other non-string
values will simply be coerced to a string.
Note that, by default,
@@ -8494,24 +8449,24 @@ string to escape; and should return the escaped command line.
.IP F77
The Fortran 77 compiler.
-You should normally set the $FORTRAN variable,
+You should normally set the \fB$FORTRAN\fP variable,
which specifies the default Fortran compiler
for all Fortran versions.
-You only need to set $F77 if you need to use a specific compiler
+You only need to set \fB$F77\fP if you need to use a specific compiler
or compiler version for Fortran 77 files.
.IP F77COM
The command line used to compile a Fortran 77 source file to an object file.
-You only need to set $F77COM if you need to use a specific
+You only need to set \fB$F77COM\fP if you need to use a specific
command line for Fortran 77 files.
-You should normally set the $FORTRANCOM variable,
+You should normally set the \fB$FORTRANCOM\fP variable,
which specifies the default command line
for all Fortran versions.
.IP F77COMSTR
The string displayed when a Fortran 77 source file
is compiled to an object file.
-If this is not set, then $F77COM or $FORTRANCOM
+If this is not set, then \fB$F77COM\fP or \fB$FORTRANCOM\fP
(the command line) is displayed.
.IP F77FILESUFFIXES
@@ -8525,14 +8480,14 @@ Note that this variable does
contain
.B \-I
(or similar) include search path options
-that scons generates automatically from $F77PATH.
+that scons generates automatically from \fB$F77PATH\fP.
See
-$_F77INCFLAGS
+.B $_F77INCFLAGS
below,
for the variable that expands to those options.
-You only need to set $F77FLAGS if you need to define specific
+You only need to set \fB$F77FLAGS\fP if you need to define specific
user options for Fortran 77 files.
-You should normally set the $FORTRANFLAGS variable,
+You should normally set the \fB$FORTRANFLAGS\fP variable,
which specifies the user-specified options
passed to the default Fortran compiler
for all Fortran versions.
@@ -8541,24 +8496,24 @@ for all Fortran versions.
An automatically-generated construction variable
containing the Fortran 77 compiler command-line options
for specifying directories to be searched for include files.
-The value of $_F77INCFLAGS is created
-by appending $INCPREFIX and $INCSUFFIX
+The value of \fB$_F77INCFLAGS\fP is created
+by appending \fB$INCPREFIX\fP and \fB$INCSUFFIX\fP
to the beginning and end
-of each directory in $F77PATH.
+of each directory in \fB$F77PATH\fP.
.IP F77PATH
The list of directories that the Fortran 77 compiler will search for include
directories. The implicit dependency scanner will search these
directories for include files. Don't explicitly put include directory
-arguments in $F77FLAGS because the result will be non-portable
+arguments in \fB$F77FLAGS\fP because the result will be non-portable
and the directories will not be searched by the dependency scanner. Note:
-directory names in $F77PATH will be looked-up relative to the SConscript
+directory names in \fB$F77PATH\fP will be looked-up relative to the SConscript
directory when they are used in a command. To force
.B scons
to look-up a directory relative to the root of the source tree use #:
-You only need to set $F77PATH if you need to define a specific
+You only need to set \fB$F77PATH\fP if you need to define a specific
include path for Fortran 77 files.
-You should normally set the $FORTRANPATH variable,
+You should normally set the \fB$FORTRANPATH\fP variable,
which specifies the include path
for the default Fortran compiler
for all Fortran versions.
@@ -8578,17 +8533,17 @@ env = Environment(F77PATH=include)
.IP
The directory list will be added to command lines
through the automatically-generated
-$_F77INCFLAGS
+.B $_F77INCFLAGS
construction variable,
which is constructed by
appending the values of the
-$INCPREFIX and $INCSUFFIX
+.BR $INCPREFIX and $INCSUFFIX
construction variables
to the beginning and end
-of each directory in $F77PATH.
+of each directory in \fB$F77PATH\fP.
Any command lines you define that need
the F77PATH directory list should
-include $_F77INCFLAGS:
+include \fB$_F77INCFLAGS\fP:
.ES
env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
@@ -8597,11 +8552,11 @@ env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
.IP F77PPCOM
The command line used to compile a Fortran 77 source file to an object file
after first running the file through the C preprocessor.
-Any options specified in the $F77FLAGS and $CPPFLAGS construction variables
+Any options specified in the \fB$F77FLAGS\fP and \fB$CPPFLAGS\fP construction variables
are included on this command line.
-You only need to set $F77PPCOM if you need to use a specific
+You only need to set \fB$F77PPCOM\fP if you need to use a specific
C-preprocessor command line for Fortran 77 files.
-You should normally set the $FORTRANPPCOM variable,
+You should normally set the \fB$FORTRANPPCOM\fP variable,
which specifies the default C-preprocessor command line
for all Fortran versions.
@@ -8609,7 +8564,7 @@ for all Fortran versions.
The string displayed when a Fortran 77 source file
is compiled to an object file
after first running the file through the C preprocessor.
-If this is not set, then $F77PPCOM or $FORTRANPPCOM
+If this is not set, then \fB$F77PPCOM\fP or \fB$FORTRANPPCOM\fP
(the command line) is displayed.
.IP F77PPFILESUFFIXES
@@ -8618,24 +8573,24 @@ F77 dialect will be used. By default, this is empty
.IP F90
The Fortran 90 compiler.
-You should normally set the $FORTRAN variable,
+You should normally set the \fB$FORTRAN\fP variable,
which specifies the default Fortran compiler
for all Fortran versions.
-You only need to set $F90 if you need to use a specific compiler
+You only need to set \fB$F90\fP if you need to use a specific compiler
or compiler version for Fortran 90 files.
.IP F90COM
The command line used to compile a Fortran 90 source file to an object file.
-You only need to set $F90COM if you need to use a specific
+You only need to set \fB$F90COM\fP if you need to use a specific
command line for Fortran 90 files.
-You should normally set the $FORTRANCOM variable,
+You should normally set the \fB$FORTRANCOM\fP variable,
which specifies the default command line
for all Fortran versions.
.IP F90COMSTR
The string displayed when a Fortran 90 source file
is compiled to an object file.
-If this is not set, then $F90COM or $FORTRANCOM
+If this is not set, then \fB$F90COM\fP or \fB$FORTRANCOM\fP
(the command line) is displayed.
.IP F90FILESUFFIXES
@@ -8649,14 +8604,14 @@ Note that this variable does
contain
.B \-I
(or similar) include search path options
-that scons generates automatically from $F90PATH.
+that scons generates automatically from \fB$F90PATH\fP.
See
-$_F90INCFLAGS
+.B $_F90INCFLAGS
below,
for the variable that expands to those options.
-You only need to set $F90FLAGS if you need to define specific
+You only need to set \fB$F90FLAGS\fP if you need to define specific
user options for Fortran 90 files.
-You should normally set the $FORTRANFLAGS variable,
+You should normally set the \fB$FORTRANFLAGS\fP variable,
which specifies the user-specified options
passed to the default Fortran compiler
for all Fortran versions.
@@ -8665,24 +8620,24 @@ for all Fortran versions.
An automatically-generated construction variable
containing the Fortran 90 compiler command-line options
for specifying directories to be searched for include files.
-The value of $_F90INCFLAGS is created
-by appending $INCPREFIX and $INCSUFFIX
+The value of \fB$_F90INCFLAGS\fP is created
+by appending \fB$INCPREFIX\fP and \fB$INCSUFFIX\fP
to the beginning and end
-of each directory in $F90PATH.
+of each directory in \fB$F90PATH\fP.
.IP F90PATH
The list of directories that the Fortran 90 compiler will search for include
directories. The implicit dependency scanner will search these
directories for include files. Don't explicitly put include directory
-arguments in $F90FLAGS because the result will be non-portable
+arguments in \fB$F90FLAGS\fP because the result will be non-portable
and the directories will not be searched by the dependency scanner. Note:
-directory names in $F90PATH will be looked-up relative to the SConscript
+directory names in \fB$F90PATH\fP will be looked-up relative to the SConscript
directory when they are used in a command. To force
.B scons
to look-up a directory relative to the root of the source tree use #:
-You only need to set $F90PATH if you need to define a specific
+You only need to set \fB$F90PATH\fP if you need to define a specific
include path for Fortran 90 files.
-You should normally set the $FORTRANPATH variable,
+You should normally set the \fB$FORTRANPATH\fP variable,
which specifies the include path
for the default Fortran compiler
for all Fortran versions.
@@ -8702,17 +8657,17 @@ env = Environment(F90PATH=include)
.IP
The directory list will be added to command lines
through the automatically-generated
-$_F90INCFLAGS
+.B $_F90INCFLAGS
construction variable,
which is constructed by
appending the values of the
-$INCPREFIX and $INCSUFFIX
+.BR $INCPREFIX and $INCSUFFIX
construction variables
to the beginning and end
-of each directory in $F90PATH.
+of each directory in \fB$F90PATH\fP.
Any command lines you define that need
the F90PATH directory list should
-include $_F90INCFLAGS:
+include \fB$_F90INCFLAGS\fP:
.ES
env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE")
@@ -8721,18 +8676,18 @@ env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE")
.IP F90PPCOM
The command line used to compile a Fortran 90 source file to an object file
after first running the file through the C preprocessor.
-Any options specified in the $F90FLAGS and $CPPFLAGS construction variables
+Any options specified in the \fB$F90FLAGS\fP and \fB$CPPFLAGS\fP construction variables
are included on this command line.
-You only need to set $F90PPCOM if you need to use a specific
+You only need to set \fB$F90PPCOM\fP if you need to use a specific
C-preprocessor command line for Fortran 90 files.
-You should normally set the $FORTRANPPCOM variable,
+You should normally set the \fB$FORTRANPPCOM\fP variable,
which specifies the default C-preprocessor command line
for all Fortran versions.
.IP F90PPCOMSTR
The string displayed when a Fortran 90 source file
is compiled after first running the file through the C preprocessor.
-If this is not set, then $F90PPCOM or $FORTRANPPCOM
+If this is not set, then \fB$F90PPCOM\fP or \fB$FORTRANPPCOM\fP
(the command line) is displayed.
.IP F90PPFILESUFFIXES
@@ -8741,24 +8696,24 @@ F90 dialect will be used. By default, this is empty
.IP F95
The Fortran 95 compiler.
-You should normally set the $FORTRAN variable,
+You should normally set the \fB$FORTRAN\fP variable,
which specifies the default Fortran compiler
for all Fortran versions.
-You only need to set $F95 if you need to use a specific compiler
+You only need to set \fB$F95\fP if you need to use a specific compiler
or compiler version for Fortran 95 files.
.IP F95COM
The command line used to compile a Fortran 95 source file to an object file.
-You only need to set $F95COM if you need to use a specific
+You only need to set \fB$F95COM\fP if you need to use a specific
command line for Fortran 95 files.
-You should normally set the $FORTRANCOM variable,
+You should normally set the \fB$FORTRANCOM\fP variable,
which specifies the default command line
for all Fortran versions.
.IP F95COMSTR
The string displayed when a Fortran 95 source file
is compiled to an object file.
-If this is not set, then $F95COM or $FORTRANCOM
+If this is not set, then \fB$F95COM\fP or \fB$FORTRANCOM\fP
(the command line) is displayed.
.IP F95FILESUFFIXES
@@ -8772,14 +8727,14 @@ Note that this variable does
contain
.B \-I
(or similar) include search path options
-that scons generates automatically from $F95PATH.
+that scons generates automatically from \fB$F95PATH\fP.
See
-$_F95INCFLAGS
+.B $_F95INCFLAGS
below,
for the variable that expands to those options.
-You only need to set $F95FLAGS if you need to define specific
+You only need to set \fB$F95FLAGS\fP if you need to define specific
user options for Fortran 95 files.
-You should normally set the $FORTRANFLAGS variable,
+You should normally set the \fB$FORTRANFLAGS\fP variable,
which specifies the user-specified options
passed to the default Fortran compiler
for all Fortran versions.
@@ -8788,24 +8743,24 @@ for all Fortran versions.
An automatically-generated construction variable
containing the Fortran 95 compiler command-line options
for specifying directories to be searched for include files.
-The value of $_F95INCFLAGS is created
-by appending $INCPREFIX and $INCSUFFIX
+The value of \fB$_F95INCFLAGS\fP is created
+by appending \fB$INCPREFIX\fP and \fB$INCSUFFIX\fP
to the beginning and end
-of each directory in $F95PATH.
+of each directory in \fB$F95PATH\fP.
.IP F95PATH
The list of directories that the Fortran 95 compiler will search for include
directories. The implicit dependency scanner will search these
directories for include files. Don't explicitly put include directory
-arguments in $F95FLAGS because the result will be non-portable
+arguments in \fB$F95FLAGS\fP because the result will be non-portable
and the directories will not be searched by the dependency scanner. Note:
-directory names in $F95PATH will be looked-up relative to the SConscript
+directory names in \fB$F95PATH\fP will be looked-up relative to the SConscript
directory when they are used in a command. To force
.B scons
to look-up a directory relative to the root of the source tree use #:
-You only need to set $F95PATH if you need to define a specific
+You only need to set \fB$F95PATH\fP if you need to define a specific
include path for Fortran 95 files.
-You should normally set the $FORTRANPATH variable,
+You should normally set the \fB$FORTRANPATH\fP variable,
which specifies the include path
for the default Fortran compiler
for all Fortran versions.
@@ -8825,17 +8780,17 @@ env = Environment(F95PATH=include)
.IP
The directory list will be added to command lines
through the automatically-generated
-$_F95INCFLAGS
+.B $_F95INCFLAGS
construction variable,
which is constructed by
appending the values of the
-$INCPREFIX and $INCSUFFIX
+.BR $INCPREFIX and $INCSUFFIX
construction variables
to the beginning and end
-of each directory in $F95PATH.
+of each directory in \fB$F95PATH\fP.
Any command lines you define that need
the F95PATH directory list should
-include $_F95INCFLAGS:
+include \fB$_F95INCFLAGS\fP:
.ES
env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE")
@@ -8844,11 +8799,11 @@ env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE")
.IP F95PPCOM
The command line used to compile a Fortran 95 source file to an object file
after first running the file through the C preprocessor.
-Any options specified in the $F95FLAGS and $CPPFLAGS construction variables
+Any options specified in the \fB$F95FLAGS\fP and \fB$CPPFLAGS\fP construction variables
are included on this command line.
-You only need to set $F95PPCOM if you need to use a specific
+You only need to set \fB$F95PPCOM\fP if you need to use a specific
C-preprocessor command line for Fortran 95 files.
-You should normally set the $FORTRANPPCOM variable,
+You should normally set the \fB$FORTRANPPCOM\fP variable,
which specifies the default C-preprocessor command line
for all Fortran versions.
@@ -8856,7 +8811,7 @@ for all Fortran versions.
The string displayed when a Fortran 95 source file
is compiled to an object file
after first running the file through the C preprocessor.
-If this is not set, then $F95PPCOM or $FORTRANPPCOM
+If this is not set, then \fB$F95PPCOM\fP or \fB$FORTRANPPCOM\fP
(the command line) is displayed.
.IP F95PPFILESUFFIXES
@@ -8874,17 +8829,17 @@ for all versions of Fortran.
.IP FORTRANCOM
The command line used to compile a Fortran source file to an object file.
By default, any options specified
-in the $FORTRANFLAGS,
-$CPPFLAGS,
-$_CPPDEFFLAGS,
-$_FORTRANMODFLAG, and
-$_FORTRANINCFLAGS construction variables
+in the \fB$FORTRANFLAGS\fP,
+.BR $CPPFLAGS ,
+.BR $_CPPDEFFLAGS ,
+\fB$_FORTRANMODFLAG\fP, and
+\fB$_FORTRANINCFLAGS\fP construction variables
are included on this command line.
.IP FORTRANCOMSTR
The string displayed when a Fortran source file
is compiled to an object file.
-If this is not set, then $FORTRANCOM
+If this is not set, then \fB$FORTRANCOM\fP
(the command line) is displayed.
.IP FORTRANFILESUFFIXES
@@ -8898,9 +8853,9 @@ Note that this variable does
contain
.B \-I
(or similar) include or module search path options
-that scons generates automatically from $FORTRANPATH.
+that scons generates automatically from \fB$FORTRANPATH\fP.
See
-$_FORTRANINCFLAGS and $_FORTRANMODFLAG,
+.BR $_FORTRANINCFLAGS\fP and \fB$_FORTRANMODFLAG ,
below,
for the variables that expand those options.
@@ -8909,10 +8864,10 @@ An automatically-generated construction variable
containing the Fortran compiler command-line options
for specifying directories to be searched for include
files and module files.
-The value of $_FORTRANINCFLAGS is created
-by prepending/appending $INCPREFIX and $INCSUFFIX
+The value of \fB$_FORTRANINCFLAGS\fP is created
+by prepending/appending \fB$INCPREFIX\fP and \fB$INCSUFFIX\fP
to the beginning and end
-of each directory in $FORTRANPATH.
+of each directory in \fB$FORTRANPATH\fP.
.IP FORTRANMODDIR
Directory location where the Fortran compiler should place
@@ -8924,15 +8879,15 @@ for module files, as well.
The prefix used to specify a module directory on the Fortran compiler command
line.
This will be appended to the beginning of the directory
-in the $FORTRANMODDIR construction variables
-when the $_FORTRANMODFLAG variables is automatically generated.
+in the \fB$FORTRANMODDIR\fP construction variables
+when the \fB$_FORTRANMODFLAG\fP variables is automatically generated.
.IP FORTRANMODDIRSUFFIX
The suffix used to specify a module directory on the Fortran compiler command
line.
This will be appended to the beginning of the directory
-in the $FORTRANMODDIR construction variables
-when the $_FORTRANMODFLAG variables is automatically generated.
+in the \fB$FORTRANMODDIR\fP construction variables
+when the \fB$_FORTRANMODFLAG\fP variables is automatically generated.
.IP _FORTRANMODFLAG
An automatically-generated construction variable
@@ -8940,10 +8895,10 @@ containing the Fortran compiler command-line option
for specifying the directory location where the Fortran
compiler should place any module files that happen to get
generated during compilation.
-The value of $_FORTRANMODFLAG is created
-by prepending/appending $FORTRANMODDIRPREFIX and
-$FORTRANMODDIRSUFFIX
-to the beginning and end of the directory in $FORTRANMODDIR.
+The value of \fB$_FORTRANMODFLAG\fP is created
+by prepending/appending \fB$FORTRANMODDIRPREFIX\fP and
+.B $FORTRANMODDIRSUFFIX
+to the beginning and end of the directory in \fB$FORTRANMODDIR\fP.
.IP FORTRANMODPREFIX
The module file prefix used by the Fortran compiler. SCons assumes that
@@ -8993,17 +8948,17 @@ env = Environment(FORTRANPATH=include)
.IP
The directory list will be added to command lines
through the automatically-generated
-$_FORTRANINCFLAGS
+.B $_FORTRANINCFLAGS
construction variable,
which is constructed by
appending the values of the
-$INCPREFIX and $INCSUFFIX
+.BR $INCPREFIX and $INCSUFFIX
construction variables
to the beginning and end
-of each directory in $FORTRANPATH.
+of each directory in \fB$FORTRANPATH\fP.
Any command lines you define that need
the FORTRANPATH directory list should
-include $_FORTRANINCFLAGS:
+include \fB$_FORTRANINCFLAGS\fP:
.ES
env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE")
@@ -9012,18 +8967,18 @@ env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURC
.IP FORTRANPPCOM
The command line used to compile a Fortran source file to an object file
after first running the file through the C preprocessor.
-By default, any options specified in the $FORTRANFLAGS,
-$CPPFLAGS,
-$_CPPDEFFLAGS,
-$_FORTRANMODFLAG, and
-$_FORTRANINCFLAGS
+By default, any options specified in the \fB$FORTRANFLAGS\fP,
+.BR $CPPFLAGS ,
+.BR $_CPPDEFFLAGS ,
+\fB$_FORTRANMODFLAG\fP, and
+.B $_FORTRANINCFLAGS
construction variables are included on this command line.
.IP FORTRANPPCOMSTR
The string displayed when a Fortran source file
is compiled to an object file
after first running the file through the C preprocessor.
-If this is not set, then $FORTRANPPCOM
+If this is not set, then \fB$FORTRANPPCOM\fP
(the command line) is displayed.
.IP FORTRANPPFILESUFFIXES
@@ -9047,7 +9002,7 @@ a list containing the paths to search for frameworks.
Used by the compiler to find framework-style includes like
#include <Fmwk/Header.h>.
Used by the linker to find user-specified frameworks when linking (see
-$FRAMEWORKS).
+.BR $FRAMEWORKS ).
For example:
.ES
@@ -9065,18 +9020,18 @@ to the compiler and linker command lines.
.IP _FRAMEWORKPATH
On Mac OS X with gcc, an automatically-generated construction variable
containing the linker command-line options corresponding to
-$FRAMEWORKPATH.
+.BR $FRAMEWORKPATH .
.IP FRAMEWORKPATHPREFIX
On Mac OS X with gcc, the prefix to be used for the FRAMEWORKPATH entries.
-(see $FRAMEWORKPATH).
+(see \fB$FRAMEWORKPATH\fP).
The default value is
.BR \-F .
.IP FRAMEWORKPREFIX
On Mac OS X with gcc,
the prefix to be used for linking in frameworks
-(see $FRAMEWORKS).
+(see \fB$FRAMEWORKS\fP).
The default value is
.BR \-framework .
@@ -9103,8 +9058,8 @@ general user-supplied frameworks options to be added at
the end of a command
line building a loadable module.
(This has been largely superseded by
-the $FRAMEWORKPATH, $FRAMEWORKPATHPREFIX,
-$FRAMEWORKPREFIX and $FRAMEWORKS variables
+the \fB$FRAMEWORKPATH\fP, \fB$FRAMEWORKPATHPREFIX\fP,
+\fB$FRAMEWORKPREFIX\fP and \fB$FRAMEWORKS\fP variables
described above.)
.IP GS
@@ -9117,7 +9072,7 @@ The Ghostscript command line used to convert PostScript to PDF files.
The string displayed when
Ghostscript is used to convert
a PostScript file to a PDF file.
-If this is not set, then $GSCOM (the command line) is displayed.
+If this is not set, then \fB$GSCOM\fP (the command line) is displayed.
.IP GSFLAGS
General options passed to the Ghostscript program
@@ -9130,7 +9085,7 @@ on the python you are using.
This variable must be passed as an argument to the Environment()
constructor; setting it later has no effect.
-Valid values are the same as for $TARGET_ARCH.
+Valid values are the same as for \fB$TARGET_ARCH\fP.
This is currently only used on Windows, but in the future it will be
used on other OSes as well.
@@ -9171,7 +9126,7 @@ variable in the
environment used to execute the command.
If the construction variable
-$IMPLICIT_COMMAND_DEPENDENCIES
+.B $IMPLICIT_COMMAND_DEPENDENCIES
is set to a false value
.RB ( None ,
.BR False ,
@@ -9189,16 +9144,16 @@ env = Environment(IMPLICIT_COMMAND_DEPENDENCIES = 0)
The prefix used to specify an include directory on the C compiler command
line.
This will be appended to the beginning of each directory
-in the $CPPPATH and $FORTRANPATH construction variables
-when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
+in the \fB$CPPPATH\fP and \fB$FORTRANPATH\fP construction variables
+when the \fB$_CPPINCFLAGS\fP and \fB$_FORTRANINCFLAGS\fP
variables are automatically generated.
.IP INCSUFFIX
The suffix used to specify an include directory on the C compiler command
line.
This will be appended to the end of each directory
-in the $CPPPATH and $FORTRANPATH construction variables
-when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
+in the \fB$CPPPATH\fP and \fB$FORTRANPATH\fP construction variables
+when the \fB$_CPPINCFLAGS\fP and \fB$_FORTRANINCFLAGS\fP
variables are automatically generated.
.IP INSTALL
@@ -9250,7 +9205,7 @@ The command line used to call the Java archive tool.
.IP JARCOMSTR
The string displayed when the Java archive tool
is called
-If this is not set, then $JARCOM (the command line) is displayed.
+If this is not set, then \fB$JARCOM\fP (the command line) is displayed.
.ES
env = Environment(JARCOMSTR = "JARchiving $SOURCES into $TARGET")
@@ -9286,14 +9241,14 @@ The Java compiler.
The command line used to compile a directory tree containing
Java source files to
corresponding Java class files.
-Any options specified in the $JAVACFLAGS construction variable
+Any options specified in the \fB$JAVACFLAGS\fP construction variable
are included on this command line.
.IP JAVACCOMSTR
The string displayed when compiling
a directory tree of Java source files to
corresponding Java class files.
-If this is not set, then $JAVACCOM (the command line) is displayed.
+If this is not set, then \fB$JAVACCOM\fP (the command line) is displayed.
.ES
env = Environment(JAVACCOMSTR = "Compiling class files $TARGETS from $SOURCES")
@@ -9324,7 +9279,7 @@ separated by the operating system's path separate character
Note that this currently just adds the specified
directory via the \fB\-classpath\fP option.
&SCons; does not currently search the
-$JAVACLASSPATH directories for dependency
+\fB$JAVACLASSPATH\fP directories for dependency
\fB.class\fP files.
.IP JAVACLASSSUFFIX
@@ -9338,13 +9293,13 @@ The Java generator for C header and stub files.
.IP JAVAHCOM
The command line used to generate C header and stub files
from Java classes.
-Any options specified in the $JAVAHFLAGS construction variable
+Any options specified in the \fB$JAVAHFLAGS\fP construction variable
are included on this command line.
.IP JAVAHCOMSTR
The string displayed when C header and stub files
are generated from Java classes.
-If this is not set, then $JAVAHCOM (the command line) is displayed.
+If this is not set, then \fB$JAVAHCOM\fP (the command line) is displayed.
.ES
env = Environment(JAVAHCOMSTR = "Generating header/stub file(s) $TARGETS from $SOURCES")
@@ -9369,7 +9324,7 @@ separated by the operating system's path separate character
Note that this currently just adds the specified
directory via the \fB\-sourcepath\fP option.
&SCons; does not currently search the
-$JAVASOURCEPATH directories for dependency
+\fB$JAVASOURCEPATH\fP directories for dependency
\fB.java\fP files.
.IP JAVASUFFIX
@@ -9390,7 +9345,7 @@ Java 1.5 changed the file names that are created
for nested anonymous inner classes,
which can cause a mismatch with the files
that &SCons; expects will be generated by the &javac; compiler.
-Setting $JAVAVERSION to \fB1.5\fP
+Setting \fB$JAVAVERSION\fP to \fB1.5\fP
(or \fB1.6\fP, as appropriate)
can make &SCons; realize that a Java 1.5 or 1.6
build is actually up to date.
@@ -9404,7 +9359,7 @@ The command line used to call the LaTeX structured formatter and typesetter.
.IP LATEXCOMSTR
The string displayed when calling
the LaTeX structured formatter and typesetter.
-If this is not set, then $LATEXCOM (the command line) is displayed.
+If this is not set, then \fB$LATEXCOM\fP (the command line) is displayed.
.ES
env = Environment(LATEXCOMSTR = "Building $TARGET from LaTeX input $SOURCES")
@@ -9417,7 +9372,7 @@ General options passed to the LaTeX structured formatter and typesetter.
The maximum number of times that LaTeX
will be re-run if the
.B .log
-generated by the $LATEXCOM command
+generated by the \fB$LATEXCOM\fP command
indicates that there are undefined references.
The default is to try to resolve undefined references
by re-running LaTeX up to three times.
@@ -9434,18 +9389,18 @@ The default list is:
.IP LDMODULE
The linker for building loadable modules.
-By default, this is the same as $SHLINK.
+By default, this is the same as \fB$SHLINK\fP.
.IP LDMODULECOM
The command line for building loadable modules.
-On Mac OS X, this uses the $LDMODULE,
-$LDMODULEFLAGS and
-$FRAMEWORKSFLAGS variables.
-On other systems, this is the same as $SHLINK.
+On Mac OS X, this uses the \fB$LDMODULE\fP,
+\fB$LDMODULEFLAGS\fP and
+\fB$FRAMEWORKSFLAGS\fP variables.
+On other systems, this is the same as \fB$SHLINK\fP.
.IP LDMODULECOMSTR
The string displayed when building loadable modules.
-If this is not set, then $LDMODULECOM (the command line) is displayed.
+If this is not set, then \fB$LDMODULECOM\fP (the command line) is displayed.
.IP LDMODULEFLAGS
General user options passed to the linker for building loadable modules.
@@ -9454,7 +9409,7 @@ General user options passed to the linker for building loadable modules.
The prefix used for loadable module file names.
On Mac OS X, this is null;
on other systems, this is
-the same as $SHLIBPREFIX.
+the same as \fB$SHLIBPREFIX\fP.
.IP LDMODULESUFFIX
The suffix used for loadable module file names.
@@ -9472,7 +9427,7 @@ to generate a source file.
.IP LEXCOMSTR
The string displayed when generating a source file
using the lexical analyzer generator.
-If this is not set, then $LEXCOM (the command line) is displayed.
+If this is not set, then \fB$LEXCOM\fP (the command line) is displayed.
.ES
env = Environment(LEXCOMSTR = "Lex'ing $TARGET from $SOURCES")
@@ -9485,49 +9440,52 @@ General options passed to the lexical analyzer generator.
An automatically-generated construction variable
containing the linker command-line options
for specifying directories to be searched for library.
-The value of $_LIBDIRFLAGS is created
-by appending $LIBDIRPREFIX and $LIBDIRSUFFIX
+The value of \fB$_LIBDIRFLAGS\fP is created
+by appending \fB$LIBDIRPREFIX\fP and \fB$LIBDIRSUFFIX\fP
to the beginning and end
-of each directory in $LIBPATH.
+of each directory in \fB$LIBPATH\fP.
.IP LIBDIRPREFIX
The prefix used to specify a library directory on the linker command line.
This will be appended to the beginning of each directory
-in the $LIBPATH construction variable
-when the $_LIBDIRFLAGS variable is automatically generated.
+in the \fB$LIBPATH\fP construction variable
+when the \fB$_LIBDIRFLAGS\fP variable is automatically generated.
.IP LIBDIRSUFFIX
The suffix used to specify a library directory on the linker command line.
This will be appended to the end of each directory
-in the $LIBPATH construction variable
-when the $_LIBDIRFLAGS variable is automatically generated.
+in the \fB$LIBPATH\fP construction variable
+when the \fB$_LIBDIRFLAGS\fP variable is automatically generated.
+
+.IP LIBEMITTER
+TODO
.IP _LIBFLAGS
An automatically-generated construction variable
containing the linker command-line options
for specifying libraries to be linked with the resulting target.
-The value of $_LIBFLAGS is created
-by appending $LIBLINKPREFIX and $LIBLINKSUFFIX
+The value of \fB$_LIBFLAGS\fP is created
+by appending \fB$LIBLINKPREFIX\fP and \fB$LIBLINKSUFFIX\fP
to the beginning and end
-of each filename in $LIBS.
+of each filename in \fB$LIBS\fP.
.IP LIBLINKPREFIX
The prefix used to specify a library to link on the linker command line.
This will be appended to the beginning of each library
-in the $LIBS construction variable
-when the $_LIBFLAGS variable is automatically generated.
+in the \fB$LIBS\fP construction variable
+when the \fB$_LIBFLAGS\fP variable is automatically generated.
.IP LIBLINKSUFFIX
The suffix used to specify a library to link on the linker command line.
This will be appended to the end of each library
-in the $LIBS construction variable
-when the $_LIBFLAGS variable is automatically generated.
+in the \fB$LIBS\fP construction variable
+when the \fB$_LIBFLAGS\fP variable is automatically generated.
.IP LIBPATH
The list of directories that will be searched for libraries.
The implicit dependency scanner will search these
directories for include files. Don't explicitly put include directory
-arguments in $LINKFLAGS or $SHLINKFLAGS
+arguments in \fB$LINKFLAGS\fP or \fB$SHLINKFLAGS\fP
because the result will be non-portable
and the directories will not be searched by the dependency scanner. Note:
directory names in LIBPATH will be looked-up relative to the SConscript
@@ -9550,17 +9508,17 @@ env = Environment(LIBPATH=libs)
.IP
The directory list will be added to command lines
through the automatically-generated
-$_LIBDIRFLAGS
+.B $_LIBDIRFLAGS
construction variable,
which is constructed by
appending the values of the
-$LIBDIRPREFIX and $LIBDIRSUFFIX
+.BR $LIBDIRPREFIX and $LIBDIRSUFFIX
construction variables
to the beginning and end
-of each directory in $LIBPATH.
+of each directory in \fB$LIBPATH\fP.
Any command lines you define that need
the LIBPATH directory list should
-include $_LIBDIRFLAGS:
+include \fB$_LIBDIRFLAGS\fP:
.ES
env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
@@ -9579,7 +9537,7 @@ A list of all legal prefixes for library file names.
When searching for library dependencies,
SCons will look for files with these prefixes,
the base library name,
-and suffixes in the $LIBSUFFIXES list.
+and suffixes in the \fB$LIBSUFFIXES\fP list.
.IP LIBS
A list of one or more libraries
@@ -9589,17 +9547,17 @@ created by this environment.
The library list will be added to command lines
through the automatically-generated
-$_LIBFLAGS
+.B $_LIBFLAGS
construction variable,
which is constructed by
appending the values of the
-$LIBLINKPREFIX and $LIBLINKSUFFIX
+.BR $LIBLINKPREFIX and $LIBLINKSUFFIX
construction variables
to the beginning and end
-of each filename in $LIBS.
+of each filename in \fB$LIBS\fP.
Any command lines you define that need
the LIBS library list should
-include $_LIBFLAGS:
+include \fB$_LIBFLAGS\fP:
.ES
env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
@@ -9608,13 +9566,13 @@ env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE
If you add a
File
object to the
-$LIBS
+.B $LIBS
list, the name of that file will be added to
-$_LIBFLAGS,
+.BR $_LIBFLAGS ,
and thus the link line, as is, without
-$LIBLINKPREFIX
+.B $LIBLINKPREFIX
or
-$LIBLINKSUFFIX.
+.BR $LIBLINKSUFFIX .
For example:
.ES
@@ -9635,7 +9593,7 @@ to reflect the names of the libraries they create.
.IP LIBSUFFIXES
A list of all legal suffixes for library file names.
When searching for library dependencies,
-SCons will look for files with prefixes, in the $LIBPREFIXES list,
+SCons will look for files with prefixes, in the \fB$LIBPREFIXES\fP list,
the base library name,
and these suffixes.
@@ -9659,7 +9617,7 @@ The command line used to link object files into an executable.
.IP LINKCOMSTR
The string displayed when object files
are linked into an executable.
-If this is not set, then $LINKCOM (the command line) is displayed.
+If this is not set, then \fB$LINKCOM\fP (the command line) is displayed.
.ES
env = Environment(LINKCOMSTR = "Linking $TARGET")
@@ -9671,17 +9629,17 @@ Note that this variable should
.I not
contain
.B \-l
-(or similar) options for linking with the libraries listed in $LIBS,
+(or similar) options for linking with the libraries listed in \fB$LIBS\fP,
nor
.B \-L
(or similar) library search path options
-that scons generates automatically from $LIBPATH.
+that scons generates automatically from \fB$LIBPATH\fP.
See
-$_LIBFLAGS
+.B $_LIBFLAGS
above,
for the variable that expands to library-link options,
and
-$_LIBDIRFLAGS
+.B $_LIBDIRFLAGS
above,
for the variable that expands to library search path options.
@@ -9694,7 +9652,7 @@ The command line used to pass files through the M4 macro preprocessor.
.IP M4COMSTR
The string displayed when
a file is passed through the M4 macro preprocessor.
-If this is not set, then $M4COM (the command line) is displayed.
+If this is not set, then \fB$M4COM\fP (the command line) is displayed.
.IP M4FLAGS
General options passed to the M4 macro preprocessor.
@@ -9712,7 +9670,7 @@ typesetter.
The string displayed when calling the makeindex generator for the
TeX formatter and typesetter
and the LaTeX structured formatter and typesetter.
-If this is not set, then $MAKEINDEXCOM (the command line) is displayed.
+If this is not set, then \fB$MAKEINDEXCOM\fP (the command line) is displayed.
.IP MAKEINDEXFLAGS
General options passed to the makeindex generator for the TeX formatter
@@ -9733,7 +9691,7 @@ The command line used to pass files to the Microsoft IDL compiler.
.IP MIDLCOMSTR
The string displayed when
the Microsoft IDL copmiler is called.
-If this is not set, then $MIDLCOM (the command line) is displayed.
+If this is not set, then \fB$MIDLCOM\fP (the command line) is displayed.
.IP MIDLFLAGS
General options passed to the Microsoft IDL compiler.
@@ -9766,7 +9724,7 @@ and were configured in SCons using the same construction environment
will be built in a single call to the compiler.
Only source files that have changed since their
object files were built will be passed to each compiler invocation
-(via the $CHANGED_SOURCES construction variable).
+(via the \fB$CHANGED_SOURCES\fP construction variable).
Any compilations where the object (target) file base name
(minus the \fB.obj\fP)
does not match the source file base name
@@ -9775,7 +9733,7 @@ will be compiled separately.
.IP MSVC_USE_SCRIPT
Use a batch script to set up Microsoft Visual Studio compiler
-$MSVC_USE_SCRIPT overrides $MSVC_VERSION and $TARGET_ARCH.
+.BR $MSVC_USE_SCRIPT\fP overrides \fB$MSVC_VERSION\fP and \fB$TARGET_ARCH .
If set to the name of a Visual Studio .bat file (e.g. vcvars.bat),
SCons will run that bat file and extract the relevant variables from
the result (typically %INCLUDE%, %LIB%, and %PATH%). Setting
@@ -9786,7 +9744,7 @@ window and importing the shell's environment variables.
.IP MSVC_VERSION
Sets the preferred version of Microsoft Visual C/C++ to use.
-If $MSVC_VERSION is not set, SCons will (by default) select the
+If \fB$MSVC_VERSION\fP is not set, SCons will (by default) select the
latest version of Visual C/C++ installed on your system. If the
specified version isn't installed, tool initialization will fail.
This variable must be passed as an argument to the Environment()
@@ -9799,7 +9757,7 @@ this dictionary with the following keys:
.BR VERSION :
the version of MSVS being used (can be set via
-$MSVS_VERSION)
+.BR $MSVS_VERSION )
.BR VERSIONS :
the available versions of MSVS installed
@@ -9839,34 +9797,17 @@ Sets the architecture for which the generated project(s) should build.
The default value is \fBx86\fP.
\fBamd64\fP is also supported
by &SCons; for some Visual Studio versions.
-Trying to set $MSVS_ARCH to an architecture that's not
+Trying to set \fB$MSVS_ARCH\fP to an architecture that's not
supported for a given Visual Studio version
will generate an error.
-.IP MSVS_PROJECT_BASE_PATH
-The string
-placed in a generated Microsoft Visual Studio solution file
-as the value of the
-.B SccProjectFilePathRelativizedFromConnection0
-and
-.B SccProjectFilePathRelativizedFromConnection1
-attributes of the
-.B GlobalSection(SourceCodeControl)
-section.
-There is no default value.
-
.IP MSVS_PROJECT_GUID
The string
placed in a generated Microsoft Visual Studio project file
as the value of the
.B ProjectGUID
attribute.
-The string is also placed in the
-.B SolutionUniqueID
-attribute of the
-.B GlobalSection(SourceCodeControl)
-section of the Microsoft Visual Studio solution file.
-There is no default value.
+There is no default value. If not defined, a new GUID is generated.
.IP MSVS_SCC_AUX_PATH
The path name
@@ -9879,30 +9820,47 @@ if the
construction variable is also set.
There is no default value.
-.IP MSVS_SCC_LOCAL_PATH
-The path name
-placed in a generated Microsoft Visual Studio project file
-as the value of the
+.IP MSVS_SCC_CONNECTION_ROOT
+The root path of projects in your SCC workspace, i.e the path under which
+all project and solution files will be generated. It is used as a
+reference path from which the relative paths of the generated
+Microsoft Visual Studio project and solution files are computed.
+The relative project file path is placed as the value of the
.B SccLocalPath
attribute
-if the
-.B MSVS_SCC_PROVIDER
-construction variable is also set.
-The path name is also placed in the
-.B SccLocalPath0
-and
-.B SccLocalPath1
+of the project file
+and as the values of the
+.B SccProjectFilePathRelativizedFromConnection[i]
+(where [i] ranges from 0 to the number of projects in the solution)
attributes of the
.B GlobalSection(SourceCodeControl)
section of the Microsoft Visual Studio solution file.
-There is no default value.
+Similarly the relative solution file path is placed as the values of the
+.B SccLocalPath[i]
+(where [i] ranges from 0 to the number of projects in the solution)
+attributes of the
+.B GlobalSection(SourceCodeControl)
+section of the Microsoft Visual Studio solution file.
+This is used only
+if the
+.B MSVS_SCC_PROVIDER
+construction variable is also set.
+The default value is the current working directory.
.IP MSVS_SCC_PROJECT_NAME
The project name
placed in a generated Microsoft Visual Studio project file
as the value of the
.B SccProjectName
-attribute.
+attribute
+if the
+.B MSVS_SCC_PROVIDER
+construction variable is also set.
+In this case the string is also placed in the
+.B SccProjectName0
+attribute of the
+.B GlobalSection(SourceCodeControl)
+section of the Microsoft Visual Studio solution file.
There is no default value.
.IP MSVS_SCC_PROVIDER
@@ -9912,7 +9870,7 @@ as the value of the
.B SccProvider
attribute.
The string is also placed in the
-.B SccProvider1
+.B SccProvider0
attribute of the
.B GlobalSection(SourceCodeControl)
section of the Microsoft Visual Studio solution file.
@@ -9921,7 +9879,7 @@ There is no default value.
.IP MSVS_VERSION
Sets the preferred version of Microsoft Visual Studio to use.
-If $MSVS_VERSION is not set,
+If \fB$MSVS_VERSION\fP is not set,
&SCons; will (by default) select the latest version
of Visual Studio installed on your system.
So, if you have version 6 and version 7 (MSVS .NET) installed,
@@ -9934,8 +9892,8 @@ appropriate version ('6.0' or '7.0', for example).
If the specified version isn't installed,
tool initialization will fail.
-This is obsolete: use $MSVC_VERSION instead. If $MSVS_VERSION is set and
-$MSVC_VERSION is not, $MSVC_VERSION will be set automatically to $MSVS_VERSION.
+This is obsolete: use \fB$MSVC_VERSION\fP instead. If \fB$MSVS_VERSION\fP is set and
+.BR $MSVC_VERSION\fP is not, \fB$MSVC_VERSION\fP will be set automatically to \fB$MSVS_VERSION .
If both are set to different values, scons will raise an error.
.IP MSVSBUILDCOM
@@ -9994,7 +9952,7 @@ file)
that will be invoked by Visual Studio
project files
(through the
-$MSVSSCONSCOM
+.B $MSVSSCONSCOM
variable).
The default is the same sconscript file
that contains the call to
@@ -10017,6 +9975,21 @@ and
.B .dsw
when using earlier versions of Visual Studio.
+.IP MT
+The program used on Windows systems to embed manifests into DLLs and EXEs.
+See also \fB$WINDOWS_EMBED_MANIFEST\fP.
+
+.IP MTEXECOM
+The Windows command line used to embed manifests into executables.
+See also \fB$MTSHLIBCOM\fP.
+
+.IP MTFLAGS
+Flags passed to the \fB$MT\fP manifest embedding program (Windows only).
+
+.IP MTSHLIBCOM
+The Windows command line used to embed manifests into shared libraries (DLLs).
+See also \fB$MTEXECOM\fP.
+
.IP MWCW_VERSION
The version number of the MetroWerks CodeWarrior C compiler
to be used.
@@ -10054,7 +10027,7 @@ fetch source files from Perforce.
.IP P4COMSTR
The string displayed when
fetching a source file from Perforce.
-If this is not set, then $P4COM (the command line) is displayed.
+If this is not set, then \fB$P4COM\fP (the command line) is displayed.
.IP P4FLAGS
General options that are passed to Perforce.
@@ -10104,12 +10077,12 @@ builder to generated a precompiled header.
.IP PCHCOMSTR
The string displayed when generating a precompiled header.
-If this is not set, then $PCHCOM (the command line) is displayed.
+If this is not set, then \fB$PCHCOM\fP (the command line) is displayed.
.IP PCHPDBFLAGS
A construction variable that, when expanded,
adds the \fB/yD\fP flag to the command line
-only if the $PDB construction variable is set.
+only if the \fB$PDB\fP construction variable is set.
.IP PCHSTOP
This variable specifies how much of a source file is precompiled. This
@@ -10148,11 +10121,11 @@ Using the \fB/Zi\fP instead may yield improved
link-time performance,
although parallel builds will no longer work.
You can generate PDB files with the \fB/Zi\fP
-switch by overriding the default $CCPDBFLAGS variable;
+switch by overriding the default \fB$CCPDBFLAGS\fP variable;
see the entry for that variable for specific examples.
.IP PDFCOM
-A deprecated synonym for $DVIPDFCOM.
+A deprecated synonym for \fB$DVIPDFCOM\fP.
.IP PDFLATEX
The &pdflatex; utility.
@@ -10162,7 +10135,7 @@ The command line used to call the &pdflatex; utility.
.IP PDFLATEXCOMSTR
The string displayed when calling the &pdflatex; utility.
-If this is not set, then $PDFLATEXCOM (the command line) is displayed.
+If this is not set, then \fB$PDFLATEXCOM\fP (the command line) is displayed.
.ES
env = Environment(PDFLATEX;COMSTR = "Building $TARGET from LaTeX input $SOURCES")
@@ -10185,7 +10158,7 @@ The command line used to call the &pdftex; utility.
.IP PDFTEXCOMSTR
The string displayed when calling the &pdftex; utility.
-If this is not set, then $PDFTEXCOM (the command line) is displayed.
+If this is not set, then \fB$PDFTEXCOM\fP (the command line) is displayed.
.ES
env = Environment(PDFTEXCOMSTR = "Building $TARGET from TeX input $SOURCES")
@@ -10197,7 +10170,7 @@ General options passed to the &pdftex; utility.
.IP PKGCHK
On Solaris systems,
the package-checking program that will
-be used (along with $PKGINFO)
+be used (along with \fB$PKGINFO\fP)
to look for installed versions of
the Sun PRO C++ compiler.
The default is
@@ -10206,7 +10179,7 @@ The default is
.IP PKGINFO
On Solaris systems,
the package information program that will
-be used (along with $PKGCHK)
+be used (along with \fB$PKGCHK\fP)
to look for installed versions of
the Sun PRO C++ compiler.
The default is
@@ -10266,6 +10239,9 @@ of the actual commands.
Such a function could also log the actual commands to a log file,
for example.
+.IP PROGEMITTER
+TODO
+
.IP PROGPREFIX
The prefix used for executable file names.
@@ -10278,7 +10254,7 @@ The command line used to convert TeX DVI files into a PostScript file.
.IP PSCOMSTR
The string displayed when a TeX DVI file
is converted into a PostScript file.
-If this is not set, then $PSCOM (the command line) is displayed.
+If this is not set, then \fB$PSCOM\fP (the command line) is displayed.
.IP PSPREFIX
The prefix used for PostScript file names.
@@ -10292,13 +10268,13 @@ specify files to run moc on.
.IP QT_BINPATH
The path where the qt binaries are installed.
-The default value is '$QTDIR/bin'.
+The default value is '\fB$QTDIR\fP/bin'.
.IP QT_CPPPATH
The path where the qt header files are installed.
-The default value is '$QTDIR/include'.
+The default value is '\fB$QTDIR\fP/include'.
Note: If you set this variable to None,
-the tool won't change the $CPPPATH
+the tool won't change the \fB$CPPPATH\fP
construction variable.
.IP QT_DEBUG
@@ -10306,17 +10282,17 @@ Prints lots of debugging information while scanning for moc files.
.IP QT_LIB
Default value is 'qt'. You may want to set this to 'qt-mt'. Note: If you set
-this variable to None, the tool won't change the $LIBS variable.
+this variable to None, the tool won't change the \fB$LIBS\fP variable.
.IP QT_LIBPATH
The path where the qt libraries are installed.
-The default value is '$QTDIR/lib'.
+The default value is '\fB$QTDIR\fP/lib'.
Note: If you set this variable to None,
-the tool won't change the $LIBPATH
+the tool won't change the \fB$LIBPATH\fP
construction variable.
.IP QT_MOC
-Default value is '$QT_BINPATH/moc'.
+Default value is '\fB$QT_BINPATH\fP/moc'.
.IP QT_MOCCXXPREFIX
Default value is ''. Prefix for moc output files, when source is a cxx file.
@@ -10330,7 +10306,7 @@ Command to generate a moc file from a cpp file.
.IP QT_MOCFROMCXXCOMSTR
The string displayed when generating a moc file from a cpp file.
-If this is not set, then $QT_MOCFROMCXXCOM (the command line) is displayed.
+If this is not set, then \fB$QT_MOCFROMCXXCOM\fP (the command line) is displayed.
.IP QT_MOCFROMCXXFLAGS
Default value is '-i'. These flags are passed to moc, when moccing a
@@ -10341,7 +10317,7 @@ Command to generate a moc file from a header.
.IP QT_MOCFROMHCOMSTR
The string displayed when generating a moc file from a cpp file.
-If this is not set, then $QT_MOCFROMHCOM (the command line) is displayed.
+If this is not set, then \fB$QT_MOCFROMHCOM\fP (the command line) is displayed.
.IP QT_MOCFROMHFLAGS
Default value is ''. These flags are passed to moc, when moccing a header
@@ -10351,18 +10327,18 @@ file.
Default value is 'moc_'. Prefix for moc output files, when source is a header.
.IP QT_MOCHSUFFIX
-Default value is '$CXXFILESUFFIX'. Suffix for moc output files, when source is
+Default value is '\fB$CXXFILESUFFIX\fP'. Suffix for moc output files, when source is
a header.
.IP QT_UIC
-Default value is '$QT_BINPATH/uic'.
+Default value is '\fB$QT_BINPATH\fP/uic'.
.IP QT_UICCOM
Command to generate header files from .ui files.
.IP QT_UICCOMSTR
The string displayed when generating header files from .ui files.
-If this is not set, then $QT_UICCOM (the command line) is displayed.
+If this is not set, then \fB$QT_UICCOM\fP (the command line) is displayed.
.IP QT_UICDECLFLAGS
Default value is ''. These flags are passed to uic, when creating a a h
@@ -10382,7 +10358,7 @@ file from a .ui file.
Default value is 'uic_'. Prefix for uic generated implementation files.
.IP QT_UICIMPLSUFFIX
-Default value is '$CXXFILESUFFIX'. Suffix for uic generated implementation
+Default value is '\fB$CXXFILESUFFIX\fP'. Suffix for uic generated implementation
files.
.IP QT_UISUFFIX
@@ -10397,11 +10373,11 @@ with python's os.path.join() method,
but are listed here with the '/' separator
for easier reading.)
In addition, the construction environment
-variables $CPPPATH,
-$LIBPATH and
-$LIBS may be modified
+variables \fB$CPPPATH\fP,
+\fB$LIBPATH\fP and
+\fB$LIBS\fP may be modified
and the variables
-PROGEMITTER, SHLIBEMITTER and LIBEMITTER
+.BR $PROGEMITTER\fP, \fB$SHLIBEMITTER and $LIBEMITTER
are modified. Because the build-performance is affected when using this tool,
you have to explicitly specify it at Environment creation:
@@ -10417,8 +10393,9 @@ However, there are a few preconditions to do so: Your header file must have
the same filebase as your implementation file and must stay in the same
directory. It must have one of the suffixes .h, .hpp, .H, .hxx, .hh. You
can turn off automatic moc file generation by setting QT_AUTOSCAN to 0.
-See also the corresponding builder method
-.B Moc()
+See also the corresponding
+.BR Moc() ()
+builder method.
.I "Automatic moc file generation from cxx files."
As stated in the qt documentation, include the moc file at the end of
@@ -10449,7 +10426,7 @@ The command line used to index a static library archive.
.IP RANLIBCOMSTR
The string displayed when a static library archive is indexed.
-If this is not set, then $RANLIBCOM (the command line) is displayed.
+If this is not set, then \fB$RANLIBCOM\fP (the command line) is displayed.
.ES
env = Environment(RANLIBCOMSTR = "Indexing $TARGET")
@@ -10469,7 +10446,7 @@ a Microsoft Visual C++ resource file.
.IP RCCOMSTR
The string displayed when invoking the resource compiler
to build a Microsoft Visual C++ resource file.
-If this is not set, then $RCCOM (the command line) is displayed.
+If this is not set, then \fB$RCCOM\fP (the command line) is displayed.
.IP RCFLAGS
The flags passed to the resource compiler by the RES builder.
@@ -10479,31 +10456,31 @@ An automatically-generated construction variable
containing the command-line options
for specifying directories to be searched
by the resource compiler.
-The value of $RCINCFLAGS is created
-by appending $RCINCPREFIX and $RCINCSUFFIX
+The value of \fB$RCINCFLAGS\fP is created
+by appending \fB$RCINCPREFIX\fP and \fB$RCINCSUFFIX\fP
to the beginning and end
-of each directory in $CPPPATH.
+of each directory in \fB$CPPPATH\fP.
.IP RCINCPREFIX
The prefix (flag) used to specify an include directory
on the resource compiler command line.
This will be appended to the beginning of each directory
-in the $CPPPATH construction variable
-when the $RCINCFLAGS variable is expanded.
+in the \fB$CPPPATH\fP construction variable
+when the \fB$RCINCFLAGS\fP variable is expanded.
.IP RCINCSUFFIX
The suffix used to specify an include directory
on the resource compiler command line.
This will be appended to the end of each directory
-in the $CPPPATH construction variable
-when the $RCINCFLAGS variable is expanded.
+in the \fB$CPPPATH\fP construction variable
+when the \fB$RCINCFLAGS\fP variable is expanded.
.IP RCS
The RCS executable.
Note that this variable is not actually used
for the command to fetch source files from RCS;
see the
-$RCS_CO
+.B $RCS_CO
construction variable, below.
.IP RCS_CO
@@ -10517,11 +10494,11 @@ fetch (checkout) source files from RCS.
.IP RCS_COCOMSTR
The string displayed when fetching
a source file from RCS.
-If this is not set, then $RCS_COCOM
+If this is not set, then \fB$RCS_COCOM\fP
(the command line) is displayed.
.IP RCS_COFLAGS
-Options that are passed to the $RCS_CO command.
+Options that are passed to the \fB$RCS_CO\fP command.
.IP RDirs
A function that converts a string into a list of Dir instances by
@@ -10541,7 +10518,7 @@ is passed a keyword argument of \fBregister=1\fP.
.IP REGSVRCOMSTR
The string displayed when registering a newly-built DLL file.
-If this is not set, then $REGSVRCOM (the command line) is displayed.
+If this is not set, then \fB$REGSVRCOM\fP (the command line) is displayed.
.IP REGSVRFLAGS
Flags passed to the DLL registration program
@@ -10558,14 +10535,14 @@ The Java RMI stub compiler.
The command line used to compile stub
and skeleton class files
from Java classes that contain RMI implementations.
-Any options specified in the $RMICFLAGS construction variable
+Any options specified in the \fB$RMICFLAGS\fP construction variable
are included on this command line.
.IP RMICCOMSTR
The string displayed when compiling
stub and skeleton class files
from Java classes that contain RMI implementations.
-If this is not set, then $RMICCOM (the command line) is displayed.
+If this is not set, then \fB$RMICCOM\fP (the command line) is displayed.
.ES
env = Environment(RMICCOMSTR = "Generating stub/skeleton class files $TARGETS from $SOURCES")
@@ -10578,10 +10555,10 @@ General options passed to the Java RMI stub compiler.
An automatically-generated construction variable
containing the rpath flags to be used when linking
a program with shared libraries.
-The value of $_RPATH is created
-by appending $RPATHPREFIX and $RPATHSUFFIX
+The value of \fB$_RPATH\fP is created
+by appending \fB$RPATHPREFIX\fP and \fB$RPATHSUFFIX\fP
to the beginning and end
-of each directory in $RPATH.
+of each directory in \fB$RPATH\fP.
.IP RPATH
A list of paths to search for shared libraries when running programs.
@@ -10598,15 +10575,15 @@ path, you must make it absolute yourself.
The prefix used to specify a directory to be searched for
shared libraries when running programs.
This will be appended to the beginning of each directory
-in the $RPATH construction variable
-when the $_RPATH variable is automatically generated.
+in the \fB$RPATH\fP construction variable
+when the \fB$_RPATH\fP variable is automatically generated.
.IP RPATHSUFFIX
The suffix used to specify a directory to be searched for
shared libraries when running programs.
This will be appended to the end of each directory
-in the $RPATH construction variable
-when the $_RPATH variable is automatically generated.
+in the \fB$RPATH\fP construction variable
+when the \fB$_RPATH\fP variable is automatically generated.
.IP RPCGEN
The RPC protocol compiler.
@@ -10615,7 +10592,7 @@ The RPC protocol compiler.
Options passed to the RPC protocol compiler
when generating client side stubs.
These are in addition to any flags specified in the
-$RPCGENFLAGS
+.B $RPCGENFLAGS
construction variable.
.IP RPCGENFLAGS
@@ -10625,21 +10602,21 @@ General options passed to the RPC protocol compiler.
Options passed to the RPC protocol compiler
when generating a header file.
These are in addition to any flags specified in the
-$RPCGENFLAGS
+.B $RPCGENFLAGS
construction variable.
.IP RPCGENSERVICEFLAGS
Options passed to the RPC protocol compiler
when generating server side stubs.
These are in addition to any flags specified in the
-$RPCGENFLAGS
+.B $RPCGENFLAGS
construction variable.
.IP RPCGENXDRFLAGS
Options passed to the RPC protocol compiler
when generating XDR routines.
These are in addition to any flags specified in the
-$RPCGENFLAGS
+.B $RPCGENFLAGS
construction variable.
.IP SCANNERS
@@ -10663,7 +10640,7 @@ fetch source files from SCCS.
.IP SCCSCOMSTR
The string displayed when fetching
a source file from a CVS repository.
-If this is not set, then $SCCSCOM
+If this is not set, then \fB$SCCSCOM\fP
(the command line) is displayed.
.IP SCCSFLAGS
@@ -10680,7 +10657,7 @@ The (optional) path to the SCons library directory,
initialized from the external environment.
If set, this is used to construct a shorter and more
efficient search path in the
-$MSVSSCONS
+.B $MSVSSCONS
command line executed
from Microsoft Visual Studio project files.
@@ -10690,15 +10667,15 @@ The C compiler used for generating shared-library objects.
.IP SHCCCOM
The command line used to compile a C source file
to a shared-library object file.
-Any options specified in the $SHCFLAGS,
-$SHCCFLAGS and
-$CPPFLAGS construction variables
+Any options specified in the \fB$SHCFLAGS\fP,
+\fB$SHCCFLAGS\fP and
+\fB$CPPFLAGS\fP construction variables
are included on this command line.
.IP SHCCCOMSTR
The string displayed when a C source file
is compiled to a shared object file.
-If this is not set, then $SHCCCOM (the command line) is displayed.
+If this is not set, then \fB$SHCCCOM\fP (the command line) is displayed.
.ES
env = Environment(SHCCCOMSTR = "Compiling shared object $TARGET")
@@ -10718,14 +10695,14 @@ The C++ compiler used for generating shared-library objects.
.IP SHCXXCOM
The command line used to compile a C++ source file
to a shared-library object file.
-Any options specified in the $SHCXXFLAGS and
-$CPPFLAGS construction variables
+Any options specified in the \fB$SHCXXFLAGS\fP and
+\fB$CPPFLAGS\fP construction variables
are included on this command line.
.IP SHCXXCOMSTR
The string displayed when a C++ source file
is compiled to a shared object file.
-If this is not set, then $SHCXXCOM (the command line) is displayed.
+If this is not set, then \fB$SHCXXCOM\fP (the command line) is displayed.
.ES
env = Environment(SHCXXCOMSTR = "Compiling shared object $TARGET")
@@ -10737,41 +10714,41 @@ to generate shared-library objects.
.IP SHELL
A string naming the shell program that will be passed to the
-$SPAWN
+.B $SPAWN
function.
See the
-$SPAWN
+.B $SPAWN
construction variable for more information.
.IP SHF77
The Fortran 77 compiler used for generating shared-library objects.
-You should normally set the $SHFORTRAN variable,
+You should normally set the \fB$SHFORTRAN\fP variable,
which specifies the default Fortran compiler
for all Fortran versions.
-You only need to set $SHF77 if you need to use a specific compiler
+You only need to set \fB$SHF77\fP if you need to use a specific compiler
or compiler version for Fortran 77 files.
.IP SHF77COM
The command line used to compile a Fortran 77 source file
to a shared-library object file.
-You only need to set $SHF77COM if you need to use a specific
+You only need to set \fB$SHF77COM\fP if you need to use a specific
command line for Fortran 77 files.
-You should normally set the $SHFORTRANCOM variable,
+You should normally set the \fB$SHFORTRANCOM\fP variable,
which specifies the default command line
for all Fortran versions.
.IP SHF77COMSTR
The string displayed when a Fortran 77 source file
is compiled to a shared-library object file.
-If this is not set, then $SHF77COM or $SHFORTRANCOM
+If this is not set, then \fB$SHF77COM\fP or \fB$SHFORTRANCOM\fP
(the command line) is displayed.
.IP SHF77FLAGS
Options that are passed to the Fortran 77 compiler
to generated shared-library objects.
-You only need to set $SHF77FLAGS if you need to define specific
+You only need to set \fB$SHF77FLAGS\fP if you need to define specific
user options for Fortran 77 files.
-You should normally set the $SHFORTRANFLAGS variable,
+You should normally set the \fB$SHFORTRANFLAGS\fP variable,
which specifies the user-specified options
passed to the default Fortran compiler
for all Fortran versions.
@@ -10780,11 +10757,11 @@ for all Fortran versions.
The command line used to compile a Fortran 77 source file to a
shared-library object file
after first running the file through the C preprocessor.
-Any options specified in the $SHF77FLAGS and $CPPFLAGS construction variables
+Any options specified in the \fB$SHF77FLAGS\fP and \fB$CPPFLAGS\fP construction variables
are included on this command line.
-You only need to set $SHF77PPCOM if you need to use a specific
+You only need to set \fB$SHF77PPCOM\fP if you need to use a specific
C-preprocessor command line for Fortran 77 files.
-You should normally set the $SHFORTRANPPCOM variable,
+You should normally set the \fB$SHFORTRANPPCOM\fP variable,
which specifies the default C-preprocessor command line
for all Fortran versions.
@@ -10792,38 +10769,38 @@ for all Fortran versions.
The string displayed when a Fortran 77 source file
is compiled to a shared-library object file
after first running the file through the C preprocessor.
-If this is not set, then $SHF77PPCOM or $SHFORTRANPPCOM
+If this is not set, then \fB$SHF77PPCOM\fP or \fB$SHFORTRANPPCOM\fP
(the command line) is displayed.
.IP SHF90
The Fortran 90 compiler used for generating shared-library objects.
-You should normally set the $SHFORTRAN variable,
+You should normally set the \fB$SHFORTRAN\fP variable,
which specifies the default Fortran compiler
for all Fortran versions.
-You only need to set $SHF90 if you need to use a specific compiler
+You only need to set \fB$SHF90\fP if you need to use a specific compiler
or compiler version for Fortran 90 files.
.IP SHF90COM
The command line used to compile a Fortran 90 source file
to a shared-library object file.
-You only need to set $SHF90COM if you need to use a specific
+You only need to set \fB$SHF90COM\fP if you need to use a specific
command line for Fortran 90 files.
-You should normally set the $SHFORTRANCOM variable,
+You should normally set the \fB$SHFORTRANCOM\fP variable,
which specifies the default command line
for all Fortran versions.
.IP SHF90COMSTR
The string displayed when a Fortran 90 source file
is compiled to a shared-library object file.
-If this is not set, then $SHF90COM or $SHFORTRANCOM
+If this is not set, then \fB$SHF90COM\fP or \fB$SHFORTRANCOM\fP
(the command line) is displayed.
.IP SHF90FLAGS
Options that are passed to the Fortran 90 compiler
to generated shared-library objects.
-You only need to set $SHF90FLAGS if you need to define specific
+You only need to set \fB$SHF90FLAGS\fP if you need to define specific
user options for Fortran 90 files.
-You should normally set the $SHFORTRANFLAGS variable,
+You should normally set the \fB$SHFORTRANFLAGS\fP variable,
which specifies the user-specified options
passed to the default Fortran compiler
for all Fortran versions.
@@ -10832,11 +10809,11 @@ for all Fortran versions.
The command line used to compile a Fortran 90 source file to a
shared-library object file
after first running the file through the C preprocessor.
-Any options specified in the $SHF90FLAGS and $CPPFLAGS construction variables
+Any options specified in the \fB$SHF90FLAGS\fP and \fB$CPPFLAGS\fP construction variables
are included on this command line.
-You only need to set $SHF90PPCOM if you need to use a specific
+You only need to set \fB$SHF90PPCOM\fP if you need to use a specific
C-preprocessor command line for Fortran 90 files.
-You should normally set the $SHFORTRANPPCOM variable,
+You should normally set the \fB$SHFORTRANPPCOM\fP variable,
which specifies the default C-preprocessor command line
for all Fortran versions.
@@ -10844,38 +10821,38 @@ for all Fortran versions.
The string displayed when a Fortran 90 source file
is compiled to a shared-library object file
after first running the file through the C preprocessor.
-If this is not set, then $SHF90PPCOM or $SHFORTRANPPCOM
+If this is not set, then \fB$SHF90PPCOM\fP or \fB$SHFORTRANPPCOM\fP
(the command line) is displayed.
.IP SHF95
The Fortran 95 compiler used for generating shared-library objects.
-You should normally set the $SHFORTRAN variable,
+You should normally set the \fB$SHFORTRAN\fP variable,
which specifies the default Fortran compiler
for all Fortran versions.
-You only need to set $SHF95 if you need to use a specific compiler
+You only need to set \fB$SHF95\fP if you need to use a specific compiler
or compiler version for Fortran 95 files.
.IP SHF95COM
The command line used to compile a Fortran 95 source file
to a shared-library object file.
-You only need to set $SHF95COM if you need to use a specific
+You only need to set \fB$SHF95COM\fP if you need to use a specific
command line for Fortran 95 files.
-You should normally set the $SHFORTRANCOM variable,
+You should normally set the \fB$SHFORTRANCOM\fP variable,
which specifies the default command line
for all Fortran versions.
.IP SHF95COMSTR
The string displayed when a Fortran 95 source file
is compiled to a shared-library object file.
-If this is not set, then $SHF95COM or $SHFORTRANCOM
+If this is not set, then \fB$SHF95COM\fP or \fB$SHFORTRANCOM\fP
(the command line) is displayed.
.IP SHF95FLAGS
Options that are passed to the Fortran 95 compiler
to generated shared-library objects.
-You only need to set $SHF95FLAGS if you need to define specific
+You only need to set \fB$SHF95FLAGS\fP if you need to define specific
user options for Fortran 95 files.
-You should normally set the $SHFORTRANFLAGS variable,
+You should normally set the \fB$SHFORTRANFLAGS\fP variable,
which specifies the user-specified options
passed to the default Fortran compiler
for all Fortran versions.
@@ -10884,11 +10861,11 @@ for all Fortran versions.
The command line used to compile a Fortran 95 source file to a
shared-library object file
after first running the file through the C preprocessor.
-Any options specified in the $SHF95FLAGS and $CPPFLAGS construction variables
+Any options specified in the \fB$SHF95FLAGS\fP and \fB$CPPFLAGS\fP construction variables
are included on this command line.
-You only need to set $SHF95PPCOM if you need to use a specific
+You only need to set \fB$SHF95PPCOM\fP if you need to use a specific
C-preprocessor command line for Fortran 95 files.
-You should normally set the $SHFORTRANPPCOM variable,
+You should normally set the \fB$SHFORTRANPPCOM\fP variable,
which specifies the default C-preprocessor command line
for all Fortran versions.
@@ -10896,7 +10873,7 @@ for all Fortran versions.
The string displayed when a Fortran 95 source file
is compiled to a shared-library object file
after first running the file through the C preprocessor.
-If this is not set, then $SHF95PPCOM or $SHFORTRANPPCOM
+If this is not set, then \fB$SHF95PPCOM\fP or \fB$SHFORTRANPPCOM\fP
(the command line) is displayed.
.IP SHFORTRAN
@@ -10909,7 +10886,7 @@ to a shared-library object file.
.IP SHFORTRANCOMSTR
The string displayed when a Fortran source file
is compiled to a shared-library object file.
-If this is not set, then $SHFORTRANCOM
+If this is not set, then \fB$SHFORTRANCOM\fP
(the command line) is displayed.
.IP SHFORTRANFLAGS
@@ -10921,17 +10898,20 @@ The command line used to compile a Fortran source file to a
shared-library object file
after first running the file through the C preprocessor.
Any options specified
-in the $SHFORTRANFLAGS and
-$CPPFLAGS construction variables
+in the \fB$SHFORTRANFLAGS\fP and
+\fB$CPPFLAGS\fP construction variables
are included on this command line.
.IP SHFORTRANPPCOMSTR
The string displayed when a Fortran source file
is compiled to a shared-library object file
after first running the file through the C preprocessor.
-If this is not set, then $SHFORTRANPPCOM
+If this is not set, then \fB$SHFORTRANPPCOM\fP
(the command line) is displayed.
+.IP SHLIBEMITTER
+TODO
+
.IP SHLIBPREFIX
The prefix used for shared library file names.
@@ -10946,7 +10926,7 @@ The command line used to link programs using shared libraries.
.IP SHLINKCOMSTR
The string displayed when programs using shared libraries are linked.
-If this is not set, then $SHLINKCOM (the command line) is displayed.
+If this is not set, then \fB$SHLINKCOM\fP (the command line) is displayed.
.ES
env = Environment(SHLINKCOMSTR = "Linking shared $TARGET")
@@ -10958,17 +10938,17 @@ Note that this variable should
.I not
contain
.B \-l
-(or similar) options for linking with the libraries listed in $LIBS,
+(or similar) options for linking with the libraries listed in \fB$LIBS\fP,
nor
.B \-L
(or similar) include search path options
-that scons generates automatically from $LIBPATH.
+that scons generates automatically from \fB$LIBPATH\fP.
See
-$_LIBFLAGS
+.B $_LIBFLAGS
above,
for the variable that expands to library-link options,
and
-$_LIBDIRFLAGS
+.B $_LIBDIRFLAGS
above,
for the variable that expands to library search path options.
@@ -11049,13 +11029,13 @@ The suffix that will be used for intermediate C
source files generated by
the scripting language wrapper and interface generator.
The default value is
-.BR _wrap $CFILESUFFIX.
+.BR _wrap\fP\fB$CFILESUFFIX .
By default, this value is used whenever the
.B \-c++
option is
.I not
specified as part of the
-$SWIGFLAGS
+.B $SWIGFLAGS
construction variable.
.IP SWIGCOM
@@ -11065,18 +11045,18 @@ the scripting language wrapper and interface generator.
.IP SWIGCOMSTR
The string displayed when calling
the scripting language wrapper and interface generator.
-If this is not set, then $SWIGCOM (the command line) is displayed.
+If this is not set, then \fB$SWIGCOM\fP (the command line) is displayed.
.IP SWIGCXXFILESUFFIX
The suffix that will be used for intermediate C++
source files generated by
the scripting language wrapper and interface generator.
The default value is
-.BR _wrap $CFILESUFFIX.
+.BR _wrap\fP\fB$CFILESUFFIX .
By default, this value is used whenever the
.B \-c++
option is specified as part of the
-$SWIGFLAGS
+.B $SWIGFLAGS
construction variable.
.IP SWIGDIRECTORSUFFIX
@@ -11102,29 +11082,29 @@ option in this variable,
will, by default,
generate a C++ intermediate source file
with the extension that is specified as the
-$CXXFILESUFFIX
+.B $CXXFILESUFFIX
variable.
.IP _SWIGINCFLAGS
An automatically-generated construction variable
containing the SWIG command-line options
for specifying directories to be searched for included files.
-The value of $_SWIGINCFLAGS is created
-by appending $SWIGINCPREFIX and $SWIGINCSUFFIX
+The value of \fB$_SWIGINCFLAGS\fP is created
+by appending \fB$SWIGINCPREFIX\fP and \fB$SWIGINCSUFFIX\fP
to the beginning and end
-of each directory in $SWIGPATH.
+of each directory in \fB$SWIGPATH\fP.
.IP SWIGINCPREFIX
The prefix used to specify an include directory on the SWIG command line.
This will be appended to the beginning of each directory
-in the $SWIGPATH construction variable
-when the $_SWIGINCFLAGS variable is automatically generated.
+in the \fB$SWIGPATH\fP construction variable
+when the \fB$_SWIGINCFLAGS\fP variable is automatically generated.
.IP SWIGINCSUFFIX
The suffix used to specify an include directory on the SWIG command line.
This will be appended to the end of each directory
-in the $SWIGPATH construction variable
-when the $_SWIGINCFLAGS variable is automatically generated.
+in the \fB$SWIGPATH\fP construction variable
+when the \fB$_SWIGINCFLAGS\fP variable is automatically generated.
.IP SWIGOUTDIR
Specifies the output directory in which
@@ -11141,7 +11121,7 @@ and interface generate will search for included files.
The SWIG implicit dependency scanner will search these
directories for include files.
The default is to use the same path
-specified as $CPPPATH.
+specified as \fB$CPPPATH\fP.
Don't explicitly put include directory
arguments in SWIGFLAGS;
@@ -11168,17 +11148,17 @@ env = Environment(SWIGPATH=include)
.IP
The directory list will be added to command lines
through the automatically-generated
-$_SWIGINCFLAGS
+.B $_SWIGINCFLAGS
construction variable,
which is constructed by
appending the values of the
-$SWIGINCPREFIX and $SWIGINCSUFFIX
+.BR $SWIGINCPREFIX and $SWIGINCSUFFIX
construction variables
to the beginning and end
-of each directory in $SWIGPATH.
+of each directory in \fB$SWIGPATH\fP.
Any command lines you define that need
the SWIGPATH directory list should
-include $_SWIGINCFLAGS:
+include \fB$_SWIGINCFLAGS\fP:
.ES
env = Environment(SWIGCOM="my_swig -o $TARGET $_SWIGINCFLAGS $SORUCES")
@@ -11196,7 +11176,7 @@ The command line used to call the tar archiver.
.IP TARCOMSTR
The string displayed when archiving files
using the tar archiver.
-If this is not set, then $TARCOM (the command line) is displayed.
+If this is not set, then \fB$TARCOM\fP (the command line) is displayed.
.ES
env = Environment(TARCOMSTR = "Archiving $TARGET")
@@ -11213,7 +11193,7 @@ that may not be set or used in a construction environment.
.IP TARGET_ARCH
Sets the target architecture for Visual Studio compiler (i.e. the arch
of the binaries generated by the compiler). If not set, default to
-$HOST_ARCH, or, if that is unset, to the architecture of the
+\fB$HOST_ARCH\fP, or, if that is unset, to the architecture of the
running machine's OS (note that the python build or architecture has no
effect).
This variable must be passed as an argument to the Environment()
@@ -11264,7 +11244,7 @@ The command line used to call the TeX formatter and typesetter.
.IP TEXCOMSTR
The string displayed when calling
the TeX formatter and typesetter.
-If this is not set, then $TEXCOM (the command line) is displayed.
+If this is not set, then \fB$TEXCOM\fP (the command line) is displayed.
.ES
env = Environment(TEXCOMSTR = "Building $TARGET from TeX input $SOURCES")
@@ -11314,19 +11294,26 @@ field in the controlling information for MSI packages.
The version of the project, specified as a string.
.IP WIN32_INSERT_DEF
-A deprecated synonym for $WINDOWS_INSERT_DEF.
+A deprecated synonym for \fB$WINDOWS_INSERT_DEF\fP.
.IP WIN32DEFPREFIX
-A deprecated synonym for $WINDOWSDEFPREFIX.
+A deprecated synonym for \fB$WINDOWSDEFPREFIX\fP.
.IP WIN32DEFSUFFIX
-A deprecated synonym for $WINDOWSDEFSUFFIX.
+A deprecated synonym for \fB$WINDOWSDEFSUFFIX\fP.
.IP WIN32EXPPREFIX
-A deprecated synonym for $WINDOWSEXPSUFFIX.
+A deprecated synonym for \fB$WINDOWSEXPSUFFIX\fP.
.IP WIN32EXPSUFFIX
-A deprecated synonym for $WINDOWSEXPSUFFIX.
+A deprecated synonym for \fB$WINDOWSEXPSUFFIX\fP.
+
+.IP WINDOWS_EMBED_MANIFEST
+Set this variable to True or 1 to embed the compiler-generated manifest
+(normally \fB${TARGET}.manifest\fP)
+into all Windows exes and DLLs built with this environment,
+as a resource during their link step.
+This is done using \fB$MT\fP and \fB$MTEXECOM\fP and \fB$MTSHLIBCOM\fP.
.IP WINDOWS_INSERT_DEF
When this is set to true,
@@ -11346,7 +11333,7 @@ will be aware of the
files generated by Microsoft Visua C/C++ 8.
.IP WINDOWSDEFPREFIX
-The prefix used for Windows \fB.def\fPfile names.
+The prefix used for Windows \fB.def\fP file names.
.IP WINDOWSDEFSUFFIX
The suffix used for Windows \fB.def\fP file names.
@@ -11383,7 +11370,7 @@ This is used to fill in the
.B Description:
field in the controlling information for Ipkg packages.
The default value is
-.B "$SUMMARY\\\\$SUMMARY"
+.B "$SUMMARY\\n$DESCRIPTION"
.IP X_IPK_MAINTAINER
This is used to fill in the
.B Maintainer:
@@ -11407,7 +11394,7 @@ attribute in the controlling information for MSI packages.
.IP X_MSI_LICENSE_TEXT
The text of the software license in RTF format.
Carriage return characters will be
-replaced with the RTF equivalent \\\par.
+replaced with the RTF equivalent \\\\par.
.IP X_MSI_UPGRADE_CODE
TODO
@@ -11567,7 +11554,7 @@ to generate a source file.
.IP YACCCOMSTR
The string displayed when generating a source file
using the parser generator.
-If this is not set, then $YACCCOM (the command line) is displayed.
+If this is not set, then \fB$YACCCOM\fP (the command line) is displayed.
.ES
env = Environment(YACCCOMSTR = "Yacc'ing $TARGET from $SOURCES")
@@ -11575,7 +11562,7 @@ env = Environment(YACCCOMSTR = "Yacc'ing $TARGET from $SOURCES")
.IP YACCFLAGS
General options passed to the parser generator.
-If $YACCFLAGS contains a \fB\-d\fP option,
+If \fB$YACCFLAGS\fP contains a \fB\-d\fP option,
SCons assumes that the call will also create a .h file
(if the yacc source file ends in a .y suffix)
or a .hpp file
@@ -11656,7 +11643,7 @@ module is unavailable.
.IP ZIPCOMSTR
The string displayed when archiving files
using the zip utility.
-If this is not set, then $ZIPCOM
+If this is not set, then \fB$ZIPCOM\fP
(the command line or internal Python function) is displayed.
.ES
@@ -13144,14 +13131,14 @@ implicit dependencies
based only on the target file
and the construction environment,
.I not
-for implicit
-(See the section "Scanner Objects," below,
+for implicit dependencies based on source files.
+(See the section "Scanner Objects" below,
for information about creating Scanner objects.)
.IP source_scanner
A Scanner object that
will be invoked to
-find implicit dependences in
+find implicit dependencies in
any source files
used to build this target file.
This is where you would
@@ -13168,7 +13155,7 @@ for on-disk changes to files
that
.B scons
does not know about from other Builder or function calls.
-(See the section "Scanner Objects," below,
+(See the section "Scanner Objects" below,
for information about creating your own Scanner objects.)
.IP target_factory
@@ -14273,7 +14260,7 @@ 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,
+See the section "Python Code Substitution" below,
for more thorough examples of
how this can be used.
@@ -14450,9 +14437,9 @@ function accepts the following arguments:
This can be either:
1) a Python function that will process
the Node (file)
-and return a list of strings (file names)
+and return a list of File Nodes
representing the implicit
-dependencies found in the contents;
+dependencies (file names) found in the contents;
or:
2) a dictionary that maps keys
(typically the file suffix, but see below for more discussion)
@@ -14626,7 +14613,7 @@ def xyz_scan(node, env, path):
XYZScanner = Scanner(xyz_scan)
-SourceFileScanner.add_scanner('.xyx', XYZScanner)
+SourceFileScanner.add_scanner('.xyz', XYZScanner)
env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz'])
.EE
@@ -14895,7 +14882,7 @@ include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
def kfile_scan(node, env, path, arg):
contents = node.get_text_contents()
includes = include_re.findall(contents)
- return includes
+ return env.File(includes)
kscan = Scanner(name = 'kfile',
function = kfile_scan,
@@ -14911,6 +14898,14 @@ env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
bar_in.target_scanner = kscan
.EE
+It is important to note that you
+have to return a list of File nodes from the scan function, simple
+strings for the file names won't do. As in the examples we are showing here,
+you can use the
+.BR File()
+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
a path of directories
(specified as the
@@ -14919,30 +14914,35 @@ construction variable)
for files that actually exist:
.ES
+import re
+import os
include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
def my_scan(node, env, path, arg):
- contents = node.get_text_contents()
- includes = include_re.findall(contents)
- if includes == []:
+ contents = node.get_text_contents()
+ includes = include_re.findall(contents)
+ if includes == []:
return []
results = []
for inc in includes:
for dir in path:
- file = dir + os.sep + inc
+ file = str(dir) + os.sep + inc
if os.path.exists(file):
results.append(file)
break
- return results
+ return env.File(results)
scanner = Scanner(name = 'myscanner',
function = my_scan,
argument = None,
skeys = ['.x'],
- path_function = FindPathDirs('MYPATH'),
+ path_function = FindPathDirs('MYPATH')
)
scanners = Environment().Dictionary('SCANNERS')
-env = Environment(SCANNERS = scanners + [scanner])
+env = Environment(SCANNERS = scanners + [scanner],
+ MYPATH = ['incs'])
+
+env.Command('foo', 'foo.x', 'xprocess < $SOURCES > $TARGET')
.EE
The
@@ -14952,7 +14952,13 @@ function used in the previous example returns a function
that will return a list of directories
specified in the
.B $MYPATH
-construction variable.
+construction variable. It lets SCons detect the file
+.B incs/foo.inc
+, even if
+.B foo.x
+contains the line
+.B include foo.inc
+only.
If you need to customize how the search path is derived,
you would provide your own
.B path_function
@@ -14973,7 +14979,7 @@ scanner = Scanner(name = 'myscanner',
function = my_scan,
argument = None,
skeys = ['.x'],
- path_function = pf,
+ path_function = pf
)
.EE