Relintai/scons_gd
1
0
Fork 0
mirror of https://github.com/Relintai/scons_gd.git synced 2025-03-12 18:38:59 +01:00
Code Issues Packages Projects Releases Wiki Activity
master
scons_gd/scons/doc/generated/variables.gen
Relintai 2f9a2dce8b Added scons.
2022-10-15 16:06:26 +02:00

10361 lines
301 KiB
Plaintext
Raw Permalink Blame History

<!DOCTYPE sconsdoc [
<!ENTITY % scons SYSTEM "../scons.mod">
%scons;
<!ENTITY % builders-mod SYSTEM "builders.mod">
%builders-mod;
<!ENTITY % functions-mod SYSTEM "functions.mod">
%functions-mod;
<!ENTITY % tools-mod SYSTEM "tools.mod">
%tools-mod;
<!ENTITY % variables-mod SYSTEM "variables.mod">
%variables-mod;
]>
<variablelist xmlns="http://www.scons.org/dbxsd/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
<varlistentry id="cv-__LDMODULEVERSIONFLAGS">
<term>
<envar>__LDMODULEVERSIONFLAGS</envar>
</term>
<listitem><para>
This construction variable automatically introduces &cv-link-_LDMODULEVERSIONFLAGS;
if &cv-link-LDMODULEVERSION; is set. Othervise it evaluates to an empty string.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-__SHLIBVERSIONFLAGS">
<term>
<envar>__SHLIBVERSIONFLAGS</envar>
</term>
<listitem><para>
This construction variable automatically introduces &cv-link-_SHLIBVERSIONFLAGS;
if &cv-link-SHLIBVERSION; is set. Othervise it evaluates to an empty string.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-APPLELINK_COMPATIBILITY_VERSION">
<term>
<envar>APPLELINK_COMPATIBILITY_VERSION</envar>
</term>
<listitem><para>
On Mac OS X this is used to set the linker flag:
-compatibility_version
</para>
<para>
The value is specified as X[.Y[.Z]] where X is between 1 and 65535, Y can be omitted or between 1 and
255, Z can be omitted or between 1 and 255. This value will be derived from &cv-link-SHLIBVERSION; if
not
specified. The lowest digit will be dropped and replaced by a 0.
</para>
<para>
If the &cv-link-APPLELINK_NO_COMPATIBILITY_VERSION; is set then no -compatibility_version will be
output.
</para>
<para>See MacOS's ld manpage for more details</para>
</listitem>
</varlistentry>
<varlistentry id="cv-_APPLELINK_COMPATIBILITY_VERSION">
<term>
<envar>_APPLELINK_COMPATIBILITY_VERSION</envar>
</term>
<listitem><para>
A macro (by default a generator function) used to create the linker flags to specify
apple's linker's -compatibility_version flag.
The default generator uses &cv-link-APPLELINK_COMPATIBILITY_VERSION;
and &cv-link-APPLELINK_NO_COMPATIBILITY_VERSION; and &cv-link-SHLIBVERSION;
to determine the correct flag.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-APPLELINK_CURRENT_VERSION">
<term>
<envar>APPLELINK_CURRENT_VERSION</envar>
</term>
<listitem><para>
On Mac OS X this is used to set the linker flag:
-current_version
</para>
<para>
The value is specified as X[.Y[.Z]] where X is between 1 and 65535, Y can be omitted or between 1 and
255, Z can be omitted or between 1 and 255. This value will be set to &cv-link-SHLIBVERSION; if not
specified.
</para>
<para>
If the &cv-link-APPLELINK_NO_CURRENT_VERSION; is set then no -current_version will be
output.
</para>
<para>See MacOS's ld manpage for more details</para>
</listitem>
</varlistentry>
<varlistentry id="cv-_APPLELINK_CURRENT_VERSION">
<term>
<envar>_APPLELINK_CURRENT_VERSION</envar>
</term>
<listitem><para>
A macro (by default a generator function) used to create the linker flags to specify apple's linker's
-current_version flag. The default generator uses &cv-link-APPLELINK_CURRENT_VERSION; and
&cv-link-APPLELINK_NO_CURRENT_VERSION; and &cv-link-SHLIBVERSION; to determine the correct flag.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-APPLELINK_NO_COMPATIBILITY_VERSION">
<term>
<envar>APPLELINK_NO_COMPATIBILITY_VERSION</envar>
</term>
<listitem><para>
Set this to any True (1|True|non-empty string) value to disable adding -compatibility_version flag when
generating versioned shared libraries.
</para>
<para>
This overrides &cv-link-APPLELINK_COMPATIBILITY_VERSION;.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-APPLELINK_NO_CURRENT_VERSION">
<term>
<envar>APPLELINK_NO_CURRENT_VERSION</envar>
</term>
<listitem><para>
Set this to any True (1|True|non-empty string) value to disable adding -current_version flag when
generating versioned shared libraries.
</para>
<para>
This overrides &cv-link-APPLELINK_CURRENT_VERSION;.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-AR">
<term>
<envar>AR</envar>
</term>
<listitem><para>
The static library archiver.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-ARCHITECTURE">
<term>
<envar>ARCHITECTURE</envar>
</term>
<listitem><para>
Specifies the system architecture for which
the package is being built.
The default is the system architecture
of the machine on which SCons is running.
This is used to fill in the
<literal>Architecture:</literal>
field in an Ipkg
<filename>control</filename> file,
and the <literal>BuildArch:</literal> field
in the RPM <filename>.spec</filename> file,
as well as forming part of the name of a generated RPM package file.
</para>
<para>See the &b-link-Package; builder.</para>
</listitem>
</varlistentry>
<varlistentry id="cv-ARCOM">
<term>
<envar>ARCOM</envar>
</term>
<listitem><para>
The command line used to generate a static library from object files.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-ARCOMSTR">
<term>
<envar>ARCOMSTR</envar>
</term>
<listitem><para>
The string displayed when a static library is
generated from object files.
If this is not set, then &cv-link-ARCOM; (the command line) is displayed.
</para>
<example_commands>
env = Environment(ARCOMSTR = "Archiving $TARGET")
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-ARFLAGS">
<term>
<envar>ARFLAGS</envar>
</term>
<listitem><para>
General options passed to the static library archiver.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-AS">
<term>
<envar>AS</envar>
</term>
<listitem><para>
The assembler.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-ASCOM">
<term>
<envar>ASCOM</envar>
</term>
<listitem><para>
The command line used to generate an object file
from an assembly-language source file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-ASCOMSTR">
<term>
<envar>ASCOMSTR</envar>
</term>
<listitem><para>
The string displayed when an object file
is generated from an assembly-language source file.
If this is not set, then &cv-link-ASCOM; (the command line) is displayed.
</para>
<example_commands>
env = Environment(ASCOMSTR = "Assembling $TARGET")
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-ASFLAGS">
<term>
<envar>ASFLAGS</envar>
</term>
<listitem><para>
General options passed to the assembler.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-ASPPCOM">
<term>
<envar>ASPPCOM</envar>
</term>
<listitem><para>
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 &cv-link-ASFLAGS; and &cv-link-CPPFLAGS; construction variables
are included on this command line.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-ASPPCOMSTR">
<term>
<envar>ASPPCOMSTR</envar>
</term>
<listitem><para>
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 &cv-link-ASPPCOM; (the command line) is displayed.
</para>
<example_commands>
env = Environment(ASPPCOMSTR = "Assembling $TARGET")
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-ASPPFLAGS">
<term>
<envar>ASPPFLAGS</envar>
</term>
<listitem><para>
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 &cv-link-ASFLAGS;.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-BIBTEX">
<term>
<envar>BIBTEX</envar>
</term>
<listitem><para>
The bibliography generator for the TeX formatter and typesetter and the
LaTeX structured formatter and typesetter.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-BIBTEXCOM">
<term>
<envar>BIBTEXCOM</envar>
</term>
<listitem><para>
The command line used to call the bibliography generator for the
TeX formatter and typesetter and the LaTeX structured formatter and
typesetter.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-BIBTEXCOMSTR">
<term>
<envar>BIBTEXCOMSTR</envar>
</term>
<listitem><para>
The string displayed when generating a bibliography
for TeX or LaTeX.
If this is not set, then &cv-link-BIBTEXCOM; (the command line) is displayed.
</para>
<example_commands>
env = Environment(BIBTEXCOMSTR = "Generating bibliography $TARGET")
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-BIBTEXFLAGS">
<term>
<envar>BIBTEXFLAGS</envar>
</term>
<listitem><para>
General options passed to the bibliography generator for the TeX formatter
and typesetter and the LaTeX structured formatter and typesetter.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-BUILDERS">
<term>
<envar>BUILDERS</envar>
</term>
<listitem><para>
A dictionary mapping the names of the builders
available through the &consenv; to underlying Builder objects.
Custom builders need to be added to this to make them available.
</para>
<para>
A platform-dependent default list of builders such as
&b-link-Program;, &b-link-Library; etc. is used to
populate this &consvar; when the &consenv; is initialized
via the presence/absence of the tools those builders depend on.
&cv-BUILDERS; can be examined to learn which builders will
actually be available at run-time.
</para>
<para>
Note that if you initialize this &consvar; through
assignment when the &consenv; is created,
that value for &cv-BUILDERS; will override any defaults:
</para>
<example_commands>
bld = Builder(action='foobuild &lt; $SOURCE &gt; $TARGET')
env = Environment(BUILDERS={'NewBuilder': bld})
</example_commands>
<para>
To instead use a new Builder object in addition to the default Builders,
add your new Builder object like this:
</para>
<example_commands>
env = Environment()
env.Append(BUILDERS={'NewBuilder': bld})
</example_commands>
<para>
or this:
</para>
<example_commands>
env = Environment()
env['BUILDERS']['NewBuilder'] = bld
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-CACHEDIR_CLASS">
<term>
<envar>CACHEDIR_CLASS</envar>
</term>
<listitem><para>
The class type that SCons should use when instantiating a
new &f-link-CacheDir; for the given environment. It must be
a subclass of the SCons.CacheDir.CacheDir class.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-CC">
<term>
<envar>CC</envar>
</term>
<listitem><para>
The C compiler.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-CCCOM">
<term>
<envar>CCCOM</envar>
</term>
<listitem><para>
The command line used to compile a C source file to a (static) object
file. Any options specified in the &cv-link-CFLAGS;, &cv-link-CCFLAGS; and
&cv-link-CPPFLAGS; construction variables are included on this command line.
See also &cv-link-SHCCCOM; for compiling to shared objects.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-CCCOMSTR">
<term>
<envar>CCCOMSTR</envar>
</term>
<listitem><para>
If set, the string displayed when a C source file
is compiled to a (static) object file.
If not set, then &cv-link-CCCOM; (the command line) is displayed.
See also &cv-link-SHCCCOMSTR; for compiling to shared objects.
</para>
<example_commands>
env = Environment(CCCOMSTR = "Compiling static object $TARGET")
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-CCDEPFLAGS">
<term>
<envar>CCDEPFLAGS</envar>
</term>
<listitem><para>
Options to pass to C or C++ compiler to generate list of dependency files.
</para>
<para>
This is set only by compilers which support this functionality. (&t-link-gcc;, &t-link-clang;, and &t-link-msvc; currently)
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-CCFLAGS">
<term>
<envar>CCFLAGS</envar>
</term>
<listitem><para>
General options that are passed to the C and C++ compilers.
See also &cv-link-SHCCFLAGS; for compiling to shared objects.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-CCPCHFLAGS">
<term>
<envar>CCPCHFLAGS</envar>
</term>
<listitem><para>
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 &cv-link-PCH; construction variable is set.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-CCPDBFLAGS">
<term>
<envar>CCPDBFLAGS</envar>
</term>
<listitem><para>
Options added to the compiler command line
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 &cv-link-PDB; construction variable is set.
</para>
<para>
The Visual C++ compiler option that SCons uses by default
to generate PDB information is <option>/Z7</option>.
This works correctly with parallel (<option>-j</option>) builds
because it embeds the debug information in the intermediate object files,
as opposed to sharing a single PDB file between multiple object files.
This is also the only way to get debug information
embedded into a static library.
Using the <option>/Zi</option> instead may yield improved
link-time performance,
although parallel builds will no longer work.
</para>
<para>
You can generate PDB files with the <option>/Zi</option>
switch by overriding the default &cv-link-CCPDBFLAGS; variable as follows:
</para>
<example_commands>
env['CCPDBFLAGS'] = ['${(PDB and "/Zi /Fd%s" % File(PDB)) or ""}']
</example_commands>
<para>
An alternative would be to use the <option>/Zi</option>
to put the debugging information in a separate <filename>.pdb</filename>
file for each object file by overriding
the &cv-link-CCPDBFLAGS; variable as follows:
</para>
<example_commands>
env['CCPDBFLAGS'] = '/Zi /Fd${TARGET}.pdb'
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-CCVERSION">
<term>
<envar>CCVERSION</envar>
</term>
<listitem><para>
The version number of the C compiler.
This may or may not be set,
depending on the specific C compiler being used.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-CFILESUFFIX">
<term>
<envar>CFILESUFFIX</envar>
</term>
<listitem><para>
The suffix for C source files.
This is used by the internal CFile builder
when generating C files from Lex (.l) or YACC (.y) input files.
The default suffix, of course, is
<filename>.c</filename>
(lower case).
On case-insensitive systems (like Windows),
SCons also treats
<filename>.C</filename>
(upper case) files
as C files.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-CFLAGS">
<term>
<envar>CFLAGS</envar>
</term>
<listitem><para>
General options that are passed to the C compiler (C only; not C++).
See also &cv-link-SHCFLAGS; for compiling to shared objects.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-CHANGE_SPECFILE">
<term>
<envar>CHANGE_SPECFILE</envar>
</term>
<listitem><para>
A hook for modifying the file that controls the packaging build
(the <filename>.spec</filename> for RPM,
the <filename>control</filename> for Ipkg,
the <filename>.wxs</filename> for MSI).
If set, the function will be called
after the SCons template for the file has been written.
</para>
<para>See the &b-link-Package; builder.</para>
</listitem>
</varlistentry>
<varlistentry id="cv-CHANGED_SOURCES">
<term>
<envar>CHANGED_SOURCES</envar>
</term>
<listitem><para>
A reserved variable name
that may not be set or used in a construction environment.
(See the manpage section "Variable Substitution"
for more information).
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-CHANGED_TARGETS">
<term>
<envar>CHANGED_TARGETS</envar>
</term>
<listitem><para>
A reserved variable name
that may not be set or used in a construction environment.
(See the manpage section "Variable Substitution"
for more information).
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-CHANGELOG">
<term>
<envar>CHANGELOG</envar>
</term>
<listitem><para>
The name of a file containing the change log text
to be included in the package.
This is included as the
<literal>%changelog</literal>
section of the RPM
<filename>.spec</filename> file.
</para>
<para>See the &b-link-Package; builder.</para>
</listitem>
</varlistentry>
<varlistentry id="cv-COMPILATIONDB_COMSTR">
<term>
<envar>COMPILATIONDB_COMSTR</envar>
</term>
<listitem><para>
The string displayed when the &b-link-CompilationDatabase;
builder's action is run.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-COMPILATIONDB_PATH_FILTER">
<term>
<envar>COMPILATIONDB_PATH_FILTER</envar>
</term>
<listitem><para>
A string which instructs &b-link-CompilationDatabase; to
only include entries where the <literal>output</literal> member
matches the pattern in the filter string using fnmatch, which
uses glob style wildcards.
</para>
<para>
The default value is an empty string '', which disables filtering.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-COMPILATIONDB_USE_ABSPATH">
<term>
<envar>COMPILATIONDB_USE_ABSPATH</envar>
</term>
<listitem><para>
A boolean flag to instruct &b-link-CompilationDatabase;
whether to write the <literal>file</literal> and
<literal>output</literal> members
in the compilation database using absolute or relative paths.
</para>
<para>
The default value is False (use relative paths)
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-_concat">
<term>
<envar>_concat</envar>
</term>
<listitem><para>
A function used to produce variables like &cv-link-_CPPINCFLAGS;. It takes
four mandatory arguments, and up to 4 additional optional arguments:
1) a prefix to concatenate onto each element,
2) a list of elements,
3) a suffix to concatenate onto each element,
4) an environment for variable interpolation,
5) an optional function that will be called to transform the list before concatenation,
6) an optionally specified target (Can use TARGET),
7) an optionally specified source (Can use SOURCE),
8) optional <parameter>affect_signature</parameter> flag which will wrap non-empty returned value with $( and $) to indicate the contents
should not affect the signature of the generated command line.
</para>
<example_commands>
env['_CPPINCFLAGS'] = '${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs, TARGET, SOURCE, affect_signature=False)}'
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-CONFIGUREDIR">
<term>
<envar>CONFIGUREDIR</envar>
</term>
<listitem><para>
The name of the directory in which
Configure context test files are written.
The default is
<filename>.sconf_temp</filename>
in the top-level directory
containing the
<filename>SConstruct</filename>
file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-CONFIGURELOG">
<term>
<envar>CONFIGURELOG</envar>
</term>
<listitem><para>
The name of the &Configure; context log file.
The default is
<filename>config.log</filename>
in the top-level directory
containing the
<filename>SConstruct</filename>
file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-_CPPDEFFLAGS">
<term>
<envar>_CPPDEFFLAGS</envar>
</term>
<listitem><para>
An automatically-generated &consvar;
containing the C preprocessor command-line options
to define values.
The value of &cv-link-_CPPDEFFLAGS; is created
by respectively prepending and appending
&cv-link-CPPDEFPREFIX; and &cv-link-CPPDEFSUFFIX;
to each definition in &cv-link-CPPDEFINES;.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-CPPDEFINES">
<term>
<envar>CPPDEFINES</envar>
</term>
<listitem><para>
A platform independent specification of C preprocessor macro definitions.
The definitions will be added to command lines
through the automatically-generated
&cv-link-_CPPDEFFLAGS; &consvar; (see above),
which is constructed according to
the type of value of &cv-CPPDEFINES;:
</para>
<para>
If &cv-CPPDEFINES; is a string,
the values of the
&cv-link-CPPDEFPREFIX; and &cv-link-CPPDEFSUFFIX; &consvars;
will be respectively prepended and appended to
each definition in &cv-link-CPPDEFINES;.
</para>
<example_commands>
# Will add -Dxyz to POSIX compiler command lines,
# and /Dxyz to Microsoft Visual C++ command lines.
env = Environment(CPPDEFINES='xyz')
</example_commands>
<para>
If &cv-CPPDEFINES; is a list,
the values of the
&cv-CPPDEFPREFIX; and &cv-CPPDEFSUFFIX; &consvars;
will be respectively prepended and appended to
each element in the list.
If any element is a list or tuple,
then the first item is the name being
defined and the second item is its value:
</para>
<example_commands>
# Will add -DB=2 -DA to POSIX compiler command lines,
# and /DB=2 /DA to Microsoft Visual C++ command lines.
env = Environment(CPPDEFINES=[('B', 2), 'A'])
</example_commands>
<para>
If &cv-CPPDEFINES; is a dictionary,
the values of the
&cv-CPPDEFPREFIX; and &cv-CPPDEFSUFFIX; &consvars;
will be respectively prepended and appended to
each item from the dictionary.
The key of each dictionary item
is a name being defined
to the dictionary item's corresponding value;
if the value is
<literal>None</literal>,
then the name is defined without an explicit value.
Note that the resulting flags are sorted by keyword
to ensure that the order of the options on the
command line is consistent each time
&scons;
is run.
</para>
<example_commands>
# Will add -DA -DB=2 to POSIX compiler command lines,
# and /DA /DB=2 to Microsoft Visual C++ command lines.
env = Environment(CPPDEFINES={'B':2, 'A':None})
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-CPPDEFPREFIX">
<term>
<envar>CPPDEFPREFIX</envar>
</term>
<listitem><para>
The prefix used to specify preprocessor macro definitions
on the C compiler command line.
This will be prepended to each definition
in the &cv-link-CPPDEFINES; &consvar;
when the &cv-link-_CPPDEFFLAGS; variable is automatically generated.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-CPPDEFSUFFIX">
<term>
<envar>CPPDEFSUFFIX</envar>
</term>
<listitem><para>
The suffix used to specify preprocessor macro definitions
on the C compiler command line.
This will be appended to each definition
in the &cv-link-CPPDEFINES; &consvar;
when the &cv-link-_CPPDEFFLAGS; variable is automatically generated.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-CPPFLAGS">
<term>
<envar>CPPFLAGS</envar>
</term>
<listitem><para>
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 &cv-link-CCCOM;,
&cv-link-SHCCCOM;,
&cv-link-CXXCOM; and
&cv-link-SHCXXCOM; command lines,
but also the &cv-link-FORTRANPPCOM;,
&cv-link-SHFORTRANPPCOM;,
&cv-link-F77PPCOM; and
&cv-link-SHF77PPCOM; command lines
used to compile a Fortran source file,
and the &cv-link-ASPPCOM; command line
used to assemble an assembly language source file,
after first running each file through the C preprocessor.
Note that this variable does
<emphasis>not</emphasis>
contain
<option>-I</option>
(or similar) include search path options
that scons generates automatically from &cv-link-CPPPATH;.
See &cv-link-_CPPINCFLAGS;, below,
for the variable that expands to those options.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-_CPPINCFLAGS">
<term>
<envar>_CPPINCFLAGS</envar>
</term>
<listitem><para>
An automatically-generated &consvar;
containing the C preprocessor command-line options
for specifying directories to be searched for include files.
The value of &cv-_CPPINCFLAGS; is created
by respectively prepending and appending
&cv-link-INCPREFIX; and &cv-link-INCSUFFIX;
to each directory in &cv-link-CPPPATH;.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-CPPPATH">
<term>
<envar>CPPPATH</envar>
</term>
<listitem><para>
The list of directories that the C preprocessor will search for include
directories. The C/C++ implicit dependency scanner will search these
directories for include files.
In general it's not advised to put include directory directives
directly into &cv-link-CCFLAGS; or &cv-link-CXXFLAGS;
as the result will be non-portable
and the directories will not be searched by the dependency scanner.
&cv-CPPPATH; should be a list of path strings,
or a single string, not a pathname list joined by
Python's <systemitem>os.sep</systemitem>.
</para>
<para>
Note:
directory names in &cv-CPPPATH;
will be looked-up relative to the directory of the SConscript file
when they are used in a command.
To force &scons;
to look-up a directory relative to the root of the source tree use
the <literal>#</literal> prefix:
</para>
<example_commands>
env = Environment(CPPPATH='#/include')
</example_commands>
<para>
The directory look-up can also be forced using the
&f-link-Dir;
function:
</para>
<example_commands>
include = Dir('include')
env = Environment(CPPPATH=include)
</example_commands>
<para>
The directory list will be added to command lines
through the automatically-generated
&cv-link-_CPPINCFLAGS; &consvar;,
which is constructed by
respectively prepending and appending the values of the
&cv-link-INCPREFIX; and &cv-link-INCSUFFIX; &consvars;
to each directory in &cv-link-CPPPATH;.
Any command lines you define that need
the &cv-CPPPATH; directory list should
include &cv-link-_CPPINCFLAGS;:
</para>
<example_commands>
env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-CPPSUFFIXES">
<term>
<envar>CPPSUFFIXES</envar>
</term>
<listitem><para>
The list of suffixes of files that will be scanned
for C preprocessor implicit dependencies
(#include lines).
The default list is:
</para>
<example_commands>
[".c", ".C", ".cxx", ".cpp", ".c++", ".cc",
".h", ".H", ".hxx", ".hpp", ".hh",
".F", ".fpp", ".FPP",
".m", ".mm",
".S", ".spp", ".SPP"]
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-CXX">
<term>
<envar>CXX</envar>
</term>
<listitem><para>
The C++ compiler.
See also &cv-link-SHCXX; for compiling to shared objects..
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-CXXCOM">
<term>
<envar>CXXCOM</envar>
</term>
<listitem><para>
The command line used to compile a C++ source file to an object file.
Any options specified in the &cv-link-CXXFLAGS; and
&cv-link-CPPFLAGS; construction variables
are included on this command line.
See also &cv-link-SHCXXCOM; for compiling to shared objects..
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-CXXCOMSTR">
<term>
<envar>CXXCOMSTR</envar>
</term>
<listitem><para>
If set, the string displayed when a C++ source file
is compiled to a (static) object file.
If not set, then &cv-link-CXXCOM; (the command line) is displayed.
See also &cv-link-SHCXXCOMSTR; for compiling to shared objects..
</para>
<example_commands>
env = Environment(CXXCOMSTR = "Compiling static object $TARGET")
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-CXXFILESUFFIX">
<term>
<envar>CXXFILESUFFIX</envar>
</term>
<listitem><para>
The suffix for C++ source files.
This is used by the internal CXXFile builder
when generating C++ files from Lex (.ll) or YACC (.yy) input files.
The default suffix is
<filename>.cc</filename>.
SCons also treats files with the suffixes
<filename>.cpp</filename>,
<filename>.cxx</filename>,
<filename>.c++</filename>,
and
<filename>.C++</filename>
as C++ files,
and files with
<filename>.mm</filename>
suffixes as Objective C++ files.
On case-sensitive systems (Linux, UNIX, and other POSIX-alikes),
SCons also treats
<filename>.C</filename>
(upper case) files
as C++ files.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-CXXFLAGS">
<term>
<envar>CXXFLAGS</envar>
</term>
<listitem><para>
General options that are passed to the C++ compiler.
By default, this includes the value of &cv-link-CCFLAGS;,
so that setting &cv-CCFLAGS; affects both C and C++ compilation.
If you want to add C++-specific flags,
you must set or override the value of &cv-link-CXXFLAGS;.
See also &cv-link-SHCXXFLAGS; for compiling to shared objects..
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-CXXVERSION">
<term>
<envar>CXXVERSION</envar>
</term>
<listitem><para>
The version number of the C++ compiler.
This may or may not be set,
depending on the specific C++ compiler being used.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DC">
<term>
<envar>DC</envar>
</term>
<listitem><para>
The D compiler to use.
See also &cv-link-SHDC; for compiling to shared objects.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DCOM">
<term>
<envar>DCOM</envar>
</term>
<listitem><para>
The command line used to compile a D file to an object file.
Any options specified in the &cv-link-DFLAGS; construction variable
is included on this command line.
See also &cv-link-SHDCOM; for compiling to shared objects.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DCOMSTR">
<term>
<envar>DCOMSTR</envar>
</term>
<listitem><para>
If set, the string displayed when a D source file
is compiled to a (static) object file.
If not set, then &cv-link-DCOM; (the command line) is displayed.
See also &cv-link-SHDCOMSTR; for compiling to shared objects.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DDEBUG">
<term>
<envar>DDEBUG</envar>
</term>
<listitem><para>
List of debug tags to enable when compiling.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DDEBUGPREFIX">
<term>
<envar>DDEBUGPREFIX</envar>
</term>
<listitem><para>
DDEBUGPREFIX.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DDEBUGSUFFIX">
<term>
<envar>DDEBUGSUFFIX</envar>
</term>
<listitem><para>
DDEBUGSUFFIX.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DESCRIPTION">
<term>
<envar>DESCRIPTION</envar>
</term>
<listitem><para>
A long description of the project being packaged.
This is included in the relevant section
of the file that controls the packaging build.
</para>
<para>See the &b-link-Package; builder.</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DESCRIPTION_lang">
<term>
<envar>DESCRIPTION_lang</envar>
</term>
<listitem><para>
A language-specific long description for
the specified <varname>lang</varname>.
This is used to populate a
<literal>%description -l</literal>
section of an RPM
<filename>.spec</filename> file.
</para>
<para>See the &b-link-Package; builder.</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DFILESUFFIX">
<term>
<envar>DFILESUFFIX</envar>
</term>
<listitem><para>
DFILESUFFIX.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DFLAGPREFIX">
<term>
<envar>DFLAGPREFIX</envar>
</term>
<listitem><para>
DFLAGPREFIX.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DFLAGS">
<term>
<envar>DFLAGS</envar>
</term>
<listitem><para>
General options that are passed to the D compiler.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DFLAGSUFFIX">
<term>
<envar>DFLAGSUFFIX</envar>
</term>
<listitem><para>
DFLAGSUFFIX.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DINCPREFIX">
<term>
<envar>DINCPREFIX</envar>
</term>
<listitem><para>
DINCPREFIX.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DINCSUFFIX">
<term>
<envar>DINCSUFFIX</envar>
</term>
<listitem><para>
DLIBFLAGSUFFIX.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-Dir">
<term>
<envar>Dir</envar>
</term>
<listitem><para>
A function that converts a string
into a Dir instance relative to the target being built.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-Dirs">
<term>
<envar>Dirs</envar>
</term>
<listitem><para>
A function that converts a list of strings
into a list of Dir instances relative to the target being built.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DLIB">
<term>
<envar>DLIB</envar>
</term>
<listitem><para>
Name of the lib tool to use for D codes.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DLIBCOM">
<term>
<envar>DLIBCOM</envar>
</term>
<listitem><para>
The command line to use when creating libraries.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DLIBDIRPREFIX">
<term>
<envar>DLIBDIRPREFIX</envar>
</term>
<listitem><para>
DLIBLINKPREFIX.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DLIBDIRSUFFIX">
<term>
<envar>DLIBDIRSUFFIX</envar>
</term>
<listitem><para>
DLIBLINKSUFFIX.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DLIBFLAGPREFIX">
<term>
<envar>DLIBFLAGPREFIX</envar>
</term>
<listitem><para>
DLIBFLAGPREFIX.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DLIBFLAGSUFFIX">
<term>
<envar>DLIBFLAGSUFFIX</envar>
</term>
<listitem><para>
DLIBFLAGSUFFIX.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DLIBLINKPREFIX">
<term>
<envar>DLIBLINKPREFIX</envar>
</term>
<listitem><para>
DLIBLINKPREFIX.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DLIBLINKSUFFIX">
<term>
<envar>DLIBLINKSUFFIX</envar>
</term>
<listitem><para>
DLIBLINKSUFFIX.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DLINK">
<term>
<envar>DLINK</envar>
</term>
<listitem><para>
Name of the linker to use for linking systems including D sources.
See also &cv-link-SHDLINK; for linking shared objects.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DLINKCOM">
<term>
<envar>DLINKCOM</envar>
</term>
<listitem><para>
The command line to use when linking systems including D sources.
See also &cv-link-SHDLINKCOM; for linking shared objects.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DLINKFLAGPREFIX">
<term>
<envar>DLINKFLAGPREFIX</envar>
</term>
<listitem><para>
DLINKFLAGPREFIX.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DLINKFLAGS">
<term>
<envar>DLINKFLAGS</envar>
</term>
<listitem><para>
List of linker flags.
See also &cv-link-SHDLINKFLAGS; for linking shared objects.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DLINKFLAGSUFFIX">
<term>
<envar>DLINKFLAGSUFFIX</envar>
</term>
<listitem><para>
DLINKFLAGSUFFIX.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DOCBOOK_DEFAULT_XSL_EPUB">
<term>
<envar>DOCBOOK_DEFAULT_XSL_EPUB</envar>
</term>
<listitem><para>
The default XSLT file for the &b-link-DocbookEpub; builder within the
current environment, if no other XSLT gets specified via keyword.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DOCBOOK_DEFAULT_XSL_HTML">
<term>
<envar>DOCBOOK_DEFAULT_XSL_HTML</envar>
</term>
<listitem><para>
The default XSLT file for the &b-link-DocbookHtml; builder within the
current environment, if no other XSLT gets specified via keyword.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DOCBOOK_DEFAULT_XSL_HTMLCHUNKED">
<term>
<envar>DOCBOOK_DEFAULT_XSL_HTMLCHUNKED</envar>
</term>
<listitem><para>
The default XSLT file for the &b-link-DocbookHtmlChunked; builder within the
current environment, if no other XSLT gets specified via keyword.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DOCBOOK_DEFAULT_XSL_HTMLHELP">
<term>
<envar>DOCBOOK_DEFAULT_XSL_HTMLHELP</envar>
</term>
<listitem><para>
The default XSLT file for the &b-link-DocbookHtmlhelp; builder within the
current environment, if no other XSLT gets specified via keyword.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DOCBOOK_DEFAULT_XSL_MAN">
<term>
<envar>DOCBOOK_DEFAULT_XSL_MAN</envar>
</term>
<listitem><para>
The default XSLT file for the &b-link-DocbookMan; builder within the
current environment, if no other XSLT gets specified via keyword.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DOCBOOK_DEFAULT_XSL_PDF">
<term>
<envar>DOCBOOK_DEFAULT_XSL_PDF</envar>
</term>
<listitem><para>
The default XSLT file for the &b-link-DocbookPdf; builder within the
current environment, if no other XSLT gets specified via keyword.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DOCBOOK_DEFAULT_XSL_SLIDESHTML">
<term>
<envar>DOCBOOK_DEFAULT_XSL_SLIDESHTML</envar>
</term>
<listitem><para>
The default XSLT file for the &b-link-DocbookSlidesHtml; builder within the
current environment, if no other XSLT gets specified via keyword.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DOCBOOK_DEFAULT_XSL_SLIDESPDF">
<term>
<envar>DOCBOOK_DEFAULT_XSL_SLIDESPDF</envar>
</term>
<listitem><para>
The default XSLT file for the &b-link-DocbookSlidesPdf; builder within the
current environment, if no other XSLT gets specified via keyword.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DOCBOOK_FOP">
<term>
<envar>DOCBOOK_FOP</envar>
</term>
<listitem><para>
The path to the PDF renderer <literal>fop</literal> or <literal>xep</literal>,
if one of them is installed (<literal>fop</literal> gets checked first).
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DOCBOOK_FOPCOM">
<term>
<envar>DOCBOOK_FOPCOM</envar>
</term>
<listitem><para>
The full command-line for the
PDF renderer <literal>fop</literal> or <literal>xep</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DOCBOOK_FOPCOMSTR">
<term>
<envar>DOCBOOK_FOPCOMSTR</envar>
</term>
<listitem><para>
The string displayed when a renderer like <literal>fop</literal> or
<literal>xep</literal> is used to create PDF output from an XML file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DOCBOOK_FOPFLAGS">
<term>
<envar>DOCBOOK_FOPFLAGS</envar>
</term>
<listitem><para>
Additonal command-line flags for the
PDF renderer <literal>fop</literal> or <literal>xep</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DOCBOOK_XMLLINT">
<term>
<envar>DOCBOOK_XMLLINT</envar>
</term>
<listitem><para>
The path to the external executable <literal>xmllint</literal>, if it's installed.
Note, that this is only used as last fallback for resolving
XIncludes, if no lxml Python binding can be imported
in the current system.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DOCBOOK_XMLLINTCOM">
<term>
<envar>DOCBOOK_XMLLINTCOM</envar>
</term>
<listitem><para>
The full command-line for the external executable
<literal>xmllint</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DOCBOOK_XMLLINTCOMSTR">
<term>
<envar>DOCBOOK_XMLLINTCOMSTR</envar>
</term>
<listitem><para>
The string displayed when <literal>xmllint</literal> is used to resolve
XIncludes for a given XML file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DOCBOOK_XMLLINTFLAGS">
<term>
<envar>DOCBOOK_XMLLINTFLAGS</envar>
</term>
<listitem><para>
Additonal command-line flags for the external executable
<literal>xmllint</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DOCBOOK_XSLTPROC">
<term>
<envar>DOCBOOK_XSLTPROC</envar>
</term>
<listitem><para>
The path to the external executable <literal>xsltproc</literal>
(or <literal>saxon</literal>, <literal>xalan</literal>), if one of them
is installed.
Note, that this is only used as last fallback for XSL transformations, if
no lxml Python binding can be imported in the current system.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DOCBOOK_XSLTPROCCOM">
<term>
<envar>DOCBOOK_XSLTPROCCOM</envar>
</term>
<listitem><para>
The full command-line for the external executable
<literal>xsltproc</literal> (or <literal>saxon</literal>,
<literal>xalan</literal>).
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DOCBOOK_XSLTPROCCOMSTR">
<term>
<envar>DOCBOOK_XSLTPROCCOMSTR</envar>
</term>
<listitem><para>
The string displayed when <literal>xsltproc</literal> is used to transform
an XML file via a given XSLT stylesheet.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DOCBOOK_XSLTPROCFLAGS">
<term>
<envar>DOCBOOK_XSLTPROCFLAGS</envar>
</term>
<listitem><para>
Additonal command-line flags for the external executable
<literal>xsltproc</literal> (or <literal>saxon</literal>,
<literal>xalan</literal>).
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DOCBOOK_XSLTPROCPARAMS">
<term>
<envar>DOCBOOK_XSLTPROCPARAMS</envar>
</term>
<listitem><para>
Additonal parameters that are not intended for the XSLT processor executable, but
the XSL processing itself. By default, they get appended at the end of the command line
for <literal>saxon</literal> and <literal>saxon-xslt</literal>, respectively.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DPATH">
<term>
<envar>DPATH</envar>
</term>
<listitem><para>
List of paths to search for import modules.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DRPATHPREFIX">
<term>
<envar>DRPATHPREFIX</envar>
</term>
<listitem><para>
DRPATHPREFIX.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DRPATHSUFFIX">
<term>
<envar>DRPATHSUFFIX</envar>
</term>
<listitem><para>
DRPATHSUFFIX.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DSUFFIXES">
<term>
<envar>DSUFFIXES</envar>
</term>
<listitem><para>
The list of suffixes of files that will be scanned
for imported D package files.
The default list is <literal>['.d']</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DVERPREFIX">
<term>
<envar>DVERPREFIX</envar>
</term>
<listitem><para>
DVERPREFIX.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DVERSIONS">
<term>
<envar>DVERSIONS</envar>
</term>
<listitem><para>
List of version tags to enable when compiling.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DVERSUFFIX">
<term>
<envar>DVERSUFFIX</envar>
</term>
<listitem><para>
DVERSUFFIX.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DVIPDF">
<term>
<envar>DVIPDF</envar>
</term>
<listitem><para>
The TeX DVI file to PDF file converter.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DVIPDFCOM">
<term>
<envar>DVIPDFCOM</envar>
</term>
<listitem><para>
The command line used to convert TeX DVI files into a PDF file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DVIPDFCOMSTR">
<term>
<envar>DVIPDFCOMSTR</envar>
</term>
<listitem><para>
The string displayed when a TeX DVI file
is converted into a PDF file.
If this is not set, then &cv-link-DVIPDFCOM; (the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DVIPDFFLAGS">
<term>
<envar>DVIPDFFLAGS</envar>
</term>
<listitem><para>
General options passed to the TeX DVI file to PDF file converter.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DVIPS">
<term>
<envar>DVIPS</envar>
</term>
<listitem><para>
The TeX DVI file to PostScript converter.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-DVIPSFLAGS">
<term>
<envar>DVIPSFLAGS</envar>
</term>
<listitem><para>
General options passed to the TeX DVI file to PostScript converter.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-ENV">
<term>
<envar>ENV</envar>
</term>
<listitem><para>
The <firstterm>execution environment</firstterm> -
a dictionary of environment variables
used when &SCons; invokes external commands
to build targets defined in this &consenv;.
When &cv-ENV; is passed to a command,
all list values are assumed to be path lists and
are joined using the search path separator.
Any other non-string values are coerced to a string.
</para>
<para>
Note that by default
&SCons;
does
<emphasis>not</emphasis>
propagate the environment in effect when you execute
&scons; (the "shell environment")
to the execution environment.
This is so that builds will be guaranteed
repeatable regardless of the environment
variables set at the time
&scons;
is invoked.
If you want to propagate a
shell environment variable
to the commands executed
to build target files,
you must do so explicitly.
A common example is
the system &PATH;
environment variable,
so that
&scons;
will find utilities the same way
as the invoking shell (or other process):
</para>
<example_commands>
import os
env = Environment(ENV={'PATH': os.environ['PATH']})
</example_commands>
<para>
Although it is usually not recommended,
you can propagate the entire shell environment
in one go:
</para>
<example_commands>
import os
env = Environment(ENV=os.environ.copy())
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-ESCAPE">
<term>
<envar>ESCAPE</envar>
</term>
<listitem><para>
A function that will be called to escape shell special characters in
command lines. The function should take one argument: the command line
string to escape; and should return the escaped command line.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F03">
<term>
<envar>F03</envar>
</term>
<listitem><para>
The Fortran 03 compiler.
You should normally set the &cv-link-FORTRAN; variable,
which specifies the default Fortran compiler
for all Fortran versions.
You only need to set &cv-link-F03; if you need to use a specific compiler
or compiler version for Fortran 03 files.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F03COM">
<term>
<envar>F03COM</envar>
</term>
<listitem><para>
The command line used to compile a Fortran 03 source file to an object file.
You only need to set &cv-link-F03COM; if you need to use a specific
command line for Fortran 03 files.
You should normally set the &cv-link-FORTRANCOM; variable,
which specifies the default command line
for all Fortran versions.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F03COMSTR">
<term>
<envar>F03COMSTR</envar>
</term>
<listitem><para>
If set, the string displayed when a Fortran 03 source file
is compiled to an object file.
If not set, then &cv-link-F03COM; or &cv-link-FORTRANCOM;
(the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F03FILESUFFIXES">
<term>
<envar>F03FILESUFFIXES</envar>
</term>
<listitem><para>
The list of file extensions for which the F03 dialect will be used. By
default, this is <literal>['.f03']</literal>
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F03FLAGS">
<term>
<envar>F03FLAGS</envar>
</term>
<listitem><para>
General user-specified options that are passed to the Fortran 03 compiler.
Note that this variable does
<emphasis>not</emphasis>
contain
<option>-I</option>
(or similar) include search path options
that scons generates automatically from &cv-link-F03PATH;.
See
&cv-link-_F03INCFLAGS;
below,
for the variable that expands to those options.
You only need to set &cv-link-F03FLAGS; if you need to define specific
user options for Fortran 03 files.
You should normally set the &cv-link-FORTRANFLAGS; variable,
which specifies the user-specified options
passed to the default Fortran compiler
for all Fortran versions.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-_F03INCFLAGS">
<term>
<envar>_F03INCFLAGS</envar>
</term>
<listitem><para>
An automatically-generated construction variable
containing the Fortran 03 compiler command-line options
for specifying directories to be searched for include files.
The value of &cv-link-_F03INCFLAGS; is created
by appending &cv-link-INCPREFIX; and &cv-link-INCSUFFIX;
to the beginning and end
of each directory in &cv-link-F03PATH;.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F03PATH">
<term>
<envar>F03PATH</envar>
</term>
<listitem><para>
The list of directories that the Fortran 03 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 &cv-link-F03FLAGS; because the result will be non-portable
and the directories will not be searched by the dependency scanner. Note:
directory names in &cv-link-F03PATH; will be looked-up relative to the SConscript
directory when they are used in a command. To force
&scons;
to look-up a directory relative to the root of the source tree use #:
You only need to set &cv-link-F03PATH; if you need to define a specific
include path for Fortran 03 files.
You should normally set the &cv-link-FORTRANPATH; variable,
which specifies the include path
for the default Fortran compiler
for all Fortran versions.
</para>
<example_commands>
env = Environment(F03PATH='#/include')
</example_commands>
<para>
The directory look-up can also be forced using the
&Dir;()
function:
</para>
<example_commands>
include = Dir('include')
env = Environment(F03PATH=include)
</example_commands>
<para>
The directory list will be added to command lines
through the automatically-generated
&cv-link-_F03INCFLAGS;
construction variable,
which is constructed by
appending the values of the
&cv-link-INCPREFIX; and &cv-link-INCSUFFIX;
construction variables
to the beginning and end
of each directory in &cv-link-F03PATH;.
Any command lines you define that need
the F03PATH directory list should
include &cv-link-_F03INCFLAGS;:
</para>
<example_commands>
env = Environment(F03COM="my_compiler $_F03INCFLAGS -c -o $TARGET $SOURCE")
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-F03PPCOM">
<term>
<envar>F03PPCOM</envar>
</term>
<listitem><para>
The command line used to compile a Fortran 03 source file to an object file
after first running the file through the C preprocessor.
Any options specified in the &cv-link-F03FLAGS; and &cv-link-CPPFLAGS; construction variables
are included on this command line.
You only need to set &cv-link-F03PPCOM; if you need to use a specific
C-preprocessor command line for Fortran 03 files.
You should normally set the &cv-link-FORTRANPPCOM; variable,
which specifies the default C-preprocessor command line
for all Fortran versions.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F03PPCOMSTR">
<term>
<envar>F03PPCOMSTR</envar>
</term>
<listitem><para>
If set, the string displayed when a Fortran 03 source file
is compiled to an object file
after first running the file through the C preprocessor.
If not set, then &cv-link-F03PPCOM; or &cv-link-FORTRANPPCOM;
(the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F03PPFILESUFFIXES">
<term>
<envar>F03PPFILESUFFIXES</envar>
</term>
<listitem><para>
The list of file extensions for which the compilation + preprocessor pass for
F03 dialect will be used. By default, this is empty.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F08">
<term>
<envar>F08</envar>
</term>
<listitem><para>
The Fortran 08 compiler.
You should normally set the &cv-link-FORTRAN; variable,
which specifies the default Fortran compiler
for all Fortran versions.
You only need to set &cv-link-F08; if you need to use a specific compiler
or compiler version for Fortran 08 files.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F08COM">
<term>
<envar>F08COM</envar>
</term>
<listitem><para>
The command line used to compile a Fortran 08 source file to an object file.
You only need to set &cv-link-F08COM; if you need to use a specific
command line for Fortran 08 files.
You should normally set the &cv-link-FORTRANCOM; variable,
which specifies the default command line
for all Fortran versions.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F08COMSTR">
<term>
<envar>F08COMSTR</envar>
</term>
<listitem><para>
If set, the string displayed when a Fortran 08 source file
is compiled to an object file.
If not set, then &cv-link-F08COM; or &cv-link-FORTRANCOM;
(the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F08FILESUFFIXES">
<term>
<envar>F08FILESUFFIXES</envar>
</term>
<listitem><para>
The list of file extensions for which the F08 dialect will be used. By
default, this is <literal>['.f08']</literal>
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F08FLAGS">
<term>
<envar>F08FLAGS</envar>
</term>
<listitem><para>
General user-specified options that are passed to the Fortran 08 compiler.
Note that this variable does
<emphasis>not</emphasis>
contain
<option>-I</option>
(or similar) include search path options
that scons generates automatically from &cv-link-F08PATH;.
See
&cv-link-_F08INCFLAGS;
below,
for the variable that expands to those options.
You only need to set &cv-link-F08FLAGS; if you need to define specific
user options for Fortran 08 files.
You should normally set the &cv-link-FORTRANFLAGS; variable,
which specifies the user-specified options
passed to the default Fortran compiler
for all Fortran versions.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-_F08INCFLAGS">
<term>
<envar>_F08INCFLAGS</envar>
</term>
<listitem><para>
An automatically-generated construction variable
containing the Fortran 08 compiler command-line options
for specifying directories to be searched for include files.
The value of &cv-link-_F08INCFLAGS; is created
by appending &cv-link-INCPREFIX; and &cv-link-INCSUFFIX;
to the beginning and end
of each directory in &cv-link-F08PATH;.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F08PATH">
<term>
<envar>F08PATH</envar>
</term>
<listitem><para>
The list of directories that the Fortran 08 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 &cv-link-F08FLAGS; because the result will be non-portable
and the directories will not be searched by the dependency scanner. Note:
directory names in &cv-link-F08PATH; will be looked-up relative to the SConscript
directory when they are used in a command. To force
&scons;
to look-up a directory relative to the root of the source tree use #:
You only need to set &cv-link-F08PATH; if you need to define a specific
include path for Fortran 08 files.
You should normally set the &cv-link-FORTRANPATH; variable,
which specifies the include path
for the default Fortran compiler
for all Fortran versions.
</para>
<example_commands>
env = Environment(F08PATH='#/include')
</example_commands>
<para>
The directory look-up can also be forced using the
&Dir;()
function:
</para>
<example_commands>
include = Dir('include')
env = Environment(F08PATH=include)
</example_commands>
<para>
The directory list will be added to command lines
through the automatically-generated
&cv-link-_F08INCFLAGS;
construction variable,
which is constructed by
appending the values of the
&cv-link-INCPREFIX; and &cv-link-INCSUFFIX;
construction variables
to the beginning and end
of each directory in &cv-link-F08PATH;.
Any command lines you define that need
the F08PATH directory list should
include &cv-link-_F08INCFLAGS;:
</para>
<example_commands>
env = Environment(F08COM="my_compiler $_F08INCFLAGS -c -o $TARGET $SOURCE")
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-F08PPCOM">
<term>
<envar>F08PPCOM</envar>
</term>
<listitem><para>
The command line used to compile a Fortran 08 source file to an object file
after first running the file through the C preprocessor.
Any options specified in the &cv-link-F08FLAGS; and &cv-link-CPPFLAGS; construction variables
are included on this command line.
You only need to set &cv-link-F08PPCOM; if you need to use a specific
C-preprocessor command line for Fortran 08 files.
You should normally set the &cv-link-FORTRANPPCOM; variable,
which specifies the default C-preprocessor command line
for all Fortran versions.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F08PPCOMSTR">
<term>
<envar>F08PPCOMSTR</envar>
</term>
<listitem><para>
If set, the string displayed when a Fortran 08 source file
is compiled to an object file
after first running the file through the C preprocessor.
If not set, then &cv-link-F08PPCOM; or &cv-link-FORTRANPPCOM;
(the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F08PPFILESUFFIXES">
<term>
<envar>F08PPFILESUFFIXES</envar>
</term>
<listitem><para>
The list of file extensions for which the compilation + preprocessor pass for
F08 dialect will be used. By default, this is empty.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F77">
<term>
<envar>F77</envar>
</term>
<listitem><para>
The Fortran 77 compiler.
You should normally set the &cv-link-FORTRAN; variable,
which specifies the default Fortran compiler
for all Fortran versions.
You only need to set &cv-link-F77; if you need to use a specific compiler
or compiler version for Fortran 77 files.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F77COM">
<term>
<envar>F77COM</envar>
</term>
<listitem><para>
The command line used to compile a Fortran 77 source file to an object file.
You only need to set &cv-link-F77COM; if you need to use a specific
command line for Fortran 77 files.
You should normally set the &cv-link-FORTRANCOM; variable,
which specifies the default command line
for all Fortran versions.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F77COMSTR">
<term>
<envar>F77COMSTR</envar>
</term>
<listitem><para>
If set, the string displayed when a Fortran 77 source file
is compiled to an object file.
If not set, then &cv-link-F77COM; or &cv-link-FORTRANCOM;
(the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F77FILESUFFIXES">
<term>
<envar>F77FILESUFFIXES</envar>
</term>
<listitem><para>
The list of file extensions for which the F77 dialect will be used. By
default, this is <literal>['.f77']</literal>
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F77FLAGS">
<term>
<envar>F77FLAGS</envar>
</term>
<listitem><para>
General user-specified options that are passed to the Fortran 77 compiler.
Note that this variable does
<emphasis>not</emphasis>
contain
<option>-I</option>
(or similar) include search path options
that scons generates automatically from &cv-link-F77PATH;.
See
&cv-link-_F77INCFLAGS;
below,
for the variable that expands to those options.
You only need to set &cv-link-F77FLAGS; if you need to define specific
user options for Fortran 77 files.
You should normally set the &cv-link-FORTRANFLAGS; variable,
which specifies the user-specified options
passed to the default Fortran compiler
for all Fortran versions.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-_F77INCFLAGS">
<term>
<envar>_F77INCFLAGS</envar>
</term>
<listitem><para>
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 &cv-link-_F77INCFLAGS; is created
by appending &cv-link-INCPREFIX; and &cv-link-INCSUFFIX;
to the beginning and end
of each directory in &cv-link-F77PATH;.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F77PATH">
<term>
<envar>F77PATH</envar>
</term>
<listitem><para>
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 &cv-link-F77FLAGS; because the result will be non-portable
and the directories will not be searched by the dependency scanner. Note:
directory names in &cv-link-F77PATH; will be looked-up relative to the SConscript
directory when they are used in a command. To force
&scons;
to look-up a directory relative to the root of the source tree use #:
You only need to set &cv-link-F77PATH; if you need to define a specific
include path for Fortran 77 files.
You should normally set the &cv-link-FORTRANPATH; variable,
which specifies the include path
for the default Fortran compiler
for all Fortran versions.
</para>
<example_commands>
env = Environment(F77PATH='#/include')
</example_commands>
<para>
The directory look-up can also be forced using the
&Dir;()
function:
</para>
<example_commands>
include = Dir('include')
env = Environment(F77PATH=include)
</example_commands>
<para>
The directory list will be added to command lines
through the automatically-generated
&cv-link-_F77INCFLAGS;
construction variable,
which is constructed by
appending the values of the
&cv-link-INCPREFIX; and &cv-link-INCSUFFIX;
construction variables
to the beginning and end
of each directory in &cv-link-F77PATH;.
Any command lines you define that need
the F77PATH directory list should
include &cv-link-_F77INCFLAGS;:
</para>
<example_commands>
env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-F77PPCOM">
<term>
<envar>F77PPCOM</envar>
</term>
<listitem><para>
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 &cv-link-F77FLAGS; and &cv-link-CPPFLAGS; construction variables
are included on this command line.
You only need to set &cv-link-F77PPCOM; if you need to use a specific
C-preprocessor command line for Fortran 77 files.
You should normally set the &cv-link-FORTRANPPCOM; variable,
which specifies the default C-preprocessor command line
for all Fortran versions.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F77PPCOMSTR">
<term>
<envar>F77PPCOMSTR</envar>
</term>
<listitem><para>
If set, 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 not set, then &cv-link-F77PPCOM; or &cv-link-FORTRANPPCOM;
(the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F77PPFILESUFFIXES">
<term>
<envar>F77PPFILESUFFIXES</envar>
</term>
<listitem><para>
The list of file extensions for which the compilation + preprocessor pass for
F77 dialect will be used. By default, this is empty.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F90">
<term>
<envar>F90</envar>
</term>
<listitem><para>
The Fortran 90 compiler.
You should normally set the &cv-link-FORTRAN; variable,
which specifies the default Fortran compiler
for all Fortran versions.
You only need to set &cv-link-F90; if you need to use a specific compiler
or compiler version for Fortran 90 files.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F90COM">
<term>
<envar>F90COM</envar>
</term>
<listitem><para>
The command line used to compile a Fortran 90 source file to an object file.
You only need to set &cv-link-F90COM; if you need to use a specific
command line for Fortran 90 files.
You should normally set the &cv-link-FORTRANCOM; variable,
which specifies the default command line
for all Fortran versions.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F90COMSTR">
<term>
<envar>F90COMSTR</envar>
</term>
<listitem><para>
If set, the string displayed when a Fortran 90 source file
is compiled to an object file.
If not set, then &cv-link-F90COM; or &cv-link-FORTRANCOM;
(the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F90FILESUFFIXES">
<term>
<envar>F90FILESUFFIXES</envar>
</term>
<listitem><para>
The list of file extensions for which the F90 dialect will be used. By
default, this is <literal>['.f90']</literal>
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F90FLAGS">
<term>
<envar>F90FLAGS</envar>
</term>
<listitem><para>
General user-specified options that are passed to the Fortran 90 compiler.
Note that this variable does
<emphasis>not</emphasis>
contain
<option>-I</option>
(or similar) include search path options
that scons generates automatically from &cv-link-F90PATH;.
See
&cv-link-_F90INCFLAGS;
below,
for the variable that expands to those options.
You only need to set &cv-link-F90FLAGS; if you need to define specific
user options for Fortran 90 files.
You should normally set the &cv-link-FORTRANFLAGS; variable,
which specifies the user-specified options
passed to the default Fortran compiler
for all Fortran versions.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-_F90INCFLAGS">
<term>
<envar>_F90INCFLAGS</envar>
</term>
<listitem><para>
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 &cv-link-_F90INCFLAGS; is created
by appending &cv-link-INCPREFIX; and &cv-link-INCSUFFIX;
to the beginning and end
of each directory in &cv-link-F90PATH;.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F90PATH">
<term>
<envar>F90PATH</envar>
</term>
<listitem><para>
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 &cv-link-F90FLAGS; because the result will be non-portable
and the directories will not be searched by the dependency scanner. Note:
directory names in &cv-link-F90PATH; will be looked-up relative to the SConscript
directory when they are used in a command. To force
&scons;
to look-up a directory relative to the root of the source tree use #:
You only need to set &cv-link-F90PATH; if you need to define a specific
include path for Fortran 90 files.
You should normally set the &cv-link-FORTRANPATH; variable,
which specifies the include path
for the default Fortran compiler
for all Fortran versions.
</para>
<example_commands>
env = Environment(F90PATH='#/include')
</example_commands>
<para>
The directory look-up can also be forced using the
&Dir;()
function:
</para>
<example_commands>
include = Dir('include')
env = Environment(F90PATH=include)
</example_commands>
<para>
The directory list will be added to command lines
through the automatically-generated
&cv-link-_F90INCFLAGS;
construction variable,
which is constructed by
appending the values of the
&cv-link-INCPREFIX; and &cv-link-INCSUFFIX;
construction variables
to the beginning and end
of each directory in &cv-link-F90PATH;.
Any command lines you define that need
the F90PATH directory list should
include &cv-link-_F90INCFLAGS;:
</para>
<example_commands>
env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE")
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-F90PPCOM">
<term>
<envar>F90PPCOM</envar>
</term>
<listitem><para>
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 &cv-link-F90FLAGS; and &cv-link-CPPFLAGS; construction variables
are included on this command line.
You only need to set &cv-link-F90PPCOM; if you need to use a specific
C-preprocessor command line for Fortran 90 files.
You should normally set the &cv-link-FORTRANPPCOM; variable,
which specifies the default C-preprocessor command line
for all Fortran versions.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F90PPCOMSTR">
<term>
<envar>F90PPCOMSTR</envar>
</term>
<listitem><para>
If set, the string displayed when a Fortran 90 source file
is compiled after first running the file through the C preprocessor.
If not set, then &cv-link-F90PPCOM; or &cv-link-FORTRANPPCOM;
(the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F90PPFILESUFFIXES">
<term>
<envar>F90PPFILESUFFIXES</envar>
</term>
<listitem><para>
The list of file extensions for which the compilation + preprocessor pass for
F90 dialect will be used. By default, this is empty.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F95">
<term>
<envar>F95</envar>
</term>
<listitem><para>
The Fortran 95 compiler.
You should normally set the &cv-link-FORTRAN; variable,
which specifies the default Fortran compiler
for all Fortran versions.
You only need to set &cv-link-F95; if you need to use a specific compiler
or compiler version for Fortran 95 files.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F95COM">
<term>
<envar>F95COM</envar>
</term>
<listitem><para>
The command line used to compile a Fortran 95 source file to an object file.
You only need to set &cv-link-F95COM; if you need to use a specific
command line for Fortran 95 files.
You should normally set the &cv-link-FORTRANCOM; variable,
which specifies the default command line
for all Fortran versions.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F95COMSTR">
<term>
<envar>F95COMSTR</envar>
</term>
<listitem><para>
If set, the string displayed when a Fortran 95 source file
is compiled to an object file.
If not set, then &cv-link-F95COM; or &cv-link-FORTRANCOM;
(the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F95FILESUFFIXES">
<term>
<envar>F95FILESUFFIXES</envar>
</term>
<listitem><para>
The list of file extensions for which the F95 dialect will be used. By
default, this is <literal>['.f95']</literal>
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F95FLAGS">
<term>
<envar>F95FLAGS</envar>
</term>
<listitem><para>
General user-specified options that are passed to the Fortran 95 compiler.
Note that this variable does
<emphasis>not</emphasis>
contain
<option>-I</option>
(or similar) include search path options
that scons generates automatically from &cv-link-F95PATH;.
See
&cv-link-_F95INCFLAGS;
below,
for the variable that expands to those options.
You only need to set &cv-link-F95FLAGS; if you need to define specific
user options for Fortran 95 files.
You should normally set the &cv-link-FORTRANFLAGS; variable,
which specifies the user-specified options
passed to the default Fortran compiler
for all Fortran versions.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-_F95INCFLAGS">
<term>
<envar>_F95INCFLAGS</envar>
</term>
<listitem><para>
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 &cv-link-_F95INCFLAGS; is created
by appending &cv-link-INCPREFIX; and &cv-link-INCSUFFIX;
to the beginning and end
of each directory in &cv-link-F95PATH;.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F95PATH">
<term>
<envar>F95PATH</envar>
</term>
<listitem><para>
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 &cv-link-F95FLAGS; because the result will be non-portable
and the directories will not be searched by the dependency scanner. Note:
directory names in &cv-link-F95PATH; will be looked-up relative to the SConscript
directory when they are used in a command. To force
&scons;
to look-up a directory relative to the root of the source tree use #:
You only need to set &cv-link-F95PATH; if you need to define a specific
include path for Fortran 95 files.
You should normally set the &cv-link-FORTRANPATH; variable,
which specifies the include path
for the default Fortran compiler
for all Fortran versions.
</para>
<example_commands>
env = Environment(F95PATH='#/include')
</example_commands>
<para>
The directory look-up can also be forced using the
&Dir;()
function:
</para>
<example_commands>
include = Dir('include')
env = Environment(F95PATH=include)
</example_commands>
<para>
The directory list will be added to command lines
through the automatically-generated
&cv-link-_F95INCFLAGS;
construction variable,
which is constructed by
appending the values of the
&cv-link-INCPREFIX; and &cv-link-INCSUFFIX;
construction variables
to the beginning and end
of each directory in &cv-link-F95PATH;.
Any command lines you define that need
the F95PATH directory list should
include &cv-link-_F95INCFLAGS;:
</para>
<example_commands>
env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE")
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-F95PPCOM">
<term>
<envar>F95PPCOM</envar>
</term>
<listitem><para>
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 &cv-link-F95FLAGS; and &cv-link-CPPFLAGS; construction variables
are included on this command line.
You only need to set &cv-link-F95PPCOM; if you need to use a specific
C-preprocessor command line for Fortran 95 files.
You should normally set the &cv-link-FORTRANPPCOM; variable,
which specifies the default C-preprocessor command line
for all Fortran versions.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F95PPCOMSTR">
<term>
<envar>F95PPCOMSTR</envar>
</term>
<listitem><para>
If set, 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 not set, then &cv-link-F95PPCOM; or &cv-link-FORTRANPPCOM;
(the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-F95PPFILESUFFIXES">
<term>
<envar>F95PPFILESUFFIXES</envar>
</term>
<listitem><para>
The list of file extensions for which the compilation + preprocessor pass for
F95 dialect will be used. By default, this is empty.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-File">
<term>
<envar>File</envar>
</term>
<listitem><para>
A function that converts a string into a File instance relative to the
target being built.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-FORTRAN">
<term>
<envar>FORTRAN</envar>
</term>
<listitem><para>
The default Fortran compiler
for all versions of Fortran.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-FORTRANCOM">
<term>
<envar>FORTRANCOM</envar>
</term>
<listitem><para>
The command line used to compile a Fortran source file to an object file.
By default, any options specified
in the &cv-link-FORTRANFLAGS;,
&cv-link-_FORTRANMODFLAG;, and
&cv-link-_FORTRANINCFLAGS;
&consvars; are included on this command line.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-FORTRANCOMMONFLAGS">
<term>
<envar>FORTRANCOMMONFLAGS</envar>
</term>
<listitem><para>
General user-specified options that are passed to the Fortran compiler.
Similar to &cv-link-FORTRANFLAGS;,
but this variable is applied to all dialects.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-FORTRANCOMSTR">
<term>
<envar>FORTRANCOMSTR</envar>
</term>
<listitem><para>
If set, the string displayed when a Fortran source file
is compiled to an object file.
If not set, then &cv-link-FORTRANCOM;
(the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-FORTRANFILESUFFIXES">
<term>
<envar>FORTRANFILESUFFIXES</envar>
</term>
<listitem><para>
The list of file extensions for which the FORTRAN dialect will be used. By
default, this is <literal>['.f', '.for', '.ftn']</literal>
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-FORTRANFLAGS">
<term>
<envar>FORTRANFLAGS</envar>
</term>
<listitem><para>
General user-specified options for the FORTRAN dialect
that are passed to the Fortran compiler.
Note that this variable does
<emphasis>not</emphasis>
contain
<option>-I</option>
(or similar) include or module search path options
that scons generates automatically from &cv-link-FORTRANPATH;.
See
&cv-link-_FORTRANINCFLAGS; and &cv-link-_FORTRANMODFLAG;,
below,
for the variables that expand those options.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-_FORTRANINCFLAGS">
<term>
<envar>_FORTRANINCFLAGS</envar>
</term>
<listitem><para>
An automatically-generated &consvar;
containing the Fortran compiler command-line options
for specifying directories to be searched for include
files and module files.
The value of &cv-link-_FORTRANINCFLAGS; is created
by respectively prepending and appending
&cv-link-INCPREFIX; and &cv-link-INCSUFFIX;
to the beginning and end
of each directory in &cv-link-FORTRANPATH;.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-FORTRANMODDIR">
<term>
<envar>FORTRANMODDIR</envar>
</term>
<listitem><para>
Directory location where the Fortran compiler should place
any module files it generates. This variable is empty, by default. Some
Fortran compilers will internally append this directory in the search path
for module files, as well.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-FORTRANMODDIRPREFIX">
<term>
<envar>FORTRANMODDIRPREFIX</envar>
</term>
<listitem><para>
The prefix used to specify a module directory on the Fortran compiler command
line.
This will be prepended to the beginning of the directory
in the &cv-link-FORTRANMODDIR; &consvars;
when the &cv-link-_FORTRANMODFLAG; variables is automatically generated.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-FORTRANMODDIRSUFFIX">
<term>
<envar>FORTRANMODDIRSUFFIX</envar>
</term>
<listitem><para>
The suffix used to specify a module directory on the Fortran compiler command
line.
This will be appended to the end of the directory
in the &cv-link-FORTRANMODDIR; &consvars;
when the &cv-link-_FORTRANMODFLAG; variables is automatically generated.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-_FORTRANMODFLAG">
<term>
<envar>_FORTRANMODFLAG</envar>
</term>
<listitem><para>
An automatically-generated &consvar;
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 &cv-link-_FORTRANMODFLAG; is created
by respectively prepending and appending
&cv-link-FORTRANMODDIRPREFIX; and &cv-link-FORTRANMODDIRSUFFIX;
to the beginning and end of the directory in &cv-link-FORTRANMODDIR;.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-FORTRANMODPREFIX">
<term>
<envar>FORTRANMODPREFIX</envar>
</term>
<listitem><para>
The module file prefix used by the Fortran compiler. SCons assumes that
the Fortran compiler follows the quasi-standard naming convention for
module files of
<filename>module_name.mod</filename>.
As a result, this variable is left empty, by default. For situations in
which the compiler does not necessarily follow the normal convention,
the user may use this variable. Its value will be appended to every
module file name as scons attempts to resolve dependencies.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-FORTRANMODSUFFIX">
<term>
<envar>FORTRANMODSUFFIX</envar>
</term>
<listitem><para>
The module file suffix used by the Fortran compiler. SCons assumes that
the Fortran compiler follows the quasi-standard naming convention for
module files of
<filename>module_name.mod</filename>.
As a result, this variable is set to ".mod", by default. For situations
in which the compiler does not necessarily follow the normal convention,
the user may use this variable. Its value will be appended to every
module file name as scons attempts to resolve dependencies.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-FORTRANPATH">
<term>
<envar>FORTRANPATH</envar>
</term>
<listitem><para>
The list of directories that the Fortran compiler will search for
include files and (for some compilers) module files. The Fortran implicit
dependency scanner will search these directories for include files (but
not module files since they are autogenerated and, as such, may not
actually exist at the time the scan takes place). Don't explicitly put
include directory arguments in FORTRANFLAGS because the result will be
non-portable and the directories will not be searched by the dependency
scanner. Note: directory names in FORTRANPATH will be looked-up relative
to the SConscript directory when they are used in a command. To force
&scons;
to look-up a directory relative to the root of the source tree use #:
</para>
<example_commands>
env = Environment(FORTRANPATH='#/include')
</example_commands>
<para>
The directory look-up can also be forced using the
&Dir;()
function:
</para>
<example_commands>
include = Dir('include')
env = Environment(FORTRANPATH=include)
</example_commands>
<para>
The directory list will be added to command lines
through the automatically-generated
&cv-link-_FORTRANINCFLAGS;
&consvar;,
which is constructed by
respectively prepending and appending the values of the
&cv-link-INCPREFIX; and &cv-link-INCSUFFIX;
&consvars;
to the beginning and end
of each directory in &cv-link-FORTRANPATH;.
Any command lines you define that need
the FORTRANPATH directory list should
include &cv-link-_FORTRANINCFLAGS;:
</para>
<example_commands>
env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE")
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-FORTRANPPCOM">
<term>
<envar>FORTRANPPCOM</envar>
</term>
<listitem><para>
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 &cv-link-FORTRANFLAGS;,
&cv-link-CPPFLAGS;,
&cv-link-_CPPDEFFLAGS;,
&cv-link-_FORTRANMODFLAG;, and
&cv-link-_FORTRANINCFLAGS;
&consvars; are included on this command line.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-FORTRANPPCOMSTR">
<term>
<envar>FORTRANPPCOMSTR</envar>
</term>
<listitem><para>
If set, the string displayed when a Fortran source file
is compiled to an object file
after first running the file through the C preprocessor.
If not set, then &cv-link-FORTRANPPCOM;
(the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-FORTRANPPFILESUFFIXES">
<term>
<envar>FORTRANPPFILESUFFIXES</envar>
</term>
<listitem><para>
The list of file extensions for which the compilation + preprocessor pass for
FORTRAN dialect will be used. By default, this is <literal>['.fpp', '.FPP']</literal>
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-FORTRANSUFFIXES">
<term>
<envar>FORTRANSUFFIXES</envar>
</term>
<listitem><para>
The list of suffixes of files that will be scanned
for Fortran implicit dependencies
(INCLUDE lines and USE statements).
The default list is:
</para>
<example_commands>
[".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP",
".f77", ".F77", ".f90", ".F90", ".f95", ".F95"]
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-FRAMEWORKPATH">
<term>
<envar>FRAMEWORKPATH</envar>
</term>
<listitem><para>
On Mac OS X with gcc,
a list containing the paths to search for frameworks.
Used by the compiler to find framework-style includes like
#include &lt;Fmwk/Header.h&gt;.
Used by the linker to find user-specified frameworks when linking (see
&cv-link-FRAMEWORKS;).
For example:
</para>
<example_commands>
env.AppendUnique(FRAMEWORKPATH='#myframeworkdir')
</example_commands>
<para>
will add
</para>
<example_commands>
... -Fmyframeworkdir
</example_commands>
<para>
to the compiler and linker command lines.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-_FRAMEWORKPATH">
<term>
<envar>_FRAMEWORKPATH</envar>
</term>
<listitem><para>
On Mac OS X with gcc, an automatically-generated construction variable
containing the linker command-line options corresponding to
&cv-link-FRAMEWORKPATH;.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-FRAMEWORKPATHPREFIX">
<term>
<envar>FRAMEWORKPATHPREFIX</envar>
</term>
<listitem><para>
On Mac OS X with gcc, the prefix to be used for the FRAMEWORKPATH entries.
(see &cv-link-FRAMEWORKPATH;).
The default value is
<option>-F</option>.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-FRAMEWORKPREFIX">
<term>
<envar>FRAMEWORKPREFIX</envar>
</term>
<listitem><para>
On Mac OS X with gcc,
the prefix to be used for linking in frameworks
(see &cv-link-FRAMEWORKS;).
The default value is
<option>-framework</option>.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-FRAMEWORKS">
<term>
<envar>FRAMEWORKS</envar>
</term>
<listitem><para>
On Mac OS X with gcc, a list of the framework names to be linked into a
program or shared library or bundle.
The default value is the empty list.
For example:
</para>
<example_commands>
env.AppendUnique(FRAMEWORKS=Split('System Cocoa SystemConfiguration'))
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-_FRAMEWORKS">
<term>
<envar>_FRAMEWORKS</envar>
</term>
<listitem><para>
On Mac OS X with gcc,
an automatically-generated construction variable
containing the linker command-line options
for linking with FRAMEWORKS.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-FRAMEWORKSFLAGS">
<term>
<envar>FRAMEWORKSFLAGS</envar>
</term>
<listitem><para>
On Mac OS X with gcc,
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 &cv-link-FRAMEWORKPATH;, &cv-link-FRAMEWORKPATHPREFIX;,
&cv-link-FRAMEWORKPREFIX; and &cv-link-FRAMEWORKS; variables
described above.)
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-GS">
<term>
<envar>GS</envar>
</term>
<listitem><para>
The Ghostscript program used to, for example, convert PostScript to PDF files.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-GSCOM">
<term>
<envar>GSCOM</envar>
</term>
<listitem><para>
The full Ghostscript command line used for the conversion process. Its default
value is <quote><literal>$GS $GSFLAGS -sOutputFile=$TARGET $SOURCES</literal></quote>.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-GSCOMSTR">
<term>
<envar>GSCOMSTR</envar>
</term>
<listitem><para>
The string displayed when
Ghostscript is called for the conversion process.
If this is not set (the default), then &cv-link-GSCOM; (the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-GSFLAGS">
<term>
<envar>GSFLAGS</envar>
</term>
<listitem><para>
General options passed to the Ghostscript program,
when converting PostScript to PDF files for example. Its default value
is <quote><literal>-dNOPAUSE -dBATCH -sDEVICE=pdfwrite</literal></quote>
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-HOST_ARCH">
<term>
<envar>HOST_ARCH</envar>
</term>
<listitem><para>
The name of the host hardware architecture
used to create this &consenv;.
The platform code sets this when initializing
(see &cv-link-PLATFORM; and the
<parameter>platform</parameter> argument to &f-link-Environment;).
Note the detected name of the architecture may not be identical to
that returned by the &Python;
<systemitem>platform.machine</systemitem> method.
</para>
<para>
On the <literal>win32</literal> platform,
if the Microsoft Visual C++ compiler is available,
&t-link-msvc; tool setup is done using
&cv-HOST_ARCH; and &cv-link-TARGET_ARCH;.
Changing the values at any later time will not cause
the tool to be reinitialized.
Valid host arch values are
<literal>x86</literal> and <literal>arm</literal>
for 32-bit hosts and
<literal>amd64</literal> and <literal>x86_64</literal>
for 64-bit hosts.
</para>
<para>
Should be considered immutable.
&cv-HOST_ARCH; is not currently used by other platforms,
but the option is reserved to do so in future
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-HOST_OS">
<term>
<envar>HOST_OS</envar>
</term>
<listitem><para>
The name of the host operating system for the platform
used to create this &consenv;.
The platform code sets this when initializing
(see &cv-link-PLATFORM; and the
<parameter>platform</parameter> argument to &f-link-Environment;).
</para>
<para>
Should be considered immutable.
&cv-HOST_OS; is not currently used by &SCons;,
but the option is reserved to do so in future
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-IDLSUFFIXES">
<term>
<envar>IDLSUFFIXES</envar>
</term>
<listitem><para>
The list of suffixes of files that will be scanned
for IDL implicit dependencies
(#include or import lines).
The default list is:
</para>
<example_commands>
[".idl", ".IDL"]
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-IMPLIBNOVERSIONSYMLINKS">
<term>
<envar>IMPLIBNOVERSIONSYMLINKS</envar>
</term>
<listitem><para>
Used to override &cv-link-SHLIBNOVERSIONSYMLINKS;/&cv-link-LDMODULENOVERSIONSYMLINKS; when
creating versioned import library for a shared library/loadable module. If not defined,
then &cv-link-SHLIBNOVERSIONSYMLINKS;/&cv-link-LDMODULENOVERSIONSYMLINKS; is used to determine
whether to disable symlink generation or not.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-IMPLIBPREFIX">
<term>
<envar>IMPLIBPREFIX</envar>
</term>
<listitem><para>
The prefix used for import library names. For example, cygwin uses import
libraries (<literal>libfoo.dll.a</literal>) in pair with dynamic libraries
(<literal>cygfoo.dll</literal>). The &t-link-cyglink; linker sets
&cv-link-IMPLIBPREFIX; to <literal>'lib'</literal> and &cv-link-SHLIBPREFIX;
to <literal>'cyg'</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-IMPLIBSUFFIX">
<term>
<envar>IMPLIBSUFFIX</envar>
</term>
<listitem><para>
The suffix used for import library names. For example, cygwin uses import
libraries (<literal>libfoo.dll.a</literal>) in pair with dynamic libraries
(<literal>cygfoo.dll</literal>). The &t-link-cyglink; linker sets
&cv-link-IMPLIBSUFFIX; to <literal>'.dll.a'</literal> and &cv-link-SHLIBSUFFIX;
to <literal>'.dll'</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-IMPLIBVERSION">
<term>
<envar>IMPLIBVERSION</envar>
</term>
<listitem><para>
Used to override &cv-link-SHLIBVERSION;/&cv-link-LDMODULEVERSION; when
generating versioned import library for a shared library/loadable module. If
undefined, the &cv-link-SHLIBVERSION;/&cv-link-LDMODULEVERSION; is used to
determine the version of versioned import library.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-IMPLICIT_COMMAND_DEPENDENCIES">
<term>
<envar>IMPLICIT_COMMAND_DEPENDENCIES</envar>
</term>
<listitem><para>
Controls whether or not SCons will
add implicit dependencies for the commands
executed to build targets.
</para>
<para>
By default, SCons will add
to each target
an implicit dependency on the command
represented by the first argument of any
command line it executes (which is typically
the command itself). By setting such
a dependency, &SCons; can determine that
a target should be rebuilt if the command changes,
such as when a compiler is upgraded to a new version.
The specific file for the dependency is
found by searching the
<varname>PATH</varname>
variable in the
<varname>ENV</varname> dictionary
in the &consenv; used to execute the command.
The default is the same as
setting the &consvar;
&cv-IMPLICIT_COMMAND_DEPENDENCIES;
to a True-like value (<quote>true</quote>,
<quote>yes</quote>,
or <quote>1</quote> - but not a number
greater than one, as that has a different meaning).
</para>
<para>
Action strings can be segmented by the
use of an AND operator, <literal>&amp;&amp;</literal>.
In a segemented string, each segment is a separate
<quote>command line</quote>, these are run
sequentially until one fails or the entire
sequence has been executed. If an
action string is segmented, then the selected
behavior of &cv-IMPLICIT_COMMAND_DEPENDENCIES;
is applied to each segment.
</para>
<para>
If &cv-IMPLICIT_COMMAND_DEPENDENCIES;
is set to a False-like value
(<quote>none</quote>,
<quote>false</quote>,
<quote>no</quote>,
<quote>0</quote>,
etc.),
then the implicit dependency will
not be added to the targets
built with that &consenv;.
</para>
<para>
If &cv-IMPLICIT_COMMAND_DEPENDENCIES;
is set to <quote>2</quote> or higher,
then that number of arguments in the command line
will be scanned for relative or absolute paths.
If any are present, they will be added as
implicit dependencies to the targets built
with that &consenv;.
The first argument in the command line will be
searched for using the <varname>PATH</varname>
variable in the <varname>ENV</varname> dictionary
in the &consenv; used to execute the command.
The other arguments will only be found if they
are absolute paths or valid paths relative
to the working directory.
</para>
<para>
If &cv-IMPLICIT_COMMAND_DEPENDENCIES;
is set to <quote>all</quote>,
then all arguments in the command line will be
scanned for relative or absolute paths.
If any are present, they will be added as
implicit dependencies to the targets built
with that &consenv;.
The first argument in the command line will be
searched for using the <varname>PATH</varname>
variable in the <varname>ENV</varname> dictionary
in the &consenv; used to execute the command.
The other arguments will only be found if they
are absolute paths or valid paths relative
to the working directory.
</para>
<example_commands>
env = Environment(IMPLICIT_COMMAND_DEPENDENCIES=False)
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-INCPREFIX">
<term>
<envar>INCPREFIX</envar>
</term>
<listitem><para>
The prefix used to specify an include directory on the C compiler command
line.
This will be prepended to each directory
in the &cv-link-CPPPATH; and &cv-link-FORTRANPATH; &consvars;
when the &cv-link-_CPPINCFLAGS; and &cv-link-_FORTRANINCFLAGS;
variables are automatically generated.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-INCSUFFIX">
<term>
<envar>INCSUFFIX</envar>
</term>
<listitem><para>
The suffix used to specify an include directory on the C compiler command
line.
This will be appended to each directory
in the &cv-link-CPPPATH; and &cv-link-FORTRANPATH; &consvars;
when the &cv-link-_CPPINCFLAGS; and &cv-link-_FORTRANINCFLAGS;
variables are automatically generated.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-INSTALL">
<term>
<envar>INSTALL</envar>
</term>
<listitem><para>
A function to be called to install a file into a
destination file name.
The default function copies the file into the destination
(and sets the destination file's mode and permission bits
to match the source file's).
The function takes the following arguments:
</para>
<example_commands>
def install(dest, source, env):
</example_commands>
<para>
<varname>dest</varname>
is the path name of the destination file.
<varname>source</varname>
is the path name of the source file.
<varname>env</varname>
is the construction environment
(a dictionary of construction values)
in force for this file installation.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-INSTALLSTR">
<term>
<envar>INSTALLSTR</envar>
</term>
<listitem><para>
The string displayed when a file is
installed into a destination file name.
The default is:
</para>
<example_commands>
Install file: "$SOURCE" as "$TARGET"
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-INTEL_C_COMPILER_VERSION">
<term>
<envar>INTEL_C_COMPILER_VERSION</envar>
</term>
<listitem><para>
Set by the &t-link-intelc; Tool
to the major version number of the Intel C compiler
selected for use.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-JAR">
<term>
<envar>JAR</envar>
</term>
<listitem><para>
The Java archive tool.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-JARCHDIR">
<term>
<envar>JARCHDIR</envar>
</term>
<listitem><para>
The directory to which the Java archive tool should change
(using the
<option>-C</option>
option).
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-JARCOM">
<term>
<envar>JARCOM</envar>
</term>
<listitem><para>
The command line used to call the Java archive tool.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-JARCOMSTR">
<term>
<envar>JARCOMSTR</envar>
</term>
<listitem><para>
The string displayed when the Java archive tool
is called
If this is not set, then &cv-link-JARCOM; (the command line) is displayed.
</para>
<example_commands>
env = Environment(JARCOMSTR="JARchiving $SOURCES into $TARGET")
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-JARFLAGS">
<term>
<envar>JARFLAGS</envar>
</term>
<listitem><para>
General options passed to the Java archive tool.
By default this is set to
<option>cf</option>
to create the necessary
<command>jar</command>
file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-JARSUFFIX">
<term>
<envar>JARSUFFIX</envar>
</term>
<listitem><para>
The suffix for Java archives:
<filename>.jar</filename>
by default.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-JAVABOOTCLASSPATH">
<term>
<envar>JAVABOOTCLASSPATH</envar>
</term>
<listitem><para>
Specifies the list of directories that
will be added to the
&javac; command line
via the <option>-bootclasspath</option> option.
The individual directory names will be
separated by the operating system's path separate character
(<filename>:</filename> on UNIX/Linux/POSIX,
<filename>;</filename>
on Windows).
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-JAVAC">
<term>
<envar>JAVAC</envar>
</term>
<listitem><para>
The Java compiler.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-JAVACCOM">
<term>
<envar>JAVACCOM</envar>
</term>
<listitem><para>
The command line used to compile a directory tree containing
Java source files to
corresponding Java class files.
Any options specified in the &cv-link-JAVACFLAGS; construction variable
are included on this command line.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-JAVACCOMSTR">
<term>
<envar>JAVACCOMSTR</envar>
</term>
<listitem><para>
The string displayed when compiling
a directory tree of Java source files to
corresponding Java class files.
If this is not set, then &cv-link-JAVACCOM; (the command line) is displayed.
</para>
<example_commands>
env = Environment(JAVACCOMSTR="Compiling class files $TARGETS from $SOURCES")
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-JAVACFLAGS">
<term>
<envar>JAVACFLAGS</envar>
</term>
<listitem><para>
General options that are passed to the Java compiler.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-JAVACLASSDIR">
<term>
<envar>JAVACLASSDIR</envar>
</term>
<listitem><para>
The directory in which Java class files may be found.
This is stripped from the beginning of any Java .class
file names supplied to the
<literal>JavaH</literal>
builder.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-JAVACLASSPATH">
<term>
<envar>JAVACLASSPATH</envar>
</term>
<listitem><para>
Specifies the list of directories that
will be searched for Java
<filename>.class</filename>
file.
The directories in this list will be added to the
&javac; and &javah; command lines
via the <option>-classpath</option> option.
The individual directory names will be
separated by the operating system's path separate character
(<filename>:</filename> on UNIX/Linux/POSIX,
<filename>;</filename>
on Windows).
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-JAVACLASSSUFFIX">
<term>
<envar>JAVACLASSSUFFIX</envar>
</term>
<listitem><para>
The suffix for Java class files;
<filename>.class</filename>
by default.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-JAVAH">
<term>
<envar>JAVAH</envar>
</term>
<listitem><para>
The Java generator for C header and stub files.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-JAVAHCOM">
<term>
<envar>JAVAHCOM</envar>
</term>
<listitem><para>
The command line used to generate C header and stub files
from Java classes.
Any options specified in the &cv-link-JAVAHFLAGS; construction variable
are included on this command line.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-JAVAHCOMSTR">
<term>
<envar>JAVAHCOMSTR</envar>
</term>
<listitem><para>
The string displayed when C header and stub files
are generated from Java classes.
If this is not set, then &cv-link-JAVAHCOM; (the command line) is displayed.
</para>
<example_commands>
env = Environment(JAVAHCOMSTR="Generating header/stub file(s) $TARGETS from $SOURCES")
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-JAVAHFLAGS">
<term>
<envar>JAVAHFLAGS</envar>
</term>
<listitem><para>
General options passed to the C header and stub file generator
for Java classes.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-JAVAINCLUDES">
<term>
<envar>JAVAINCLUDES</envar>
</term>
<listitem><para>
Include path for Java header files (such as jni.h)
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-JAVASOURCEPATH">
<term>
<envar>JAVASOURCEPATH</envar>
</term>
<listitem><para>
Specifies the list of directories that
will be searched for input
<filename>.java</filename>
file.
The directories in this list will be added to the
&javac; command line
via the <option>-sourcepath</option> option.
The individual directory names will be
separated by the operating system's path separate character
(<filename>:</filename> on UNIX/Linux/POSIX,
<filename>;</filename>
on Windows).
</para>
<para>
Note that this currently just adds the specified
directory via the <option>-sourcepath</option> option.
&SCons; does not currently search the
&cv-JAVASOURCEPATH; directories for dependency
<filename>.java</filename>
files.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-JAVASUFFIX">
<term>
<envar>JAVASUFFIX</envar>
</term>
<listitem><para>
The suffix for Java files;
<filename>.java</filename>
by default.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-JAVAVERSION">
<term>
<envar>JAVAVERSION</envar>
</term>
<listitem><para>
Specifies the Java version being used by the &b-link-Java;
builder. Set this to specify the version of Java targeted
by the &javac; compiler.
This is sometimes necessary because
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 &cv-JAVAVERSION; to a version greater than
<literal>1.4</literal> makes &SCons; realize that a build
with such a compiler is actually up to date.
The default is <literal>1.4</literal>.
</para>
<para>
While this is <emphasis>not</emphasis> primarily intended for
selecting one version of the Java compiler vs. another,
it does have that effect on the Windows platform. A
more precise approach is to set &cv-link-JAVAC; (and related
&consvars; for related utilities) to the path to the specific
Java compiler you want, if that is not the default compiler.
On non-Windows platforms, the
<systemitem>alternatives</systemitem> system may provide a
way to adjust the default Java compiler without
having to specify explicit paths.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-LATEX">
<term>
<envar>LATEX</envar>
</term>
<listitem><para>
The LaTeX structured formatter and typesetter.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-LATEXCOM">
<term>
<envar>LATEXCOM</envar>
</term>
<listitem><para>
The command line used to call the LaTeX structured formatter and typesetter.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-LATEXCOMSTR">
<term>
<envar>LATEXCOMSTR</envar>
</term>
<listitem><para>
The string displayed when calling
the LaTeX structured formatter and typesetter.
If this is not set, then &cv-link-LATEXCOM; (the command line) is displayed.
</para>
<example_commands>
env = Environment(LATEXCOMSTR = "Building $TARGET from LaTeX input $SOURCES")
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-LATEXFLAGS">
<term>
<envar>LATEXFLAGS</envar>
</term>
<listitem><para>
General options passed to the LaTeX structured formatter and typesetter.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-LATEXRETRIES">
<term>
<envar>LATEXRETRIES</envar>
</term>
<listitem><para>
The maximum number of times that LaTeX
will be re-run if the
<filename>.log</filename>
generated by the &cv-link-LATEXCOM; command
indicates that there are undefined references.
The default is to try to resolve undefined references
by re-running LaTeX up to three times.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-LATEXSUFFIXES">
<term>
<envar>LATEXSUFFIXES</envar>
</term>
<listitem><para>
The list of suffixes of files that will be scanned
for LaTeX implicit dependencies
(<literal>\include</literal> or <literal>\import</literal> files).
The default list is:
</para>
<example_commands>
[".tex", ".ltx", ".latex"]
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-LDMODULE">
<term>
<envar>LDMODULE</envar>
</term>
<listitem><para>
The linker for building loadable modules.
By default, this is the same as &cv-link-SHLINK;.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-LDMODULECOM">
<term>
<envar>LDMODULECOM</envar>
</term>
<listitem><para>
The command line for building loadable modules.
On Mac OS X, this uses the &cv-link-LDMODULE;,
&cv-link-LDMODULEFLAGS; and
&cv-link-FRAMEWORKSFLAGS; variables.
On other systems, this is the same as &cv-link-SHLINK;.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-LDMODULECOMSTR">
<term>
<envar>LDMODULECOMSTR</envar>
</term>
<listitem><para>
If set, the string displayed when building loadable modules.
If not set, then &cv-link-LDMODULECOM; (the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-LDMODULEEMITTER">
<term>
<envar>LDMODULEEMITTER</envar>
</term>
<listitem><para>
Contains the emitter specification for the
&b-link-LoadableModule; builder.
The manpage section "Builder Objects" contains
general information on specifying emitters.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-LDMODULEFLAGS">
<term>
<envar>LDMODULEFLAGS</envar>
</term>
<listitem><para>
General user options passed to the linker for building loadable modules.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-LDMODULENOVERSIONSYMLINKS">
<term>
<envar>LDMODULENOVERSIONSYMLINKS</envar>
</term>
<listitem><para>
Instructs the &b-link-LoadableModule; builder to not automatically create symlinks
for versioned modules. Defaults to <literal>$SHLIBNOVERSIONSYMLINKS</literal>
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-LDMODULEPREFIX">
<term>
<envar>LDMODULEPREFIX</envar>
</term>
<listitem><para>
The prefix used for loadable module file names.
On Mac OS X, this is null;
on other systems, this is
the same as &cv-link-SHLIBPREFIX;.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-_LDMODULESONAME">
<term>
<envar>_LDMODULESONAME</envar>
</term>
<listitem><para>
A macro that automatically generates loadable module's SONAME based on $TARGET,
$LDMODULEVERSION and $LDMODULESUFFIX. Used by &b-link-LoadableModule; builder
when the linker tool supports SONAME (e.g. &t-link-gnulink;).
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-LDMODULESUFFIX">
<term>
<envar>LDMODULESUFFIX</envar>
</term>
<listitem><para>
The suffix used for loadable module file names.
On Mac OS X, this is null;
on other systems, this is
the same as $SHLIBSUFFIX.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-LDMODULEVERSION">
<term>
<envar>LDMODULEVERSION</envar>
</term>
<listitem><para>
When this &consvar; is defined, a versioned loadable module
is created by &b-link-LoadableModule; builder. This activates the
&cv-link-_LDMODULEVERSIONFLAGS; and thus modifies the &cv-link-LDMODULECOM; as
required, adds the version number to the library name, and creates the symlinks
that are needed. &cv-link-LDMODULEVERSION; versions should exist in the same
format as &cv-link-SHLIBVERSION;.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-_LDMODULEVERSIONFLAGS">
<term>
<envar>_LDMODULEVERSIONFLAGS</envar>
</term>
<listitem><para>
This macro automatically introduces extra flags to &cv-link-LDMODULECOM; when
building versioned &b-link-LoadableModule; (that is when
&cv-link-LDMODULEVERSION; is set). <literal>_LDMODULEVERSIONFLAGS</literal>
usually adds &cv-link-SHLIBVERSIONFLAGS; and some extra dynamically generated
options (such as <literal>-Wl,-soname=$_LDMODULESONAME</literal>). It is unused
by plain (unversioned) loadable modules.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-LDMODULEVERSIONFLAGS">
<term>
<envar>LDMODULEVERSIONFLAGS</envar>
</term>
<listitem><para>
Extra flags added to &cv-link-LDMODULECOM; when building versioned
&b-link-LoadableModule;. These flags are only used when &cv-link-LDMODULEVERSION; is
set.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-LEX">
<term>
<envar>LEX</envar>
</term>
<listitem><para>
The lexical analyzer generator.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-LEX_HEADER_FILE">
<term>
<envar>LEX_HEADER_FILE</envar>
</term>
<listitem><para>
If supplied, generate a C header file with the name taken from this variable.
Will be emitted as a <option>--header-file=</option>
command-line option. Use this in preference to including
<option>--header-file=</option> in &cv-link-LEXFLAGS; directly.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-LEX_TABLES_FILE">
<term>
<envar>LEX_TABLES_FILE</envar>
</term>
<listitem><para>
If supplied, write the lex tables to a file with the name
taken from this variable.
Will be emitted as a <option>--tables-file=</option>
command-line option. Use this in preference to including
<option>--tables-file=</option> in &cv-link-LEXFLAGS; directly.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-LEXCOM">
<term>
<envar>LEXCOM</envar>
</term>
<listitem><para>
The command line used to call the lexical analyzer generator
to generate a source file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-LEXCOMSTR">
<term>
<envar>LEXCOMSTR</envar>
</term>
<listitem><para>
The string displayed when generating a source file
using the lexical analyzer generator.
If this is not set, then &cv-link-LEXCOM; (the command line) is displayed.
</para>
<example_commands>
env = Environment(LEXCOMSTR="Lex'ing $TARGET from $SOURCES")
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-LEXFLAGS">
<term>
<envar>LEXFLAGS</envar>
</term>
<listitem><para>
General options passed to the lexical analyzer generator.
In addition to passing the value on during invocation,
the &t-link-lex; tool also examines this &consvar; for options
which cause additional output files to be generated,
and adds those to the target list.
Recognized for this purpose are GNU &flex; options
<option>--header-file=</option> and
<option>--tables-file=</option>;
the output file is named by the option argument.
</para>
<para>
Note that files specified by <option>--header-file=</option> and
<option>--tables-file=</option> may not be properly handled
by &SCons; in all situations. Consider using
&cv-link-LEX_HEADER_FILE; and &cv-link-LEX_TABLES_FILE; instead.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-LEXUNISTD">
<term>
<envar>LEXUNISTD</envar>
</term>
<listitem><para>
Used only on windows environments to set a lex flag to prevent 'unistd.h' from being included. The default value is '--nounistd'.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-_LIBDIRFLAGS">
<term>
<envar>_LIBDIRFLAGS</envar>
</term>
<listitem><para>
An automatically-generated construction variable
containing the linker command-line options
for specifying directories to be searched for library.
The value of &cv-_LIBDIRFLAGS; is created
by respectively prepending and appending &cv-link-LIBDIRPREFIX;
and &cv-link-LIBDIRSUFFIX;
to each directory in &cv-link-LIBPATH;.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-LIBDIRPREFIX">
<term>
<envar>LIBDIRPREFIX</envar>
</term>
<listitem><para>
The prefix used to specify a library directory on the linker command line.
This will be prepended to each directory
in the &cv-link-LIBPATH; construction variable
when the &cv-link-_LIBDIRFLAGS; variable is automatically generated.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-LIBDIRSUFFIX">
<term>
<envar>LIBDIRSUFFIX</envar>
</term>
<listitem><para>
The suffix used to specify a library directory on the linker command line.
This will be appended to each directory
in the &cv-link-LIBPATH; construction variable
when the &cv-link-_LIBDIRFLAGS; variable is automatically generated.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-LIBEMITTER">
<term>
<envar>LIBEMITTER</envar>
</term>
<listitem><para>
Contains the emitter specification for the
&b-link-StaticLibrary; builder.
The manpage section "Builder Objects" contains
general information on specifying emitters.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-_LIBFLAGS">
<term>
<envar>_LIBFLAGS</envar>
</term>
<listitem><para>
An automatically-generated construction variable
containing the linker command-line options
for specifying libraries to be linked with the resulting target.
The value of &cv-link-_LIBFLAGS; is created
by respectively prepending and appending &cv-link-LIBLINKPREFIX;
and &cv-link-LIBLINKSUFFIX;
to each filename in &cv-link-LIBS;.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-LIBLINKPREFIX">
<term>
<envar>LIBLINKPREFIX</envar>
</term>
<listitem><para>
The prefix used to specify a library to link on the linker command line.
This will be prepended to each library
in the &cv-link-LIBS; construction variable
when the &cv-link-_LIBFLAGS; variable is automatically generated.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-LIBLINKSUFFIX">
<term>
<envar>LIBLINKSUFFIX</envar>
</term>
<listitem><para>
The suffix used to specify a library to link on the linker command line.
This will be appended to each library
in the &cv-link-LIBS; construction variable
when the &cv-link-_LIBFLAGS; variable is automatically generated.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-LIBPATH">
<term>
<envar>LIBPATH</envar>
</term>
<listitem><para>
The list of directories that will be searched for libraries
specified by the &cv-link-LIBS; &consvar;.
&cv-LIBPATH; should be a list of path strings,
or a single string, not a pathname list joined by
Python's <systemitem>os.sep</systemitem>.
<!-- XXX OLD
The implicit dependency scanner will search these
directories for include files. Don't explicitly put include directory
arguments into &cv-LINKFLAGS; or &cv-SHLINKFLAGS;
because the result will be non-portable
and the directories will not be searched by the dependency scanner.
-->
<!-- XXX NEW -->
Do not put library search directives directly
into &cv-LINKFLAGS; or &cv-SHLINKFLAGS;
as the result will be non-portable.
<!-- end NEW -->
</para>
<para>
Note:
directory names in &cv-LIBPATH; will be looked-up relative to the
directory of the SConscript file
when they are used in a command.
To force &scons;
to look-up a directory relative to the root of the source tree use
the <literal>#</literal> prefix:
</para>
<example_commands>
env = Environment(LIBPATH='#/libs')
</example_commands>
<para>
The directory look-up can also be forced using the
&f-link-Dir; function:
</para>
<example_commands>
libs = Dir('libs')
env = Environment(LIBPATH=libs)
</example_commands>
<para>
The directory list will be added to command lines
through the automatically-generated
&cv-link-_LIBDIRFLAGS;
construction variable,
which is constructed by
respectively prepending and appending the values of the
&cv-link-LIBDIRPREFIX; and &cv-link-LIBDIRSUFFIX;
construction variables
to each directory in &cv-LIBPATH;.
Any command lines you define that need
the &cv-LIBPATH; directory list should
include &cv-_LIBDIRFLAGS;:
</para>
<example_commands>
env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-LIBPREFIX">
<term>
<envar>LIBPREFIX</envar>
</term>
<listitem><para>
The prefix used for (static) library file names.
A default value is set for each platform
(posix, win32, os2, etc.),
but the value is overridden by individual tools
(ar, mslib, sgiar, sunar, tlib, etc.)
to reflect the names of the libraries they create.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-LIBPREFIXES">
<term>
<envar>LIBPREFIXES</envar>
</term>
<listitem><para>
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 from the &cv-link-LIBSUFFIXES; list.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-LIBS">
<term>
<envar>LIBS</envar>
</term>
<listitem><para>
A list of one or more libraries
that will be added to the link line
for linking with any executable program, shared library, or loadable module
created by the &consenv; or override.
</para>
<para>
String-valued library names should include
only the library base names,
without prefixes such as <filename>lib</filename>
or suffixes such as <filename>.so</filename> or <filename>.dll</filename>.
The library list will be added to command lines
through the automatically-generated
&cv-_LIBFLAGS; &consvar;
which is constructed by
respectively prepending and appending the values of the
&cv-LIBLINKPREFIX; and &cv-LIBLINKSUFFIX; &consvars;
to each library name in &cv-LIBS;.
Library name strings should not include a
path component, instead the compiler will be
directed to look for libraries in the paths
specified by &cv-link-LIBPATH;.
</para>
<para>
Any command lines you define that need
the &cv-LIBS; library list should
include &cv-_LIBFLAGS;:
</para>
<example_commands>
env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
</example_commands>
<para>
If you add a
<classname>File</classname>
object to the
&cv-LIBS;
list, the name of that file will be added to
&cv-_LIBFLAGS;,
and thus to the link line, as-is, without
&cv-LIBLINKPREFIX;
or
&cv-LIBLINKSUFFIX;.
For example:
</para>
<example_commands>
env.Append(LIBS=File('/tmp/mylib.so'))
</example_commands>
<para>
In all cases, scons will add dependencies from the executable program to
all the libraries in this list.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-LIBSUFFIX">
<term>
<envar>LIBSUFFIX</envar>
</term>
<listitem><para>
The suffix used for (static) library file names.
A default value is set for each platform
(posix, win32, os2, etc.),
but the value is overridden by individual tools
(ar, mslib, sgiar, sunar, tlib, etc.)
to reflect the names of the libraries they create.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-LIBSUFFIXES">
<term>
<envar>LIBSUFFIXES</envar>
</term>
<listitem><para>
A list of all legal suffixes for library file names.
When searching for library dependencies,
SCons will look for files with prefixes from the &cv-link-LIBPREFIXES; list,
the base library name,
and these suffixes.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-LICENSE">
<term>
<envar>LICENSE</envar>
</term>
<listitem><para>
The abbreviated name, preferably the SPDX code, of the license under which
this project is released (GPL-3.0, LGPL-2.1, BSD-2-Clause etc.).
See
<ulink url="http://www.opensource.org/licenses/alphabetical">
http://www.opensource.org/licenses/alphabetical</ulink>
for a list of license names and SPDX codes.
</para>
<para>See the &b-link-Package; builder.</para>
</listitem>
</varlistentry>
<varlistentry id="cv-LINESEPARATOR">
<term>
<envar>LINESEPARATOR</envar>
</term>
<listitem><para>
The separator used by the &b-link-Substfile; and &b-link-Textfile; builders.
This value is used between sources when constructing the target.
It defaults to the current system line separator.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-LINGUAS_FILE">
<term>
<envar>LINGUAS_FILE</envar>
</term>
<listitem><para>
The &cv-LINGUAS_FILE; defines file(s) containing list of additional linguas
to be processed by &b-link-POInit;, &b-link-POUpdate; or &b-link-MOFiles;
builders. It also affects &b-link-Translate; builder. If the variable contains
a string, it defines name of the list file. The &cv-LINGUAS_FILE; may be a
list of file names as well. If &cv-LINGUAS_FILE; is set to
<literal>True</literal> (or non-zero numeric value), the list will be read from
default file named
<filename>LINGUAS</filename>.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-LINK">
<term>
<envar>LINK</envar>
</term>
<listitem><para>
The linker.
See also &cv-link-SHLINK; for linking shared objects.
</para>
<para>
On POSIX systems (those using the &t-link-link; tool),
you should normally not change this value as it defaults
to a "smart" linker tool which selects a compiler
driver matching the type of source files in use.
So for example, if you set &cv-link-CXX; to a specific
compiler name, and are compiling C++ sources,
the smartlink function will automatically select the same compiler
for linking.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-LINKCOM">
<term>
<envar>LINKCOM</envar>
</term>
<listitem><para>
The command line used to link object files into an executable.
See also &cv-link-SHLINKCOM; for linking shared objects.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-LINKCOMSTR">
<term>
<envar>LINKCOMSTR</envar>
</term>
<listitem><para>
If set, the string displayed when object files
are linked into an executable.
If not set, then &cv-link-LINKCOM; (the command line) is displayed.
See also &cv-link-SHLINKCOMSTR;. for linking shared objects.
</para>
<example_commands>
env = Environment(LINKCOMSTR = "Linking $TARGET")
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-LINKFLAGS">
<term>
<envar>LINKFLAGS</envar>
</term>
<listitem><para>
General user options passed to the linker.
Note that this variable should
<emphasis>not</emphasis>
contain
<option>-l</option>
(or similar) options for linking with the libraries listed in &cv-link-LIBS;,
nor
<option>-L</option>
(or similar) library search path options
that scons generates automatically from &cv-link-LIBPATH;.
See
&cv-link-_LIBFLAGS;
above,
for the variable that expands to library-link options,
and
&cv-link-_LIBDIRFLAGS;
above,
for the variable that expands to library search path options.
See also &cv-link-SHLINKFLAGS;. for linking shared objects.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-M4">
<term>
<envar>M4</envar>
</term>
<listitem><para>
The M4 macro preprocessor.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-M4COM">
<term>
<envar>M4COM</envar>
</term>
<listitem><para>
The command line used to pass files through the M4 macro preprocessor.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-M4COMSTR">
<term>
<envar>M4COMSTR</envar>
</term>
<listitem><para>
The string displayed when
a file is passed through the M4 macro preprocessor.
If this is not set, then &cv-link-M4COM; (the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-M4FLAGS">
<term>
<envar>M4FLAGS</envar>
</term>
<listitem><para>
General options passed to the M4 macro preprocessor.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MAKEINDEX">
<term>
<envar>MAKEINDEX</envar>
</term>
<listitem><para>
The makeindex generator for the TeX formatter and typesetter and the
LaTeX structured formatter and typesetter.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MAKEINDEXCOM">
<term>
<envar>MAKEINDEXCOM</envar>
</term>
<listitem><para>
The command line used to call the makeindex generator for the
TeX formatter and typesetter and the LaTeX structured formatter and
typesetter.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MAKEINDEXCOMSTR">
<term>
<envar>MAKEINDEXCOMSTR</envar>
</term>
<listitem><para>
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 &cv-link-MAKEINDEXCOM; (the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MAKEINDEXFLAGS">
<term>
<envar>MAKEINDEXFLAGS</envar>
</term>
<listitem><para>
General options passed to the makeindex generator for the TeX formatter
and typesetter and the LaTeX structured formatter and typesetter.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MAXLINELENGTH">
<term>
<envar>MAXLINELENGTH</envar>
</term>
<listitem><para>
The maximum number of characters allowed on an external command line.
On Win32 systems,
link lines longer than this many characters
are linked via a temporary file name.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MIDL">
<term>
<envar>MIDL</envar>
</term>
<listitem><para>
The Microsoft IDL compiler.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MIDLCOM">
<term>
<envar>MIDLCOM</envar>
</term>
<listitem><para>
The command line used to pass files to the Microsoft IDL compiler.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MIDLCOMSTR">
<term>
<envar>MIDLCOMSTR</envar>
</term>
<listitem><para>
The string displayed when
the Microsoft IDL compiler is called.
If this is not set, then &cv-link-MIDLCOM; (the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MIDLFLAGS">
<term>
<envar>MIDLFLAGS</envar>
</term>
<listitem><para>
General options passed to the Microsoft IDL compiler.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MOSUFFIX">
<term>
<envar>MOSUFFIX</envar>
</term>
<listitem><para>
Suffix used for <literal>MO</literal> files (default: <literal>'.mo'</literal>).
See &t-link-msgfmt; tool and &b-link-MOFiles; builder.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSGFMT">
<term>
<envar>MSGFMT</envar>
</term>
<listitem><para>
Absolute path to <command>msgfmt(1)</command> binary, found by
<function>Detect()</function>.
See &t-link-msgfmt; tool and &b-link-MOFiles; builder.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSGFMTCOM">
<term>
<envar>MSGFMTCOM</envar>
</term>
<listitem><para>
Complete command line to run <command>msgfmt(1)</command> program.
See &t-link-msgfmt; tool and &b-link-MOFiles; builder.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSGFMTCOMSTR">
<term>
<envar>MSGFMTCOMSTR</envar>
</term>
<listitem><para>
String to display when <command>msgfmt(1)</command> is invoked
(default: <literal>''</literal>, which means ``print &cv-link-MSGFMTCOM;'').
See &t-link-msgfmt; tool and &b-link-MOFiles; builder.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSGFMTFLAGS">
<term>
<envar>MSGFMTFLAGS</envar>
</term>
<listitem><para>
Additional flags to <command>msgfmt(1)</command>.
See &t-link-msgfmt; tool and &b-link-MOFiles; builder.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSGINIT">
<term>
<envar>MSGINIT</envar>
</term>
<listitem><para>
Path to <command>msginit(1)</command> program (found via
<literal>Detect()</literal>).
See &t-link-msginit; tool and &b-link-POInit; builder.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSGINITCOM">
<term>
<envar>MSGINITCOM</envar>
</term>
<listitem><para>
Complete command line to run <command>msginit(1)</command> program.
See &t-link-msginit; tool and &b-link-POInit; builder.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSGINITCOMSTR">
<term>
<envar>MSGINITCOMSTR</envar>
</term>
<listitem><para>
String to display when <command>msginit(1)</command> is invoked
(default: <literal>''</literal>, which means ``print &cv-link-MSGINITCOM;'').
See &t-link-msginit; tool and &b-link-POInit; builder.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSGINITFLAGS">
<term>
<envar>MSGINITFLAGS</envar>
</term>
<listitem><para>
List of additional flags to <command>msginit(1)</command> (default:
<literal>[]</literal>).
See &t-link-msginit; tool and &b-link-POInit; builder.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-_MSGINITLOCALE">
<term>
<envar>_MSGINITLOCALE</envar>
</term>
<listitem><para>
Internal ``macro''. Computes locale (language) name based on target filename
(default: <literal>'${TARGET.filebase}' </literal>).
</para>
<para>
See &t-link-msginit; tool and &b-link-POInit; builder.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSGMERGE">
<term>
<envar>MSGMERGE</envar>
</term>
<listitem><para>
Absolute path to <command>msgmerge(1)</command> binary as found by
<function>Detect()</function>.
See &t-link-msgmerge; tool and &b-link-POUpdate; builder.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSGMERGECOM">
<term>
<envar>MSGMERGECOM</envar>
</term>
<listitem><para>
Complete command line to run <command>msgmerge(1)</command> command.
See &t-link-msgmerge; tool and &b-link-POUpdate; builder.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSGMERGECOMSTR">
<term>
<envar>MSGMERGECOMSTR</envar>
</term>
<listitem><para>
String to be displayed when <command>msgmerge(1)</command> is invoked
(default: <literal>''</literal>, which means ``print &cv-link-MSGMERGECOM;'').
See &t-link-msgmerge; tool and &b-link-POUpdate; builder.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSGMERGEFLAGS">
<term>
<envar>MSGMERGEFLAGS</envar>
</term>
<listitem><para>
Additional flags to <command>msgmerge(1)</command> command.
See &t-link-msgmerge; tool and &b-link-POUpdate; builder.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSSDK_DIR">
<term>
<envar>MSSDK_DIR</envar>
</term>
<listitem><para>
The directory containing the Microsoft SDK
(either Platform SDK or Windows SDK)
to be used for compilation.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSSDK_VERSION">
<term>
<envar>MSSDK_VERSION</envar>
</term>
<listitem><para>
The version string of the Microsoft SDK
(either Platform SDK or Windows SDK)
to be used for compilation.
Supported versions include
<literal>6.1</literal>,
<literal>6.0A</literal>,
<literal>6.0</literal>,
<literal>2003R2</literal>
and
<literal>2003R1</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSVC_BATCH">
<term>
<envar>MSVC_BATCH</envar>
</term>
<listitem><para>
When set to any true value,
specifies that SCons should batch
compilation of object files
when calling the Microsoft Visual C/C++ compiler.
All compilations of source files from the same source directory
that generate target files in a same output directory
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 &cv-link-CHANGED_SOURCES; construction variable).
Any compilations where the object (target) file base name
(minus the <filename>.obj</filename>)
does not match the source file base name
will be compiled separately.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSVC_NOTFOUND_POLICY">
<term>
<envar>MSVC_NOTFOUND_POLICY</envar>
</term>
<listitem><para>
Specify the &scons; behavior when the Microsoft Visual C/C++ compiler is not detected.
</para>
<para>
The &cv-MSVC_NOTFOUND_POLICY; specifies the &scons; behavior when no msvc versions are detected or
when the requested msvc version is not detected.
</para>
<para>
The valid values for &cv-MSVC_NOTFOUND_POLICY; and the corresponding &scons; behavior are:
</para>
<variablelist>
<varlistentry>
<term><parameter>'Error' or 'Exception'</parameter></term>
<listitem>
<para>
Raise an exception when no msvc versions are detected or when the requested msvc version is not detected.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>'Warning' or 'Warn'</parameter></term>
<listitem>
<para>
Issue a warning and continue when no msvc versions are detected or when the requested msvc version is not detected.
Depending on usage, this could result in build failure(s).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>'Ignore' or 'Suppress'</parameter></term>
<listitem>
<para>
Take no action and continue when no msvc versions are detected or when the requested msvc version is not detected.
Depending on usage, this could result in build failure(s).
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
Note: in addition to the camel case values shown above, lower case and upper case values are accepted as well.
</para>
<para>
The &cv-MSVC_NOTFOUND_POLICY; is applied when any of the following conditions are satisfied:
<itemizedlist>
<listitem><para>
&cv-MSVC_VERSION; is specified, the default tools list is implicitly defined (i.e., the tools list is not specified),
and the default tools list contains one or more of the msvc tools.
</para></listitem>
<listitem><para>
&cv-MSVC_VERSION; is specified, the default tools list is explicitly specified (e.g., <literal>tools=['default']</literal>),
and the default tools list contains one or more of the msvc tools.
</para></listitem>
<listitem><para>
A non-default tools list is specified that contains one or more of the msvc tools (e.g., <literal>tools=['msvc', 'mslink']</literal>).
</para></listitem>
</itemizedlist>
</para>
<para>
The &cv-MSVC_NOTFOUND_POLICY; is ignored when any of the following conditions are satisfied:
<itemizedlist>
<listitem><para>
&cv-MSVC_VERSION; is not specified and the default tools list is implicitly defined (i.e., the tools list is not specified).
</para></listitem>
<listitem><para>
&cv-MSVC_VERSION; is not specified and the default tools list is explicitly specified (e.g., <literal>tools=['default']</literal>).
</para></listitem>
<listitem><para>
A non-default tool list is specified that does not contain any of the msvc tools (e.g., <literal>tools=['mingw']</literal>).
</para></listitem>
</itemizedlist>
</para>
<para>
Important usage details:
<itemizedlist>
<listitem><para>
&cv-MSVC_NOTFOUND_POLICY; must be passed as an argument to the &f-link-Environment;
constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
loaded via the default tools list or via a tools list passed to the
&f-link-Environment; constructor.
Otherwise, &cv-MSVC_NOTFOUND_POLICY; must be set before the first msvc tool is
loaded into the environment.
</para></listitem>
</itemizedlist>
</para>
<para>
When &cv-MSVC_NOTFOUND_POLICY; is not specified, the default &scons; behavior is to issue a warning and continue
subject to the conditions listed above. The default &scons; behavior may change in the future.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSVC_SCRIPT_ARGS">
<term>
<envar>MSVC_SCRIPT_ARGS</envar>
</term>
<listitem><para>
Pass user-defined arguments to the Visual C++ batch file determined via autodetection.
</para>
<para>
&cv-MSVC_SCRIPT_ARGS; is available for msvc batch file arguments that do not have first-class support
via construction variables or when there is an issue with the appropriate construction variable validation.
When available, it is recommended to use the appropriate construction variables (e.g., &cv-link-MSVC_TOOLSET_VERSION;)
rather than &cv-MSVC_SCRIPT_ARGS; arguments.
</para>
<para>
The valid values for &cv-MSVC_SCRIPT_ARGS; are: <literal>None</literal>, a string,
or a list of strings.
</para>
<para>
The &cv-MSVC_SCRIPT_ARGS; value is converted to a scalar string (i.e., "flattened").
The resulting scalar string, if not empty, is passed as an argument to the msvc batch file determined
via autodetection subject to the validation conditions listed below.
</para>
<para>
&cv-MSVC_SCRIPT_ARGS; is ignored when the value is <literal>None</literal> and when the
result from argument conversion is an empty string. The validation conditions below do not apply.
</para>
<para>
An exception is raised when any of the following conditions are satisfied:
<itemizedlist>
<listitem><para>
&cv-MSVC_SCRIPT_ARGS; is specified for Visual Studio 2013 and earlier.
</para></listitem>
<listitem><para>
Multiple SDK version arguments (e.g., <literal>'10.0.20348.0'</literal>) are specified
in &cv-MSVC_SCRIPT_ARGS;.
</para></listitem>
<listitem><para>
&cv-link-MSVC_SDK_VERSION; is specified and an SDK version argument
(e.g., <literal>'10.0.20348.0'</literal>) is specified in &cv-MSVC_SCRIPT_ARGS;.
Multiple SDK version declarations via &cv-link-MSVC_SDK_VERSION; and &cv-MSVC_SCRIPT_ARGS;
are not allowed.
</para></listitem>
<listitem><para>
Multiple toolset version arguments (e.g., <literal>'-vcvars_ver=14.29'</literal>)
are specified in &cv-MSVC_SCRIPT_ARGS;.
</para></listitem>
<listitem><para>
&cv-link-MSVC_TOOLSET_VERSION; is specified and a toolset version argument
(e.g., <literal>'-vcvars_ver=14.29'</literal>) is specified in &cv-MSVC_SCRIPT_ARGS;.
Multiple toolset version declarations via &cv-link-MSVC_TOOLSET_VERSION; and
&cv-MSVC_SCRIPT_ARGS; are not allowed.
</para></listitem>
<listitem><para>
Multiple spectre library arguments (e.g., <literal>'-vcvars_spectre_libs=spectre'</literal>)
are specified in &cv-MSVC_SCRIPT_ARGS;.
</para></listitem>
<listitem><para>
&cv-link-MSVC_SPECTRE_LIBS; is enabled and a spectre library argument
(e.g., <literal>'-vcvars_spectre_libs=spectre'</literal>) is specified in
&cv-MSVC_SCRIPT_ARGS;. Multiple spectre library declarations via &cv-link-MSVC_SPECTRE_LIBS;
and &cv-MSVC_SCRIPT_ARGS; are not allowed.
</para></listitem>
<listitem><para>
Multiple UWP arguments (e.g., <literal>uwp</literal> or <literal>store</literal>) are specified
in &cv-MSVC_SCRIPT_ARGS;.
</para></listitem>
<listitem><para>
&cv-link-MSVC_UWP_APP; is enabled and a UWP argument (e.g., <literal>uwp</literal> or
<literal>store</literal>) is specified in &cv-MSVC_SCRIPT_ARGS;. Multiple UWP declarations
via &cv-link-MSVC_UWP_APP; and &cv-MSVC_SCRIPT_ARGS; are not allowed.
</para></listitem>
</itemizedlist>
</para>
<para>
Example 1 - A Visual Studio 2022 build with an SDK version and a toolset version
specified with a string argument:
<example_commands>
env = Environment(MSVC_VERSION='14.3', MSVC_SCRIPT_ARGS='10.0.20348.0 -vcvars_ver=14.29.30133')
</example_commands>
</para>
<para>
Example 2 - A Visual Studio 2022 build with an SDK version and a toolset version
specified with a list argument:
<example_commands>
env = Environment(MSVC_VERSION='14.3', MSVC_SCRIPT_ARGS=['10.0.20348.0', '-vcvars_ver=14.29.30133'])
</example_commands>
</para>
<para>
Important usage details:
<itemizedlist>
<listitem><para>
&cv-MSVC_SCRIPT_ARGS; must be passed as an argument to the &f-link-Environment;
constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
loaded via the default tools list or via a tools list passed to the
&f-link-Environment; constructor.
Otherwise, &cv-MSVC_SCRIPT_ARGS; must be set before the first msvc tool is
loaded into the environment.
</para></listitem>
<listitem><para>
Other than checking for multiple declarations as described above, &cv-MSVC_SCRIPT_ARGS; arguments
are not validated.
</para></listitem>
<listitem><para>
<emphasis>
Erroneous, inconsistent, and/or version incompatible &cv-MSVC_SCRIPT_ARGS; arguments are likely
to result in build failures for reasons that are not readily apparent and may be difficult to diagnose.
</emphasis>
The burden is on the user to ensure that the arguments provided to the msvc batch file are valid, consistent
and compatible with the version of msvc selected.
</para></listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSVC_SCRIPTERROR_POLICY">
<term>
<envar>MSVC_SCRIPTERROR_POLICY</envar>
</term>
<listitem><para>
Specify the &scons; behavior when Microsoft Visual C/C++ batch file errors are detected.
</para>
<para>
The &cv-MSVC_SCRIPTERROR_POLICY; specifies the &scons; behavior when msvc batch file errors are
detected.
When &cv-MSVC_SCRIPTERROR_POLICY; is not specified, the default &scons; behavior is to suppress
msvc batch file error messages.
</para>
<para>
The root cause of msvc build failures may be difficult to diagnose. In these situations, setting
the &scons; behavior to issue a warning when msvc batch file errors are detected <emphasis>may</emphasis>
produce additional diagnostic information.
</para>
<para>
The valid values for &cv-MSVC_SCRIPTERROR_POLICY; and the corresponding &scons; behavior are:
</para>
<variablelist>
<varlistentry>
<term><parameter>'Error' or 'Exception'</parameter></term>
<listitem>
<para>
Raise an exception when msvc batch file errors are detected.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>'Warning' or 'Warn'</parameter></term>
<listitem>
<para>
Issue a warning when msvc batch file errors are detected.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>'Ignore' or 'Suppress'</parameter></term>
<listitem>
<para>
Suppress msvc batch file error messages.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
Note: in addition to the camel case values shown above, lower case and upper case values are accepted as well.
</para>
<para>
Example 1 - A Visual Studio 2022 build with user-defined script arguments:
<example_commands>
env = environment(MSVC_VERSION='14.3', MSVC_SCRIPT_ARGS=['8.1', 'store', '-vcvars_ver=14.1'])
env.Program('hello', ['hello.c'], CCFLAGS='/MD', LIBS=['kernel32', 'user32', 'runtimeobject'])
</example_commands>
</para>
<para>
Example 1 - Output fragment:
<example_commands>
...
link /nologo /OUT:_build001\hello.exe kernel32.lib user32.lib runtimeobject.lib _build001\hello.obj
LINK : fatal error LNK1104: cannot open file 'MSVCRT.lib'
...
</example_commands>
</para>
<para>
Example 2 - A Visual Studio 2022 build with user-defined script arguments and the script error policy set
to issue a warning when msvc batch file errors are detected:
<example_commands>
env = environment(MSVC_VERSION='14.3', MSVC_SCRIPT_ARGS=['8.1', 'store', '-vcvars_ver=14.1'], MSVC_SCRIPTERROR_POLICY='warn')
env.Program('hello', ['hello.c'], CCFLAGS='/MD', LIBS=['kernel32', 'user32', 'runtimeobject'])
</example_commands>
</para>
<para>
Example 2 - Output fragment:
<example_commands>
...
scons: warning: vc script errors detected:
[ERROR:vcvars.bat] The UWP Application Platform requires a Windows 10 SDK.
[ERROR:vcvars.bat] WindowsSdkDir = "C:\Program Files (x86)\Windows Kits\8.1\"
[ERROR:vcvars.bat] host/target architecture is not supported : { x64 , x64 }
...
link /nologo /OUT:_build001\hello.exe kernel32.lib user32.lib runtimeobject.lib _build001\hello.obj
LINK : fatal error LNK1104: cannot open file 'MSVCRT.lib'
</example_commands>
</para>
<para>
Important usage details:
<itemizedlist>
<listitem><para>
&cv-MSVC_SCRIPTERROR_POLICY; must be passed as an argument to the &f-link-Environment;
constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
loaded via the default tools list or via a tools list passed to the
&f-link-Environment; constructor.
Otherwise, &cv-MSVC_SCRIPTERROR_POLICY; must be set before the first msvc tool is
loaded into the environment.
</para></listitem>
<listitem><para>
Due to &scons; implementation details, not all Windows system environment variables are propagated
to the environment in which the msvc batch file is executed. Depending on Visual Studio version
and installation options, non-fatal msvc batch file error messages may be generated for ancillary
tools which may not affect builds with the msvc compiler. For this reason, caution is recommended
when setting the script error policy to raise an exception (e.g., <literal>'Error'</literal>).
</para></listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSVC_SDK_VERSION">
<term>
<envar>MSVC_SDK_VERSION</envar>
</term>
<listitem><para>
Build with a specific version of the Microsoft Software Development Kit (SDK).
</para>
<para>
The valid values for &cv-MSVC_SDK_VERSION; are: <literal>None</literal>
or a string containing the requested SDK version (e.g., <literal>'10.0.20348.0'</literal>).
</para>
<para>
&cv-MSVC_SDK_VERSION; is ignored when the value is <literal>None</literal> and when
the value is an empty string. The validation conditions below do not apply.
</para>
<para>
An exception is raised when any of the following conditions are satisfied:
<itemizedlist>
<listitem><para>
&cv-MSVC_SDK_VERSION; is specified for Visual Studio 2013 and earlier.
</para></listitem>
<listitem><para>
&cv-MSVC_SDK_VERSION; is specified and an SDK version argument is specified in
&cv-link-MSVC_SCRIPT_ARGS;. Multiple SDK version declarations via &cv-MSVC_SDK_VERSION;
and &cv-link-MSVC_SCRIPT_ARGS; are not allowed.
</para></listitem>
<listitem><para>
The &cv-MSVC_SDK_VERSION; specified does not match any of the supported formats:
<itemizedlist>
<listitem><para>
<literal>'10.0.XXXXX.Y'</literal> [SDK 10.0]
</para></listitem>
<listitem><para>
<literal>'8.1'</literal> [SDK 8.1]
</para></listitem>
</itemizedlist>
</para></listitem>
<listitem><para>
The system folder for the corresponding &cv-MSVC_SDK_VERSION; version is not found.
The requested SDK version does not appear to be installed.
</para></listitem>
<listitem><para>
The &cv-MSVC_SDK_VERSION; version does not appear to support the requested platform
type (i.e., <literal>UWP</literal> or <literal>Desktop</literal>). The requested SDK version
platform type components do not appear to be installed.
</para></listitem>
<listitem><para>
The &cv-MSVC_SDK_VERSION; version is <literal>8.1</literal>, the platform type is
<literal>UWP</literal>, and the build tools selected are from Visual Studio 2017
and later (i.e., &cv-link-MSVC_VERSION; must be '14.0' or &cv-link-MSVC_TOOLSET_VERSION;
must be '14.0').
</para></listitem>
</itemizedlist>
</para>
<para>
Example 1 - A Visual Studio 2022 build with a specific Windows SDK version:
<example_commands>
env = Environment(MSVC_VERSION='14.3', MSVC_SDK_VERSION='10.0.20348.0')
</example_commands>
</para>
<para>
Example 2 - A Visual Studio 2022 build with a specific SDK version for the Universal Windows Platform:
<example_commands>
env = Environment(MSVC_VERSION='14.3', MSVC_SDK_VERSION='10.0.20348.0', MSVC_UWP_APP=True)
</example_commands>
</para>
<para>
Important usage details:
<itemizedlist>
<listitem><para>
&cv-MSVC_SDK_VERSION; must be passed as an argument to the &f-link-Environment;
constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
loaded via the default tools list or via a tools list passed to the
&f-link-Environment; constructor.
Otherwise, &cv-MSVC_SDK_VERSION; must be set before the first msvc tool is
loaded into the environment.
</para></listitem>
<listitem>
<para><emphasis>
Should a SDK 10.0 version be installed that does not follow the naming scheme above, the
SDK version will need to be specified via &cv-link-MSVC_SCRIPT_ARGS; until the version number
validation format can be extended.
</emphasis></para>
</listitem>
<listitem><para>
Should an exception be raised indicating that the SDK version is not found, verify that
the requested SDK version is installed with the necessary platform type components.
</para></listitem>
<listitem><para>
There is a known issue with the Microsoft libraries when the target architecture is
<literal>ARM64</literal> and a Windows 11 SDK (version <literal>'10.0.22000.0'</literal> and later) is used
with the <literal>v141</literal> build tools and older <literal>v142</literal> toolsets
(versions <literal>'14.28.29333'</literal> and earlier). Should build failures arise with these combinations
of settings due to unresolved symbols in the Microsoft libraries, &cv-MSVC_SDK_VERSION; may be employed to
specify a Windows 10 SDK (e.g., <literal>'10.0.20348.0'</literal>) for the build.
</para></listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSVC_SPECTRE_LIBS">
<term>
<envar>MSVC_SPECTRE_LIBS</envar>
</term>
<listitem><para>
Build with the spectre-mitigated Visual C++ libraries.
</para>
<para>
The valid values for &cv-MSVC_SPECTRE_LIBS; are: <literal>True</literal>,
<literal>False</literal>, or <literal>None</literal>.
</para>
<para>
When &cv-MSVC_SPECTRE_LIBS; is enabled (i.e., <literal>True</literal>),
the Visual C++ environment will include the paths to the spectre-mitigated implementations
of the Microsoft Visual C++ libraries.
</para>
<para>
An exception is raised when any of the following conditions are satisfied:
<itemizedlist>
<listitem><para>
&cv-MSVC_SPECTRE_LIBS; is enabled for Visual Studio 2015 and earlier.
</para></listitem>
<listitem><para>
&cv-MSVC_SPECTRE_LIBS; is enabled and a spectre library argument is specified in
&cv-link-MSVC_SCRIPT_ARGS;. Multiple spectre library declarations via &cv-MSVC_SPECTRE_LIBS;
and &cv-link-MSVC_SCRIPT_ARGS; are not allowed.
</para></listitem>
<listitem><para>
&cv-MSVC_SPECTRE_LIBS; is enabled and the platform type is <literal>UWP</literal>. There
are no spectre-mitigated libraries for Universal Windows Platform (UWP) applications or
components.
</para></listitem>
</itemizedlist>
</para>
<para>
Example - A Visual Studio 2022 build with spectre mitigated Visual C++ libraries:
<example_commands>
env = Environment(MSVC_VERSION='14.3', MSVC_SPECTRE_LIBS=True)
</example_commands>
</para>
<para>
Important usage details:
<itemizedlist>
<listitem><para>
&cv-MSVC_SPECTRE_LIBS; must be passed as an argument to the &f-link-Environment;
constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
loaded via the default tools list or via a tools list passed to the
&f-link-Environment; constructor.
Otherwise, &cv-MSVC_SPECTRE_LIBS; must be set before the first msvc tool is
loaded into the environment.
</para></listitem>
<listitem><para>
Additional compiler switches (e.g., <literal>/Qspectre</literal>) are necessary for including
spectre mitigations when building user artifacts. Refer to the Visual Studio documentation for
details.
</para></listitem>
<listitem><para>
<emphasis>
The existence of the spectre libraries host architecture and target architecture folders are not
verified when &cv-MSVC_SPECTRE_LIBS; is enabled which could result in build failures.
</emphasis>
The burden is on the user to ensure the requisite libraries with spectre mitigations are installed.
</para></listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSVC_TOOLSET_VERSION">
<term>
<envar>MSVC_TOOLSET_VERSION</envar>
</term>
<listitem><para>
Build with a specific Visual C++ toolset version.
</para>
<para><emphasis>
Specifying &cv-MSVC_TOOLSET_VERSION; does not affect the autodetection and selection
of msvc instances. The &cv-MSVC_TOOLSET_VERSION; is applied <emphasis>after</emphasis>
an msvc instance is selected. This could be the default version of msvc if &cv-link-MSVC_VERSION;
is not specified.
</emphasis></para>
<para>
The valid values for &cv-MSVC_TOOLSET_VERSION; are: <literal>None</literal>
or a string containing the requested toolset version (e.g., <literal>'14.29'</literal>).
</para>
<para>
&cv-MSVC_TOOLSET_VERSION; is ignored when the value is <literal>None</literal> and when
the value is an empty string. The validation conditions below do not apply.
</para>
<para>
An exception is raised when any of the following conditions are satisfied:
<itemizedlist>
<listitem><para>
&cv-MSVC_TOOLSET_VERSION; is specified for Visual Studio 2015 and earlier.
</para></listitem>
<listitem><para>
&cv-MSVC_TOOLSET_VERSION; is specified and a toolset version argument is specified in
&cv-link-MSVC_SCRIPT_ARGS;. Multiple toolset version declarations via &cv-MSVC_TOOLSET_VERSION;
and &cv-link-MSVC_SCRIPT_ARGS; are not allowed.
</para></listitem>
<listitem>
<para>
The &cv-MSVC_TOOLSET_VERSION; specified does not match any of the supported formats:
</para>
<itemizedlist>
<listitem><para>
<literal>'XX.Y'</literal>
</para></listitem>
<listitem><para>
<literal>'XX.YY'</literal>
</para></listitem>
<listitem><para>
<literal>'XX.YY.ZZZZZ'</literal>
</para></listitem>
<listitem><para>
<literal>'XX.YY.Z'</literal> to <literal>'XX.YY.ZZZZ'</literal>
<emphasis>
[&scons; extension not directly supported by the msvc batch files and may be removed in the future]
</emphasis>
</para></listitem>
<listitem><para>
<literal>'XX.YY.ZZ.N'</literal> [SxS format]
</para></listitem>
<listitem><para>
<literal>'XX.YY.ZZ.NN'</literal> [SxS format]
</para></listitem>
</itemizedlist>
</listitem>
<listitem><para>
The major msvc version prefix (i.e., <literal>'XX.Y'</literal>) of the &cv-MSVC_TOOLSET_VERSION; specified
is for Visual Studio 2013 and earlier (e.g., <literal>'12.0'</literal>).
</para></listitem>
<listitem><para>
The major msvc version prefix (i.e., <literal>'XX.Y'</literal>) of the &cv-MSVC_TOOLSET_VERSION; specified
is greater than the msvc version selected (e.g., <literal>'99.0'</literal>).
</para></listitem>
<listitem><para>
A system folder for the corresponding &cv-MSVC_TOOLSET_VERSION; version is not found.
The requested toolset version does not appear to be installed.
</para></listitem>
</itemizedlist>
</para>
<para>
Toolset selection details:
<itemizedlist>
<listitem><para>
When &cv-MSVC_TOOLSET_VERSION; is not an SxS version number or a full toolset version number:
the first toolset version, ranked in descending order, that matches the &cv-MSVC_TOOLSET_VERSION;
prefix is selected.
</para></listitem>
<listitem><para>
When &cv-MSVC_TOOLSET_VERSION; is specified using the major msvc version prefix
(i.e., <literal>'XX.Y'</literal>) and the major msvc version is that of the latest release of
Visual Studio, the selected toolset version may not be the same as the default Visual C++ toolset version.
</para><para>
In the latest release of Visual Studio, the default Visual C++ toolset version is not necessarily the
toolset with the largest version number.
</para></listitem>
</itemizedlist>
</para>
<para>
Example 1 - A default Visual Studio build with a partial toolset version specified:
<example_commands>
env = Environment(MSVC_TOOLSET_VERSION='14.2')
</example_commands>
</para>
<para>
Example 2 - A default Visual Studio build with a partial toolset version specified:
<example_commands>
env = Environment(MSVC_TOOLSET_VERSION='14.29')
</example_commands>
</para>
<para>
Example 3 - A Visual Studio 2022 build with a full toolset version specified:
<example_commands>
env = Environment(MSVC_VERSION='14.3', MSVC_TOOLSET_VERSION='14.29.30133')
</example_commands>
</para>
<para>
Example 4 - A Visual Studio 2022 build with an SxS toolset version specified:
<example_commands>
env = Environment(MSVC_VERSION='14.3', MSVC_TOOLSET_VERSION='14.29.16.11')
</example_commands>
</para>
<para>
Important usage details:
<itemizedlist>
<listitem><para>
&cv-MSVC_TOOLSET_VERSION; must be passed as an argument to the &f-link-Environment;
constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
loaded via the default tools list or via a tools list passed to the
&f-link-Environment; constructor.
Otherwise, &cv-MSVC_TOOLSET_VERSION; must be set before the first msvc tool is
loaded into the environment.
</para></listitem>
<listitem><para>
<emphasis>
The existence of the toolset host architecture and target architecture folders are not verified
when &cv-MSVC_TOOLSET_VERSION; is specified which could result in build failures.
</emphasis>
The burden is on the user to ensure the requisite toolset target architecture build tools are installed.
</para></listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSVC_USE_SCRIPT">
<term>
<envar>MSVC_USE_SCRIPT</envar>
</term>
<listitem><para>
Use a batch script to set up the Microsoft Visual C++ compiler.
</para>
<para>
If set to the name of a Visual Studio <filename>.bat</filename> file
(e.g. <filename>vcvars.bat</filename>),
&SCons; will run that batch file instead of the auto-detected one,
and extract the relevant variables from the result (typically
<envar>%INCLUDE%</envar>,
<envar>%LIB%</envar>, and
<envar>%PATH%</envar>) for supplying to the build.
This can be useful to force the use of a compiler version that
&SCons; does not detect.
&cv-link-MSVC_USE_SCRIPT_ARGS; provides arguments passed to this script.
</para>
<para>
Setting
&cv-MSVC_USE_SCRIPT; to <constant>None</constant> bypasses the
Visual Studio autodetection entirely;
use this if you are running SCons in a Visual Studio <command>cmd</command>
window and importing the shell's environment variables - that
is, if you are sure everything is set correctly already and
you don't want &SCons; to change anything.
</para>
<para>
&cv-MSVC_USE_SCRIPT; ignores &cv-link-MSVC_VERSION; and &cv-link-TARGET_ARCH;.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSVC_USE_SCRIPT_ARGS">
<term>
<envar>MSVC_USE_SCRIPT_ARGS</envar>
</term>
<listitem><para>
Provides arguments passed to the script &cv-link-MSVC_USE_SCRIPT;.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSVC_USE_SETTINGS">
<term>
<envar>MSVC_USE_SETTINGS</envar>
</term>
<listitem><para>
Use a dictionary to set up the Microsoft Visual C++ compiler.
</para>
<para>
&cv-MSVC_USE_SETTINGS; is ignored when &cv-link-MSVC_USE_SCRIPT; is defined
and/or when &cv-MSVC_USE_SETTINGS; is set to <constant>None</constant>.
</para>
<para>
The dictionary is used to populate the environment with the relevant variables
(typically <envar>%INCLUDE%</envar>, <envar>%LIB%</envar>, and <envar>%PATH%</envar>)
for supplying to the build. This can be useful to force the use of a compiler environment
that &SCons; does not configure correctly. This is an alternative to manually configuring
the environment when bypassing Visual Studio autodetection entirely by setting
&cv-link-MSVC_USE_SCRIPT; to <constant>None</constant>.
</para>
<para>
Here is an example of configuring a build environment using the Microsoft Visual C/C++ compiler
included in the Microsoft SDK on a 64-bit host and building for a 64-bit architecture:
<programlisting>
# Microsoft SDK 6.0 (MSVC 8.0): 64-bit host and 64-bit target
msvc_use_settings = {
"PATH": [
"C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\VC\\Bin\\x64",
"C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Bin\\x64",
"C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Bin",
"C:\\Windows\\Microsoft.NET\\Framework\\v2.0.50727",
"C:\\Windows\\system32",
"C:\\Windows",
"C:\\Windows\\System32\\Wbem",
"C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\"
],
"INCLUDE": [
"C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\VC\\Include",
"C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\VC\\Include\\Sys",
"C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Include",
"C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Include\\gl",
],
"LIB": [
"C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\VC\\Lib\\x64",
"C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Lib\\x64",
],
"LIBPATH": [],
"VSCMD_ARG_app_plat": [],
"VCINSTALLDIR": [],
"VCToolsInstallDir": []
}
# Specifying MSVC_VERSION is recommended
env = Environment(MSVC_VERSION='8.0', MSVC_USE_SETTINGS=msvc_use_settings)
</programlisting>
</para>
<para>
Important usage details:
<itemizedlist>
<listitem><para>
&cv-MSVC_USE_SETTINGS; must be passed as an argument to the &f-link-Environment;
constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
loaded via the default tools list or via a tools list passed to the
&f-link-Environment; constructor.
Otherwise, &cv-MSVC_USE_SETTINGS; must be set before the first msvc tool is
loaded into the environment.
</para></listitem>
<listitem><para>
<emphasis>
The dictionary content requirements are based on the internal msvc implementation and
therefore may change at any time.
</emphasis>
The burden is on the user to ensure the dictionary contents are minimally sufficient to
ensure successful builds.
</para></listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSVC_UWP_APP">
<term>
<envar>MSVC_UWP_APP</envar>
</term>
<listitem><para>
Build with the Universal Windows Platform (UWP) application Visual C++ libraries.
</para>
<para>
The valid values for &cv-MSVC_UWP_APP; are: <literal>True</literal>,
<literal>'1'</literal>, <literal>False</literal>, <literal>'0'</literal>,
or <literal>None</literal>.
</para>
<para>
When &cv-MSVC_UWP_APP; is enabled (i.e., <literal>True</literal> or
<literal>'1'</literal>), the Visual C++ environment will be set up to point
to the Windows Store compatible libraries and Visual C++ runtimes. In doing so,
any libraries that are built will be able to be used in a UWP App and published
to the Windows Store.
<!-- This flag will only have an effect with Visual Studio 2015 or later. -->
<!-- This variable must be passed as an argument to the Environment()
constructor; setting it later has no effect. -->
</para>
<para>
An exception is raised when any of the following conditions are satisfied:
<itemizedlist>
<listitem><para>
&cv-MSVC_UWP_APP; is enabled for Visual Studio 2013 and earlier.
</para></listitem>
<listitem><para>
&cv-MSVC_UWP_APP; is enabled and a UWP argument is specified in
&cv-link-MSVC_SCRIPT_ARGS;. Multiple UWP declarations via &cv-MSVC_UWP_APP;
and &cv-link-MSVC_SCRIPT_ARGS; are not allowed.
</para></listitem>
</itemizedlist>
</para>
<para>
Example - A Visual Studio 2022 build for the Universal Windows Platform:
<example_commands>
env = Environment(MSVC_VERSION='14.3', MSVC_UWP_APP=True)
</example_commands>
</para>
<para>
Important usage details:
<itemizedlist>
<listitem><para>
&cv-MSVC_UWP_APP; must be passed as an argument to the &f-link-Environment;
constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
loaded via the default tools list or via a tools list passed to the
&f-link-Environment; constructor.
Otherwise, &cv-MSVC_UWP_APP; must be set before the first msvc tool is
loaded into the environment.
</para></listitem>
<listitem><para>
<emphasis>
The existence of the UWP libraries is not verified when &cv-MSVC_UWP_APP; is enabled
which could result in build failures.
</emphasis>
The burden is on the user to ensure the requisite UWP libraries are installed.
</para></listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSVC_VERSION">
<term>
<envar>MSVC_VERSION</envar>
</term>
<listitem><para>
Sets the preferred version of Microsoft Visual C/C++ to use.
</para>
<para>
If &cv-MSVC_VERSION; 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.
</para>
<para>
&cv-MSVC_VERSION; must be passed as an argument to the &f-link-Environment;
constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
loaded via the default tools list or via a tools list passed to the
&f-link-Environment; constructor.
Otherwise, &cv-MSVC_VERSION; must be set before the first msvc tool is
loaded into the environment.
</para>
<para>
Valid values for Windows are
<literal>14.3</literal>,
<literal>14.2</literal>,
<literal>14.1</literal>,
<literal>14.1Exp</literal>,
<literal>14.0</literal>,
<literal>14.0Exp</literal>,
<literal>12.0</literal>,
<literal>12.0Exp</literal>,
<literal>11.0</literal>,
<literal>11.0Exp</literal>,
<literal>10.0</literal>,
<literal>10.0Exp</literal>,
<literal>9.0</literal>,
<literal>9.0Exp</literal>,
<literal>8.0</literal>,
<literal>8.0Exp</literal>,
<literal>7.1</literal>,
<literal>7.0</literal>,
and <literal>6.0</literal>.
Versions ending in <literal>Exp</literal> refer to "Express" or
"Express for Desktop" editions.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSVS">
<term>
<envar>MSVS</envar>
</term>
<listitem><para>
When the Microsoft Visual Studio tools are initialized,
they set up this dictionary with the following keys:
</para>
<variablelist>
<varlistentry>
<term>VERSION</term> <listitem>
<para>the version of MSVS being used (can be set via
&cv-link-MSVS_VERSION;)</para>
</listitem>
</varlistentry> <varlistentry>
<term>VERSIONS</term> <listitem>
<para>the available versions of MSVS installed</para>
</listitem>
</varlistentry> <varlistentry>
<term>VCINSTALLDIR</term> <listitem>
<para>installed directory of Visual C++</para>
</listitem>
</varlistentry> <varlistentry>
<term>VSINSTALLDIR</term> <listitem>
<para>installed directory of Visual Studio</para>
</listitem>
</varlistentry> <varlistentry>
<term>FRAMEWORKDIR</term> <listitem>
<para>installed directory of the .NET framework</para>
</listitem>
</varlistentry> <varlistentry>
<term>FRAMEWORKVERSIONS</term> <listitem>
<para>
list of installed versions of the .NET framework,
sorted latest to oldest.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>FRAMEWORKVERSION</term>
<listitem>
<para>latest installed version of the .NET framework</para>
</listitem>
</varlistentry>
<varlistentry>
<term>FRAMEWORKSDKDIR</term>
<listitem>
<para>installed location of the .NET SDK.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PLATFORMSDKDIR</term>
<listitem>
<para>installed location of the Platform SDK.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PLATFORMSDK_MODULES</term>
<listitem>
<para>
dictionary of installed Platform SDK modules, where the
dictionary keys are keywords for the various modules,
and the values are 2-tuples where the first is the
release date, and the second is the version number.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>If a value is not set, it was not available in the registry.</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSVS_ARCH">
<term>
<envar>MSVS_ARCH</envar>
</term>
<listitem><para>Sets the architecture for which the generated project(s) should build.</para>
<para>
The default value is <literal>x86</literal>.
<literal>amd64</literal> is also supported by &SCons; for
most Visual Studio versions. Since Visual Studio 2015
<literal>arm</literal> is supported, and since Visual Studio
2017 <literal>arm64</literal> is supported.
Trying to set &cv-MSVS_ARCH;
to an architecture that's not supported for a given Visual
Studio version will generate an error.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSVS_PROJECT_GUID">
<term>
<envar>MSVS_PROJECT_GUID</envar>
</term>
<listitem><para>
The string placed in a generated
Microsoft Visual Studio project file as the value of the
<literal>ProjectGUID</literal> attribute. There is no default
value. If not
defined, a new GUID is generated.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSVS_SCC_AUX_PATH">
<term>
<envar>MSVS_SCC_AUX_PATH</envar>
</term>
<listitem><para>
The path name placed in a generated
Microsoft Visual Studio project file as the value of the
<literal>SccAuxPath</literal> attribute if the
<envar>MSVS_SCC_PROVIDER</envar> construction variable is
also set. There is
no default value.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSVS_SCC_CONNECTION_ROOT">
<term>
<envar>MSVS_SCC_CONNECTION_ROOT</envar>
</term>
<listitem><para>
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 <literal>SccLocalPath</literal>
attribute of the project file and as the values of the
<literal>SccProjectFilePathRelativizedFromConnection[i]</literal>
(where [i] ranges from 0 to the number of projects in the solution)
attributes of the <literal>GlobalSection(SourceCodeControl)</literal>
section of the Microsoft Visual Studio solution file. Similarly
the relative solution file path is placed as the values of the
<literal>SccLocalPath[i]</literal> (where [i] ranges from 0
to the number of projects in the solution) attributes of the
<literal>GlobalSection(SourceCodeControl)</literal> section of
the Microsoft Visual Studio solution file. This is used only if
the <envar>MSVS_SCC_PROVIDER</envar> construction variable is
also set. The default value is the current working directory.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSVS_SCC_PROJECT_NAME">
<term>
<envar>MSVS_SCC_PROJECT_NAME</envar>
</term>
<listitem><para>
The project name placed in a generated Microsoft
Visual Studio project file as the value of the
<literal>SccProjectName</literal> attribute if the
<envar>MSVS_SCC_PROVIDER</envar> construction variable
is also set. In this case the string is also placed in
the <literal>SccProjectName0</literal> attribute of the
<literal>GlobalSection(SourceCodeControl)</literal> section
of the Microsoft Visual Studio solution file. There is no
default value.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSVS_SCC_PROVIDER">
<term>
<envar>MSVS_SCC_PROVIDER</envar>
</term>
<listitem><para>
The string placed in a generated Microsoft
Visual Studio project file as the value of the
<literal>SccProvider</literal> attribute. The string is
also placed in the <literal>SccProvider0</literal> attribute
of the <literal>GlobalSection(SourceCodeControl)</literal>
section of the Microsoft Visual Studio solution file. There
is no default value.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSVS_VERSION">
<term>
<envar>MSVS_VERSION</envar>
</term>
<listitem><para>Sets the preferred version of Microsoft Visual Studio to use.</para>
<para>
If &cv-MSVS_VERSION; 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, it will prefer version 7. You can override this by
specifying the <envar>MSVS_VERSION</envar> variable in the
Environment initialization, setting it to the appropriate
version ('6.0' or '7.0', for example). If the specified
version isn't installed, tool initialization will fail.
</para>
<para>
This is obsolete: use &cv-MSVC_VERSION; instead. If
&cv-MSVS_VERSION; is set and &cv-MSVC_VERSION; is
not, &cv-MSVC_VERSION; will be set automatically to
&cv-MSVS_VERSION;. If both are set to different values,
scons will raise an error.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSVSBUILDCOM">
<term>
<envar>MSVSBUILDCOM</envar>
</term>
<listitem><para>
The build command line placed in a generated Microsoft Visual
Studio project file. The default is to have Visual Studio
invoke SCons with any specified build targets.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSVSCLEANCOM">
<term>
<envar>MSVSCLEANCOM</envar>
</term>
<listitem><para>
The clean command line placed in a generated Microsoft Visual
Studio project file. The default is to have Visual Studio
invoke SCons with the -c option to remove any specified
targets.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSVSENCODING">
<term>
<envar>MSVSENCODING</envar>
</term>
<listitem><para>
The encoding string placed in a generated Microsoft
Visual Studio project file. The default is encoding
<literal>Windows-1252</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSVSPROJECTCOM">
<term>
<envar>MSVSPROJECTCOM</envar>
</term>
<listitem><para>The action used to generate Microsoft Visual Studio project files.</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSVSPROJECTSUFFIX">
<term>
<envar>MSVSPROJECTSUFFIX</envar>
</term>
<listitem><para>
The suffix used for Microsoft Visual Studio project (DSP)
files. The default value is <filename>.vcproj</filename>
when using Visual Studio version 7.x (.NET) or later version,
and <filename>.dsp</filename> when using earlier versions of
Visual Studio.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSVSREBUILDCOM">
<term>
<envar>MSVSREBUILDCOM</envar>
</term>
<listitem><para>
The rebuild command line placed in a generated Microsoft
Visual Studio project file. The default is to have Visual
Studio invoke SCons with any specified rebuild targets.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSVSSCONS">
<term>
<envar>MSVSSCONS</envar>
</term>
<listitem><para>
The SCons used in generated Microsoft Visual Studio project
files. The default is the version of SCons being used to
generate the project file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSVSSCONSCOM">
<term>
<envar>MSVSSCONSCOM</envar>
</term>
<listitem><para>
The default SCons command used in generated Microsoft Visual
Studio project files.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSVSSCONSCRIPT">
<term>
<envar>MSVSSCONSCRIPT</envar>
</term>
<listitem><para>
The sconscript file (that is, &SConstruct; or &SConscript;
file) that will be invoked by Visual Studio project files
(through the &cv-link-MSVSSCONSCOM; variable). The default
is the same sconscript file that contains the call to
&b-MSVSProject; to build the project file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSVSSCONSFLAGS">
<term>
<envar>MSVSSCONSFLAGS</envar>
</term>
<listitem><para>
The SCons flags used in generated Microsoft Visual Studio project files.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSVSSOLUTIONCOM">
<term>
<envar>MSVSSOLUTIONCOM</envar>
</term>
<listitem><para>The action used to generate Microsoft Visual Studio solution files.</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MSVSSOLUTIONSUFFIX">
<term>
<envar>MSVSSOLUTIONSUFFIX</envar>
</term>
<listitem><para>
The suffix used for Microsoft Visual Studio solution (DSW)
files. The default value is <filename>.sln</filename>
when using Visual Studio version 7.x (.NET), and
<filename>.dsw</filename> when using earlier versions of
Visual Studio.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MT">
<term>
<envar>MT</envar>
</term>
<listitem><para>
The program used on Windows systems to embed manifests into DLLs and EXEs.
See also &cv-link-WINDOWS_EMBED_MANIFEST;.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MTEXECOM">
<term>
<envar>MTEXECOM</envar>
</term>
<listitem><para>
The Windows command line used to embed manifests into executables.
See also &cv-link-MTSHLIBCOM;.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MTFLAGS">
<term>
<envar>MTFLAGS</envar>
</term>
<listitem><para>
Flags passed to the &cv-link-MT; manifest embedding program (Windows only).
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MTSHLIBCOM">
<term>
<envar>MTSHLIBCOM</envar>
</term>
<listitem><para>
The Windows command line used to embed manifests into shared libraries (DLLs).
See also &cv-link-MTEXECOM;.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MWCW_VERSION">
<term>
<envar>MWCW_VERSION</envar>
</term>
<listitem><para>
The version number of the MetroWerks CodeWarrior C compiler
to be used.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-MWCW_VERSIONS">
<term>
<envar>MWCW_VERSIONS</envar>
</term>
<listitem><para>
A list of installed versions of the MetroWerks CodeWarrior C compiler
on this system.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-NAME">
<term>
<envar>NAME</envar>
</term>
<listitem><para>
Specfies the name of the project to package.
</para>
<para>See the &b-link-Package; builder.</para>
</listitem>
</varlistentry>
<varlistentry id="cv-NINJA_ALIAS_NAME">
<term>
<envar>NINJA_ALIAS_NAME</envar>
</term>
<listitem><para>
The name of the alias target which will cause &SCons; to create the &ninja; build file,
and then (optionally) run &ninja;.
The default value is <literal>generate-ninja</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-NINJA_CMD_ARGS">
<term>
<envar>NINJA_CMD_ARGS</envar>
</term>
<listitem><para>
A string which will pass arguments through SCons to the ninja command when scons executes ninja.
Has no effect if &cv-NINJA_DISABLE_AUTO_RUN; is set.
</para>
<para>
This value can also be passed on the command line:
</para>
<example_commands>
scons NINJA_CMD_ARGS=-v
or
scons NINJA_CMD_ARGS="-v -j 3"
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-NINJA_COMPDB_EXPAND">
<term>
<envar>NINJA_COMPDB_EXPAND</envar>
</term>
<listitem><para>
Boolean value to instruct &ninja; to expand the command line arguments normally put into
response files.
If true, prevents unexpanded lines in the compilation database like
<quote><literal>gcc @rsp_file</literal></quote> and instead yields expanded lines like
<quote><literal>gcc -c -o myfile.o myfile.c -Ia -DXYZ</literal></quote>.
</para>
<para>
Ninja's compdb tool added the <option>-x</option> flag in Ninja V1.9.0
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-NINJA_DEPFILE_PARSE_FORMAT">
<term>
<envar>NINJA_DEPFILE_PARSE_FORMAT</envar>
</term>
<listitem><para>
Determines the type of format ninja should expect when parsing header
include depfiles. Can be <option>msvc</option>, <option>gcc</option>, or <option>clang</option>.
The <option>msvc</option> option corresponds to <option>/showIncludes</option> format, and
<option>gcc</option> or <option>clang</option> correspond to <option>-MMD -MF</option>.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-NINJA_DIR">
<term>
<envar>NINJA_DIR</envar>
</term>
<listitem><para>
The <parameter>builddir</parameter> value.
Propagates directly into the generated &ninja; build file.
From Ninja's docs:
<quote>
A directory for some Ninja output files. ... (You can also store other build output in this
directory.)
</quote>
The default value is <filename>.ninja</filename>.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-NINJA_DISABLE_AUTO_RUN">
<term>
<envar>NINJA_DISABLE_AUTO_RUN</envar>
</term>
<listitem><para>
Boolean. Default: <constant>False</constant>.
If true, &SCons; will not run &ninja; automatically after creating the &ninja; build file.
</para>
<para>
If not explicitly set, this will be set to <constant>True</constant>
if <option>--disable_execute_ninja</option> or
<code>SetOption('disable_execute_ninja', True)</code> is seen.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-NINJA_ENV_VAR_CACHE">
<term>
<envar>NINJA_ENV_VAR_CACHE</envar>
</term>
<listitem><para>
A string that sets the environment for any environment variables that
differ between the OS environment and the &SCons; execution environment.
</para>
<para>
It will be compatible with the default shell of the operating system.
</para>
<para>
If not explicitly set, &SCons; will generate this dynamically from the
execution environment stored in the current &consenv;
(e.g. <literal>env['ENV']</literal>)
where those values differ from the existing shell..
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-NINJA_FILE_NAME">
<term>
<envar>NINJA_FILE_NAME</envar>
</term>
<listitem><para>
The filename for the generated Ninja build file.
The default is <filename>ninja.build</filename>.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-NINJA_FORCE_SCONS_BUILD">
<term>
<envar>NINJA_FORCE_SCONS_BUILD</envar>
</term>
<listitem><para>
If true, causes the build nodes to callback to scons instead of using
&ninja; to build them. This is intended to be passed to the environment on the builder invocation.
It is useful if you have a build node which does something which is not easily translated into &ninja;.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-NINJA_GENERATED_SOURCE_ALIAS_NAME">
<term>
<envar>NINJA_GENERATED_SOURCE_ALIAS_NAME</envar>
</term>
<listitem><para>
A string matching the name of a user defined alias which represents a list of all generated sources.
This will prevent the auto-detection of generated sources from &cv-NINJA_GENERATED_SOURCE_SUFFIXES;.
Then all other source files will be made to depend on this in the &ninja; build file, forcing the
generated sources to be built first.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-NINJA_GENERATED_SOURCE_SUFFIXES">
<term>
<envar>NINJA_GENERATED_SOURCE_SUFFIXES</envar>
</term>
<listitem><para>
The list of source file suffixes which are generated by &SCons; build steps.
All source files which match these suffixes will be added to the _generated_sources alias in the output
&ninja; build file.
Then all other source files will be made to depend on this in the &ninja; build file, forcing the
generated sources to be built first.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-NINJA_MSVC_DEPS_PREFIX">
<term>
<envar>NINJA_MSVC_DEPS_PREFIX</envar>
</term>
<listitem><para>
The <parameter>msvc_deps_prefix</parameter> string.
Propagates directly into the generated &ninja; build file.
From Ninja's docs:
<quote>defines the string which should be stripped from msvc's <option>/showIncludes</option> output</quote>
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-NINJA_POOL">
<term>
<envar>NINJA_POOL</envar>
</term>
<listitem><para>
Set the <parameter>ninja_pool</parameter> for this or all targets in scope for this env var.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-NINJA_REGENERATE_DEPS">
<term>
<envar>NINJA_REGENERATE_DEPS</envar>
</term>
<listitem><para>
A generator function used to create a &ninja; depfile which
includes all the files which would require
&SCons; to be invoked if they change.
Or a list of said files.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-_NINJA_REGENERATE_DEPS_FUNC">
<term>
<envar>_NINJA_REGENERATE_DEPS_FUNC</envar>
</term>
<listitem><para>
Internal value used to specify the function to call with argument env to generate the list of files
which if changed would require the &ninja; build file to be regenerated.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-NINJA_SCONS_DAEMON_KEEP_ALIVE">
<term>
<envar>NINJA_SCONS_DAEMON_KEEP_ALIVE</envar>
</term>
<listitem><para>
The number of seconds for the SCons deamon launched by ninja to stay alive.
(Default: 180000)
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-NINJA_SCONS_DAEMON_PORT">
<term>
<envar>NINJA_SCONS_DAEMON_PORT</envar>
</term>
<listitem><para>
The TCP/IP port for the SCons daemon to listen on.
<emphasis>NOTE: You cannot use a port already being listened to on your build machine.</emphasis>
(Default: random number between 10000,60000)
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-NINJA_SYNTAX">
<term>
<envar>NINJA_SYNTAX</envar>
</term>
<listitem><para>
The path to a custom <filename>ninja_syntax.py</filename> file which is used in generation.
The tool currently assumes you have &ninja; installed as a &Python; module and grabs the syntax file from that
installation if &cv-NINJA_SYNTAX; is not explicitly set.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-no_import_lib">
<term>
<envar>no_import_lib</envar>
</term>
<listitem><para>
When set to non-zero,
suppresses creation of a corresponding Windows static import lib by the
&b-link-SharedLibrary;
builder when used with
MinGW, Microsoft Visual Studio or Metrowerks.
This also suppresses creation
of an export (<filename>.exp</filename>) file
when using Microsoft Visual Studio.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-OBJPREFIX">
<term>
<envar>OBJPREFIX</envar>
</term>
<listitem><para>
The prefix used for (static) object file names.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-OBJSUFFIX">
<term>
<envar>OBJSUFFIX</envar>
</term>
<listitem><para>
The suffix used for (static) object file names.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-PACKAGEROOT">
<term>
<envar>PACKAGEROOT</envar>
</term>
<listitem><para>
Specifies the directory where all files in resulting archive will be
placed if applicable. The default value is <quote>&cv-NAME;-&cv-VERSION;</quote>.
</para>
<para>See the &b-link-Package; builder.</para>
</listitem>
</varlistentry>
<varlistentry id="cv-PACKAGETYPE">
<term>
<envar>PACKAGETYPE</envar>
</term>
<listitem><para>
Selects the package type to build when using the &b-link-Package;
builder. May be a string or list of strings. See the docuentation
for the builder for the currently supported types.
</para>
<para>
&cv-PACKAGETYPE; may be overridden with the <option>--package-type</option>
command line option.
</para>
<para>See the &b-link-Package; builder.</para>
</listitem>
</varlistentry>
<varlistentry id="cv-PACKAGEVERSION">
<term>
<envar>PACKAGEVERSION</envar>
</term>
<listitem><para>
The version of the package (not the underlying project).
This is currently only used by the rpm packager
and should reflect changes in the packaging,
not the underlying project code itself.
</para>
<para>See the &b-link-Package; builder.</para>
</listitem>
</varlistentry>
<varlistentry id="cv-PCH">
<term>
<envar>PCH</envar>
</term>
<listitem><para>
The Microsoft Visual C++ precompiled header that will be used when compiling
object files. This variable is ignored by tools other than Microsoft Visual C++.
When this variable is
defined SCons will add options to the compiler command line to
cause it to use the precompiled header, and will also set up the
dependencies for the PCH file.
Example:
</para>
<example_commands>
env['PCH'] = File('StdAfx.pch')
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-PCHCOM">
<term>
<envar>PCHCOM</envar>
</term>
<listitem><para>
The command line used by the
&b-link-PCH;
builder to generated a precompiled header.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-PCHCOMSTR">
<term>
<envar>PCHCOMSTR</envar>
</term>
<listitem><para>
The string displayed when generating a precompiled header.
If this is not set, then &cv-link-PCHCOM; (the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-PCHPDBFLAGS">
<term>
<envar>PCHPDBFLAGS</envar>
</term>
<listitem><para>
A construction variable that, when expanded,
adds the <option>/yD</option> flag to the command line
only if the &cv-link-PDB; construction variable is set.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-PCHSTOP">
<term>
<envar>PCHSTOP</envar>
</term>
<listitem><para>
This variable specifies how much of a source file is precompiled. This
variable is ignored by tools other than Microsoft Visual C++, or when
the PCH variable is not being used. When this variable is define it
must be a string that is the name of the header that
is included at the end of the precompiled portion of the source files, or
the empty string if the "#pragma hrdstop" construct is being used:
</para>
<example_commands>
env['PCHSTOP'] = 'StdAfx.h'
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-PDB">
<term>
<envar>PDB</envar>
</term>
<listitem><para>
The Microsoft Visual C++ PDB file that will store debugging information for
object files, shared libraries, and programs. This variable is ignored by
tools other than Microsoft Visual C++.
When this variable is
defined SCons will add options to the compiler and linker command line to
cause them to generate external debugging information, and will also set up the
dependencies for the PDB file.
Example:
</para>
<example_commands>
env['PDB'] = 'hello.pdb'
</example_commands>
<para>
The Visual C++ compiler switch that SCons uses by default
to generate PDB information is <option>/Z7</option>.
This works correctly with parallel (<option>-j</option>) builds
because it embeds the debug information in the intermediate object files,
as opposed to sharing a single PDB file between multiple object files.
This is also the only way to get debug information
embedded into a static library.
Using the <option>/Zi</option> instead may yield improved
link-time performance,
although parallel builds will no longer work.
You can generate PDB files with the <option>/Zi</option>
switch by overriding the default &cv-link-CCPDBFLAGS; variable;
see the entry for that variable for specific examples.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-PDFLATEX">
<term>
<envar>PDFLATEX</envar>
</term>
<listitem><para>
The &pdflatex; utility.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-PDFLATEXCOM">
<term>
<envar>PDFLATEXCOM</envar>
</term>
<listitem><para>
The command line used to call the &pdflatex; utility.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-PDFLATEXCOMSTR">
<term>
<envar>PDFLATEXCOMSTR</envar>
</term>
<listitem><para>
The string displayed when calling the &pdflatex; utility.
If this is not set, then &cv-link-PDFLATEXCOM; (the command line) is displayed.
</para>
<example_commands>
env = Environment(PDFLATEX;COMSTR = "Building $TARGET from LaTeX input $SOURCES")
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-PDFLATEXFLAGS">
<term>
<envar>PDFLATEXFLAGS</envar>
</term>
<listitem><para>
General options passed to the &pdflatex; utility.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-PDFPREFIX">
<term>
<envar>PDFPREFIX</envar>
</term>
<listitem><para>
The prefix used for PDF file names.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-PDFSUFFIX">
<term>
<envar>PDFSUFFIX</envar>
</term>
<listitem><para>
The suffix used for PDF file names.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-PDFTEX">
<term>
<envar>PDFTEX</envar>
</term>
<listitem><para>
The &pdftex; utility.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-PDFTEXCOM">
<term>
<envar>PDFTEXCOM</envar>
</term>
<listitem><para>
The command line used to call the &pdftex; utility.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-PDFTEXCOMSTR">
<term>
<envar>PDFTEXCOMSTR</envar>
</term>
<listitem><para>
The string displayed when calling the &pdftex; utility.
If this is not set, then &cv-link-PDFTEXCOM; (the command line) is displayed.
</para>
<example_commands>
env = Environment(PDFTEXCOMSTR = "Building $TARGET from TeX input $SOURCES")
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-PDFTEXFLAGS">
<term>
<envar>PDFTEXFLAGS</envar>
</term>
<listitem><para>
General options passed to the &pdftex; utility.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-PKGCHK">
<term>
<envar>PKGCHK</envar>
</term>
<listitem><para>
On Solaris systems,
the package-checking program that will
be used (along with &cv-PKGINFO;)
to look for installed versions of
the Sun PRO C++ compiler.
The default is
<filename>/usr/sbin/pgkchk</filename>.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-PKGINFO">
<term>
<envar>PKGINFO</envar>
</term>
<listitem><para>
On Solaris systems,
the package information program that will
be used (along with &cv-PKGCHK;)
to look for installed versions of
the Sun PRO C++ compiler.
The default is
<filename>pkginfo</filename>.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-PLATFORM">
<term>
<envar>PLATFORM</envar>
</term>
<listitem><para>
The name of the platform used to create this &consenv;.
&SCons; sets this when initializing the platform,
which by default is auto-detected
(see the <parameter>platform</parameter>
argument to &f-link-Environment;).
</para>
<example_commands>
env = Environment(tools=[])
if env['PLATFORM'] == 'cygwin':
Tool('mingw')(env)
else:
Tool('msvc')(env)
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-POAUTOINIT">
<term>
<envar>POAUTOINIT</envar>
</term>
<listitem><para>
The &cv-POAUTOINIT; variable, if set to <literal>True</literal> (on non-zero
numeric value), let the &t-link-msginit; tool to automatically initialize
<emphasis>missing</emphasis> <literal>PO</literal> files with
<command>msginit(1)</command>. This applies to both,
&b-link-POInit; and &b-link-POUpdate; builders (and others that use any of
them).
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-POCREATE_ALIAS">
<term>
<envar>POCREATE_ALIAS</envar>
</term>
<listitem><para>
Common alias for all <literal>PO</literal> files created with &b-POInit;
builder (default: <literal>'po-create'</literal>).
See &t-link-msginit; tool and &b-link-POInit; builder.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-POSUFFIX">
<term>
<envar>POSUFFIX</envar>
</term>
<listitem><para>
Suffix used for <literal>PO</literal> files (default: <literal>'.po'</literal>)
See &t-link-msginit; tool and &b-link-POInit; builder.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-POTDOMAIN">
<term>
<envar>POTDOMAIN</envar>
</term>
<listitem><para>
The &cv-POTDOMAIN; defines default domain, used to generate
<literal>POT</literal> filename as <filename>&cv-POTDOMAIN;.pot</filename> when
no <literal>POT</literal> file name is provided by the user. This applies to
&b-link-POTUpdate;, &b-link-POInit; and &b-link-POUpdate; builders (and
builders, that use them, e.g. &b-Translate;). Normally (if &cv-POTDOMAIN; is
not defined), the builders use <filename>messages.pot</filename> as default
<literal>POT</literal> file name.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-POTSUFFIX">
<term>
<envar>POTSUFFIX</envar>
</term>
<listitem><para>
Suffix used for PO Template files (default: <literal>'.pot'</literal>).
See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-POTUPDATE_ALIAS">
<term>
<envar>POTUPDATE_ALIAS</envar>
</term>
<listitem><para>
Name of the common phony target for all PO Templates created with
&b-link-POUpdate; (default: <literal>'pot-update'</literal>).
See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-POUPDATE_ALIAS">
<term>
<envar>POUPDATE_ALIAS</envar>
</term>
<listitem><para>
Common alias for all <literal>PO</literal> files being defined with
&b-link-POUpdate; builder (default: <literal>'po-update'</literal>).
See &t-link-msgmerge; tool and &b-link-POUpdate; builder.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-PRINT_CMD_LINE_FUNC">
<term>
<envar>PRINT_CMD_LINE_FUNC</envar>
</term>
<listitem><para>
A Python function used to print the command lines as they are executed
(assuming command printing is not disabled by the
<option>-q</option>
or
<option>-s</option>
options or their equivalents).
The function must accept four arguments:
<varname>s</varname>,
<varname>target</varname>,
<varname>source</varname> and
<varname>env</varname>.
<varname>s</varname>
is a string showing the command being executed,
<varname>target</varname>,
is the target being built (file node, list, or string name(s)),
<varname>source</varname>,
is the source(s) used (file node, list, or string name(s)),
and <varname>env</varname>
is the environment being used.
</para>
<para>
The function must do the printing itself.
The default implementation,
used if this variable is not set or is <constant>None</constant>,
is to just print the string, as in:
</para>
<example_commands>
def print_cmd_line(s, target, source, env):
sys.stdout.write(s + "\n")
</example_commands>
<para>
Here is an example of a more interesting function:
</para>
<example_commands>
def print_cmd_line(s, target, source, env):
sys.stdout.write(
"Building %s -&gt; %s...\n"
% (
' and '.join([str(x) for x in source]),
' and '.join([str(x) for x in target]),
)
)
env = Environment(PRINT_CMD_LINE_FUNC=print_cmd_line)
env.Program('foo', ['foo.c', 'bar.c'])
</example_commands>
<para>
This prints:
</para>
<screen>
...
scons: Building targets ...
Building bar.c -&gt; bar.o...
Building foo.c -&gt; foo.o...
Building foo.o and bar.o -&gt; foo...
scons: done building targets.
</screen>
<para>
Another example could be a function that logs the actual commands to a file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-PROGEMITTER">
<term>
<envar>PROGEMITTER</envar>
</term>
<listitem><para>
Contains the emitter specification for the
&b-link-Program; builder.
The manpage section "Builder Objects" contains
general information on specifying emitters.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-PROGPREFIX">
<term>
<envar>PROGPREFIX</envar>
</term>
<listitem><para>
The prefix used for executable file names.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-PROGSUFFIX">
<term>
<envar>PROGSUFFIX</envar>
</term>
<listitem><para>
The suffix used for executable file names.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-PSCOM">
<term>
<envar>PSCOM</envar>
</term>
<listitem><para>
The command line used to convert TeX DVI files into a PostScript file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-PSCOMSTR">
<term>
<envar>PSCOMSTR</envar>
</term>
<listitem><para>
The string displayed when a TeX DVI file
is converted into a PostScript file.
If this is not set, then &cv-link-PSCOM; (the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-PSPREFIX">
<term>
<envar>PSPREFIX</envar>
</term>
<listitem><para>
The prefix used for PostScript file names.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-PSSUFFIX">
<term>
<envar>PSSUFFIX</envar>
</term>
<listitem><para>
The prefix used for PostScript file names.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-QT_AUTOSCAN">
<term>
<envar>QT_AUTOSCAN</envar>
</term>
<listitem><para>
Turn off scanning for mocable files. Use the &b-link-Moc; Builder to explicitly
specify files to run <command>moc</command> on.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-QT_BINPATH">
<term>
<envar>QT_BINPATH</envar>
</term>
<listitem><para>
The path where the Qt binaries are installed.
The default value is '&cv-link-QTDIR;<filename>/bin</filename>'.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-QT_CPPPATH">
<term>
<envar>QT_CPPPATH</envar>
</term>
<listitem><para>
The path where the Qt header files are installed.
The default value is '&cv-link-QTDIR;/include'.
Note: If you set this variable to <constant>None</constant>,
the tool won't change the &cv-link-CPPPATH;
construction variable.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-QT_DEBUG">
<term>
<envar>QT_DEBUG</envar>
</term>
<listitem><para>
Prints lots of debugging information while scanning for moc files.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-QT_LIB">
<term>
<envar>QT_LIB</envar>
</term>
<listitem><para>
Default value is <literal>'qt'</literal>.
You may want to set this to <literal>'qt-mt'</literal>.
Note: If you set this variable to <constant>None</constant>,
the tool won't change the &cv-link-LIBS; variable.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-QT_LIBPATH">
<term>
<envar>QT_LIBPATH</envar>
</term>
<listitem><para>
The path where the Qt libraries are installed.
The default value is '&cv-link-QTDIR;<filename>/lib</filename>'.
Note: If you set this variable to <constant>None</constant>,
the tool won't change the &cv-link-LIBPATH;
construction variable.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-QT_MOC">
<term>
<envar>QT_MOC</envar>
</term>
<listitem><para>
Default value is '&cv-link-QT_BINPATH;<filename>/moc</filename>'.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-QT_MOCCXXPREFIX">
<term>
<envar>QT_MOCCXXPREFIX</envar>
</term>
<listitem><para>
Default value is <literal>''</literal>.
Prefix for <command>moc</command> output files when source is a C++ file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-QT_MOCCXXSUFFIX">
<term>
<envar>QT_MOCCXXSUFFIX</envar>
</term>
<listitem><para>
Default value is <literal>'.moc'</literal>.
Suffix for <command>moc</command> output files when source is a C++ file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-QT_MOCFROMCXXCOM">
<term>
<envar>QT_MOCFROMCXXCOM</envar>
</term>
<listitem><para>
Command to generate a moc file from a C++ file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-QT_MOCFROMCXXCOMSTR">
<term>
<envar>QT_MOCFROMCXXCOMSTR</envar>
</term>
<listitem><para>
The string displayed when generating a moc file from a C++ file.
If this is not set, then &cv-link-QT_MOCFROMCXXCOM; (the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-QT_MOCFROMCXXFLAGS">
<term>
<envar>QT_MOCFROMCXXFLAGS</envar>
</term>
<listitem><para>
Default value is <literal>'-i'</literal>.
These flags are passed to <command>moc</command> when moccing a C++ file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-QT_MOCFROMHCOM">
<term>
<envar>QT_MOCFROMHCOM</envar>
</term>
<listitem><para>
Command to generate a moc file from a header.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-QT_MOCFROMHCOMSTR">
<term>
<envar>QT_MOCFROMHCOMSTR</envar>
</term>
<listitem><para>
The string displayed when generating a moc file from a C++ file.
If this is not set, then &cv-link-QT_MOCFROMHCOM; (the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-QT_MOCFROMHFLAGS">
<term>
<envar>QT_MOCFROMHFLAGS</envar>
</term>
<listitem><para>
Default value is <literal>''</literal>. These flags are passed to <command>moc</command>
when moccing a header file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-QT_MOCHPREFIX">
<term>
<envar>QT_MOCHPREFIX</envar>
</term>
<listitem><para>
Default value is <literal>'moc_'</literal>.
Prefix for <command>moc</command> output files when source is a header.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-QT_MOCHSUFFIX">
<term>
<envar>QT_MOCHSUFFIX</envar>
</term>
<listitem><para>
Default value is '&cv-link-CXXFILESUFFIX;'.
Suffix for moc output files when source is a header.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-QT_UIC">
<term>
<envar>QT_UIC</envar>
</term>
<listitem><para>
Default value is '&cv-link-QT_BINPATH;<filename>/uic</filename>'.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-QT_UICCOM">
<term>
<envar>QT_UICCOM</envar>
</term>
<listitem><para>
Command to generate header files from <filename>.ui</filename> files.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-QT_UICCOMSTR">
<term>
<envar>QT_UICCOMSTR</envar>
</term>
<listitem><para>
The string displayed when generating header files from <filename>.ui</filename> files.
If this is not set, then &cv-link-QT_UICCOM; (the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-QT_UICDECLFLAGS">
<term>
<envar>QT_UICDECLFLAGS</envar>
</term>
<listitem><para>
Default value is ''. These flags are passed to <command>uic</command>
when creating a header file from a <filename>.ui</filename> file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-QT_UICDECLPREFIX">
<term>
<envar>QT_UICDECLPREFIX</envar>
</term>
<listitem><para>
Default value is <literal>''</literal>.
Prefix for <command>uic</command> generated header files.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-QT_UICDECLSUFFIX">
<term>
<envar>QT_UICDECLSUFFIX</envar>
</term>
<listitem><para>
Default value is <literal>'.h'</literal>.
Suffix for <command>uic</command> generated header files.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-QT_UICIMPLFLAGS">
<term>
<envar>QT_UICIMPLFLAGS</envar>
</term>
<listitem><para>
Default value is <literal>''</literal>.
These flags are passed to <command>uic</command> when creating a C++
file from a <filename>.ui</filename> file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-QT_UICIMPLPREFIX">
<term>
<envar>QT_UICIMPLPREFIX</envar>
</term>
<listitem><para>
Default value is <literal>'uic_'</literal>.
Prefix for uic generated implementation files.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-QT_UICIMPLSUFFIX">
<term>
<envar>QT_UICIMPLSUFFIX</envar>
</term>
<listitem><para>
Default value is '&cv-link-CXXFILESUFFIX;'. Suffix for uic generated implementation
files.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-QT_UISUFFIX">
<term>
<envar>QT_UISUFFIX</envar>
</term>
<listitem><para>
Default value is <literal>'.ui'</literal>.
Suffix of designer input files.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-QTDIR">
<term>
<envar>QTDIR</envar>
</term>
<listitem><para>
The path to the Qt installation to build against.
If not already set,
&t-link-qt; tool tries to obtain this from
<varname>os.environ</varname>;
if not found there, it tries to make a guess.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-RANLIB">
<term>
<envar>RANLIB</envar>
</term>
<listitem><para>
The archive indexer.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-RANLIBCOM">
<term>
<envar>RANLIBCOM</envar>
</term>
<listitem><para>
The command line used to index a static library archive.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-RANLIBCOMSTR">
<term>
<envar>RANLIBCOMSTR</envar>
</term>
<listitem><para>
The string displayed when a static library archive is indexed.
If this is not set, then &cv-link-RANLIBCOM; (the command line) is displayed.
</para>
<example_commands>
env = Environment(RANLIBCOMSTR = "Indexing $TARGET")
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-RANLIBFLAGS">
<term>
<envar>RANLIBFLAGS</envar>
</term>
<listitem><para>
General options passed to the archive indexer.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-RC">
<term>
<envar>RC</envar>
</term>
<listitem><para>
The resource compiler used to build
a Microsoft Visual C++ resource file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-RCCOM">
<term>
<envar>RCCOM</envar>
</term>
<listitem><para>
The command line used to build
a Microsoft Visual C++ resource file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-RCCOMSTR">
<term>
<envar>RCCOMSTR</envar>
</term>
<listitem><para>
The string displayed when invoking the resource compiler
to build a Microsoft Visual C++ resource file.
If this is not set, then &cv-link-RCCOM; (the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-RCFLAGS">
<term>
<envar>RCFLAGS</envar>
</term>
<listitem><para>
The flags passed to the resource compiler by the &b-link-RES; builder.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-RCINCFLAGS">
<term>
<envar>RCINCFLAGS</envar>
</term>
<listitem><para>
An automatically-generated construction variable
containing the command-line options
for specifying directories to be searched
by the resource compiler.
The value of &cv-RCINCFLAGS; is created
by respectively prepending and appending
&cv-link-RCINCPREFIX; and &cv-link-RCINCSUFFIX;
to the beginning and end
of each directory in &cv-link-CPPPATH;.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-RCINCPREFIX">
<term>
<envar>RCINCPREFIX</envar>
</term>
<listitem><para>
The prefix (flag) used to specify an include directory
on the resource compiler command line.
This will be prepended to the beginning of each directory
in the &cv-link-CPPPATH; construction variable
when the &cv-link-RCINCFLAGS; variable is expanded.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-RCINCSUFFIX">
<term>
<envar>RCINCSUFFIX</envar>
</term>
<listitem><para>
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 &cv-link-CPPPATH; construction variable
when the &cv-link-RCINCFLAGS; variable is expanded.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-RDirs">
<term>
<envar>RDirs</envar>
</term>
<listitem><para>
A function that converts a string into a list of Dir instances by
searching the repositories.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-REGSVR">
<term>
<envar>REGSVR</envar>
</term>
<listitem><para>
The program used on Windows systems
to register a newly-built DLL library
whenever the &b-link-SharedLibrary; builder
is passed a keyword argument of <literal>register=True</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-REGSVRCOM">
<term>
<envar>REGSVRCOM</envar>
</term>
<listitem><para>
The command line used on Windows systems
to register a newly-built DLL library
whenever the &b-link-SharedLibrary; builder
is passed a keyword argument of <literal>register=True</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-REGSVRCOMSTR">
<term>
<envar>REGSVRCOMSTR</envar>
</term>
<listitem><para>
The string displayed when registering a newly-built DLL file.
If this is not set, then &cv-link-REGSVRCOM; (the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-REGSVRFLAGS">
<term>
<envar>REGSVRFLAGS</envar>
</term>
<listitem><para>
Flags passed to the DLL registration program
on Windows systems when a newly-built DLL library is registered.
By default,
this includes the <option>/s</option>
that prevents dialog boxes from popping up
and requiring user attention.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-RMIC">
<term>
<envar>RMIC</envar>
</term>
<listitem><para>
The Java RMI stub compiler.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-RMICCOM">
<term>
<envar>RMICCOM</envar>
</term>
<listitem><para>
The command line used to compile stub
and skeleton class files
from Java classes that contain RMI implementations.
Any options specified in the &cv-link-RMICFLAGS; construction variable
are included on this command line.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-RMICCOMSTR">
<term>
<envar>RMICCOMSTR</envar>
</term>
<listitem><para>
The string displayed when compiling
stub and skeleton class files
from Java classes that contain RMI implementations.
If this is not set, then &cv-link-RMICCOM; (the command line) is displayed.
</para>
<example_commands>
env = Environment(RMICCOMSTR = "Generating stub/skeleton class files $TARGETS from $SOURCES")
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-RMICFLAGS">
<term>
<envar>RMICFLAGS</envar>
</term>
<listitem><para>
General options passed to the Java RMI stub compiler.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-RPATH">
<term>
<envar>RPATH</envar>
</term>
<listitem><para>
A list of paths to search for shared libraries when running programs.
Currently only used in the GNU (gnulink),
IRIX (sgilink) and Sun (sunlink) linkers.
Ignored on platforms and toolchains that don't support it.
Note that the paths added to RPATH
are not transformed by
&scons;
in any way: if you want an absolute
path, you must make it absolute yourself.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-_RPATH">
<term>
<envar>_RPATH</envar>
</term>
<listitem><para>
An automatically-generated construction variable
containing the rpath flags to be used when linking
a program with shared libraries.
The value of &cv-_RPATH; is created
by respectively prepending &cv-RPATHPREFIX; and appending &cv-RPATHSUFFIX;
to the beginning and end
of each directory in &cv-RPATH;.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-RPATHPREFIX">
<term>
<envar>RPATHPREFIX</envar>
</term>
<listitem><para>
The prefix used to specify a directory to be searched for
shared libraries when running programs.
This will be prepended to the beginning of each directory
in the &cv-RPATH; construction variable
when the &cv-_RPATH; variable is automatically generated.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-RPATHSUFFIX">
<term>
<envar>RPATHSUFFIX</envar>
</term>
<listitem><para>
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 &cv-RPATH; construction variable
when the &cv-_RPATH; variable is automatically generated.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-RPCGEN">
<term>
<envar>RPCGEN</envar>
</term>
<listitem><para>
The RPC protocol compiler.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-RPCGENCLIENTFLAGS">
<term>
<envar>RPCGENCLIENTFLAGS</envar>
</term>
<listitem><para>
Options passed to the RPC protocol compiler
when generating client side stubs.
These are in addition to any flags specified in the
&cv-link-RPCGENFLAGS;
construction variable.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-RPCGENFLAGS">
<term>
<envar>RPCGENFLAGS</envar>
</term>
<listitem><para>
General options passed to the RPC protocol compiler.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-RPCGENHEADERFLAGS">
<term>
<envar>RPCGENHEADERFLAGS</envar>
</term>
<listitem><para>
Options passed to the RPC protocol compiler
when generating a header file.
These are in addition to any flags specified in the
&cv-link-RPCGENFLAGS;
construction variable.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-RPCGENSERVICEFLAGS">
<term>
<envar>RPCGENSERVICEFLAGS</envar>
</term>
<listitem><para>
Options passed to the RPC protocol compiler
when generating server side stubs.
These are in addition to any flags specified in the
&cv-link-RPCGENFLAGS;
construction variable.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-RPCGENXDRFLAGS">
<term>
<envar>RPCGENXDRFLAGS</envar>
</term>
<listitem><para>
Options passed to the RPC protocol compiler
when generating XDR routines.
These are in addition to any flags specified in the
&cv-link-RPCGENFLAGS;
construction variable.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SCANNERS">
<term>
<envar>SCANNERS</envar>
</term>
<listitem><para>
A list of the available implicit dependency scanners.
New file scanners may be added by
appending to this list,
although the more flexible approach
is to associate scanners
with a specific Builder.
See the manpage sections "Builder Objects"
and "Scanner Objects"
for more information.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SCONS_HOME">
<term>
<envar>SCONS_HOME</envar>
</term>
<listitem><para>
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 &cv-link-MSVSSCONS; command line executed from Microsoft
Visual Studio project files.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHCC">
<term>
<envar>SHCC</envar>
</term>
<listitem><para>
The C compiler used for generating shared-library objects.
See also &cv-link-CC; for compiling to static objects.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHCCCOM">
<term>
<envar>SHCCCOM</envar>
</term>
<listitem><para>
The command line used to compile a C source file
to a shared-library object file.
Any options specified in the &cv-link-SHCFLAGS;,
&cv-link-SHCCFLAGS; and
&cv-link-CPPFLAGS; construction variables
are included on this command line.
See also &cv-link-CCCOM; for compiling to static objects.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHCCCOMSTR">
<term>
<envar>SHCCCOMSTR</envar>
</term>
<listitem><para>
If set, the string displayed when a C source file
is compiled to a shared object file.
If not set, then &cv-link-SHCCCOM; (the command line) is displayed.
See also &cv-link-CCCOMSTR; for compiling to static objects.
</para>
<example_commands>
env = Environment(SHCCCOMSTR = "Compiling shared object $TARGET")
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-SHCCFLAGS">
<term>
<envar>SHCCFLAGS</envar>
</term>
<listitem><para>
Options that are passed to the C and C++ compilers
to generate shared-library objects.
See also &cv-link-CCFLAGS; for compiling to static objects.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHCFLAGS">
<term>
<envar>SHCFLAGS</envar>
</term>
<listitem><para>
Options that are passed to the C compiler (only; not C++)
to generate shared-library objects.
See also &cv-link-CFLAGS; for compiling to static objects.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHCXX">
<term>
<envar>SHCXX</envar>
</term>
<listitem><para>
The C++ compiler used for generating shared-library objects.
See also &cv-link-CXX; for compiling to static objects.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHCXXCOM">
<term>
<envar>SHCXXCOM</envar>
</term>
<listitem><para>
The command line used to compile a C++ source file
to a shared-library object file.
Any options specified in the &cv-link-SHCXXFLAGS; and
&cv-link-CPPFLAGS; construction variables
are included on this command line.
See also &cv-link-CXXCOM; for compiling to static objects.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHCXXCOMSTR">
<term>
<envar>SHCXXCOMSTR</envar>
</term>
<listitem><para>
If set, the string displayed when a C++ source file
is compiled to a shared object file.
If not set, then &cv-link-SHCXXCOM; (the command line) is displayed.
See also &cv-link-CXXCOMSTR; for compiling to static objects.
</para>
<example_commands>
env = Environment(SHCXXCOMSTR = "Compiling shared object $TARGET")
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-SHCXXFLAGS">
<term>
<envar>SHCXXFLAGS</envar>
</term>
<listitem><para>
Options that are passed to the C++ compiler
to generate shared-library objects.
See also &cv-link-CXXFLAGS; for compiling to static objects.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHDC">
<term>
<envar>SHDC</envar>
</term>
<listitem><para>
The name of the compiler to use when compiling D source
destined to be in a shared objects.
See also &cv-link-DC; for compiling to static objects.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHDCOM">
<term>
<envar>SHDCOM</envar>
</term>
<listitem><para>
The command line to use when compiling code to be part of shared objects.
See also &cv-link-DCOM; for compiling to static objects.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHDCOMSTR">
<term>
<envar>SHDCOMSTR</envar>
</term>
<listitem><para>
If set, the string displayed when a D source file
is compiled to a (shared) object file.
If not set, then &cv-link-SHDCOM; (the command line) is displayed.
See also &cv-link-DCOMSTR; for compiling to static objects.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHDLIBVERSIONFLAGS">
<term>
<envar>SHDLIBVERSIONFLAGS</envar>
</term>
<listitem><para>
Extra flags added to &cv-link-SHDLINKCOM; when building versioned
&b-link-SharedLibrary;. These flags are only used when &cv-link-SHLIBVERSION; is
set.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHDLINK">
<term>
<envar>SHDLINK</envar>
</term>
<listitem><para>
The linker to use when creating shared objects for code bases
include D sources.
See also &cv-link-DLINK; for linking static objects.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHDLINKCOM">
<term>
<envar>SHDLINKCOM</envar>
</term>
<listitem><para>
The command line to use when generating shared objects.
See also &cv-link-DLINKCOM; for linking static objects.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHDLINKFLAGS">
<term>
<envar>SHDLINKFLAGS</envar>
</term>
<listitem><para>
The list of flags to use when generating a shared object.
See also &cv-link-DLINKFLAGS; for linking static objects.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHELL">
<term>
<envar>SHELL</envar>
</term>
<listitem><para>
A string naming the shell program that will be passed to the
&cv-SPAWN;
function.
See the
&cv-SPAWN;
construction variable for more information.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHELL_ENV_GENERATORS">
<term>
<envar>SHELL_ENV_GENERATORS</envar>
</term>
<listitem><para>
Must be a list (or an iterable) containing functions where each function generates or
alters the environment dictionary which will be used
when executing the &cv-link-SPAWN; function. The functions will initially
be passed a reference of the current execution environment (e.g. env['ENV']),
and each called while iterating the list. Each function must return a dictionary
which will then be passed to the next function iterated. The return dictionary
should contain keys which represent the environment variables and their respective
values.
This primary purpose of this construction variable is to give the user the ability
to substitute execution environment variables based on env, targets, and sources.
If desired, the user can completely customize the execution environment for particular
targets.
</para>
<example_commands>
def custom_shell_env(env, target, source, shell_env):
"""customize shell_env if desired"""
if str(target[0]) == 'special_target':
shell_env['SPECIAL_VAR'] = env.subst('SOME_VAR', target=target, source=source)
return shell_env
env["SHELL_ENV_GENERATORS"] = [custom_shell_env]
</example_commands>
<para>
<varname>env</varname>
The SCons construction environment from which the
execution environment can be derived from.
</para>
<para>
<varname>target</varname>
The list of targets associated with this action.
</para>
<para>
<varname>source</varname>
The list of sources associated with this action.
</para>
<para>
<varname>shell_env</varname>
The current shell_env after iterating other SHELL_ENV_GENERATORS functions. This can be compared
to the passed env['ENV'] to detect any changes.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHF03">
<term>
<envar>SHF03</envar>
</term>
<listitem><para>
The Fortran 03 compiler used for generating shared-library objects.
You should normally set the &cv-link-SHFORTRAN; variable,
which specifies the default Fortran compiler
for all Fortran versions.
You only need to set &cv-link-SHF03; if you need to use a specific compiler
or compiler version for Fortran 03 files.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHF03COM">
<term>
<envar>SHF03COM</envar>
</term>
<listitem><para>
The command line used to compile a Fortran 03 source file
to a shared-library object file.
You only need to set &cv-link-SHF03COM; if you need to use a specific
command line for Fortran 03 files.
You should normally set the &cv-link-SHFORTRANCOM; variable,
which specifies the default command line
for all Fortran versions.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHF03COMSTR">
<term>
<envar>SHF03COMSTR</envar>
</term>
<listitem><para>
If set, the string displayed when a Fortran 03 source file
is compiled to a shared-library object file.
If not set, then &cv-link-SHF03COM; or &cv-link-SHFORTRANCOM;
(the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHF03FLAGS">
<term>
<envar>SHF03FLAGS</envar>
</term>
<listitem><para>
Options that are passed to the Fortran 03 compiler
to generated shared-library objects.
You only need to set &cv-link-SHF03FLAGS; if you need to define specific
user options for Fortran 03 files.
You should normally set the &cv-link-FORTRANCOMMONFLAGS; variable,
which specifies the user-specified options
passed to the default Fortran compiler
for all Fortran versions.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHF03PPCOM">
<term>
<envar>SHF03PPCOM</envar>
</term>
<listitem><para>
The command line used to compile a Fortran 03 source file to a
shared-library object file
after first running the file through the C preprocessor.
Any options specified in the &cv-link-SHF03FLAGS; and &cv-link-CPPFLAGS; construction variables
are included on this command line.
You only need to set &cv-link-SHF03PPCOM; if you need to use a specific
C-preprocessor command line for Fortran 03 files.
You should normally set the &cv-link-SHFORTRANPPCOM; variable,
which specifies the default C-preprocessor command line
for all Fortran versions.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHF03PPCOMSTR">
<term>
<envar>SHF03PPCOMSTR</envar>
</term>
<listitem><para>
If set, the string displayed when a Fortran 03 source file
is compiled to a shared-library object file
after first running the file through the C preprocessor.
If not set, then &cv-link-SHF03PPCOM; or &cv-link-SHFORTRANPPCOM;
(the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHF08">
<term>
<envar>SHF08</envar>
</term>
<listitem><para>
The Fortran 08 compiler used for generating shared-library objects.
You should normally set the &cv-link-SHFORTRAN; variable,
which specifies the default Fortran compiler
for all Fortran versions.
You only need to set &cv-link-SHF08; if you need to use a specific compiler
or compiler version for Fortran 08 files.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHF08COM">
<term>
<envar>SHF08COM</envar>
</term>
<listitem><para>
The command line used to compile a Fortran 08 source file
to a shared-library object file.
You only need to set &cv-link-SHF08COM; if you need to use a specific
command line for Fortran 08 files.
You should normally set the &cv-link-SHFORTRANCOM; variable,
which specifies the default command line
for all Fortran versions.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHF08COMSTR">
<term>
<envar>SHF08COMSTR</envar>
</term>
<listitem><para>
If set, the string displayed when a Fortran 08 source file
is compiled to a shared-library object file.
If not set, then &cv-link-SHF08COM; or &cv-link-SHFORTRANCOM;
(the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHF08FLAGS">
<term>
<envar>SHF08FLAGS</envar>
</term>
<listitem><para>
Options that are passed to the Fortran 08 compiler
to generated shared-library objects.
You only need to set &cv-link-SHF08FLAGS; if you need to define specific
user options for Fortran 08 files.
You should normally set the &cv-link-FORTRANCOMMONFLAGS; variable,
which specifies the user-specified options
passed to the default Fortran compiler
for all Fortran versions.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHF08PPCOM">
<term>
<envar>SHF08PPCOM</envar>
</term>
<listitem><para>
The command line used to compile a Fortran 08 source file to a
shared-library object file
after first running the file through the C preprocessor.
Any options specified in the &cv-link-SHF08FLAGS; and &cv-link-CPPFLAGS; construction variables
are included on this command line.
You only need to set &cv-link-SHF08PPCOM; if you need to use a specific
C-preprocessor command line for Fortran 08 files.
You should normally set the &cv-link-SHFORTRANPPCOM; variable,
which specifies the default C-preprocessor command line
for all Fortran versions.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHF08PPCOMSTR">
<term>
<envar>SHF08PPCOMSTR</envar>
</term>
<listitem><para>
If set, the string displayed when a Fortran 08 source file
is compiled to a shared-library object file
after first running the file through the C preprocessor.
If not set, then &cv-link-SHF08PPCOM; or &cv-link-SHFORTRANPPCOM;
(the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHF77">
<term>
<envar>SHF77</envar>
</term>
<listitem><para>
The Fortran 77 compiler used for generating shared-library objects.
You should normally set the &cv-link-SHFORTRAN; variable,
which specifies the default Fortran compiler
for all Fortran versions.
You only need to set &cv-link-SHF77; if you need to use a specific compiler
or compiler version for Fortran 77 files.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHF77COM">
<term>
<envar>SHF77COM</envar>
</term>
<listitem><para>
The command line used to compile a Fortran 77 source file
to a shared-library object file.
You only need to set &cv-link-SHF77COM; if you need to use a specific
command line for Fortran 77 files.
You should normally set the &cv-link-SHFORTRANCOM; variable,
which specifies the default command line
for all Fortran versions.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHF77COMSTR">
<term>
<envar>SHF77COMSTR</envar>
</term>
<listitem><para>
If set, the string displayed when a Fortran 77 source file
is compiled to a shared-library object file.
If not set, then &cv-link-SHF77COM; or &cv-link-SHFORTRANCOM;
(the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHF77FLAGS">
<term>
<envar>SHF77FLAGS</envar>
</term>
<listitem><para>
Options that are passed to the Fortran 77 compiler
to generated shared-library objects.
You only need to set &cv-link-SHF77FLAGS; if you need to define specific
user options for Fortran 77 files.
You should normally set the &cv-link-FORTRANCOMMONFLAGS; variable,
which specifies the user-specified options
passed to the default Fortran compiler
for all Fortran versions.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHF77PPCOM">
<term>
<envar>SHF77PPCOM</envar>
</term>
<listitem><para>
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 &cv-link-SHF77FLAGS; and &cv-link-CPPFLAGS; construction variables
are included on this command line.
You only need to set &cv-link-SHF77PPCOM; if you need to use a specific
C-preprocessor command line for Fortran 77 files.
You should normally set the &cv-link-SHFORTRANPPCOM; variable,
which specifies the default C-preprocessor command line
for all Fortran versions.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHF77PPCOMSTR">
<term>
<envar>SHF77PPCOMSTR</envar>
</term>
<listitem><para>
If set, 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 not set, then &cv-link-SHF77PPCOM; or &cv-link-SHFORTRANPPCOM;
(the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHF90">
<term>
<envar>SHF90</envar>
</term>
<listitem><para>
The Fortran 90 compiler used for generating shared-library objects.
You should normally set the &cv-link-SHFORTRAN; variable,
which specifies the default Fortran compiler
for all Fortran versions.
You only need to set &cv-link-SHF90; if you need to use a specific compiler
or compiler version for Fortran 90 files.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHF90COM">
<term>
<envar>SHF90COM</envar>
</term>
<listitem><para>
The command line used to compile a Fortran 90 source file
to a shared-library object file.
You only need to set &cv-link-SHF90COM; if you need to use a specific
command line for Fortran 90 files.
You should normally set the &cv-link-SHFORTRANCOM; variable,
which specifies the default command line
for all Fortran versions.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHF90COMSTR">
<term>
<envar>SHF90COMSTR</envar>
</term>
<listitem><para>
If set, the string displayed when a Fortran 90 source file
is compiled to a shared-library object file.
If not set, then &cv-link-SHF90COM; or &cv-link-SHFORTRANCOM;
(the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHF90FLAGS">
<term>
<envar>SHF90FLAGS</envar>
</term>
<listitem><para>
Options that are passed to the Fortran 90 compiler
to generated shared-library objects.
You only need to set &cv-link-SHF90FLAGS; if you need to define specific
user options for Fortran 90 files.
You should normally set the &cv-link-FORTRANCOMMONFLAGS; variable,
which specifies the user-specified options
passed to the default Fortran compiler
for all Fortran versions.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHF90PPCOM">
<term>
<envar>SHF90PPCOM</envar>
</term>
<listitem><para>
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 &cv-link-SHF90FLAGS; and &cv-link-CPPFLAGS; construction variables
are included on this command line.
You only need to set &cv-link-SHF90PPCOM; if you need to use a specific
C-preprocessor command line for Fortran 90 files.
You should normally set the &cv-link-SHFORTRANPPCOM; variable,
which specifies the default C-preprocessor command line
for all Fortran versions.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHF90PPCOMSTR">
<term>
<envar>SHF90PPCOMSTR</envar>
</term>
<listitem><para>
If set, 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 not set, then &cv-link-SHF90PPCOM; or &cv-link-SHFORTRANPPCOM;
(the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHF95">
<term>
<envar>SHF95</envar>
</term>
<listitem><para>
The Fortran 95 compiler used for generating shared-library objects.
You should normally set the &cv-link-SHFORTRAN; variable,
which specifies the default Fortran compiler
for all Fortran versions.
You only need to set &cv-link-SHF95; if you need to use a specific compiler
or compiler version for Fortran 95 files.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHF95COM">
<term>
<envar>SHF95COM</envar>
</term>
<listitem><para>
The command line used to compile a Fortran 95 source file
to a shared-library object file.
You only need to set &cv-link-SHF95COM; if you need to use a specific
command line for Fortran 95 files.
You should normally set the &cv-link-SHFORTRANCOM; variable,
which specifies the default command line
for all Fortran versions.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHF95COMSTR">
<term>
<envar>SHF95COMSTR</envar>
</term>
<listitem><para>
If set, the string displayed when a Fortran 95 source file
is compiled to a shared-library object file.
If not set, then &cv-link-SHF95COM; or &cv-link-SHFORTRANCOM;
(the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHF95FLAGS">
<term>
<envar>SHF95FLAGS</envar>
</term>
<listitem><para>
Options that are passed to the Fortran 95 compiler
to generated shared-library objects.
You only need to set &cv-link-SHF95FLAGS; if you need to define specific
user options for Fortran 95 files.
You should normally set the &cv-link-FORTRANCOMMONFLAGS; variable,
which specifies the user-specified options
passed to the default Fortran compiler
for all Fortran versions.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHF95PPCOM">
<term>
<envar>SHF95PPCOM</envar>
</term>
<listitem><para>
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 &cv-link-SHF95FLAGS; and &cv-link-CPPFLAGS; construction variables
are included on this command line.
You only need to set &cv-link-SHF95PPCOM; if you need to use a specific
C-preprocessor command line for Fortran 95 files.
You should normally set the &cv-link-SHFORTRANPPCOM; variable,
which specifies the default C-preprocessor command line
for all Fortran versions.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHF95PPCOMSTR">
<term>
<envar>SHF95PPCOMSTR</envar>
</term>
<listitem><para>
If set, 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 not set, then &cv-link-SHF95PPCOM; or &cv-link-SHFORTRANPPCOM;
(the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHFORTRAN">
<term>
<envar>SHFORTRAN</envar>
</term>
<listitem><para>
The default Fortran compiler used for generating shared-library objects.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHFORTRANCOM">
<term>
<envar>SHFORTRANCOM</envar>
</term>
<listitem><para>
The command line used to compile a Fortran source file
to a shared-library object file.
By default, any options specified
in the &cv-link-SHFORTRANFLAGS;,
&cv-link-_FORTRANMODFLAG;, and
&cv-link-_FORTRANINCFLAGS;
&consvars; are included on this command line.
See also &cv-link-FORTRANCOM;.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHFORTRANCOMSTR">
<term>
<envar>SHFORTRANCOMSTR</envar>
</term>
<listitem><para>
If set, the string displayed when a Fortran source file
is compiled to a shared-library object file.
If not set, then &cv-link-SHFORTRANCOM;
(the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHFORTRANFLAGS">
<term>
<envar>SHFORTRANFLAGS</envar>
</term>
<listitem><para>
Options that are passed to the Fortran compiler
to generate shared-library objects.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHFORTRANPPCOM">
<term>
<envar>SHFORTRANPPCOM</envar>
</term>
<listitem><para>
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.
By default, any options specified in the &cv-link-SHFORTRANFLAGS;,
&cv-link-CPPFLAGS;,
&cv-link-_CPPDEFFLAGS;,
&cv-link-_FORTRANMODFLAG;, and
&cv-link-_FORTRANINCFLAGS;
&consvars; are included on this command line.
See also &cv-link-SHFORTRANCOM;.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHFORTRANPPCOMSTR">
<term>
<envar>SHFORTRANPPCOMSTR</envar>
</term>
<listitem><para>
If set, 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 not set, then &cv-link-SHFORTRANPPCOM;
(the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHLIBEMITTER">
<term>
<envar>SHLIBEMITTER</envar>
</term>
<listitem><para>
Contains the emitter specification for the
&b-link-SharedLibrary; builder.
The manpage section "Builder Objects" contains
general information on specifying emitters.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHLIBNOVERSIONSYMLINKS">
<term>
<envar>SHLIBNOVERSIONSYMLINKS</envar>
</term>
<listitem><para>
Instructs the &b-link-SharedLibrary; builder to not create symlinks for versioned
shared libraries.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHLIBPREFIX">
<term>
<envar>SHLIBPREFIX</envar>
</term>
<listitem><para>
The prefix used for shared library file names.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-_SHLIBSONAME">
<term>
<envar>_SHLIBSONAME</envar>
</term>
<listitem><para>
A macro that automatically generates shared library's SONAME based on $TARGET,
$SHLIBVERSION and $SHLIBSUFFIX. Used by &b-link-SharedLibrary; builder when
the linker tool supports SONAME (e.g. &t-link-gnulink;).
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHLIBSUFFIX">
<term>
<envar>SHLIBSUFFIX</envar>
</term>
<listitem><para>
The suffix used for shared library file names.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHLIBVERSION">
<term>
<envar>SHLIBVERSION</envar>
</term>
<listitem><para>
When this &consvar; is defined, a versioned shared library
is created by the &b-link-SharedLibrary; builder. This activates the
&cv-link-_SHLIBVERSIONFLAGS; and thus modifies the &cv-link-SHLINKCOM; as
required, adds the version number to the library name, and creates the symlinks
that are needed. &cv-link-SHLIBVERSION; versions should exist as alpha-numeric,
decimal-delimited values as defined by the regular expression "\w+[\.\w+]*".
Example &cv-link-SHLIBVERSION; values include '1', '1.2.3', and '1.2.gitaa412c8b'.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-_SHLIBVERSIONFLAGS">
<term>
<envar>_SHLIBVERSIONFLAGS</envar>
</term>
<listitem><para>
This macro automatically introduces extra flags to &cv-link-SHLINKCOM; when
building versioned &b-link-SharedLibrary; (that is when &cv-link-SHLIBVERSION;
is set). <literal>_SHLIBVERSIONFLAGS</literal> usually adds &cv-link-SHLIBVERSIONFLAGS;
and some extra dynamically generated options (such as
<literal>-Wl,-soname=$_SHLIBSONAME</literal>. It is unused by "plain"
(unversioned) shared libraries.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHLIBVERSIONFLAGS">
<term>
<envar>SHLIBVERSIONFLAGS</envar>
</term>
<listitem><para>
Extra flags added to &cv-link-SHLINKCOM; when building versioned
&b-link-SharedLibrary;. These flags are only used when &cv-link-SHLIBVERSION; is
set.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHLINK">
<term>
<envar>SHLINK</envar>
</term>
<listitem><para>
The linker for programs that use shared libraries.
See also &cv-link-LINK; for linking static objects.
</para>
<para>
On POSIX systems (those using the &t-link-link; tool),
you should normally not change this value as it defaults
to a "smart" linker tool which selects a compiler
driver matching the type of source files in use.
So for example, if you set &cv-link-SHCXX; to a specific
compiler name, and are compiling C++ sources,
the smartlink function will automatically select the same compiler
for linking.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHLINKCOM">
<term>
<envar>SHLINKCOM</envar>
</term>
<listitem><para>
The command line used to link programs using shared libraries.
See also &cv-link-LINKCOM; for linking static objects.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHLINKCOMSTR">
<term>
<envar>SHLINKCOMSTR</envar>
</term>
<listitem><para>
The string displayed when programs using shared libraries are linked.
If this is not set, then &cv-link-SHLINKCOM; (the command line) is displayed.
See also &cv-link-LINKCOMSTR; for linking static objects.
</para>
<example_commands>
env = Environment(SHLINKCOMSTR = "Linking shared $TARGET")
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-SHLINKFLAGS">
<term>
<envar>SHLINKFLAGS</envar>
</term>
<listitem><para>
General user options passed to the linker for programs using shared libraries.
Note that this variable should
<emphasis>not</emphasis>
contain
<option>-l</option>
(or similar) options for linking with the libraries listed in &cv-link-LIBS;,
nor
<option>-L</option>
(or similar) include search path options
that scons generates automatically from &cv-link-LIBPATH;.
See
&cv-link-_LIBFLAGS;
above,
for the variable that expands to library-link options,
and
&cv-link-_LIBDIRFLAGS;
above,
for the variable that expands to library search path options.
See also &cv-link-LINKFLAGS; for linking static objects.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHOBJPREFIX">
<term>
<envar>SHOBJPREFIX</envar>
</term>
<listitem><para>
The prefix used for shared object file names.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SHOBJSUFFIX">
<term>
<envar>SHOBJSUFFIX</envar>
</term>
<listitem><para>
The suffix used for shared object file names.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SONAME">
<term>
<envar>SONAME</envar>
</term>
<listitem><para>
Variable used to hard-code SONAME for versioned shared library/loadable module.
<example_commands>
env.SharedLibrary('test', 'test.c', SHLIBVERSION='0.1.2', SONAME='libtest.so.2')
</example_commands>
The variable is used, for example, by &t-link-gnulink; linker tool.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SOURCE">
<term>
<envar>SOURCE</envar>
</term>
<listitem><para>
A reserved variable name
that may not be set or used in a construction environment.
(See the manpage section "Variable Substitution"
for more information).
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SOURCE_URL">
<term>
<envar>SOURCE_URL</envar>
</term>
<listitem><para>
The URL
(web address)
of the location from which the project was retrieved.
This is used to fill in the
<literal>Source:</literal>
field in the controlling information for Ipkg and RPM packages.
</para>
<para>See the &b-link-Package; builder.</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SOURCES">
<term>
<envar>SOURCES</envar>
</term>
<listitem><para>
A reserved variable name
that may not be set or used in a construction environment.
(See the manpage section "Variable Substitution"
for more information).
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SOVERSION">
<term>
<envar>SOVERSION</envar>
</term>
<listitem><para>
This will construct the <varname>SONAME</varname> using on the base library name
(<parameter>test</parameter> in the example below) and use specified <varname>SOVERSION</varname>
to create <varname>SONAME</varname>.
<example_commands>
env.SharedLibrary('test', 'test.c', SHLIBVERSION='0.1.2', SOVERSION='2')
</example_commands>
The variable is used, for example, by &t-link-gnulink; linker tool.
</para>
<para>
In the example above <varname>SONAME</varname> would be <filename>libtest.so.2</filename>
which would be a symlink and point to <filename>libtest.so.0.1.2</filename>
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SPAWN">
<term>
<envar>SPAWN</envar>
</term>
<listitem><para>
A command interpreter function that will be called to execute command line
strings. The function must accept five arguments:
</para>
<example_commands>
def spawn(shell, escape, cmd, args, env):
</example_commands>
<para>
<varname>shell</varname>
is a string naming the shell program to use,
<varname>escape</varname>
is a function that can be called to escape shell special characters in
the command line,
<varname>cmd</varname>
is the path to the command to be executed,
<varname>args</varname>
holds the arguments to the command and
<varname>env</varname>
is a dictionary of environment variables
defining the execution environment in which the command should be executed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-STATIC_AND_SHARED_OBJECTS_ARE_THE_SAME">
<term>
<envar>STATIC_AND_SHARED_OBJECTS_ARE_THE_SAME</envar>
</term>
<listitem><para>
When this variable is true, static objects and shared objects are assumed to be the same; that is, SCons does not check for linking static objects into a shared library.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SUBST_DICT">
<term>
<envar>SUBST_DICT</envar>
</term>
<listitem><para>
The dictionary used by the &b-link-Substfile; or &b-link-Textfile; builders
for substitution values.
It can be anything acceptable to the <function>dict()</function> constructor,
so in addition to a dictionary,
lists of tuples are also acceptable.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SUBSTFILEPREFIX">
<term>
<envar>SUBSTFILEPREFIX</envar>
</term>
<listitem><para>
The prefix used for &b-link-Substfile; file names,
an empty string by default.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SUBSTFILESUFFIX">
<term>
<envar>SUBSTFILESUFFIX</envar>
</term>
<listitem><para>
The suffix used for &b-link-Substfile; file names,
an empty string by default.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SUMMARY">
<term>
<envar>SUMMARY</envar>
</term>
<listitem><para>
A short summary of what the project is about.
This is used to fill in the
<literal>Summary:</literal>
field in the controlling information for Ipkg and RPM packages,
and as the
<literal>Description:</literal>
field in MSI packages.
</para>
<para>See the &b-link-Package; builder.</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SWIG">
<term>
<envar>SWIG</envar>
</term>
<listitem><para>
The name of the &swig; compiler to use.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SWIGCFILESUFFIX">
<term>
<envar>SWIGCFILESUFFIX</envar>
</term>
<listitem><para>
The suffix that will be used for intermediate C
source files generated by &swig;.
The default value is <literal>'_wrap$CFILESUFFIX'</literal> -
that is, the concatenation of the string
<literal>_wrap</literal>
and the current C suffix &cv-link-CFILESUFFIX;.
By default, this value is used whenever the
<option>-c++</option>
option is
<emphasis>not</emphasis>
specified as part of the
&cv-link-SWIGFLAGS;
construction variable.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SWIGCOM">
<term>
<envar>SWIGCOM</envar>
</term>
<listitem><para>
The command line used to call &swig;.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SWIGCOMSTR">
<term>
<envar>SWIGCOMSTR</envar>
</term>
<listitem><para>
The string displayed when calling &swig;.
If this is not set, then &cv-link-SWIGCOM; (the command line) is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SWIGCXXFILESUFFIX">
<term>
<envar>SWIGCXXFILESUFFIX</envar>
</term>
<listitem><para>
The suffix that will be used for intermediate C++
source files generated by &swig;.
The default value is <literal>'_wrap$CXXFILESUFFIX'</literal> -
that is, the concatenation of the string
<literal>_wrap</literal>
and the current C++ suffix &cv-link-CXXFILESUFFIX;.
By default, this value is used whenever the
<option>-c++</option>
option is specified as part of the
&cv-link-SWIGFLAGS;
construction variable.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SWIGDIRECTORSUFFIX">
<term>
<envar>SWIGDIRECTORSUFFIX</envar>
</term>
<listitem><para>
The suffix that will be used for intermediate C++ header
files generated by &swig;.
These are only generated for C++ code when the &swig; 'directors' feature is
turned on.
The default value is
<filename>_wrap.h</filename>.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SWIGFLAGS">
<term>
<envar>SWIGFLAGS</envar>
</term>
<listitem><para>
General options passed to &swig;.
This is where you should set the target language
(<option>-python</option>,
<option>-perl5</option>,
<option>-tcl</option>, etc.)
and whatever other options you want to specify to &swig;,
such as the <option>-c++</option> to generate C++ code
instead of C Code.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-_SWIGINCFLAGS">
<term>
<envar>_SWIGINCFLAGS</envar>
</term>
<listitem><para>
An automatically-generated construction variable
containing the &swig; command-line options
for specifying directories to be searched for included files.
The value of &cv-_SWIGINCFLAGS; is created
by respectively prepending and appending
&cv-SWIGINCPREFIX; and &cv-SWIGINCSUFFIX;
to the beginning and end
of each directory in &cv-SWIGPATH;.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SWIGINCPREFIX">
<term>
<envar>SWIGINCPREFIX</envar>
</term>
<listitem><para>
The prefix used to specify an include directory on the &swig; command line.
This will be prepended to the beginning of each directory
in the &cv-SWIGPATH; construction variable
when the &cv-_SWIGINCFLAGS; variable is automatically generated.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SWIGINCSUFFIX">
<term>
<envar>SWIGINCSUFFIX</envar>
</term>
<listitem><para>
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 &cv-SWIGPATH; construction variable
when the &cv-_SWIGINCFLAGS; variable is automatically generated.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SWIGOUTDIR">
<term>
<envar>SWIGOUTDIR</envar>
</term>
<listitem><para>
Specifies the output directory in which &swig;
should place generated language-specific files.
This will be used by SCons to identify
the files that will be generated by the &swig; call,
and translated into the
<literal>swig -outdir</literal> option on the command line.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-SWIGPATH">
<term>
<envar>SWIGPATH</envar>
</term>
<listitem><para>
The list of directories that &swig;
will search for included files.
&SCons;' SWIG implicit dependency scanner will search these
directories for include files. The default value is an empty list.
</para>
<para>
Don't explicitly put include directory
arguments in &cv-link-SWIGFLAGS;
the result will be non-portable
and the directories will not be searched by the dependency scanner.
Note: directory names in &cv-link-SWIGPATH;
will be looked-up relative to the SConscript
directory when they are used in a command.
To force
&scons;
to look-up a directory relative to the root of the source tree use
a top-relative path (<literal>#</literal>):
</para>
<example_commands>
env = Environment(SWIGPATH='#/include')
</example_commands>
<para>
The directory look-up can also be forced using the
&Dir;()
function:
</para>
<example_commands>
include = Dir('include')
env = Environment(SWIGPATH=include)
</example_commands>
<para>
The directory list will be added to command lines
through the automatically-generated
&cv-_SWIGINCFLAGS;
construction variable,
which is constructed by
respectively prepending and appending the values of the
&cv-SWIGINCPREFIX; and &cv-SWIGINCSUFFIX;
construction variables
to the beginning and end
of each directory in &cv-SWIGPATH;.
Any command lines you define that need
the SWIGPATH directory list should
include &cv-_SWIGINCFLAGS;:
</para>
<example_commands>
env = Environment(SWIGCOM="my_swig -o $TARGET $_SWIGINCFLAGS $SOURCES")
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-SWIGVERSION">
<term>
<envar>SWIGVERSION</envar>
</term>
<listitem><para>
The detected version string of the &swig; tool.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-TAR">
<term>
<envar>TAR</envar>
</term>
<listitem><para>
The tar archiver.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-TARCOM">
<term>
<envar>TARCOM</envar>
</term>
<listitem><para>
The command line used to call the tar archiver.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-TARCOMSTR">
<term>
<envar>TARCOMSTR</envar>
</term>
<listitem><para>
The string displayed when archiving files
using the tar archiver.
If this is not set, then &cv-link-TARCOM; (the command line) is displayed.
</para>
<example_commands>
env = Environment(TARCOMSTR = "Archiving $TARGET")
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-TARFLAGS">
<term>
<envar>TARFLAGS</envar>
</term>
<listitem><para>
General options passed to the tar archiver.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-TARGET">
<term>
<envar>TARGET</envar>
</term>
<listitem><para>
A reserved variable name
that may not be set or used in a construction environment.
(See the manpage section "Variable Substitution"
for more information).
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-TARGET_ARCH">
<term>
<envar>TARGET_ARCH</envar>
</term>
<listitem><para>
The name of the hardware architecture that objects
created using this &consenv; should target.
Can be set when creating a &consenv; by passing as a keyword
argument in the &f-link-Environment; call.
</para>
<para>
On the <literal>win32</literal> platform,
if the Microsoft Visual C++ compiler is available,
&t-link-msvc; tool setup is done using
&cv-link-HOST_ARCH; and &cv-TARGET_ARCH;.
If a value is not specified,
will be set to the same value as &cv-link-HOST_ARCH;.
Changing the value after the environment is initialized
will not cause the tool to be reinitialized.
Compiled objects will be in the target architecture if
the compilation system supports generating for that target.
The latest compiler which can fulfill the requirement will
be selected, unless a different version is directed by the
value of the &cv-link-MSVC_VERSION; &consvar;.
</para>
<para>
On the win32/msvc combination, valid target arch values are
<literal>x86</literal>,
<literal>arm</literal>,
<literal>i386</literal>
for 32-bit targets and
<literal>amd64</literal>,
<literal>arm64</literal>,
<literal>x86_64</literal>
and <literal>ia64</literal> (Itanium)
for 64-bit targets.
For example, if you want to compile 64-bit binaries, you would set
<literal>TARGET_ARCH='x86_64'</literal> when creating the &consenv;.
Note that not all target architectures are
supported for all Visual Studio / MSVC versions.
Check the relevant Microsoft documentation.
</para>
<para>
&cv-TARGET_ARCH; is not currently used by other compilation tools,
but the option is reserved to do so in future
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-TARGET_OS">
<term>
<envar>TARGET_OS</envar>
</term>
<listitem><para>
The name of the operating system that objects
created using this &consenv; should target.
Can be set when creating a &consenv; by passing as a keyword
argument in the &f-link-Environment; call;.
</para>
<para>
&cv-TARGET_OS; is not currently used by &SCons;
but the option is reserved to do so in future
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-TARGETS">
<term>
<envar>TARGETS</envar>
</term>
<listitem><para>
A reserved variable name
that may not be set or used in a construction environment.
(See the manpage section "Variable Substitution"
for more information).
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-TARSUFFIX">
<term>
<envar>TARSUFFIX</envar>
</term>
<listitem><para>
The suffix used for tar file names.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-TEMPFILE">
<term>
<envar>TEMPFILE</envar>
</term>
<listitem><para>
A callable object used to handle overly long command line strings,
since operations which call out to a shell will fail
if the line is longer than the shell can accept.
This tends to particularly impact linking.
The tempfile object stores the command line in a temporary
file in the appropriate format, and returns
an alternate command line so the invoked tool will make
use of the contents of the temporary file.
If you need to replace the default tempfile object,
the callable should take into account the settings of
&cv-link-MAXLINELENGTH;,
&cv-link-TEMPFILEPREFIX;,
&cv-link-TEMPFILESUFFIX;,
&cv-link-TEMPFILEARGJOIN;,
&cv-link-TEMPFILEDIR;
and
&cv-link-TEMPFILEARGESCFUNC;.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-TEMPFILEARGESCFUNC">
<term>
<envar>TEMPFILEARGESCFUNC</envar>
</term>
<listitem><para>
The default argument escape function is
<function>SCons.Subst.quote_spaces</function>.
If you need to apply extra operations on a command argument
(to fix Windows slashes, normalize paths, etc.)
before writing to the temporary file,
you can set the &cv-TEMPFILEARGESCFUNC; variable to a custom function.
Such a function takes a single string argument and returns
a new string with any modifications applied.
Example:
</para>
<example_commands>
import sys
import re
from SCons.Subst import quote_spaces
WINPATHSEP_RE = re.compile(r"\\([^\"'\\]|$)")
def tempfile_arg_esc_func(arg):
arg = quote_spaces(arg)
if sys.platform != "win32":
return arg
# GCC requires double Windows slashes, let's use UNIX separator
return WINPATHSEP_RE.sub(r"/\1", arg)
env["TEMPFILEARGESCFUNC"] = tempfile_arg_esc_func
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-TEMPFILEARGJOIN">
<term>
<envar>TEMPFILEARGJOIN</envar>
</term>
<listitem><para>
The string to use to join the arguments passed to
&cv-link-TEMPFILE; when the command line exceeds the limit set by
&cv-link-MAXLINELENGTH;.
The default value is a space.
However for MSVC, MSLINK the default is a line separator
as defined by <systemitem>os.linesep</systemitem>.
Note this value is used literally and not expanded by the subst logic.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-TEMPFILEDIR">
<term>
<envar>TEMPFILEDIR</envar>
</term>
<listitem><para>
The directory to create the long-lines temporary file in.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-TEMPFILEPREFIX">
<term>
<envar>TEMPFILEPREFIX</envar>
</term>
<listitem><para>
The prefix for the name of the temporary file used
to store command lines exceeding &cv-link-MAXLINELENGTH;.
The default prefix is <literal>'@'</literal>, which works for the Microsoft
and GNU toolchains on Windows.
Set this appropriately for other toolchains,
for example <literal>'-@'</literal> for the diab compiler
or <literal>'-via'</literal> for ARM toolchain.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-TEMPFILESUFFIX">
<term>
<envar>TEMPFILESUFFIX</envar>
</term>
<listitem><para>
The suffix for the name of the temporary file used
to store command lines exceeding &cv-link-MAXLINELENGTH;.
The suffix should include the dot ('.') if one is wanted as
it will not be added automatically.
The default is <filename>.lnk</filename>.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-TEX">
<term>
<envar>TEX</envar>
</term>
<listitem><para>
The TeX formatter and typesetter.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-TEXCOM">
<term>
<envar>TEXCOM</envar>
</term>
<listitem><para>
The command line used to call the TeX formatter and typesetter.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-TEXCOMSTR">
<term>
<envar>TEXCOMSTR</envar>
</term>
<listitem><para>
The string displayed when calling
the TeX formatter and typesetter.
If this is not set, then &cv-link-TEXCOM; (the command line) is displayed.
</para>
<example_commands>
env = Environment(TEXCOMSTR = "Building $TARGET from TeX input $SOURCES")
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-TEXFLAGS">
<term>
<envar>TEXFLAGS</envar>
</term>
<listitem><para>
General options passed to the TeX formatter and typesetter.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-TEXINPUTS">
<term>
<envar>TEXINPUTS</envar>
</term>
<listitem><para>
List of directories that the LaTeX program will search
for include directories.
The LaTeX implicit dependency scanner will search these
directories for \include and \import files.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-TEXTFILEPREFIX">
<term>
<envar>TEXTFILEPREFIX</envar>
</term>
<listitem><para>
The prefix used for &b-link-Textfile; file names,
an empty string by default.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-TEXTFILESUFFIX">
<term>
<envar>TEXTFILESUFFIX</envar>
</term>
<listitem><para>
The suffix used for &b-link-Textfile; file names;
<filename>.txt</filename> by default.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-TOOLS">
<term>
<envar>TOOLS</envar>
</term>
<listitem><para>
A list of the names of the Tool specifications
that are part of this construction environment.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-UNCHANGED_SOURCES">
<term>
<envar>UNCHANGED_SOURCES</envar>
</term>
<listitem><para>
A reserved variable name
that may not be set or used in a construction environment.
(See the manpage section "Variable Substitution"
for more information).
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-UNCHANGED_TARGETS">
<term>
<envar>UNCHANGED_TARGETS</envar>
</term>
<listitem><para>
A reserved variable name
that may not be set or used in a construction environment.
(See the manpage section "Variable Substitution"
for more information).
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-VENDOR">
<term>
<envar>VENDOR</envar>
</term>
<listitem><para>
The person or organization who supply the packaged software.
This is used to fill in the
<literal>Vendor:</literal>
field in the controlling information for RPM packages,
and the
<literal>Manufacturer:</literal>
field in the controlling information for MSI packages.
</para>
<para>See the &b-link-Package; builder.</para>
</listitem>
</varlistentry>
<varlistentry id="cv-VERSION">
<term>
<envar>VERSION</envar>
</term>
<listitem><para>
The version of the project, specified as a string.
</para>
<para>See the &b-link-Package; builder.</para>
</listitem>
</varlistentry>
<varlistentry id="cv-VSWHERE">
<term>
<envar>VSWHERE</envar>
</term>
<listitem><para>
Specify the location of <filename>vswhere.exe</filename>.
</para>
<para>
The <filename>vswhere.exe</filename> executable is distributed with Microsoft Visual Studio and Build
Tools since the 2017 edition, but is also available standalone.
It provides full information about installations of 2017 and later editions.
With the <option>-legacy</option> argument, <filename>vswhere.exe</filename> can detect installations of the 2010 through 2015
editions with limited data returned.
If <envar>VSWHERE</envar> is set, SCons will use that location.
</para>
<para>
Otherwise SCons will look in the following locations and set <envar>VSWHERE</envar> to the path of the first <filename>vswhere.exe</filename>
located.
</para>
<itemizedlist>
<listitem><para><literal>%ProgramFiles(x86)%\Microsoft Visual Studio\Installer</literal></para></listitem>
<listitem><para><literal>%ProgramFiles%\Microsoft Visual Studio\Installer</literal></para></listitem>
<listitem><para><literal>%ChocolateyInstall%\bin</literal></para></listitem>
</itemizedlist>
<para>
Note that <envar>VSWHERE</envar> must be set at the same time or prior to any of &t-link-msvc;, &t-link-msvs; , and/or &t-link-mslink; &f-link-Tool; being initialized.
Either set it as follows
<programlisting>
env = Environment(VSWHERE='c:/my/path/to/vswhere')
</programlisting>
or if your &consenv; is created specifying an empty tools list
(or a list of tools which omits all of default, msvs, msvc, and mslink),
and also before &f-link-env-Tool; is called to ininitialize any of those tools:
<programlisting>
env = Environment(tools=[])
env['VSWHERE'] = r'c:/my/vswhere/install/location/vswhere.exe'
env.Tool('msvc')
env.Tool('mslink')
env.Tool('msvs')
</programlisting>
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-WINDOWS_EMBED_MANIFEST">
<term>
<envar>WINDOWS_EMBED_MANIFEST</envar>
</term>
<listitem><para>
Set to <constant>True</constant> to embed the
compiler-generated manifest
(normally <literal>${TARGET}.manifest</literal>)
into all Windows executables and DLLs built with this environment,
as a resource during their link step.
This is done using &cv-link-MT; and &cv-link-MTEXECOM; and &cv-link-MTSHLIBCOM;.
See also &cv-link-WINDOWS_INSERT_MANIFEST;.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-WINDOWS_INSERT_DEF">
<term>
<envar>WINDOWS_INSERT_DEF</envar>
</term>
<listitem><para>
If set to true,
a library build of a Windows shared library
(<filename>.dll</filename> file)
will include a reference to the corresponding
module-definition file at the same time,
if a module-definition file
is not already listed as a build target.
The name of the module-definition file will
be constructed from the base name of the library
and the &consvars;
&cv-link-WINDOWSDEFSUFFIX; and
&cv-link-WINDOWSDEFPREFIX;.
The default is to not add a module-definition file.
The module-definition file is not created by this directive,
and must be supplied by the developer.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-WINDOWS_INSERT_MANIFEST">
<term>
<envar>WINDOWS_INSERT_MANIFEST</envar>
</term>
<listitem><para>
If set to true,
&scons;
will add the manifest file
generated by Microsoft Visual C++ 8.0 and later
to the target list so &SCons; will be aware they
were generated.
In the case of an executable, the manifest file name
is constructed using
&cv-link-WINDOWSPROGMANIFESTSUFFIX; and
&cv-link-WINDOWSPROGMANIFESTPREFIX;.
In the case of a shared library, the manifest file name
is constructed using
&cv-link-WINDOWSSHLIBMANIFESTSUFFIX; and
&cv-link-WINDOWSSHLIBMANIFESTPREFIX;.
See also &cv-link-WINDOWS_EMBED_MANIFEST;.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-WINDOWSDEFPREFIX">
<term>
<envar>WINDOWSDEFPREFIX</envar>
</term>
<listitem><para>
The prefix used for a Windows linker module-definition file name.
Defaults to empty.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-WINDOWSDEFSUFFIX">
<term>
<envar>WINDOWSDEFSUFFIX</envar>
</term>
<listitem><para>
The suffix used for a Windows linker module-definition file name.
Defaults to <filename>.def</filename>.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-WINDOWSEXPPREFIX">
<term>
<envar>WINDOWSEXPPREFIX</envar>
</term>
<listitem><para>
The prefix used for Windows linker exports file names.
Defaults to empty.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-WINDOWSEXPSUFFIX">
<term>
<envar>WINDOWSEXPSUFFIX</envar>
</term>
<listitem><para>
The suffix used for Windows linker exports file names.
Defaults to <filename>.exp</filename>.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-WINDOWSPROGMANIFESTPREFIX">
<term>
<envar>WINDOWSPROGMANIFESTPREFIX</envar>
</term>
<listitem><para>
The prefix used for executable program manifest files
generated by Microsoft Visual C/C++.
Defaults to empty.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-WINDOWSPROGMANIFESTSUFFIX">
<term>
<envar>WINDOWSPROGMANIFESTSUFFIX</envar>
</term>
<listitem><para>
The suffix used for executable program manifest files
generated by Microsoft Visual C/C++.
Defaults to <filename>.manifest</filename>.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-WINDOWSSHLIBMANIFESTPREFIX">
<term>
<envar>WINDOWSSHLIBMANIFESTPREFIX</envar>
</term>
<listitem><para>
The prefix used for shared library manifest files
generated by Microsoft Visual C/C++.
Defaults to empty.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-WINDOWSSHLIBMANIFESTSUFFIX">
<term>
<envar>WINDOWSSHLIBMANIFESTSUFFIX</envar>
</term>
<listitem><para>
The suffix used for shared library manifest files
generated by Microsoft Visual C/C++.
Defaults to <filename>.manifest</filename>.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-X_IPK_DEPENDS">
<term>
<envar>X_IPK_DEPENDS</envar>
</term>
<listitem><para>
This is used to fill in the
<literal>Depends:</literal>
field in the controlling information for Ipkg packages.
</para>
<para>See the &b-link-Package; builder.</para>
</listitem>
</varlistentry>
<varlistentry id="cv-X_IPK_DESCRIPTION">
<term>
<envar>X_IPK_DESCRIPTION</envar>
</term>
<listitem><para>
This is used to fill in the
<literal>Description:</literal>
field in the controlling information for Ipkg packages.
The default value is
<quote>&cv-SUMMARY;\n&cv-DESCRIPTION;</quote>
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-X_IPK_MAINTAINER">
<term>
<envar>X_IPK_MAINTAINER</envar>
</term>
<listitem><para>
This is used to fill in the
<literal>Maintainer:</literal>
field in the controlling information for Ipkg packages.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-X_IPK_PRIORITY">
<term>
<envar>X_IPK_PRIORITY</envar>
</term>
<listitem><para>
This is used to fill in the
<literal>Priority:</literal>
field in the controlling information for Ipkg packages.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-X_IPK_SECTION">
<term>
<envar>X_IPK_SECTION</envar>
</term>
<listitem><para>
This is used to fill in the
<literal>Section:</literal>
field in the controlling information for Ipkg packages.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-X_MSI_LANGUAGE">
<term>
<envar>X_MSI_LANGUAGE</envar>
</term>
<listitem><para>
This is used to fill in the
<literal>Language:</literal>
attribute in the controlling information for MSI packages.
</para>
<para>See the &b-link-Package; builder.</para>
</listitem>
</varlistentry>
<varlistentry id="cv-X_MSI_LICENSE_TEXT">
<term>
<envar>X_MSI_LICENSE_TEXT</envar>
</term>
<listitem><para>
The text of the software license in RTF format.
Carriage return characters will be
replaced with the RTF equivalent \\par.
</para>
<para>See the &b-link-Package; builder.</para>
</listitem>
</varlistentry>
<varlistentry id="cv-X_MSI_UPGRADE_CODE">
<term>
<envar>X_MSI_UPGRADE_CODE</envar>
</term>
<listitem><para>
TODO
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-X_RPM_AUTOREQPROV">
<term>
<envar>X_RPM_AUTOREQPROV</envar>
</term>
<listitem><para>
This is used to fill in the
<literal>AutoReqProv:</literal>
field in the RPM
<filename>.spec</filename> file.
</para>
<para>See the &b-link-Package; builder.</para>
</listitem>
</varlistentry>
<varlistentry id="cv-X_RPM_BUILD">
<term>
<envar>X_RPM_BUILD</envar>
</term>
<listitem><para>
internal, but overridable
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-X_RPM_BUILDREQUIRES">
<term>
<envar>X_RPM_BUILDREQUIRES</envar>
</term>
<listitem><para>
This is used to fill in the
<literal>BuildRequires:</literal>
field in the RPM
<filename>.spec</filename> file.
Note this should only be used on a host managed by rpm as the dependencies will not be resolvable at build time otherwise.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-X_RPM_BUILDROOT">
<term>
<envar>X_RPM_BUILDROOT</envar>
</term>
<listitem><para>
internal, but overridable
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-X_RPM_CLEAN">
<term>
<envar>X_RPM_CLEAN</envar>
</term>
<listitem><para>
internal, but overridable
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-X_RPM_CONFLICTS">
<term>
<envar>X_RPM_CONFLICTS</envar>
</term>
<listitem><para>
This is used to fill in the
<literal>Conflicts:</literal>
field in the RPM
<filename>.spec</filename> file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-X_RPM_DEFATTR">
<term>
<envar>X_RPM_DEFATTR</envar>
</term>
<listitem><para>
This value is used as the default attributes
for the files in the RPM package.
The default value is
<quote>(-,root,root)</quote>.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-X_RPM_DISTRIBUTION">
<term>
<envar>X_RPM_DISTRIBUTION</envar>
</term>
<listitem><para>
This is used to fill in the
<literal>Distribution:</literal>
field in the RPM
<filename>.spec</filename> file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-X_RPM_EPOCH">
<term>
<envar>X_RPM_EPOCH</envar>
</term>
<listitem><para>
This is used to fill in the
<literal>Epoch:</literal>
field in the RPM
<filename>.spec</filename> file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-X_RPM_EXCLUDEARCH">
<term>
<envar>X_RPM_EXCLUDEARCH</envar>
</term>
<listitem><para>
This is used to fill in the
<literal>ExcludeArch:</literal>
field in the RPM
<filename>.spec</filename> file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-X_RPM_EXLUSIVEARCH">
<term>
<envar>X_RPM_EXLUSIVEARCH</envar>
</term>
<listitem><para>
This is used to fill in the
<literal>ExclusiveArch:</literal>
field in the RPM
<filename>.spec</filename> file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-X_RPM_EXTRADEFS">
<term>
<envar>X_RPM_EXTRADEFS</envar>
</term>
<listitem><para>
A list used to supply extra defintions or flags
to be added to the RPM <filename>.spec</filename> file.
Each item is added as-is with a carriage return appended.
This is useful if some specific RPM feature not otherwise
anticipated by SCons needs to be turned on or off.
Note if this variable is omitted, SCons will by
default supply the value
<literal>'%global debug_package %{nil}'</literal>
to disable debug package generation.
To enable debug package generation, include this
variable set either to None, or to a custom
list that does not include the default line.
Added in version 3.1.
</para>
<example_commands>
env.Package(
NAME="foo",
...
X_RPM_EXTRADEFS=[
"%define _unpackaged_files_terminate_build 0"
"%define _missing_doc_files_terminate_build 0"
],
...
)
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-X_RPM_GROUP">
<term>
<envar>X_RPM_GROUP</envar>
</term>
<listitem><para>
This is used to fill in the
<literal>Group:</literal>
field in the RPM
<filename>.spec</filename> file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-X_RPM_GROUP_lang">
<term>
<envar>X_RPM_GROUP_lang</envar>
</term>
<listitem><para>
This is used to fill in the
<literal>Group(lang):</literal>
field in the RPM
<filename>.spec</filename> file.
Note that
<varname>lang</varname>
is not literal
and should be replaced by
the appropriate language code.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-X_RPM_ICON">
<term>
<envar>X_RPM_ICON</envar>
</term>
<listitem><para>
This is used to fill in the
<literal>Icon:</literal>
field in the RPM
<filename>.spec</filename> file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-X_RPM_INSTALL">
<term>
<envar>X_RPM_INSTALL</envar>
</term>
<listitem><para>
internal, but overridable
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-X_RPM_PACKAGER">
<term>
<envar>X_RPM_PACKAGER</envar>
</term>
<listitem><para>
This is used to fill in the
<literal>Packager:</literal>
field in the RPM
<filename>.spec</filename> file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-X_RPM_POSTINSTALL">
<term>
<envar>X_RPM_POSTINSTALL</envar>
</term>
<listitem><para>
This is used to fill in the
<literal>%post:</literal>
section in the RPM
<filename>.spec</filename> file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-X_RPM_POSTUNINSTALL">
<term>
<envar>X_RPM_POSTUNINSTALL</envar>
</term>
<listitem><para>
This is used to fill in the
<literal>%postun:</literal>
section in the RPM
<filename>.spec</filename> file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-X_RPM_PREFIX">
<term>
<envar>X_RPM_PREFIX</envar>
</term>
<listitem><para>
This is used to fill in the
<literal>Prefix:</literal>
field in the RPM
<filename>.spec</filename> file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-X_RPM_PREINSTALL">
<term>
<envar>X_RPM_PREINSTALL</envar>
</term>
<listitem><para>
This is used to fill in the
<literal>%pre:</literal>
section in the RPM
<filename>.spec</filename> file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-X_RPM_PREP">
<term>
<envar>X_RPM_PREP</envar>
</term>
<listitem><para>
internal, but overridable
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-X_RPM_PREUNINSTALL">
<term>
<envar>X_RPM_PREUNINSTALL</envar>
</term>
<listitem><para>
This is used to fill in the
<literal>%preun:</literal>
section in the RPM
<filename>.spec</filename> file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-X_RPM_PROVIDES">
<term>
<envar>X_RPM_PROVIDES</envar>
</term>
<listitem><para>
This is used to fill in the
<literal>Provides:</literal>
field in the RPM
<filename>.spec</filename> file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-X_RPM_REQUIRES">
<term>
<envar>X_RPM_REQUIRES</envar>
</term>
<listitem><para>
This is used to fill in the
<literal>Requires:</literal>
field in the RPM
<filename>.spec</filename> file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-X_RPM_SERIAL">
<term>
<envar>X_RPM_SERIAL</envar>
</term>
<listitem><para>
This is used to fill in the
<literal>Serial:</literal>
field in the RPM
<filename>.spec</filename> file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-X_RPM_URL">
<term>
<envar>X_RPM_URL</envar>
</term>
<listitem><para>
This is used to fill in the
<literal>Url:</literal>
field in the RPM
<filename>.spec</filename> file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-XGETTEXT">
<term>
<envar>XGETTEXT</envar>
</term>
<listitem><para>
Path to <command>xgettext(1)</command> program (found via
<function>Detect()</function>).
See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-XGETTEXTCOM">
<term>
<envar>XGETTEXTCOM</envar>
</term>
<listitem><para>
Complete xgettext command line.
See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-XGETTEXTCOMSTR">
<term>
<envar>XGETTEXTCOMSTR</envar>
</term>
<listitem><para>
A string that is shown when <command>xgettext(1)</command> command is invoked
(default: <literal>''</literal>, which means "print &cv-link-XGETTEXTCOM;").
See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-_XGETTEXTDOMAIN">
<term>
<envar>_XGETTEXTDOMAIN</envar>
</term>
<listitem><para>
Internal "macro". Generates <command>xgettext</command> domain name
form source and target (default: <literal>'${TARGET.filebase}'</literal>).
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-XGETTEXTFLAGS">
<term>
<envar>XGETTEXTFLAGS</envar>
</term>
<listitem><para>
Additional flags to <command>xgettext(1)</command>.
See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-XGETTEXTFROM">
<term>
<envar>XGETTEXTFROM</envar>
</term>
<listitem><para>
Name of file containing list of <command>xgettext(1)</command>'s source
files. Autotools' users know this as <filename>POTFILES.in</filename> so they
will in most cases set <literal>XGETTEXTFROM="POTFILES.in"</literal> here.
The &cv-XGETTEXTFROM; files have same syntax and semantics as the well known
GNU <filename>POTFILES.in</filename>.
See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-_XGETTEXTFROMFLAGS">
<term>
<envar>_XGETTEXTFROMFLAGS</envar>
</term>
<listitem><para>
Internal "macro". Genrates list of <literal>-D&lt;dir&gt;</literal> flags
from the &cv-link-XGETTEXTPATH; list.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-XGETTEXTFROMPREFIX">
<term>
<envar>XGETTEXTFROMPREFIX</envar>
</term>
<listitem><para>
This flag is used to add single &cv-link-XGETTEXTFROM; file to
<command>xgettext(1)</command>'s commandline (default:
<literal>'-f'</literal>).
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-XGETTEXTFROMSUFFIX">
<term>
<envar>XGETTEXTFROMSUFFIX</envar>
</term>
<listitem><para>
(default: <literal>''</literal>)
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-XGETTEXTPATH">
<term>
<envar>XGETTEXTPATH</envar>
</term>
<listitem><para>
List of directories, there <command>xgettext(1)</command> will look for
source files (default: <literal>[]</literal>).
<note><para>
This variable works only together with &cv-link-XGETTEXTFROM;
</para></note>
See also &t-link-xgettext; tool and &b-link-POTUpdate; builder.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-_XGETTEXTPATHFLAGS">
<term>
<envar>_XGETTEXTPATHFLAGS</envar>
</term>
<listitem><para>
Internal "macro". Generates list of <literal>-f&lt;file&gt;</literal> flags
from &cv-link-XGETTEXTFROM;.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-XGETTEXTPATHPREFIX">
<term>
<envar>XGETTEXTPATHPREFIX</envar>
</term>
<listitem><para>
This flag is used to add single search path to
<command>xgettext(1)</command>'s commandline (default:
<literal>'-D'</literal>).
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-XGETTEXTPATHSUFFIX">
<term>
<envar>XGETTEXTPATHSUFFIX</envar>
</term>
<listitem><para>
(default: <literal>''</literal>)
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-YACC">
<term>
<envar>YACC</envar>
</term>
<listitem><para>
The parser generator.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-YACC_GRAPH_FILE">
<term>
<envar>YACC_GRAPH_FILE</envar>
</term>
<listitem><para>
If supplied, write a graph of the automaton to a file with the name
taken from this variable.
Will be emitted as a <option>--graph=</option>
command-line option. Use this in preference to including
<option>--graph=</option> in &cv-link-YACCFLAGS; directly.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-YACC_HEADER_FILE">
<term>
<envar>YACC_HEADER_FILE</envar>
</term>
<listitem><para>
If supplied, generate a header file with the name taken from this variable.
Will be emitted as a <option>--header=</option>
command-line option. Use this in preference to including
<option>--header=</option> in &cv-link-YACCFLAGS; directly.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-YACCCOM">
<term>
<envar>YACCCOM</envar>
</term>
<listitem><para>
The command line used to call the parser generator
to generate a source file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-YACCCOMSTR">
<term>
<envar>YACCCOMSTR</envar>
</term>
<listitem><para>
The string displayed when generating a source file
using the parser generator.
If this is not set, then &cv-link-YACCCOM; (the command line) is displayed.
</para>
<example_commands>
env = Environment(YACCCOMSTR="Yacc'ing $TARGET from $SOURCES")
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-YACCFLAGS">
<term>
<envar>YACCFLAGS</envar>
</term>
<listitem><para>
General options passed to the parser generator.
In addition to passing the value on during invocation,
the &t-link-yacc; tool also examines this &consvar; for options
which cause additional output files to be generated,
and adds those to the target list.
</para>
<para>
If a <option>-d</option> option is present,
&scons; assumes that the call will also create a header file
with the suffix defined by &cv-link-YACCHFILESUFFIX;
if the yacc source file ends in a <filename>.y</filename> suffix,
or a file with the suffix defined by &cv-link-YACCHXXFILESUFFIX;
if the yacc source file ends in a <filename>.yy</filename> suffix.
</para>
<para>
If a <option>-g</option> option is present,
&scons; assumes that the call will also create a graph file
with the suffix defined by &cv-link-YACCVCGFILESUFFIX;.
</para>
<para>
If a <option>-v</option> option is present,
&scons; assumes that the call will also create an output debug file
with the suffix <filename>.output</filename>.
</para>
<para>
Also recognized are GNU &bison; options
<option>--header=</option> and its deprecated synonym
<option>--defines=</option>,
which is similar to
<option>-d</option>
but the output filename is named by the option argument;
and <option>--graph=</option>,
which is similar to
<option>-g</option>
but the output filename is named by the option argument.
</para>
<para>
Note that files specified by <option>--header=</option> and
<option>--graph=</option> may not be properly handled
by &SCons; in all situations. Consider using
&cv-link-YACC_HEADER_FILE; and &cv-link-YACC_GRAPH_FILE; instead.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-YACCHFILESUFFIX">
<term>
<envar>YACCHFILESUFFIX</envar>
</term>
<listitem><para>
The suffix of the C
header file generated by the parser generator
when the
<option>-d</option>
option is used.
Note that setting this variable does not cause
the parser generator to generate a header
file with the specified suffix,
it exists to allow you to specify
what suffix the parser generator will use of its own accord.
The default value is
<filename>.h</filename>.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-YACCHXXFILESUFFIX">
<term>
<envar>YACCHXXFILESUFFIX</envar>
</term>
<listitem><para>
The suffix of the C++
header file generated by the parser generator
when the
<option>-d</option>
option is used.
Note that setting this variable does not cause
the parser generator to generate a header
file with the specified suffix,
it exists to allow you to specify
what suffix the parser generator will use of its own accord.
The default value is
<filename>.hpp</filename>,
except on Mac OS X,
where the default is
<filename>${TARGET.suffix}.h</filename>.
because the default &bison; parser generator just
appends <filename>.h</filename>
to the name of the generated C++ file.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-YACCVCGFILESUFFIX">
<term>
<envar>YACCVCGFILESUFFIX</envar>
</term>
<listitem><para>
The suffix of the file
containing the VCG grammar automaton definition
when the
<option>--graph=</option>
option is used.
Note that setting this variable does not cause
the parser generator to generate a VCG
file with the specified suffix,
it exists to allow you to specify
what suffix the parser generator will use of its own accord.
The default value is
<filename>.vcg</filename>.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-ZIP">
<term>
<envar>ZIP</envar>
</term>
<listitem><para>
The zip compression and file packaging utility.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-ZIP_OVERRIDE_TIMESTAMP">
<term>
<envar>ZIP_OVERRIDE_TIMESTAMP</envar>
</term>
<listitem><para>
An optional timestamp which overrides the last modification time of
the file when stored inside the Zip archive. This is a tuple of six values:
Year (&gt;= 1980)
Month (one-based)
Day of month (one-based)
Hours (zero-based)
Minutes (zero-based)
Seconds (zero-based)
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-ZIPCOM">
<term>
<envar>ZIPCOM</envar>
</term>
<listitem><para>
The command line used to call the zip utility,
or the internal Python function used to create a
zip archive.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-ZIPCOMPRESSION">
<term>
<envar>ZIPCOMPRESSION</envar>
</term>
<listitem><para>
The
<varname>compression</varname>
flag
from the Python
<filename>zipfile</filename>
module used by the internal Python function
to control whether the zip archive
is compressed or not.
The default value is
<literal>zipfile.ZIP_DEFLATED</literal>,
which creates a compressed zip archive.
This value has no effect if the
<literal>zipfile</literal>
module is unavailable.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-ZIPCOMSTR">
<term>
<envar>ZIPCOMSTR</envar>
</term>
<listitem><para>
The string displayed when archiving files
using the zip utility.
If this is not set, then &cv-link-ZIPCOM;
(the command line or internal Python function) is displayed.
</para>
<example_commands>
env = Environment(ZIPCOMSTR = "Zipping $TARGET")
</example_commands>
</listitem>
</varlistentry>
<varlistentry id="cv-ZIPFLAGS">
<term>
<envar>ZIPFLAGS</envar>
</term>
<listitem><para>
General options passed to the zip utility.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-ZIPROOT">
<term>
<envar>ZIPROOT</envar>
</term>
<listitem><para>
An optional zip root directory (default empty). The filenames stored
in the zip file will be relative to this directory, if given.
Otherwise the filenames are relative to the current directory of the
command.
For instance:
</para>
<example_commands>
env = Environment()
env.Zip('foo.zip', 'subdir1/subdir2/file1', ZIPROOT='subdir1')
</example_commands>
<para>
will produce a zip file <literal>foo.zip</literal>
containing a file with the name
<literal>subdir2/file1</literal> rather than
<literal>subdir1/subdir2/file1</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry id="cv-ZIPSUFFIX">
<term>
<envar>ZIPSUFFIX</envar>
</term>
<listitem><para>
The suffix used for zip file names.
</para>
</listitem>
</varlistentry>
</variablelist>
Reference in New Issue View Git Blame Copy Permalink