dirkbaechle avatar dirkbaechle committed 4cdaede Draft

- added default files in doc/generated/

Comments (0)

Files changed (247)

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>
+      <synopsis>
+        <function>CFile()</function>
+      </synopsis>
+      <synopsis>
+        <function>env.CFile()</function>
+      </synopsis>
+    </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>
+      <synopsis>
+        <function>Command()</function>
+      </synopsis>
+      <synopsis>
+        <function>env.Command()</function>
+      </synopsis>
+    </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>
+      <synopsis>
+        <function>CXXFile()</function>
+      </synopsis>
+      <synopsis>
+        <function>env.CXXFile()</function>
+      </synopsis>
+    </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>
+      <synopsis>
+        <function>DVI()</function>
+      </synopsis>
+      <synopsis>
+        <function>env.DVI()</function>
+      </synopsis>
+    </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>
+      <synopsis>
+        <function>Install()</function>
+      </synopsis>
+      <synopsis>
+        <function>env.Install()</function>
+      </synopsis>
+    </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>
+      <synopsis>
+        <function>InstallAs()</function>
+      </synopsis>
+      <synopsis>
+        <function>env.InstallAs()</function>
+      </synopsis>
+    </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>
+      <synopsis>
+        <function>InstallVersionedLib()</function>
+      </synopsis>
+      <synopsis>
+        <function>env.InstallVersionedLib()</function>
+      </synopsis>
+    </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>
+      <synopsis>
+        <function>Jar()</function>
+      </synopsis>
+      <synopsis>
+        <function>env.Jar()</function>
+      </synopsis>
+    </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>
+      <synopsis>
+        <function>Java()</function>
+      </synopsis>
+      <synopsis>
+        <function>env.Java()</function>
+      </synopsis>
+    </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>
+      <synopsis>
+        <function>JavaH()</function>
+      </synopsis>
+      <synopsis>
+        <function>env.JavaH()</function>
+      </synopsis>
+    </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>
+      <synopsis>
+        <function>Library()</function>
+      </synopsis>
+      <synopsis>
+        <function>env.Library()</function>
+      </synopsis>
+    </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>
+      <synopsis>
+        <function>LoadableModule()</function>
+      </synopsis>
+      <synopsis>
+        <function>env.LoadableModule()</function>
+      </synopsis>
+    </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>
+      <synopsis>
+        <function>M4()</function>
+      </synopsis>
+      <synopsis>
+        <function>env.M4()</function>
+      </synopsis>
+    </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>
+      <synopsis>
+        <function>Moc()</function>
+      </synopsis>
+      <synopsis>
+        <function>env.Moc()</function>
+      </synopsis>
+    </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>
+      <synopsis>
+        <function>MOFiles()</function>
+      </synopsis>
+      <synopsis>
+        <function>env.MOFiles()</function>
+      </synopsis>
+    </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>
+      <synopsis>
+        <function>MSVSProject()</function>
+      </synopsis>
+      <synopsis>
+        <function>env.MSVSProject()</function>
+      </synopsis>
+    </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>
+      <synopsis>
+        <function>MSVSSolution()</function>
+      </synopsis>
+      <synopsis>
+        <function>env.MSVSSolution()</function>
+      </synopsis>
+    </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>
+      <synopsis>
+        <function>Object()</function>
+      </synopsis>
+      <synopsis>
+        <function>env.Object()</function>
+      </synopsis>
+    </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>
+      <synopsis>
+        <function>Package()</function>
+      </synopsis>
+      <synopsis>
+        <function>env.Package()</function>
+      </synopsis>
+    </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>
+      <synopsis>
+        <function>PCH()</function>
+      </synopsis>
+      <synopsis>
+        <function>env.PCH()</function>
+      </synopsis>
+    </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>
+      <synopsis>
+        <function>PDF()</function>
+      </synopsis>
+      <synopsis>
+        <function>env.PDF()</function>
+      </synopsis>
+    </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>
+      <synopsis>
+        <function>POInit()</function>
+      </synopsis>
+      <synopsis>
+        <function>env.POInit()</function>
+      </synopsis>
+    </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>
+      <synopsis>
+        <function>PostScript()</function>
+      </synopsis>
+      <synopsis>
+        <function>env.PostScript()</function>
+      </synopsis>
+    </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>
+      <synopsis>
+        <function>POTUpdate()</function>
+      </synopsis>
+      <synopsis>
+        <function>env.POTUpdate()</function>
+      </synopsis>
+    </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>
+      <synopsis>
+        <function>POUpdate()</function>
+      </synopsis>
+      <synopsis>
+        <function>env.POUpdate()</function>
+      </synopsis>
+    </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>
+      <synopsis>
+        <function>Program()</function>
+      </synopsis>
+      <synopsis>
+        <function>env.Program()</function>
+      </synopsis>
+    </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>
+      <synopsis>
+        <function>RES()</function>
+      </synopsis>
+      <synopsis>
+        <function>env.RES()</function>
+      </synopsis>
+    </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>
+      <synopsis>
+        <function>RMIC()</function>
+      </synopsis>
+      <synopsis>
+        <function>env.RMIC()</function>
+      </synopsis>
+    </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>
+      <synopsis>
+        <function>RPCGenClient()</function>
+      </synopsis>
+      <synopsis>
+        <function>env.RPCGenClient()</function>
+      </synopsis>
+    </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>
+      <synopsis>
+        <function>RPCGenHeader()</function>
+      </synopsis>
+      <synopsis>
+        <function>env.RPCGenHeader()</function>
+      </synopsis>
+    </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>
+      <synopsis>
+        <function>RPCGenService()</function>
+      </synopsis>
+      <synopsis>
+        <function>env.RPCGenService()</function>
+      </synopsis>
+    </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>
+      <synopsis>
+        <function>RPCGenXDR()</function>
+      </synopsis>
+      <synopsis>
+        <function>env.RPCGenXDR()</function>
+      </synopsis>
+    </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>
+      <synopsis>
+        <function>SharedLibrary()</function>
+      </synopsis>
+      <synopsis>
+        <function>env.SharedLibrary()</function>
+      </synopsis>
+    </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>
+      <synopsis>
+        <function>SharedObject()</function>
+      </synopsis>
+      <synopsis>
+        <function>env.SharedObject()</function>
+      </synopsis>
+    </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>
+      <synopsis>
+        <function>StaticLibrary()</function>
+      </synopsis>
+      <synopsis>
+        <function>env.StaticLibrary()</function>
+      </synopsis>
+    </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>
+      <synopsis>
+        <function>StaticObject()</function>
+      </synopsis>
+      <synopsis>
+        <function>env.StaticObject()</function>
+      </synopsis>
+    </term>