[ci skip] Add note that this change may break SetOption() + ninja usage with fix

[scons.git] / SCons / Defaults.xml

<?xml version="1.0"?>
<!--
Copyright The SCons Foundation

This file is processed by the bin/SConsDoc.py module.
See its __doc__ string for a discussion of the format.
-->

<!DOCTYPE sconsdoc [
<!ENTITY % scons SYSTEM '../doc/scons.mod'>
%scons;
<!ENTITY % builders-mod SYSTEM '../doc/generated/builders.mod'>
%builders-mod;
<!ENTITY % functions-mod SYSTEM '../doc/generated/functions.mod'>
%functions-mod;
<!ENTITY % tools-mod SYSTEM '../doc/generated/tools.mod'>
%tools-mod;
<!ENTITY % variables-mod SYSTEM '../doc/generated/variables.mod'>
%variables-mod;
]>

<sconsdoc 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">

<cvar name ="_concat">
<summary>
    <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>
</summary>
</cvar>

<cvar name="CONFIGUREDIR">
<summary>
<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>
<para>
If variant directories are in use,
and the configure check results should not be
shared between variants,
you can set &cv-CONFIGUREDIR;
and &cv-link-CONFIGURELOG; so they are
unique per variant directory.
</para>
</summary>
</cvar>

<cvar name="CONFIGURELOG">
<summary>
<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>
<para>
If variant directories are in use,
and the configure check results should not be
shared between variants,
you can set &cv-link-CONFIGUREDIR;
and &cv-CONFIGURELOG; so they are
unique per variant directory.
</para>
</summary>
</cvar>

<cvar name="_CPPDEFFLAGS">
<summary>
<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>
</summary>
</cvar>

<cvar name="CPPDEFINES">
<summary>
<para>
A platform independent specification of C preprocessor macro definitions.
The definitions are added to command lines
through the automatically-generated
&cv-link-_CPPDEFFLAGS; &consvar;,
which is constructed according to
the contents of &cv-CPPDEFINES;:
</para>

<itemizedlist>
<listitem>
<para>
If &cv-CPPDEFINES; is a string,
the values of the
&cv-link-CPPDEFPREFIX; and &cv-link-CPPDEFSUFFIX; &consvars;
are respectively prepended and appended to
each definition in &cv-CPPDEFINES;,
split on whitespace.
</para>

<example_commands>
# Adds -Dxyz to POSIX compiler command lines,
# and /Dxyz to Microsoft Visual C++ command lines.
env = Environment(CPPDEFINES='xyz')
</example_commands>

</listitem>
<listitem>
<para>
If &cv-CPPDEFINES; is a list,
the values of the
&cv-CPPDEFPREFIX; and &cv-CPPDEFSUFFIX; &consvars;
are respectively prepended and appended to
each element in the list.
If any element is a tuple (or list)
then the first item of the tuple is the macro name
and the second is the macro definition.
If the definition is not omitted or <literal>None</literal>,
the name and definition are combined into a single
<literal>name=definition</literal> item
before the preending/appending.
</para>

<example_commands>
# Adds -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>

</listitem>
<listitem>
<para>
If &cv-CPPDEFINES; is a dictionary,
the values of the
&cv-CPPDEFPREFIX; and &cv-CPPDEFSUFFIX; &consvars;
are respectively prepended and appended to
each key from the dictionary.
If the value for a key is not <literal>None</literal>,
then the key (macro name) and the value
(macros definition) are combined into a single
<literal>name=definition</literal> item
before the prepending/appending.
</para>

<example_commands>
# Adds -DA -DB=2 to POSIX compiler command lines,
# or /DA /DB=2 to Microsoft Visual C++ command lines.
env = Environment(CPPDEFINES={'B':2, 'A':None})
</example_commands>
</listitem>
</itemizedlist>

<para>
Depending on how contents are added to &cv-CPPDEFINES;,
it may be transformed into a compound type,
for example a list containing strings, tuples and/or dictionaries.
&SCons; can correctly expand such a compound type.
</para>

<para>
Note that &SCons; may call the compiler via a shell.
If a macro definition contains characters such as spaces that
have meaning to the shell, or is intended to be a string value,
you may need to use the shell's quoting syntax to avoid
interpretation by the shell before the preprocessor sees it.
Function-like macros are not supported via this mechanism
(and some compilers do not even implement that functionality
via the command lines).
When quoting, note that
one set of quote characters are used to define a &Python; string,
then quotes embedded inside that would be consumed by the shell
unless escaped.  These examples may help illustrate:
</para>

<example_commands>
env = Environment(CPPDEFINES=['USE_ALT_HEADER=\\"foo_alt.h\\"'])
env = Environment(CPPDEFINES=[('USE_ALT_HEADER', '\\"foo_alt.h\\"')])
</example_commands>

<para>
:<emphasis>Changed in version  4.5</emphasis>:
&SCons; no longer sorts &cv-CPPDEFINES; values entered
in dictionary form.  &Python; now preserves dictionary
keys in the order they are entered, so it is no longer
necessary to sort them to ensure a stable command line.
</para>

</summary>
</cvar>

<cvar name="CPPDEFPREFIX">
<summary>
<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>
</summary>
</cvar>

<cvar name="CPPDEFSUFFIX">
<summary>
<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>
</summary>
</cvar>

<cvar name="_CPPINCFLAGS">
<summary>
<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>
</summary>
</cvar>

<cvar name="CPPPATH">
<summary>
<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.pathsep</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>
</summary>
</cvar>

<cvar name="Dir">
<summary>
<para>
A function that converts a string
into a Dir instance relative to the target being built.
</para>
</summary>
</cvar>

<cvar name="Dirs">
<summary>
<para>
A function that converts a list of strings
into a list of Dir instances relative to the target being built.
</para>
</summary>
</cvar>

<cvar name="DSUFFIXES">
<summary>
<para>
The list of suffixes of files that will be scanned
for imported D package files.
The default list is <literal>['.d']</literal>.
</para>
</summary>
</cvar>

<cvar name="File">
<summary>
<para>
A function that converts a string into a File instance relative to the
target being built.
</para>
</summary>
</cvar>

<cvar name="IDLSUFFIXES">
<summary>
<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>
</summary>
</cvar>

<cvar name="INCPREFIX">
<summary>
<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>
</summary>
</cvar>

<cvar name="INCSUFFIX">
<summary>
<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>
</summary>
</cvar>

<cvar name="INSTALL">
<summary>
<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>
</summary>
</cvar>

<cvar name="INSTALLSTR">
<summary>
<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>
</summary>
</cvar>

<cvar name="LATEXSUFFIXES">
<summary>
<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>
</summary>
</cvar>

<cvar name="_LIBDIRFLAGS">
<summary>
<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>
</summary>
</cvar>

<cvar name="LIBDIRPREFIX">
<summary>
<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>
</summary>
</cvar>

<cvar name="LIBDIRSUFFIX">
<summary>
<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>
</summary>
</cvar>

<cvar name="_LIBFLAGS">
<summary>
<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-_LIBFLAGS; is created
by respectively prepending and appending &cv-link-LIBLINKPREFIX;
and &cv-link-LIBLINKSUFFIX;
to each filename in &cv-link-LIBS;.
</para>
</summary>
</cvar>

<cvar name="LIBLINKPREFIX">
<summary>
<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>
</summary>
</cvar>

<cvar name="LIBLINKSUFFIX">
<summary>
<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>
</summary>
</cvar>

<cvar name="LIBPATH">
<summary>
<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.pathsep</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>
</summary>
</cvar>

<cvar name="LIBS">
<summary>
<para>
The list of 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>
For portability,
a string-valued library name should include
only the base library name,
without prefixes such as <filename>lib</filename>
or suffixes such as <filename>.so</filename> or <filename>.dll</filename>.
&SCons; <emphasis>will</emphasis> attempt to
strip prefixes from the &cv-link-LIBPREFIXES; list
and suffixes from the &cv-link-LIBSUFFIXES; list,
but depending on that behavior will make the build
less portable:
for example, on a POSIX system,
no attempt will be made to strip a suffix like
<filename>.dll</filename>.
Library name strings in &cv-LIBS; should not include a path component:
instead use &cv-link-LIBPATH; to direct the compiler
to look for libraries in those paths,
plus any default paths the linker searches in.
If &cv-link-LIBLITERALPREFIX; is set to a non-empty string,
then a string-valued &cv-LIBS; entry
that starts with &cv-link-LIBLITERALPREFIX;
will cause the rest of the entry
to be searched for for unmodified,
but respecting normal library search paths
(this is an exception to the guideline above
about leaving off the prefix/suffix from the library name).
</para>

<para>
If a &cv-LIBS; entry is a Node object
(either as returned by a previous Builder call,
or as the result of an explicit call to &f-link-File;),
the pathname from that Node will be added to
&cv-_LIBFLAGS;,
and thus to the link line,
unmodified - without adding
&cv-LIBLINKPREFIX;
or
&cv-LIBLINKSUFFIX;.
Such entries are searched for literally
(including any path component);
the library search paths are not used.
For example:
</para>

<example_commands>
env.Append(LIBS=File('/tmp/mylib.so'))
</example_commands>

<para>
<!-- is this actually true? -->
For each &Builder; call that causes linking with libraries,
&SCons; will add the libraries in the setting of &cv-LIBS;
in effect at that moment to the dependecy graph
as dependencies of the target being generated.
</para>

<para>
The library list will transformed to command line
arguments through the automatically-generated
&cv-link-_LIBFLAGS; &consvar;
which is constructed by
respectively prepending and appending the values of the
&cv-link-LIBLINKPREFIX; and &cv-link-LIBLINKSUFFIX; &consvars;
to each library name.
</para>

<para>
Any command lines you define yourself that need
the libraries from &cv-LIBS; should include &cv-_LIBFLAGS;
(as well as &cv-link-_LIBDIRFLAGS;)
rather than &cv-LIBS;.
For example:
</para>

<example_commands>
env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
</example_commands>
</summary>
</cvar>

<cvar name="LIBLITERALPREFIX">
<summary>
<para>
If the linker supports command line syntax directing
that the argument specifying a library should be
searched for literally (without modification),
&cv-LIBLITERALPREFIX; can be set to that indicator.
For example, the GNU linker follows this rule:
<quote>
<literal>-l:foo</literal> searches the library path
for a filename called <literal>foo</literal>,
without converting it to
<literal>libfoo.so</literal> or
<literal>libfoo.a</literal>.
</quote>
If &cv-LIBLITERALPREFIX; is set,
&SCons; will not transform a string-valued entry in
&cv-link-LIBS; that starts with that string.
The entry will still be surrounded with
&cv-link-LIBLINKPREFIX; and &cv-link-LIBLINKSUFFIX;
on the command line.
This is useful, for example,
in directing that a static library
be used when both a static and dynamic library are available
and linker policy is to prefer dynamic libraries.
Compared to the example in &cv-link-LIBS;,
</para>
<example_commands>
env.Append(LIBS=":libmylib.a")
</example_commands>
<para>
will let the linker select that specific (static)
library name if found in the library search path.
This differs from using a
<classname>File</classname> object
to specify the static library,
as the latter bypasses the library search path entirely.
</para>
</summary>
</cvar>

<cvar name="RDirs">
<summary>
<para>
A function that converts a string into a list of Dir instances by
searching the repositories.
</para>
</summary>
</cvar>

<scons_function name="DefaultEnvironment">
<arguments signature="global">
([**kwargs])
</arguments>
<summary>
<para>
Instantiates and returns the global &consenv; object.
This environment is used internally by SCons
when it executes many of the global functions listed in this section
(that is, those not called as methods of a specific &consenv;).
The &defenv; is a singleton:
the keyword arguments are used only on the first call;
on subsequent calls the already-constructed object is returned
and any keyword arguments are silently ignored.
The &defenv; can still be modified after instantiation
in the same way as any other &consenv;.
The &defenv; is independent:
modifying it has no effect on any other &consenv;
constructed by an &f-link-Environment; or &f-link-Clone; call.
</para>

<para>
It is not mandatory to call &f-DefaultEnvironment;:
the &defenv; is instantiated automatically when the
build phase begins if this function has not been called;
however calling it explicitly gives the opportunity to
affect and examine the contents of the &defenv;.
Instantiation happens even if no build instructions
appar to use it, as there are internal uses.
If there are no uses in the project &SConscript; files,
a small performance gain may be seen by calling
&f-DefaultEnvironment; with an empty tools list,
thus avoiding that part of the initialization cost.
This is mainly of interest in testing when &scons; is
launched repeatedly in a short time period:
</para>
<example_commands>
DefaultEnvironment(tools=[])
</example_commands>
</summary>
</scons_function>

</sconsdoc>