path: root/src/engine/SCons/Defaults.xml

<!-- __COPYRIGHT__ -->
<builder name="DVI">
<summary>
Builds a <filename>.dvi</filename> file
from a <filename>.tex</filename>,
<filename>.ltx</filename> or <filename>.latex</filename> input file.
If the source file suffix is <filename>.tex</filename>,
&scons;
will examine the contents of the file;
if the string
<literal>\documentclass</literal>
or
<literal>\documentstyle</literal>
is found, the file is assumed to be a LaTeX file and
the target is built by invoking the &cv-LATEXCOM; command line;
otherwise, the &cv-TEXCOM; command line is used.
If the file is a LaTeX file,
the
&b-DVI;
builder method will also examine the contents
of the
<filename>.aux</filename>
file
and invoke the &cv-BIBTEX; command line
if the string
<literal>bibdata</literal>
is found,
and will examine the contents
<filename>.log</filename>
file and re-run the &cv-LATEXCOM; command
if the log file says it is necessary.

The suffix <filename>.dvi</filename>
(hard-coded within TeX itself)
is automatically added to the target
if it is not already present.
Examples:

<example>
# builds from aaa.tex
env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
# builds bbb.dvi
env.DVI(target = 'bbb', source = 'bbb.ltx')
# builds from ccc.latex
env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
</example>
</summary>
</builder>

<builder name="PDF">
<summary>
Builds a <filename>.pdf</filename> file
from a <filename>.dvi</filename> input file
(or, by extension, a <filename>.tex</filename>,
<filename>.ltx</filename>,
or
<filename>.latex</filename> input file).
The suffix specified by the &cv-PDFSUFFIX; construction variable
(<filename>.pdf</filename> by default)
is added automatically to the target
if it is not already present.  Example:

<example>
# builds from aaa.tex
env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
# builds bbb.pdf from bbb.dvi
env.PDF(target = 'bbb', source = 'bbb.dvi')
</example>
</summary>
</builder>

<cvar name ="_concat">
<summary>
A function used to produce variables like &cv-_CPPINCFLAGS;. It takes
four or five
arguments: a prefix to concatenate onto each element, a list of
elements, a suffix to concatenate onto each element, an environment
for variable interpolation, and an optional function that will be
called to transform the list before concatenation.

<example>
env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)',
</example>
</summary>
</cvar>

<cvar name="CPPDEFINES">
<summary>
A platform independent specification of C preprocessor definitions.
The definitions will be added to command lines
through the automatically-generated
&cv-_CPPDEFFLAGS; construction variable (see below),
which is constructed according to
the type of value of &cv-CPPDEFINES;:

If &cv-CPPDEFINES; is a string,
the values of the
&cv-CPPDEFPREFIX; and &cv-CPPDEFSUFFIX;
construction variables
will be added to the beginning and end.

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

If &cv-CPPDEFINES; is a list,
the values of the
&cv-CPPDEFPREFIX; and &cv-CPPDEFSUFFIX;
construction variables
will be appended to the beginning and end
of 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:

<example>
# 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>

If &cv-CPPDEFINES; is a dictionary,
the values of the
&cv-CPPDEFPREFIX; and &cv-CPPDEFSUFFIX;
construction variables
will be appended to the beginning and end
of 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.

<example>
# 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>
</summary>
</cvar>

<cvar name="_CPPDEFFLAGS">
<summary>
An automatically-generated construction variable
containing the C preprocessor command-line options
to define values.
The value of &cv-_CPPDEFFLAGS; is created
by appending &cv-CPPDEFPREFIX; and &cv-CPPDEFSUFFIX;
to the beginning and end
of each directory in &cv-CPPDEFINES;.
</summary>
</cvar>

<cvar name="CPPDEFPREFIX">
<summary>
The prefix used to specify preprocessor definitions
on the C compiler command line.
This will be appended to the beginning of each definition
in the &cv-CPPDEFINES; construction variable
when the &cv-_CPPDEFFLAGS; variable is automatically generated.
</summary>
</cvar>

<cvar name="CPPDEFSUFFIX">
<summary>
The suffix used to specify preprocessor definitions
on the C compiler command line.
This will be appended to the end of each definition
in the &cv-CPPDEFINES; construction variable
when the &cv-_CPPDEFFLAGS; variable is automatically generated.
</summary>
</cvar>

<cvar name="_CPPINCFLAGS">
<summary>
An automatically-generated construction variable
containing the C preprocessor command-line options
for specifying directories to be searched for include files.
The value of &cv-_CPPINCFLAGS; is created
by appending &cv-INCPREFIX; and &cv-INCSUFFIX;
to the beginning and end
of each directory in &cv-CPPPATH;.
</summary>
</cvar>

<cvar name="CPPPATH">
<summary>
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. Don't explicitly put include directory
arguments in CCFLAGS or CXXFLAGS because the result will be non-portable
and the directories will not be searched by the dependency scanner. Note:
directory names in CPPPATH 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 #:

<example>
env = Environment(CPPPATH='#/include')
</example>

The directory look-up can also be forced using the 
&Dir;()
function:

<example>
include = Dir('include')
env = Environment(CPPPATH=include)
</example>

The directory list will be added to command lines
through the automatically-generated
&cv-_CPPINCFLAGS;
construction variable,
which is constructed by
appending the values of the
&cv-INCPREFIX; and &cv-INCSUFFIX;
construction variables
to the beginning and end
of each directory in &cv-CPPPATH;.
Any command lines you define that need
the CPPPATH directory list should
include &cv-_CPPINCFLAGS;:

<example>
env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
</example>
</summary>
</cvar>

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

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

<cvar name="DSUFFIXES">
<summary>
The list of suffixes of files that will be scanned
for imported D package files.
The default list is:

<example>
['.d']
</example>
</summary>
</cvar>

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

<cvar name="IDLSUFFIXES">
<summary>
The list of suffixes of files that will be scanned
for IDL implicit dependencies
(#include or import lines).
The default list is:

<example>
[".idl", ".IDL"]
</example>
</summary>
</cvar>

<cvar name="INCPREFIX">
<summary>
The prefix used to specify an include directory on the C compiler command
line.
This will be appended to the beginning of each directory
in the &cv-CPPPATH; and &cv-FORTRANPATH; construction variables
when the &cv-_CPPINCFLAGS; and &cv-_FORTRANINCFLAGS;
variables are automatically generated.
</summary>
</cvar>

<cvar name="INCSUFFIX">
<summary>
The suffix used to specify an include directory on the C compiler command
line.
This will be appended to the end of each directory
in the &cv-CPPPATH; and &cv-FORTRANPATH; construction variables
when the &cv-_CPPINCFLAGS; and &cv-_FORTRANINCFLAGS;
variables are automatically generated.
</summary>
</cvar>

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

<example>
def install(dest, source, env):
</example>

<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.
</summary>
</cvar>

<cvar name="_LIBDIRFLAGS">
<summary>
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 appending &cv-LIBDIRPREFIX; and &cv-LIBDIRSUFFIX;
to the beginning and end
of each directory in &cv-LIBPATH;.
</summary>
</cvar>

<cvar name="LIBDIRPREFIX">
<summary>
The prefix used to specify a library directory on the linker command line.
This will be appended to the beginning of each directory
in the &cv-LIBPATH; construction variable
when the &cv-_LIBDIRFLAGS; variable is automatically generated.
</summary>
</cvar>

<cvar name="LIBDIRSUFFIX">
<summary>
The suffix used to specify a library directory on the linker command line.
This will be appended to the end of each directory
in the &cv-LIBPATH; construction variable
when the &cv-_LIBDIRFLAGS; variable is automatically generated.
</summary>
</cvar>

<cvar name="_LIBFLAGS">
<summary>
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 appending &cv-LIBLINKPREFIX; and &cv-LIBLINKSUFFIX;
to the beginning and end
of each filename in &cv-LIBS;.
</summary>
</cvar>

<cvar name="LIBLINKPREFIX">
<summary>
The prefix used to specify a library to link on the linker command line.
This will be appended to the beginning of each library
in the &cv-LIBS; construction variable
when the &cv-_LIBFLAGS; variable is automatically generated.
</summary>
</cvar>

<cvar name="LIBLINKSUFFIX">
<summary>
The suffix used to specify a library to link on the linker command line.
This will be appended to the end of each library
in the &cv-LIBS; construction variable
when the &cv-_LIBFLAGS; variable is automatically generated.
</summary>
</cvar>

<cvar name="LIBPATH">
<summary>
The list of directories that will be searched for libraries.
The implicit dependency scanner will search these
directories for include files. Don't explicitly put include directory
arguments in &cv-LINKFLAGS; or &cv-SHLINKFLAGS;
because the result will be non-portable
and the directories will not be searched by the dependency scanner. Note:
directory names in LIBPATH will be looked-up relative to the SConscript
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 #:

<example>
env = Environment(LIBPATH='#/libs')
</example>

The directory look-up can also be forced using the 
&Dir;()
function:

<example>
libs = Dir('libs')
env = Environment(LIBPATH=libs)
</example>

The directory list will be added to command lines
through the automatically-generated
&cv-_LIBDIRFLAGS;
construction variable,
which is constructed by
appending the values of the
&cv-LIBDIRPREFIX; and &cv-LIBDIRSUFFIX;
construction variables
to the beginning and end
of each directory in &cv-LIBPATH;.
Any command lines you define that need
the LIBPATH directory list should
include &cv-_LIBDIRFLAGS;:

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

<cvar name="LIBS">
<summary>
A list of one or more libraries
that will be linked with
any executable programs
created by this environment.

The library list will be added to command lines
through the automatically-generated
&cv-_LIBFLAGS;
construction variable,
which is constructed by
appending the values of the
&cv-LIBLINKPREFIX; and &cv-LIBLINKSUFFIX;
construction variables
to the beginning and end
of each filename in &cv-LIBS;.
Any command lines you define that need
the LIBS library list should
include &cv-_LIBFLAGS;:

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

If you add a
File
object to the
&cv-LIBS;
list, the name of that file will be added to
&cv-_LIBFLAGS;,
and thus the link line, as is, without
&cv-LIBLINKPREFIX;
or
&cv-LIBLINKSUFFIX;.
For example:

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

In all cases, scons will add dependencies from the executable program to
all the libraries in this list.
</summary>
</cvar>

<cvar name="PDFPREFIX">
<summary>
The prefix used for PDF file names.
</summary>
</cvar>

<cvar name="PDFSUFFIX">
<summary>
The suffix used for PDF file names.
</summary>
</cvar>

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