path: root/doc/generated/builders.gen

<?xml version="1.0" encoding="UTF-8"?>
<!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/scons.xsd scons.xsd">
  <varlistentry id="b-CFile">
    <term>
      <function>CFile()</function>
    </term>
    <term>
      <function>env.CFile()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
Builds a C source file given a lex (<filename>.l</filename>)
or yacc (<filename>.y</filename>) input file.
The suffix specified by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-CFILESUFFIX"><envar>$CFILESUFFIX</envar></link> construction variable
(<filename>.c</filename> by default)
is automatically added to the target
if it is not already present.
Example:
</para>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
# builds foo.c
env.CFile(target = 'foo.c', source = 'foo.l')
# builds bar.c
env.CFile(target = 'bar', source = 'bar.y')
</example_commands>
</listitem>
  </varlistentry>
  <varlistentry id="b-Command">
    <term>
      <function>Command()</function>
    </term>
    <term>
      <function>env.Command()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
The <function xmlns="http://www.scons.org/dbxsd/v1.0">Command</function> "Builder" is actually implemented
as a function that looks like a Builder,
but actually takes an additional argument of the action
from which the Builder should be made.
See the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-Command"><function>Command</function></link> function description
for the calling syntax and details.
</para>
</listitem>
  </varlistentry>
  <varlistentry id="b-CXXFile">
    <term>
      <function>CXXFile()</function>
    </term>
    <term>
      <function>env.CXXFile()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
Builds a C++ source file given a lex (<filename>.ll</filename>)
or yacc (<filename>.yy</filename>)
input file.
The suffix specified by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-CXXFILESUFFIX"><envar>$CXXFILESUFFIX</envar></link> construction variable
(<filename>.cc</filename> by default)
is automatically added to the target
if it is not already present.
Example:
</para>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
# builds foo.cc
env.CXXFile(target = 'foo.cc', source = 'foo.ll')
# builds bar.cc
env.CXXFile(target = 'bar', source = 'bar.yy')
</example_commands>
</listitem>
  </varlistentry>
  <varlistentry id="b-DVI">
    <term>
      <function>DVI()</function>
    </term>
    <term>
      <function>env.DVI()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
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>,
<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
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 <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-LATEXCOM"><envar>$LATEXCOM</envar></link> command line;
otherwise, the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-TEXCOM"><envar>$TEXCOM</envar></link> command line is used.
If the file is a LaTeX file,
the
<function xmlns="http://www.scons.org/dbxsd/v1.0">DVI</function>
builder method will also examine the contents
of the
<filename>.aux</filename>
file and invoke the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-BIBTEX"><envar>$BIBTEX</envar></link> command line
if the string
<literal>bibdata</literal>
is found,
start <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-MAKEINDEX"><envar>$MAKEINDEX</envar></link> to generate an index if a
<filename>.ind</filename>
file is found
and will examine the contents
<filename>.log</filename>
file and re-run the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-LATEXCOM"><envar>$LATEXCOM</envar></link> command
if the log file says it is necessary.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
The suffix <filename>.dvi</filename>
(hard-coded within TeX itself)
is automatically added to the target
if it is not already present.
Examples:
</para>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
# 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_commands>
</listitem>
  </varlistentry>
  <varlistentry id="b-Install">
    <term>
      <function>Install()</function>
    </term>
    <term>
      <function>env.Install()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
Installs one or more source files or directories
in the specified target,
which must be a directory.
The names of the specified source files or directories
remain the same within the destination directory. The
sources may be given as a string or as a node returned by
a builder.
</para>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
env.Install('/usr/local/bin', source = ['foo', 'bar'])
</example_commands>
</listitem>
  </varlistentry>
  <varlistentry id="b-InstallAs">
    <term>
      <function>InstallAs()</function>
    </term>
    <term>
      <function>env.InstallAs()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
Installs one or more source files or directories
to specific names,
allowing changing a file or directory name
as part of the installation.
It is an error if the
target
and
source
arguments list different numbers of files or directories.
</para>
</listitem>
  </varlistentry>
  <varlistentry id="b-InstallVersionedLib">
    <term>
      <function>InstallVersionedLib()</function>
    </term>
    <term>
      <function>env.InstallVersionedLib()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
Installs a versioned shared library. The <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHLIBVERSION"><envar>$SHLIBVERSION</envar></link>
construction variable should be defined in the environment
to confirm the version number in the library name.
The symlinks appropriate to the architecture will be generated.
</para>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
env.InstallAs(target = '/usr/local/bin/foo',
              source = 'foo_debug')
env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
              source = ['libFOO.a', 'libBAR.a'])
</example_commands>
</listitem>
  </varlistentry>
  <varlistentry id="b-Jar">
    <term>
      <function>Jar()</function>
    </term>
    <term>
      <function>env.Jar()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
Builds a Java archive (<filename>.jar</filename>) file
from the specified list of sources.
Any directories in the source list
will be searched for <filename>.class</filename> files).
Any <filename>.java</filename> files in the source list
will be compiled  to <filename>.class</filename> files
by calling the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-Java"><function>Java</function></link> Builder.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
If the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-JARCHDIR"><envar>$JARCHDIR</envar></link> value is set, the
<application xmlns="http://www.scons.org/dbxsd/v1.0">jar</application>
command will change to the specified directory using the
<option>-C</option>
option.
If <envar xmlns="http://www.scons.org/dbxsd/v1.0">$JARCHDIR</envar> is not set explicitly,
<application xmlns="http://www.scons.org/dbxsd/v1.0">SCons</application> will use the top of any subdirectory tree
in which Java <filename>.class</filename>
were built by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-Java"><function>Java</function></link> Builder.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
If the contents any of the source files begin with the string
<literal>Manifest-Version</literal>,
the file is assumed to be a manifest
and is passed to the
<application xmlns="http://www.scons.org/dbxsd/v1.0">jar</application>
command with the
<option>m</option>
option set.
</para>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
env.Jar(target = 'foo.jar', source = 'classes')

env.Jar(target = 'bar.jar',
        source = ['bar1.java', 'bar2.java'])
</example_commands>
</listitem>
  </varlistentry>
  <varlistentry id="b-Java">
    <term>
      <function>Java()</function>
    </term>
    <term>
      <function>env.Java()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
Builds one or more Java class files.
The sources may be any combination of explicit
<filename>.java</filename> files,
or directory trees which will be scanned
for <filename>.java</filename> files.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
SCons will parse each source <filename>.java</filename> file
to find the classes
(including inner classes)
defined within that file,
and from that figure out the
target <filename>.class</filename> files that will be created.
The class files will be placed underneath
the specified target directory.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
SCons will also search each Java file
for the Java package name,
which it assumes can be found on a line
beginning with the string
<literal>package</literal>
in the first column;
the resulting <filename>.class</filename> files
will be placed in a directory reflecting
the specified package name.
For example,
the file
<filename>Foo.java</filename>
defining a single public
<classname>Foo</classname>
class and
containing a package name of
<classname>sub.dir</classname>
will generate a corresponding
<filename>sub/dir/Foo.class</filename>
class file.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
Examples:
</para>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
env.Java(target = 'classes', source = 'src')
env.Java(target = 'classes', source = ['src1', 'src2'])
env.Java(target = 'classes', source = ['File1.java', 'File2.java'])
</example_commands>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
Java source files can use the native encoding for the underlying OS.
Since SCons compiles in simple ASCII mode by default,
the compiler will generate warnings about unmappable characters,
which may lead to errors as the file is processed further.
In this case, the user must specify the <literal>LANG</literal>
environment variable to tell the compiler what encoding is used.
For portibility, it's best if the encoding is hard-coded
so that the compile will work if it is done on a system
with a different encoding.
</para>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
env = Environment()
env['ENV']['LANG'] = 'en_GB.UTF-8'
</example_commands>
</listitem>
  </varlistentry>
  <varlistentry id="b-JavaH">
    <term>
      <function>JavaH()</function>
    </term>
    <term>
      <function>env.JavaH()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
Builds C header and source files for
implementing Java native methods.
The target can be either a directory
in which the header files will be written,
or a header file name which
will contain all of the definitions.
The source can be the names of <filename>.class</filename> files,
the names of <filename>.java</filename> files
to be compiled into <filename>.class</filename> files
by calling the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-Java"><function>Java</function></link> builder method,
or the objects returned from the
<function xmlns="http://www.scons.org/dbxsd/v1.0">Java</function>
builder method.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
If the construction variable
<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-JAVACLASSDIR"><envar>$JAVACLASSDIR</envar></link>
is set, either in the environment
or in the call to the
<function xmlns="http://www.scons.org/dbxsd/v1.0">JavaH</function>
builder method itself,
then the value of the variable
will be stripped from the
beginning of any <filename>.class</filename> file names.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
Examples:
</para>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
# builds java_native.h
classes = env.Java(target = 'classdir', source = 'src')
env.JavaH(target = 'java_native.h', source = classes)

# builds include/package_foo.h and include/package_bar.h
env.JavaH(target = 'include',
          source = ['package/foo.class', 'package/bar.class'])

# builds export/foo.h and export/bar.h
env.JavaH(target = 'export',
          source = ['classes/foo.class', 'classes/bar.class'],
          JAVACLASSDIR = 'classes')
</example_commands>
</listitem>
  </varlistentry>
  <varlistentry id="b-Library">
    <term>
      <function>Library()</function>
    </term>
    <term>
      <function>env.Library()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
A synonym for the
<function xmlns="http://www.scons.org/dbxsd/v1.0">StaticLibrary</function>
builder method.
</para>
</listitem>
  </varlistentry>
  <varlistentry id="b-LoadableModule">
    <term>
      <function>LoadableModule()</function>
    </term>
    <term>
      <function>env.LoadableModule()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
On most systems,
this is the same as
<function xmlns="http://www.scons.org/dbxsd/v1.0">SharedLibrary</function>.
On Mac OS X (Darwin) platforms,
this creates a loadable module bundle.
</para>
</listitem>
  </varlistentry>
  <varlistentry id="b-M4">
    <term>
      <function>M4()</function>
    </term>
    <term>
      <function>env.M4()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
Builds an output file from an M4 input file.
This uses a default <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-M4FLAGS"><envar>$M4FLAGS</envar></link> value of
<option>-E</option>,
which considers all warnings to be fatal
and stops on the first warning
when using the GNU version of m4.
Example:
</para>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
env.M4(target = 'foo.c', source = 'foo.c.m4')
</example_commands>
</listitem>
  </varlistentry>
  <varlistentry id="b-Moc">
    <term>
      <function>Moc()</function>
    </term>
    <term>
      <function>env.Moc()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
Builds an output file from a moc input file. Moc input files are either
header files or cxx files. This builder is only available after using the
tool 'qt'. See the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-QTDIR"><envar>$QTDIR</envar></link> variable for more information.
Example:
</para>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
env.Moc('foo.h') # generates moc_foo.cc
env.Moc('foo.cpp') # generates foo.moc
</example_commands>
</listitem>
  </varlistentry>
  <varlistentry id="b-MOFiles">
    <term>
      <function>MOFiles()</function>
    </term>
    <term>
      <function>env.MOFiles()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
This builder belongs to <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="t-msgfmt"><literal>msgfmt</literal></link> tool. The builder compiles
<literal>PO</literal> files to <literal>MO</literal> files.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
<emphasis>Example 1</emphasis>.
Create <filename>pl.mo</filename> and <filename>en.mo</filename> by compiling
<filename>pl.po</filename> and <filename>en.po</filename>:
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
  # ...
  env.MOFiles(['pl', 'en'])
</example_commands>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
<emphasis>Example 2</emphasis>.
Compile files for languages defined in <filename>LINGUAS</filename> file:
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
  # ...
  env.MOFiles(LINGUAS_FILE = 1)
</example_commands>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
<emphasis>Example 3</emphasis>.
Create <filename>pl.mo</filename> and <filename>en.mo</filename> by compiling
<filename>pl.po</filename> and <filename>en.po</filename> plus files for
languages defined in <filename>LINGUAS</filename> file:
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
  # ...
  env.MOFiles(['pl', 'en'], LINGUAS_FILE = 1)
</example_commands>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
<emphasis>Example 4</emphasis>.
Compile files for languages defined in <filename>LINGUAS</filename> file 
(another version):
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
  # ...
  env['LINGUAS_FILE'] = 1
  env.MOFiles()
</example_commands>
</listitem>
  </varlistentry>
  <varlistentry id="b-MSVSProject">
    <term>
      <function>MSVSProject()</function>
    </term>
    <term>
      <function>env.MSVSProject()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
Builds a Microsoft Visual Studio project file,
and by default builds a solution file as well.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
This builds a Visual Studio project file, based on the version of
Visual Studio that is configured (either the latest installed version,
or the version specified by
<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-MSVS_VERSION"><envar>$MSVS_VERSION</envar></link>
in the Environment constructor).
For Visual Studio 6, it will generate a
<filename>.dsp</filename>
file.
For Visual Studio 7 (.NET) and later versions, it will generate a
<filename>.vcproj</filename>
file.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
By default,
this also generates a solution file
for the specified project,
a
<filename>.dsw</filename>
file for Visual Studio 6
or a
<filename>.sln</filename>
file for Visual Studio 7 (.NET).
This behavior may be disabled by specifying
<literal>auto_build_solution=0</literal>
when you call
<function xmlns="http://www.scons.org/dbxsd/v1.0">MSVSProject</function>,
in which case you presumably want to
build the solution file(s)
by calling the
<function xmlns="http://www.scons.org/dbxsd/v1.0">MSVSSolution</function>
Builder (see below).
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
The <function xmlns="http://www.scons.org/dbxsd/v1.0">MSVSProject</function> builder
takes several lists of filenames
to be placed into the project file.
These are currently limited to
<literal>srcs</literal>,
<literal>incs</literal>,
<literal>localincs</literal>,
<literal>resources</literal>,
and
<literal>misc</literal>.
These are pretty self-explanatory, but it should be noted that these
lists are added to the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SOURCES"><envar>$SOURCES</envar></link> construction variable as strings,
NOT as SCons File Nodes.  This is because they represent file
names to be added to the project file, not the source files used to
build the project file.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
The above filename lists are all optional,
although at least one must be specified
for the resulting project file to be non-empty.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
In addition to the above lists of values,
the following values may be specified:
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
<literal>target</literal>:
The name of the target
<filename>.dsp</filename>
or
<filename>.vcproj</filename>
file.
The correct
suffix for the version of Visual Studio must be used,
but the
<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-MSVSPROJECTSUFFIX"><envar>$MSVSPROJECTSUFFIX</envar></link>
construction variable
will be defined to the correct value (see example below).
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
<literal>variant</literal>:
The name of this particular variant.
For Visual Studio 7 projects,
this can also be a list of variant names.
These are typically things like "Debug" or "Release", but really
can be anything you want.
For Visual Studio 7 projects,
they may also specify a target platform
separated from the variant name by a
<literal>|</literal>
(vertical pipe)
character:
<literal>Debug|Xbox</literal>.
The default target platform is Win32.
Multiple calls to
<function xmlns="http://www.scons.org/dbxsd/v1.0">MSVSProject</function>
with different variants are allowed;
all variants will be added to the project file with their appropriate
build targets and sources.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
<literal>buildtarget</literal>:
An optional string, node, or list of strings or nodes
(one per build variant), to tell the Visual Studio debugger
what output target to use in what build variant.
The number of
<literal>buildtarget</literal>
entries must match the number of
<literal>variant</literal>
entries.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
<literal>runfile</literal>:
The name of the file that Visual Studio 7 and later
will run and debug.
This appears as the value of the
<literal>Output</literal>
field in the resutling Visual Studio project file.
If this is not specified,
the default is the same as the specified
<literal>buildtarget</literal>
value.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
Note that because <application xmlns="http://www.scons.org/dbxsd/v1.0">SCons</application> always executes its build commands
from the directory in which the <filename xmlns="http://www.scons.org/dbxsd/v1.0">SConstruct</filename> file is located,
if you generate a project file in a different directory
than the <filename xmlns="http://www.scons.org/dbxsd/v1.0">SConstruct</filename> directory,
users will not be able to double-click
on the file name in compilation error messages
displayed in the Visual Studio console output window.
This can be remedied by adding the
Visual C/C++
<literal>/FC</literal>
compiler option to the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-CCFLAGS"><envar>$CCFLAGS</envar></link>  variable
so that the compiler will print
the full path name of any
files that cause compilation errors.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
Example usage:
</para>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
barsrcs = ['bar.cpp'],
barincs = ['bar.h'],
barlocalincs = ['StdAfx.h']
barresources = ['bar.rc','resource.h']
barmisc = ['bar_readme.txt']

dll = env.SharedLibrary(target = 'bar.dll',
                        source = barsrcs)

env.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
                srcs = barsrcs,
                incs = barincs,
                localincs = barlocalincs,
                resources = barresources,
                misc = barmisc,
                buildtarget = dll,
                variant = 'Release')
</example_commands>
</listitem>
  </varlistentry>
  <varlistentry id="b-MSVSSolution">
    <term>
      <function>MSVSSolution()</function>
    </term>
    <term>
      <function>env.MSVSSolution()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
Builds a Microsoft Visual Studio solution file.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
This builds a Visual Studio solution file,
based on the version of Visual Studio that is configured
(either the latest installed version,
or the version specified by
<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-MSVS_VERSION"><envar>$MSVS_VERSION</envar></link>
in the construction environment).
For Visual Studio 6, it will generate a
<filename>.dsw</filename>
file.
For Visual Studio 7 (.NET), it will
generate a
<filename>.sln</filename>
file.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
The following values must be specified:
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
<literal>target</literal>:
The name of the target .dsw or .sln file.  The correct
suffix for the version of Visual Studio must be used, but the value
<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-MSVSSOLUTIONSUFFIX"><envar>$MSVSSOLUTIONSUFFIX</envar></link>
will be defined to the correct value (see example below).
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
<literal>variant</literal>:
The name of this particular variant, or a list of variant
names (the latter is only supported for MSVS 7 solutions). These are
typically things like "Debug" or "Release", but really can be anything
you want. For MSVS 7 they may also specify target platform, like this
"Debug|Xbox". Default platform is Win32.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
<literal>projects</literal>:
A list of project file names, or Project nodes returned by calls to the
<function xmlns="http://www.scons.org/dbxsd/v1.0">MSVSProject</function>
Builder,
to be placed into the solution file.
It should be noted that these file names are NOT added to the $SOURCES
environment variable in form of files, but rather as strings.   This
is because they represent file names to be added to the solution file,
not the source files used to build the solution file.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
Example Usage:
</para>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
env.MSVSSolution(target = 'Bar' + env['MSVSSOLUTIONSUFFIX'],
                 projects = ['bar' + env['MSVSPROJECTSUFFIX']],
                 variant = 'Release')
</example_commands>
</listitem>
  </varlistentry>
  <varlistentry id="b-Object">
    <term>
      <function>Object()</function>
    </term>
    <term>
      <function>env.Object()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
A synonym for the
<function xmlns="http://www.scons.org/dbxsd/v1.0">StaticObject</function>
builder method.
</para>
</listitem>
  </varlistentry>
  <varlistentry id="b-Package">
    <term>
      <function>Package()</function>
    </term>
    <term>
      <function>env.Package()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
Builds a Binary Package of the given source files. 
</para>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
env.Package(source = FindInstalledFiles())
</example_commands>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
Builds software distribution packages.
Packages consist of files to install and packaging information.
The former may be specified with the <varname xmlns="http://www.scons.org/dbxsd/v1.0">source</varname> parameter and may be left out,
in which case the <function xmlns="http://www.scons.org/dbxsd/v1.0">FindInstalledFiles</function> function will collect
all files that have an <function xmlns="http://www.scons.org/dbxsd/v1.0">Install</function> or <function xmlns="http://www.scons.org/dbxsd/v1.0">InstallAs</function> Builder attached.
If the <varname xmlns="http://www.scons.org/dbxsd/v1.0">target</varname> is not specified
it will be deduced from additional information given to this Builder.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
The packaging information is specified
with the help of construction variables documented below.
This information is called a tag to stress that
some of them can also be attached to files with the <function xmlns="http://www.scons.org/dbxsd/v1.0">Tag</function> function.
The mandatory ones will complain if they were not specified.
They vary depending on chosen target packager.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
The target packager may be selected with the "PACKAGETYPE" command line
option or with the <envar xmlns="http://www.scons.org/dbxsd/v1.0">$PACKAGETYPE</envar> construction variable. Currently
the following packagers available:
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
 * msi - Microsoft Installer
 * rpm - Redhat Package Manger
 * ipkg - Itsy Package Management System
 * tarbz2 - compressed tar
 * targz - compressed tar
 * zip - zip file
 * src_tarbz2 - compressed tar source
 * src_targz - compressed tar source
 * src_zip - zip file source
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
An updated list is always available under the "package_type" option when
running "scons --help" on a project that has packaging activated.
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
env = Environment(tools=['default', 'packaging'])
env.Install('/bin/', 'my_program')
env.Package( NAME           = 'foo',
             VERSION        = '1.2.3',
             PACKAGEVERSION = 0,
             PACKAGETYPE    = 'rpm',
             LICENSE        = 'gpl',
             SUMMARY        = 'balalalalal',
             DESCRIPTION    = 'this should be really really long',
             X_RPM_GROUP    = 'Application/fu',
             SOURCE_URL     = 'http://foo.org/foo-1.2.3.tar.gz'
        )
</example_commands>
</listitem>
  </varlistentry>
  <varlistentry id="b-PCH">
    <term>
      <function>PCH()</function>
    </term>
    <term>
      <function>env.PCH()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
Builds a Microsoft Visual C++ precompiled header.
Calling this builder method
returns a list of two targets: the PCH as the first element, and the object
file as the second element. Normally the object file is ignored.
This builder method is only
provided when Microsoft Visual C++ is being used as the compiler.
The PCH builder method is generally used in
conjuction with the PCH construction variable to force object files to use
the precompiled header:
</para>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
env['PCH'] = env.PCH('StdAfx.cpp')[0]
</example_commands>
</listitem>
  </varlistentry>
  <varlistentry id="b-PDF">
    <term>
      <function>PDF()</function>
    </term>
    <term>
      <function>env.PDF()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
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 <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-PDFSUFFIX"><envar>$PDFSUFFIX</envar></link> construction variable
(<filename>.pdf</filename> by default)
is added automatically to the target
if it is not already present.  Example:
</para>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
# 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_commands>
</listitem>
  </varlistentry>
  <varlistentry id="b-POInit">
    <term>
      <function>POInit()</function>
    </term>
    <term>
      <function>env.POInit()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
This builder belongs to <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="t-msginit"><literal>msginit</literal></link> tool. The builder initializes missing
<literal>PO</literal> file(s) if <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-POAUTOINIT"><envar>$POAUTOINIT</envar></link> is set.  If
<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-POAUTOINIT"><envar>$POAUTOINIT</envar></link> is not set (default), <function xmlns="http://www.scons.org/dbxsd/v1.0">POInit</function> prints instruction for
user (that is supposed to be a translator), telling how the
<literal>PO</literal> file should be initialized. In normal projects
<emphasis>you should not use <function xmlns="http://www.scons.org/dbxsd/v1.0">POInit</function> and use <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-POUpdate"><function>POUpdate</function></link>
instead</emphasis>. <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-POUpdate"><function>POUpdate</function></link> chooses intelligently between
<command>msgmerge(1)</command> and <command>msginit(1)</command>. <function xmlns="http://www.scons.org/dbxsd/v1.0">POInit</function>
always uses <command>msginit(1)</command> and should be regarded as builder for
special purposes or for temporary use (e.g. for quick, one time initialization
of a bunch of <literal>PO</literal> files) or for tests.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
Target nodes defined through <function xmlns="http://www.scons.org/dbxsd/v1.0">POInit</function> are not built by default (they're
<literal>Ignore</literal>d from <literal>'.'</literal> node) but are added to
special <literal>Alias</literal> (<literal>'po-create'</literal> by default).
The alias name may be changed through the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-POCREATE_ALIAS"><envar>$POCREATE_ALIAS</envar></link>
construction variable. All <literal>PO</literal> files defined through
<function xmlns="http://www.scons.org/dbxsd/v1.0">POInit</function> may be easily initialized by <command>scons po-create</command>.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
<emphasis>Example 1</emphasis>.
Initialize <filename>en.po</filename> and <filename>pl.po</filename> from
<filename>messages.pot</filename>:
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
  # ...
  env.POInit(['en', 'pl']) # messages.pot --&gt; [en.po, pl.po] 
</example_commands>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
<emphasis>Example 2</emphasis>.
Initialize <filename>en.po</filename> and <filename>pl.po</filename> from
<filename>foo.pot</filename>:
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
  # ...
  env.POInit(['en', 'pl'], ['foo']) # foo.pot --&gt; [en.po, pl.po] 
</example_commands>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
<emphasis>Example 3</emphasis>.
Initialize <filename>en.po</filename> and <filename>pl.po</filename> from
<filename>foo.pot</filename> but using <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-POTDOMAIN"><envar>$POTDOMAIN</envar></link> construction
variable:
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
  # ...
  env.POInit(['en', 'pl'], POTDOMAIN='foo') # foo.pot --&gt; [en.po, pl.po] 
</example_commands>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
<emphasis>Example 4</emphasis>.
Initialize <literal>PO</literal> files for languages defined in
<filename>LINGUAS</filename> file. The files will be initialized from template
<filename>messages.pot</filename>:
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
  # ...
  env.POInit(LINGUAS_FILE = 1) # needs 'LINGUAS' file
</example_commands>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
<emphasis>Example 5</emphasis>.
Initialize <filename>en.po</filename> and <filename>pl.pl</filename>
<literal>PO</literal> files plus files for languages defined in
<filename>LINGUAS</filename> file. The files will be initialized from template
<filename>messages.pot</filename>:
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
  # ...
  env.POInit(['en', 'pl'], LINGUAS_FILE = 1)
</example_commands>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
<emphasis>Example 6</emphasis>.
You may preconfigure your environment first, and then initialize
<literal>PO</literal> files:
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
  # ...
  env['POAUTOINIT'] = 1
  env['LINGUAS_FILE'] = 1
  env['POTDOMAIN'] = 'foo'
  env.POInit()
</example_commands>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
which has same efect as:
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
  # ...
  env.POInit(POAUTOINIT = 1, LINGUAS_FILE = 1, POTDOMAIN = 'foo')
</example_commands>
</listitem>
  </varlistentry>
  <varlistentry id="b-PostScript">
    <term>
      <function>PostScript()</function>
    </term>
    <term>
      <function>env.PostScript()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
Builds a <filename>.ps</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 <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-PSSUFFIX"><envar>$PSSUFFIX</envar></link> construction variable
(<filename>.ps</filename> by default)
is added automatically to the target
if it is not already present.  Example:
</para>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
# builds from aaa.tex
env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
# builds bbb.ps from bbb.dvi
env.PostScript(target = 'bbb', source = 'bbb.dvi')
</example_commands>
</listitem>
  </varlistentry>
  <varlistentry id="b-POTUpdate">
    <term>
      <function>POTUpdate()</function>
    </term>
    <term>
      <function>env.POTUpdate()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
The builder belongs to <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="t-xgettext"><literal>xgettext</literal></link> tool. The builder updates target
<literal>POT</literal> file if exists or creates one if it doesn't. The node is
not built by default (i.e. it is <literal>Ignore</literal>d from
<literal>'.'</literal>), but only on demand (i.e.  when given
<literal>POT</literal> file is required or when special alias is invoked). This
builder adds its targe node (<filename>messages.pot</filename>, say) to a
special alias (<literal>pot-update</literal> by default, see
<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-POTUPDATE_ALIAS"><envar>$POTUPDATE_ALIAS</envar></link>) so you can update/create them easily with
<command>scons pot-update</command>. The file is not written until there is no
real change in internationalized messages (or in comments that enter
<literal>POT</literal> file). 
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
<note> <para>You may see <command>xgettext(1)</command> being invoked by the
<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="t-xgettext"><literal>xgettext</literal></link> tool even if there is no real change in internationalized
messages (so the <literal>POT</literal> file is not being updated).  This
happens every time  a source file has changed. In such case we invoke
<command>xgettext(1)</command> and compare its output with the content of
<literal>POT</literal> file to decide whether the file should be updated or
not.</para></note>
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
<emphasis>Example 1.</emphasis>
Let's create <filename>po/</filename> directory and place following
<filename>SConstruct</filename> script there:
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
  # SConstruct in 'po/' subdir
  env = Environment( tools = ['default', 'xgettext'] )
  env.POTUpdate(['foo'], ['../a.cpp', '../b.cpp'])
  env.POTUpdate(['bar'], ['../c.cpp', '../d.cpp'])
</example_commands>      
<para xmlns="http://www.scons.org/dbxsd/v1.0">
Then invoke scons few times:
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
  user@host:$ scons             # Does not create foo.pot nor bar.pot
  user@host:$ scons foo.pot     # Updates or creates foo.pot
  user@host:$ scons pot-update  # Updates or creates foo.pot and bar.pot
  user@host:$ scons -c          # Does not clean foo.pot nor bar.pot.
</example_commands>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
the results shall be as the comments above say.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
<emphasis>Example 2.</emphasis>
The <function xmlns="http://www.scons.org/dbxsd/v1.0">POTUpdate</function> builder may be used with no target specified, in which
case default target <filename>messages.pot</filename> will be used. The
default target may also be overriden by setting <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-POTDOMAIN"><envar>$POTDOMAIN</envar></link> construction
variable or providing it as an override to <function xmlns="http://www.scons.org/dbxsd/v1.0">POTUpdate</function> builder:
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">    
  # SConstruct script
  env = Environment( tools = ['default', 'xgettext'] )
  env['POTDOMAIN'] = "foo"
  env.POTUpdate(source = ["a.cpp", "b.cpp"]) # Creates foo.pot ...
  env.POTUpdate(POTDOMAIN = "bar", source = ["c.cpp", "d.cpp"]) # and bar.pot
</example_commands>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
<emphasis>Example 3.</emphasis>
The sources may be specified within separate file, for example
<filename>POTFILES.in</filename>:
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">      
  # POTFILES.in in 'po/' subdirectory
  ../a.cpp
  ../b.cpp
  # end of file
</example_commands>    
<para xmlns="http://www.scons.org/dbxsd/v1.0">
The name of the file (<filename>POTFILES.in</filename>) containing the list of
sources is provided via <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-XGETTEXTFROM"><envar>$XGETTEXTFROM</envar></link>:
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">      
  # SConstruct file in 'po/' subdirectory
  env = Environment( tools = ['default', 'xgettext'] )
  env.POTUpdate(XGETTEXTFROM = 'POTFILES.in')
</example_commands>    

<para xmlns="http://www.scons.org/dbxsd/v1.0">
<emphasis>Example 4.</emphasis>
You may use <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-XGETTEXTPATH"><envar>$XGETTEXTPATH</envar></link> to define source search path. Assume, for
example, that you have files <filename>a.cpp</filename>,
<filename>b.cpp</filename>, <filename>po/SConstruct</filename>,
<filename>po/POTFILES.in</filename>. Then your <literal>POT</literal>-related
files could look as below:
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
  # POTFILES.in in 'po/' subdirectory
  a.cpp
  b.cpp
  # end of file
</example_commands>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
  # SConstruct file in 'po/' subdirectory
  env = Environment( tools = ['default', 'xgettext'] )
  env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH='../')
</example_commands>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
<emphasis>Example 5.</emphasis>
Multiple search directories may be defined within a list, i.e.
<literal>XGETTEXTPATH = ['dir1', 'dir2', ...]</literal>. The order in the list
determines the search order of source files. The path to the first file found
is used.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
Let's create <filename>0/1/po/SConstruct</filename> script:
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
  # SConstruct file in '0/1/po/' subdirectory
  env = Environment( tools = ['default', 'xgettext'] )
  env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../', '../../'])
</example_commands>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
and <filename>0/1/po/POTFILES.in</filename>:
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
  # POTFILES.in in '0/1/po/' subdirectory
  a.cpp
  # end of file
</example_commands>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
Write two <filename>*.cpp</filename> files, the first one is
<filename>0/a.cpp</filename>:
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
  /* 0/a.cpp */
  gettext("Hello from ../../a.cpp")
</example_commands>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
and the second is <filename>0/1/a.cpp</filename>:
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
  /* 0/1/a.cpp */
  gettext("Hello from ../a.cpp")
</example_commands>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
then run scons. You'll obtain <literal>0/1/po/messages.pot</literal> with the
message <literal>"Hello from ../a.cpp"</literal>. When you reverse order in
<varname>$XGETTEXTFOM</varname>, i.e. when you write SConscript as
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
  # SConstruct file in '0/1/po/' subdirectory
  env = Environment( tools = ['default', 'xgettext'] )
  env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../../', '../'])
</example_commands> 
<para xmlns="http://www.scons.org/dbxsd/v1.0">
then the <filename>messages.pot</filename> will contain
<literal>msgid "Hello from ../../a.cpp"</literal> line and not 
<literal>msgid "Hello from ../a.cpp"</literal>.
</para>

</listitem>
  </varlistentry>
  <varlistentry id="b-POUpdate">
    <term>
      <function>POUpdate()</function>
    </term>
    <term>
      <function>env.POUpdate()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
The builder belongs to <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="t-msgmerge"><literal>msgmerge</literal></link> tool. The builder updates
<literal>PO</literal> files with <command>msgmerge(1)</command>, or initializes
missing <literal>PO</literal> files as described in documentation of
<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="t-msginit"><literal>msginit</literal></link> tool and <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-POInit"><function>POInit</function></link> builder (see also
<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-POAUTOINIT"><envar>$POAUTOINIT</envar></link>). Note, that <function xmlns="http://www.scons.org/dbxsd/v1.0">POUpdate</function> <emphasis>does not add its
targets to <literal>po-create</literal> alias</emphasis> as <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-POInit"><function>POInit</function></link>
does.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
Target nodes defined through <function xmlns="http://www.scons.org/dbxsd/v1.0">POUpdate</function> are not built by default
(they're <literal>Ignore</literal>d from <literal>'.'</literal> node). Instead,
they are added automatically to special <literal>Alias</literal> 
(<literal>'po-update'</literal> by default). The alias name may be changed
through the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-POUPDATE_ALIAS"><envar>$POUPDATE_ALIAS</envar></link> construction variable.  You can easilly 
update <literal>PO</literal> files in your project by <command>scons
po-update</command>.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
<emphasis>Example 1.</emphasis>
Update <filename>en.po</filename> and <filename>pl.po</filename> from
<filename>messages.pot</filename> template (see also <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-POTDOMAIN"><envar>$POTDOMAIN</envar></link>),
assuming that the later one exists or there is rule to build it (see
<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-POTUpdate"><function>POTUpdate</function></link>):
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
  # ...
  env.POUpdate(['en','pl']) # messages.pot --&gt; [en.po, pl.po]
</example_commands>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
<emphasis>Example 2.</emphasis>
Update <filename>en.po</filename> and <filename>pl.po</filename> from
<filename>foo.pot</filename> template:
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
  # ...
  env.POUpdate(['en', 'pl'], ['foo']) # foo.pot --&gt;  [en.po, pl.pl]
</example_commands>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
<emphasis>Example 3.</emphasis>
Update <filename>en.po</filename> and <filename>pl.po</filename> from
<filename>foo.pot</filename> (another version):
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
  # ...
  env.POUpdate(['en', 'pl'], POTDOMAIN='foo') # foo.pot -- &gt; [en.po, pl.pl]
</example_commands>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
<emphasis>Example 4.</emphasis>
Update files for languages defined in <filename>LINGUAS</filename> file. The
files are updated from <filename>messages.pot</filename> template:
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
  # ...
  env.POUpdate(LINGUAS_FILE = 1) # needs 'LINGUAS' file
</example_commands>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
<emphasis>Example 5.</emphasis>
Same as above, but update from <filename>foo.pot</filename> template:
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
  # ...
  env.POUpdate(LINGUAS_FILE = 1, source = ['foo'])
</example_commands>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
<emphasis>Example 6.</emphasis>
Update <filename>en.po</filename> and <filename>pl.po</filename> plus files for
languages defined in <filename>LINGUAS</filename> file. The files are updated
from <filename>messages.pot</filename> template:
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
  # produce 'en.po', 'pl.po' + files defined in 'LINGUAS':
  env.POUpdate(['en', 'pl' ], LINGUAS_FILE = 1) 
</example_commands>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
<emphasis>Example 7.</emphasis>
Use <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-POAUTOINIT"><envar>$POAUTOINIT</envar></link> to automatically initialize <literal>PO</literal> file
if it doesn't exist:
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
  # ...
  env.POUpdate(LINGUAS_FILE = 1, POAUTOINIT = 1)
</example_commands>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
<emphasis>Example 8.</emphasis>
Update <literal>PO</literal> files for languages defined in
<filename>LINGUAS</filename> file. The files are updated from
<filename>foo.pot</filename> template. All necessary settings are
pre-configured via environment.
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
  # ...
  env['POAUTOINIT'] = 1
  env['LINGUAS_FILE'] = 1
  env['POTDOMAIN'] = 'foo'
  env.POUpdate()
</example_commands>

</listitem>
  </varlistentry>
  <varlistentry id="b-Program">
    <term>
      <function>Program()</function>
    </term>
    <term>
      <function>env.Program()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
Builds an executable given one or more object files
or C, C++, D, or Fortran source files.
If any C, C++, D or Fortran source files are specified,
then they will be automatically
compiled to object files using the
<function xmlns="http://www.scons.org/dbxsd/v1.0">Object</function>
builder method;
see that builder method's description for
a list of legal source file suffixes
and how they are interpreted.
The target executable file prefix
(specified by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-PROGPREFIX"><envar>$PROGPREFIX</envar></link> construction variable; nothing by default)
and suffix
(specified by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-PROGSUFFIX"><envar>$PROGSUFFIX</envar></link> construction variable;
by default, <filename>.exe</filename> on Windows systems,
nothing on POSIX systems)
are automatically added to the target if not already present.
Example:
</para>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
</example_commands>
</listitem>
  </varlistentry>
  <varlistentry id="b-RES">
    <term>
      <function>RES()</function>
    </term>
    <term>
      <function>env.RES()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
Builds a Microsoft Visual C++ resource file.
This builder method is only provided
when Microsoft Visual C++ or MinGW is being used as the compiler. The
<filename>.res</filename>
(or
<filename>.o</filename>
for MinGW) suffix is added to the target name if no other suffix is given.
The source
file is scanned for implicit dependencies as though it were a C file.
Example:
</para>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
env.RES('resource.rc')
</example_commands>
</listitem>
  </varlistentry>
  <varlistentry id="b-RMIC">
    <term>
      <function>RMIC()</function>
    </term>
    <term>
      <function>env.RMIC()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
Builds stub and skeleton class files
for remote objects
from Java <filename>.class</filename> files.
The target is a directory
relative to which the stub
and skeleton class files will be written.
The source can be the names of <filename>.class</filename> files,
or the objects return from the
<function xmlns="http://www.scons.org/dbxsd/v1.0">Java</function>
builder method.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
If the construction variable
<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-JAVACLASSDIR"><envar>$JAVACLASSDIR</envar></link>
is set, either in the environment
or in the call to the
<function xmlns="http://www.scons.org/dbxsd/v1.0">RMIC</function>
builder method itself,
then the value of the variable
will be stripped from the
beginning of any <filename>.class </filename>
file names.
</para>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
classes = env.Java(target = 'classdir', source = 'src')
env.RMIC(target = 'outdir1', source = classes)

env.RMIC(target = 'outdir2',
         source = ['package/foo.class', 'package/bar.class'])

env.RMIC(target = 'outdir3',
         source = ['classes/foo.class', 'classes/bar.class'],
         JAVACLASSDIR = 'classes')
</example_commands>
</listitem>
  </varlistentry>
  <varlistentry id="b-RPCGenClient">
    <term>
      <function>RPCGenClient()</function>
    </term>
    <term>
      <function>env.RPCGenClient()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
Generates an RPC client stub (<filename>_clnt.c</filename>) file
from a specified RPC (<filename>.x</filename>) source file.
Because rpcgen only builds output files
in the local directory,
the command will be executed
in the source file's directory by default.
</para>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
# Builds src/rpcif_clnt.c
env.RPCGenClient('src/rpcif.x')
</example_commands>
</listitem>
  </varlistentry>
  <varlistentry id="b-RPCGenHeader">
    <term>
      <function>RPCGenHeader()</function>
    </term>
    <term>
      <function>env.RPCGenHeader()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
Generates an RPC header (<filename>.h</filename>) file
from a specified RPC (<filename>.x</filename>) source file.
Because rpcgen only builds output files
in the local directory,
the command will be executed
in the source file's directory by default.
</para>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
# Builds src/rpcif.h
env.RPCGenHeader('src/rpcif.x')
</example_commands>
</listitem>
  </varlistentry>
  <varlistentry id="b-RPCGenService">
    <term>
      <function>RPCGenService()</function>
    </term>
    <term>
      <function>env.RPCGenService()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
Generates an RPC server-skeleton (<filename>_svc.c</filename>) file
from a specified RPC (<filename>.x</filename>) source file.
Because rpcgen only builds output files
in the local directory,
the command will be executed
in the source file's directory by default.
</para>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
# Builds src/rpcif_svc.c
env.RPCGenClient('src/rpcif.x')
</example_commands>
</listitem>
  </varlistentry>
  <varlistentry id="b-RPCGenXDR">
    <term>
      <function>RPCGenXDR()</function>
    </term>
    <term>
      <function>env.RPCGenXDR()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
Generates an RPC XDR routine (<filename>_xdr.c</filename>) file
from a specified RPC (<filename>.x</filename>) source file.
Because rpcgen only builds output files
in the local directory,
the command will be executed
in the source file's directory by default.
</para>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
# Builds src/rpcif_xdr.c
env.RPCGenClient('src/rpcif.x')
</example_commands>
</listitem>
  </varlistentry>
  <varlistentry id="b-SharedLibrary">
    <term>
      <function>SharedLibrary()</function>
    </term>
    <term>
      <function>env.SharedLibrary()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
Builds a shared library
(<filename>.so</filename> on a POSIX system,
<filename>.dll</filename> on Windows)
given one or more object files
or C, C++, D or Fortran source files.
If any source files are given,
then they will be automatically
compiled to object files.
The static library prefix and suffix (if any)
are automatically added to the target.
The target library file prefix
(specified by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHLIBPREFIX"><envar>$SHLIBPREFIX</envar></link> construction variable;
by default, <filename>lib</filename> on POSIX systems,
nothing on Windows systems)
and suffix
(specified by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHLIBSUFFIX"><envar>$SHLIBSUFFIX</envar></link> construction variable;
by default, <filename>.dll</filename> on Windows systems,
<filename>.so</filename> on POSIX systems)
are automatically added to the target if not already present.
Example:
</para>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
</example_commands>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
On Windows systems, the
<function xmlns="http://www.scons.org/dbxsd/v1.0">SharedLibrary</function>
builder method will always build an import
(<filename>.lib</filename>) library
in addition to the shared (<filename>.dll</filename>) library,
adding a <filename>.lib</filename> library with the same basename
if there is not already a <filename>.lib</filename> file explicitly
listed in the targets.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
Any object files listed in the
<literal>source</literal>
must have been built for a shared library
(that is, using the
<function xmlns="http://www.scons.org/dbxsd/v1.0">SharedObject</function>
builder method).
<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
will raise an error if there is any mismatch.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
On some platforms, there is a distinction between a shared library
(loaded automatically by the system to resolve external references)
and a loadable module (explicitly loaded by user action).
For maximum portability, use the <function xmlns="http://www.scons.org/dbxsd/v1.0">LoadableModule</function> builder for the latter.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
When the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHLIBVERSION"><envar>$SHLIBVERSION</envar></link> construction variable is defined a versioned
shared library is created. This modifies the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHLINKFLAGS"><envar>$SHLINKFLAGS</envar></link> as required,
adds the version number to the library name, and creates the symlinks that
are needed. <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHLIBVERSION"><envar>$SHLIBVERSION</envar></link> needs to be of the form X.Y.Z, where X
and Y are numbers, and Z is a number but can also contain letters to designate
alpha, beta, or release candidate patch levels.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
This builder may create multiple links to the library. On a POSIX system,
for the shared library libbar.so.2.3.1, the links created would be
libbar.so, libbar.so.2, and libbar.so.2.3; on a Darwin (OSX) system
the library would be libbar.2.3.1.dylib and the link would be
libbar.dylib.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
On Windows systems, specifying
<literal>register=1</literal>
will cause the <filename>.dll</filename> to be
registered after it is built using REGSVR32.
The command that is run
("regsvr32" by default) is determined by <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-REGSVR"><envar>$REGSVR</envar></link> construction
variable, and the flags passed are determined by <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-REGSVRFLAGS"><envar>$REGSVRFLAGS</envar></link>.  By
default, <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-REGSVRFLAGS"><envar>$REGSVRFLAGS</envar></link> includes the <option>/s</option> option,
to prevent dialogs from popping
up and requiring user attention when it is run.  If you change
<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-REGSVRFLAGS"><envar>$REGSVRFLAGS</envar></link>, be sure to include the <option>/s</option> option.
For example,
</para>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
env.SharedLibrary(target = 'bar',
                  source = ['bar.cxx', 'foo.obj'],
                  register=1)
</example_commands>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
will register <filename>bar.dll</filename> as a COM object
when it is done linking it.
</para>
</listitem>
  </varlistentry>
  <varlistentry id="b-SharedObject">
    <term>
      <function>SharedObject()</function>
    </term>
    <term>
      <function>env.SharedObject()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
Builds an object file for
inclusion in a shared library.
Source files must have one of the same set of extensions
specified above for the
<function xmlns="http://www.scons.org/dbxsd/v1.0">StaticObject</function>
builder method.
On some platforms building a shared object requires additional
compiler option
(e.g. <option>-fPIC</option> for gcc)
in addition to those needed to build a
normal (static) object, but on some platforms there is no difference between a
shared object and a normal (static) one. When there is a difference, SCons
will only allow shared objects to be linked into a shared library, and will
use a different suffix for shared objects. On platforms where there is no
difference, SCons will allow both normal (static)
and shared objects to be linked into a
shared library, and will use the same suffix for shared and normal
(static) objects.
The target object file prefix
(specified by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHOBJPREFIX"><envar>$SHOBJPREFIX</envar></link> construction variable;
by default, the same as <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-OBJPREFIX"><envar>$OBJPREFIX</envar></link>)
and suffix
(specified by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHOBJSUFFIX"><envar>$SHOBJSUFFIX</envar></link> construction variable)
are automatically added to the target if not already present.
Examples:
</para>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
env.SharedObject(target = 'ddd', source = 'ddd.c')
env.SharedObject(target = 'eee.o', source = 'eee.cpp')
env.SharedObject(target = 'fff.obj', source = 'fff.for')
</example_commands>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
Note that the source files will be scanned
according to the suffix mappings in the
<literal>SourceFileScanner</literal>
object.
See the section "Scanner Objects,"
below, for more information.
</para>
</listitem>
  </varlistentry>
  <varlistentry id="b-StaticLibrary">
    <term>
      <function>StaticLibrary()</function>
    </term>
    <term>
      <function>env.StaticLibrary()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
Builds a static library given one or more object files
or C, C++, D or Fortran source files.
If any source files are given,
then they will be automatically
compiled to object files.
The static library prefix and suffix (if any)
are automatically added to the target.
The target library file prefix
(specified by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-LIBPREFIX"><envar>$LIBPREFIX</envar></link> construction variable;
by default, <filename>lib</filename> on POSIX systems,
nothing on Windows systems)
and suffix
(specified by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-LIBSUFFIX"><envar>$LIBSUFFIX</envar></link> construction variable;
by default, <filename>.lib</filename> on Windows systems,
<filename>.a</filename> on POSIX systems)
are automatically added to the target if not already present.
Example:
</para>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
</example_commands>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
Any object files listed in the
<literal>source</literal>
must have been built for a static library
(that is, using the
<function xmlns="http://www.scons.org/dbxsd/v1.0">StaticObject</function>
builder method).
<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
will raise an error if there is any mismatch.
</para>
</listitem>
  </varlistentry>
  <varlistentry id="b-StaticObject">
    <term>
      <function>StaticObject()</function>
    </term>
    <term>
      <function>env.StaticObject()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
Builds a static object file
from one or more C, C++, D, or Fortran source files.
Source files must have one of the following extensions:
</para>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
  .asm    assembly language file
  .ASM    assembly language file
  .c      C file
  .C      Windows:  C file
          POSIX:  C++ file
  .cc     C++ file
  .cpp    C++ file
  .cxx    C++ file
  .cxx    C++ file
  .c++    C++ file
  .C++    C++ file
  .d      D file
  .f      Fortran file
  .F      Windows:  Fortran file
          POSIX:  Fortran file + C pre-processor
  .for    Fortran file
  .FOR    Fortran file
  .fpp    Fortran file + C pre-processor
  .FPP    Fortran file + C pre-processor
  .m      Object C file
  .mm     Object C++ file
  .s      assembly language file
  .S      Windows:  assembly language file
          ARM: CodeSourcery Sourcery Lite
  .sx     assembly language file + C pre-processor
          POSIX:  assembly language file + C pre-processor
  .spp    assembly language file + C pre-processor
  .SPP    assembly language file + C pre-processor
</example_commands>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
The target object file prefix
(specified by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-OBJPREFIX"><envar>$OBJPREFIX</envar></link> construction variable; nothing by default)
and suffix
(specified by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-OBJSUFFIX"><envar>$OBJSUFFIX</envar></link> construction variable;
<filename>.obj</filename> on Windows systems,
<filename>.o</filename> on POSIX systems)
are automatically added to the target if not already present.
Examples:
</para>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
env.StaticObject(target = 'aaa', source = 'aaa.c')
env.StaticObject(target = 'bbb.o', source = 'bbb.c++')
env.StaticObject(target = 'ccc.obj', source = 'ccc.f')
</example_commands>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
Note that the source files will be scanned
according to the suffix mappings in
<literal>SourceFileScanner</literal>
object.
See the section "Scanner Objects,"
below, for more information.
</para>
</listitem>
  </varlistentry>
  <varlistentry id="b-Substfile">
    <term>
      <function>Substfile()</function>
    </term>
    <term>
      <function>env.Substfile()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
The <function xmlns="http://www.scons.org/dbxsd/v1.0">Substfile</function> builder generates a single text file
by concatenating the source files.
Nested lists of sources are flattened. 
<envar xmlns="http://www.scons.org/dbxsd/v1.0">$LINESEPARATOR</envar> is used to separate the source files;
see the description of <function xmlns="http://www.scons.org/dbxsd/v1.0">Textfile</function> for details.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
If a single source file is present with an <filename>.in</filename> suffix,
the suffix is stripped and the remainder is used as the default target name.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
The prefix and suffix specified by the <envar xmlns="http://www.scons.org/dbxsd/v1.0">$SUBSTFILEPREFIX</envar>
and <envar xmlns="http://www.scons.org/dbxsd/v1.0">$SUBSTFILESUFFIX</envar> construction variables
(the null string by default in both cases)
are automatically added to the target if they are not already present.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
If a construction variable named <envar xmlns="http://www.scons.org/dbxsd/v1.0">$SUBST_DICT</envar> is present,
it may be either a Python dictionary or a sequence of (key,value) tuples.
If the former,
the dictionary is converted into a list of tuples in an arbitrary order,
so if one key is a prefix of another key
or if one substitution could be further expanded by another subsitition,
it is unpredictible whether the expansion will occur.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
Any occurences in the source of a key
are replaced by the corresponding value,
which may be a Python callable function or a string.
If a value is a function,
it is first called (with no arguments) to produce a string.
The string is <emphasis>subst</emphasis>-expanded
and the result replaces the key.
</para>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
env = Environment(tools = ['default', 'textfile'])

env['prefix'] = '/usr/bin'
script_dict = {'@prefix@': '/bin', @exec_prefix@: '$prefix'}
env.Substfile('script.in', SUBST_DICT = script_dict)

conf_dict = {'%VERSION%': '1.2.3', '%BASE%': 'MyProg'}
env.Substfile('config.h.in', conf_dict, SUBST_DICT = conf_dict)

# UNPREDICTABLE - one key is a prefix of another
bad_foo = {'$foo': '$foo', '$foobar': '$foobar'}
env.Substfile('foo.in', SUBST_DICT = bad_foo)

# PREDICTABLE - keys are applied longest first
good_foo = [('$foobar', '$foobar'), ('$foo', '$foo')]
env.Substfile('foo.in', SUBST_DICT = good_foo)

# UNPREDICTABLE - one substitution could be futher expanded
bad_bar = {'@bar@': '@soap@', '@soap@': 'lye'}
env.Substfile('bar.in', SUBST_DICT = bad_bar)

# PREDICTABLE - substitutions are expanded in order
good_bar = (('@bar@', '@soap@'), ('@soap@', 'lye'))
env.Substfile('bar.in', SUBST_DICT = good_bar)

# the SUBST_DICT may be in common (and not an override)
substutions = {}
subst = Environment(tools = ['textfile'], SUBST_DICT = substitutions)
substitutions['@foo@'] = 'foo'
subst['SUBST_DICT']['@bar@'] = 'bar'
subst.Substfile('pgm1.c', [Value('#include "@foo@.h"'),
                           Value('#include "@bar@.h"'),
                           "common.in",
                           "pgm1.in"
                          ])
subst.Substfile('pgm2.c', [Value('#include "@foo@.h"'),
                           Value('#include "@bar@.h"'),
                           "common.in",
                           "pgm2.in"
                          ])

</example_commands>
</listitem>
  </varlistentry>
  <varlistentry id="b-Tar">
    <term>
      <function>Tar()</function>
    </term>
    <term>
      <function>env.Tar()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
Builds a tar archive of the specified files
and/or directories.
Unlike most builder methods,
the
<function xmlns="http://www.scons.org/dbxsd/v1.0">Tar</function>
builder method may be called multiple times
for a given target;
each additional call
adds to the list of entries
that will be built into the archive.
Any source directories will
be scanned for changes to
any on-disk files,
regardless of whether or not
<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
knows about them from other Builder or function calls.
</para>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
env.Tar('src.tar', 'src')

# Create the stuff.tar file.
env.Tar('stuff', ['subdir1', 'subdir2'])
# Also add "another" to the stuff.tar file.
env.Tar('stuff', 'another')

# Set TARFLAGS to create a gzip-filtered archive.
env = Environment(TARFLAGS = '-c -z')
env.Tar('foo.tar.gz', 'foo')

# Also set the suffix to .tgz.
env = Environment(TARFLAGS = '-c -z',
                  TARSUFFIX = '.tgz')
env.Tar('foo')
</example_commands>
</listitem>
  </varlistentry>
  <varlistentry id="b-Textfile">
    <term>
      <function>Textfile()</function>
    </term>
    <term>
      <function>env.Textfile()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
The <function xmlns="http://www.scons.org/dbxsd/v1.0">Textfile</function> builder generates a single text file.
The source strings constitute the lines;
nested lists of sources are flattened. 
<envar xmlns="http://www.scons.org/dbxsd/v1.0">$LINESEPARATOR</envar> is used to separate the strings.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
If present, the <envar xmlns="http://www.scons.org/dbxsd/v1.0">$SUBST_DICT</envar> construction variable
is used to modify the strings before they are written;
see the <function xmlns="http://www.scons.org/dbxsd/v1.0">Substfile</function> description for details.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
The prefix and suffix specified by the <envar xmlns="http://www.scons.org/dbxsd/v1.0">$TEXTFILEPREFIX</envar>
and <envar xmlns="http://www.scons.org/dbxsd/v1.0">$TEXTFILESUFFIX</envar> construction variables
(the null string and <filename>.txt</filename> by default, respectively)
are automatically added to the target if they are not already present.
Examples:
</para>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
# builds/writes foo.txt
env.Textfile(target = 'foo.txt', source = ['Goethe', 42, 'Schiller'])

# builds/writes bar.txt
env.Textfile(target = 'bar',
             source = ['lalala', 'tanteratei'],
             LINESEPARATOR='|*')

# nested lists are flattened automatically
env.Textfile(target = 'blob', 
             source = ['lalala', ['Goethe', 42 'Schiller'], 'tanteratei'])

# files may be used as input by wraping them in File()
env.Textfile(target = 'concat',  # concatenate files with a marker between
             source = [File('concat1'), File('concat2')],
             LINESEPARATOR = '====================\n')

Results are:
foo.txt
  ....8&lt;----
  Goethe
  42
  Schiller
  ....8&lt;---- (no linefeed at the end)

bar.txt:
  ....8&lt;----
  lalala|*tanteratei
  ....8&lt;---- (no linefeed at the end)

blob.txt
  ....8&lt;----
  lalala
  Goethe
  42
  Schiller
  tanteratei
  ....8&lt;---- (no linefeed at the end)
</example_commands>
</listitem>
  </varlistentry>
  <varlistentry id="b-Translate">
    <term>
      <function>Translate()</function>
    </term>
    <term>
      <function>env.Translate()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
This pseudo-builder belongs to <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="t-gettext"><literal>gettext</literal></link> toolset. The builder extracts
internationalized messages from source files, updates <literal>POT</literal>
template (if necessary) and then updates <literal>PO</literal> translations (if
necessary). If <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-POAUTOINIT"><envar>$POAUTOINIT</envar></link> is set, missing <literal>PO</literal> files
will be automatically created (i.e. without translator person intervention).
The variables <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-LINGUAS_FILE"><envar>$LINGUAS_FILE</envar></link> and <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-POTDOMAIN"><envar>$POTDOMAIN</envar></link> are taken into
acount too. All other construction variables used by <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-POTUpdate"><function>POTUpdate</function></link>, and
<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-POUpdate"><function>POUpdate</function></link> work here too.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
<emphasis>Example 1</emphasis>.
The simplest way is to specify input files and output languages inline in
a SCons script when invoking <function xmlns="http://www.scons.org/dbxsd/v1.0">Translate</function>
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
# SConscript in 'po/' directory
env = Environment( tools = ["default", "gettext"] )
env['POAUTOINIT'] = 1
env.Translate(['en','pl'], ['../a.cpp','../b.cpp']) 
</example_commands>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
<emphasis>Example 2</emphasis>.
If you wish, you may also stick to conventional style known from
<productname>autotools</productname>, i.e. using
<filename>POTFILES.in</filename> and <filename>LINGUAS</filename> files
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
# LINGUAS
en pl 
#end
</example_commands>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
# POTFILES.in
a.cpp
b.cpp
# end
</example_commands>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
# SConscript
env = Environment( tools = ["default", "gettext"] )
env['POAUTOINIT'] = 1
env['XGETTEXTPATH'] = ['../']
env.Translate(LINGUAS_FILE = 1, XGETTEXTFROM = 'POTFILES.in') 
</example_commands>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
The last approach is perhaps the recommended one. It allows easily split
internationalization/localization onto separate SCons scripts, where a script
in source tree is responsible for translations (from sources to
<literal>PO</literal> files) and script(s) under variant directories are
responsible for compilation of <literal>PO</literal> to <literal>MO</literal>
files to and for installation of <literal>MO</literal> files. The "gluing
factor" synchronizing these two scripts is then the content of
<filename>LINGUAS</filename> file.  Note, that the updated
<literal>POT</literal> and <literal>PO</literal> files are usually going to be
committed back to the repository, so they must be updated within the source
directory (and not in variant directories). Additionaly, the file listing of
<filename>po/</filename> directory contains <filename>LINGUAS</filename> file,
so the source tree looks familiar to translators, and they may work with the
project in their usual way.
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
<emphasis>Example 3</emphasis>.
Let's prepare a development tree as below
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
 project/
  + SConstruct
  + build/        
  + src/
      + po/
          + SConscript
          + SConscript.i18n
          + POTFILES.in
          + LINGUAS
</example_commands>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
with <filename>build</filename> being variant directory. Write the top-level
<filename>SConstruct</filename> script as follows
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
  # SConstruct
  env = Environment( tools = ["default", "gettext"] )
  VariantDir('build', 'src', duplicate = 0)
  env['POAUTOINIT'] = 1
  SConscript('src/po/SConscript.i18n', exports = 'env')
  SConscript('build/po/SConscript', exports = 'env')
</example_commands>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
the <filename>src/po/SConscript.i18n</filename> as
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
  # src/po/SConscript.i18n
  Import('env')
  env.Translate(LINGUAS_FILE=1, XGETTEXTFROM='POTFILES.in', XGETTEXTPATH=['../'])
</example_commands>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
and the <filename>src/po/SConscript</filename>
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
  # src/po/SConscript
  Import('env')
  env.MOFiles(LINGUAS_FILE = 1)
</example_commands>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
Such setup produces <literal>POT</literal> and <literal>PO</literal> files
under source tree in <filename>src/po/</filename> and binary
<literal>MO</literal> files under variant tree in
<filename>build/po/</filename>. This way the <literal>POT</literal> and
<literal>PO</literal> files are separated from other output files, which must
not be committed back to source repositories (e.g. <literal>MO</literal>
files).
</para>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
<note><para>In above example, the <literal>PO</literal> files are not updated,
nor created automatically when you issue <command>scons '.'</command> command.
The files must be updated (created) by hand via <command>scons
po-update</command> and then <literal>MO</literal> files can be compiled by
running <command>scons '.'</command>.</para></note>
</para>

</listitem>
  </varlistentry>
  <varlistentry id="b-TypeLibrary">
    <term>
      <function>TypeLibrary()</function>
    </term>
    <term>
      <function>env.TypeLibrary()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
Builds a Windows type library (<filename>.tlb</filename>)
file from an input IDL file (<filename>.idl</filename>).
In addition, it will build the associated inteface stub and
proxy source files,
naming them according to the base name of the <filename>.idl</filename> file.
For example,
</para>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
env.TypeLibrary(source="foo.idl")
</example_commands>

<para xmlns="http://www.scons.org/dbxsd/v1.0">
Will create <filename>foo.tlb</filename>,
<filename>foo.h</filename>,
<filename>foo_i.c</filename>,
<filename>foo_p.c</filename>
and
<filename>foo_data.c</filename>
files.
</para>
</listitem>
  </varlistentry>
  <varlistentry id="b-Uic">
    <term>
      <function>Uic()</function>
    </term>
    <term>
      <function>env.Uic()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
Builds a header file, an implementation file and a moc file from an ui file.
and returns the corresponding nodes in the above order.
This builder is only available after using the tool 'qt'. Note: you can
specify <filename>.ui</filename> files directly as source
files to the <function xmlns="http://www.scons.org/dbxsd/v1.0">Program</function>,
<function xmlns="http://www.scons.org/dbxsd/v1.0">Library</function> and <function xmlns="http://www.scons.org/dbxsd/v1.0">SharedLibrary</function> builders
without using this builder. Using this builder lets you override the standard
naming conventions (be careful: prefixes are always prepended to names of
built files; if you don't want prefixes, you may set them to ``).
See the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-QTDIR"><envar>$QTDIR</envar></link> variable for more information.
Example:
</para>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
env.Uic('foo.ui') # -&gt; ['foo.h', 'uic_foo.cc', 'moc_foo.cc']
env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
        source = 'foo.ui') # -&gt; ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc']
</example_commands>
</listitem>
  </varlistentry>
  <varlistentry id="b-Zip">
    <term>
      <function>Zip()</function>
    </term>
    <term>
      <function>env.Zip()</function>
    </term>
    <listitem>
<para xmlns="http://www.scons.org/dbxsd/v1.0">
Builds a zip archive of the specified files
and/or directories.
Unlike most builder methods,
the
<function xmlns="http://www.scons.org/dbxsd/v1.0">Zip</function>
builder method may be called multiple times
for a given target;
each additional call
adds to the list of entries
that will be built into the archive.
Any source directories will
be scanned for changes to
any on-disk files,
regardless of whether or not
<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
knows about them from other Builder or function calls.
</para>

<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
env.Zip('src.zip', 'src')

# Create the stuff.zip file.
env.Zip('stuff', ['subdir1', 'subdir2'])
# Also add "another" to the stuff.tar file.
env.Zip('stuff', 'another')
</example_commands>
</listitem>
  </varlistentry>
</variablelist>