summaryrefslogtreecommitdiffstats
path: root/doc/generated/builders.gen
diff options
context:
space:
mode:
Diffstat (limited to 'doc/generated/builders.gen')
-rw-r--r--doc/generated/builders.gen879
1 files changed, 420 insertions, 459 deletions
diff --git a/doc/generated/builders.gen b/doc/generated/builders.gen
index 3d534b0..d08833f 100644
--- a/doc/generated/builders.gen
+++ b/doc/generated/builders.gen
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="UTF-8"?>
+<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE sconsdoc [
<!ENTITY % scons SYSTEM "../scons.mod">
%scons;
@@ -12,7 +12,7 @@
%variables-mod;
]>
-<variablelist xmlns="http://www.scons.org/dbxsd/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
+<variablelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.scons.org/dbxsd/v1.0" xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
<varlistentry id="b-CFile">
<term>
<function>CFile()</function>
@@ -20,18 +20,17 @@
<term>
<function>env.CFile()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
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
+The suffix specified by the <link 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">
+<example_commands>
# builds foo.c
env.CFile(target = 'foo.c', source = 'foo.l')
# builds bar.c
@@ -46,13 +45,12 @@ env.CFile(target = 'bar', source = 'bar.y')
<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
+ <listitem><para>
+The <function>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
+See the <link linkend="f-Command"><function>Command</function></link> function description
for the calling syntax and details.
</para>
</listitem>
@@ -64,19 +62,18 @@ for the calling syntax and details.
<term>
<function>env.CXXFile()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
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
+The suffix specified by the <link 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">
+<example_commands>
# builds foo.cc
env.CXXFile(target = 'foo.cc', source = 'foo.ll')
# builds bar.cc
@@ -91,20 +88,19 @@ env.CXXFile(target = 'bar', source = 'bar.yy')
<term>
<function>env.DocbookEpub()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
A pseudo-Builder, providing a Docbook toolchain for EPUB output.
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+<example_commands>env = Environment(tools=['docbook'])
env.DocbookEpub('manual.epub', 'manual.xml')
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
or simply
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+<example_commands>env = Environment(tools=['docbook'])
env.DocbookEpub('manual')
</example_commands>
@@ -117,17 +113,16 @@ env.DocbookEpub('manual')
<term>
<function>env.DocbookHtml()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
A pseudo-Builder, providing a Docbook toolchain for HTML output.
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+<example_commands>env = Environment(tools=['docbook'])
env.DocbookHtml('manual.html', 'manual.xml')
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
or simply
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+<example_commands>env = Environment(tools=['docbook'])
env.DocbookHtml('manual')
</example_commands>
</listitem>
@@ -139,35 +134,34 @@ env.DocbookHtml('manual')
<term>
<function>env.DocbookHtmlChunked()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
A pseudo-Builder, providing a Docbook toolchain for chunked HTML output.
It supports the <literal>base.dir</literal> parameter. The
<filename>chunkfast.xsl</filename> file (requires "EXSLT") is used as the
default stylesheet. Basic syntax:
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+<example_commands>env = Environment(tools=['docbook'])
env.DocbookHtmlChunked('manual')
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
where <filename>manual.xml</filename> is the input file.
</para>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">If you use the <literal>root.filename</literal>
+<para>If you use the <literal>root.filename</literal>
parameter in your own stylesheets you have to specify the new target name.
This ensures that the dependencies get correct, especially for the cleanup via <quote><literal>scons -c</literal></quote>:
</para>
-<screen xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+<screen>env = Environment(tools=['docbook'])
env.DocbookHtmlChunked('mymanual.html', 'manual', xsl='htmlchunk.xsl')
</screen>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">Some basic support for the <literal>base.dir</literal> is provided. You
+<para>Some basic support for the <literal>base.dir</literal> is provided. You
can add the <literal>base_dir</literal> keyword to your Builder
call, and the given prefix gets prepended to all the created filenames:
</para>
-<screen xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+<screen>env = Environment(tools=['docbook'])
env.DocbookHtmlChunked('manual', xsl='htmlchunk.xsl', base_dir='output/')
</screen>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">Make sure that you don't forget the trailing slash for the base folder, else
+<para>Make sure that you don't forget the trailing slash for the base folder, else
your files get renamed only!
</para>
</listitem>
@@ -179,35 +173,34 @@ your files get renamed only!
<term>
<function>env.DocbookHtmlhelp()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
A pseudo-Builder, providing a Docbook toolchain for HTMLHELP output.
Its basic syntax is:
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+<example_commands>env = Environment(tools=['docbook'])
env.DocbookHtmlhelp('manual')
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
where <filename>manual.xml</filename> is the input file.
</para>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">If you use the <literal>root.filename</literal>
+<para>If you use the <literal>root.filename</literal>
parameter in your own stylesheets you have to specify the new target name.
This ensures that the dependencies get correct, especially for the cleanup via <quote><literal>scons -c</literal></quote>:
</para>
-<screen xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+<screen>env = Environment(tools=['docbook'])
env.DocbookHtmlhelp('mymanual.html', 'manual', xsl='htmlhelp.xsl')
</screen>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">Some basic support for the <literal>base.dir</literal> parameter
+<para>Some basic support for the <literal>base.dir</literal> parameter
is provided. You can add the <literal>base_dir</literal> keyword to
your Builder call, and the given prefix gets prepended to all the
created filenames:
</para>
-<screen xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+<screen>env = Environment(tools=['docbook'])
env.DocbookHtmlhelp('manual', xsl='htmlhelp.xsl', base_dir='output/')
</screen>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">Make sure that you don't forget the trailing slash for the base folder, else
+<para>Make sure that you don't forget the trailing slash for the base folder, else
your files get renamed only!
</para>
@@ -220,16 +213,15 @@ your files get renamed only!
<term>
<function>env.DocbookMan()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
A pseudo-Builder, providing a Docbook toolchain for Man page output.
Its basic syntax is:
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+<example_commands>env = Environment(tools=['docbook'])
env.DocbookMan('manual')
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
where <filename>manual.xml</filename> is the input file. Note, that
you can specify a target name, but the actual output names are automatically
set from the <literal>refname</literal> entries in your XML source.
@@ -243,20 +235,19 @@ set from the <literal>refname</literal> entries in your XML source.
<term>
<function>env.DocbookPdf()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
A pseudo-Builder, providing a Docbook toolchain for PDF output.
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+<example_commands>env = Environment(tools=['docbook'])
env.DocbookPdf('manual.pdf', 'manual.xml')
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
or simply
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+<example_commands>env = Environment(tools=['docbook'])
env.DocbookPdf('manual')
</example_commands>
@@ -269,33 +260,32 @@ env.DocbookPdf('manual')
<term>
<function>env.DocbookSlidesHtml()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
A pseudo-Builder, providing a Docbook toolchain for HTML slides output.
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+<example_commands>env = Environment(tools=['docbook'])
env.DocbookSlidesHtml('manual')
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">If you use the <literal>titlefoil.html</literal> parameter in
+<para>If you use the <literal>titlefoil.html</literal> parameter in
your own stylesheets you have to give the new target name. This ensures
that the dependencies get correct, especially for the cleanup via
<quote><literal>scons -c</literal></quote>:
</para>
-<screen xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+<screen>env = Environment(tools=['docbook'])
env.DocbookSlidesHtml('mymanual.html','manual', xsl='slideshtml.xsl')
</screen>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">Some basic support for the <literal>base.dir</literal> parameter
+<para>Some basic support for the <literal>base.dir</literal> parameter
is provided. You
can add the <literal>base_dir</literal> keyword to your Builder
call, and the given prefix gets prepended to all the created filenames:
</para>
-<screen xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+<screen>env = Environment(tools=['docbook'])
env.DocbookSlidesHtml('manual', xsl='slideshtml.xsl', base_dir='output/')
</screen>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">Make sure that you don't forget the trailing slash for the base folder, else
+<para>Make sure that you don't forget the trailing slash for the base folder, else
your files get renamed only!
</para>
@@ -308,20 +298,19 @@ your files get renamed only!
<term>
<function>env.DocbookSlidesPdf()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
A pseudo-Builder, providing a Docbook toolchain for PDF slides output.
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+<example_commands>env = Environment(tools=['docbook'])
env.DocbookSlidesPdf('manual.pdf', 'manual.xml')
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
or simply
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+<example_commands>env = Environment(tools=['docbook'])
env.DocbookSlidesPdf('manual')
</example_commands>
</listitem>
@@ -333,12 +322,11 @@ env.DocbookSlidesPdf('manual')
<term>
<function>env.DocbookXInclude()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
A pseudo-Builder, for resolving XIncludes in a separate processing step.
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+<example_commands>env = Environment(tools=['docbook'])
env.DocbookXInclude('manual_xincluded.xml', 'manual.xml')
</example_commands>
</listitem>
@@ -350,16 +338,15 @@ env.DocbookXInclude('manual_xincluded.xml', 'manual.xml')
<term>
<function>env.DocbookXslt()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
A pseudo-Builder, applying a given XSL transformation to the input file.
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+<example_commands>env = Environment(tools=['docbook'])
env.DocbookXslt('manual_transformed.xml', 'manual.xml', xsl='transform.xslt')
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">Note, that this builder requires the <literal>xsl</literal> parameter
+<para>Note, that this builder requires the <literal>xsl</literal> parameter
to be set.
</para>
</listitem>
@@ -371,41 +358,40 @@ to be set.
<term>
<function>env.DVI()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
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>
+<filename>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.
+the target is built by invoking the <link linkend="cv-LATEXCOM"><envar>$LATEXCOM</envar></link> command line;
+otherwise, the <link 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>
+<function>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
+file and invoke the <link 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
+start <link 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
+file and re-run the <link 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">
+<para>
The suffix <filename>.dvi</filename>
(hard-coded within TeX itself)
is automatically added to the target
@@ -413,7 +399,7 @@ if it is not already present.
Examples:
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+<example_commands>
# builds from aaa.tex
env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
# builds bbb.dvi
@@ -430,14 +416,13 @@ env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
<term>
<function>env.Gs()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
A Builder for explicitly calling the <literal>gs</literal> executable.
Depending on the underlying OS, the different names <literal>gs</literal>,
<literal>gsos2</literal> and <literal>gswin32c</literal>
are tried.
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['gs'])
+<example_commands>env = Environment(tools=['gs'])
env.Gs('cover.jpg','scons-scons.pdf',
GSFLAGS='-dNOPAUSE -dBATCH -sDEVICE=jpeg -dFirstPage=1 -dLastPage=1 -q')
)
@@ -451,8 +436,7 @@ env.Gs('cover.jpg','scons-scons.pdf',
<term>
<function>env.Install()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
Installs one or more source files or directories
in the specified target,
which must be a directory.
@@ -462,7 +446,7 @@ 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">
+<example_commands>
env.Install('/usr/local/bin', source = ['foo', 'bar'])
</example_commands>
</listitem>
@@ -474,8 +458,7 @@ env.Install('/usr/local/bin', source = ['foo', 'bar'])
<term>
<function>env.InstallAs()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
Installs one or more source files or directories
to specific names,
allowing changing a file or directory name
@@ -486,6 +469,14 @@ and
source
arguments list different numbers of files or directories.
</para>
+
+<example_commands>
+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-InstallVersionedLib">
@@ -495,19 +486,21 @@ arguments list different numbers of files or directories.
<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>
+ <listitem><para>
+Installs a versioned shared library. The <link linkend="cv-SHLIBVERSION"><envar>$SHLIBVERSION</envar></link>
construction variable should be defined in the environment
to confirm the version number in the library name.
+If <link linkend="cv-SHLIBVERSION"><envar>$SHLIBVERSION</envar></link> is not defined a warning will be issued
+and the name of the library will be parsed to derive the version.
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>
+env.InstallVersionedLib(target = '/usr/local/bin/foo',
+ source = 'libxyz.1.5.2.so')
+env.InstallVersionedLib(target = '/usr/local/bin/foo',
+ source = 'libxyz.1.5.2.so',
+ SHLIBVERSION='1.5.2')
</example_commands>
</listitem>
</varlistentry>
@@ -518,41 +511,40 @@ env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
<term>
<function>env.Jar()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
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.
+by calling the <link 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>
+<para>
+If the <link linkend="cv-JARCHDIR"><envar>$JARCHDIR</envar></link> value is set, the
+<application>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
+If <envar>$JARCHDIR</envar> is not set explicitly,
+<application>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.
+were built by the <link linkend="b-Java"><function>Java</function></link> Builder.
</para>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
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>
+<application>jar</application>
command with the
<option>m</option>
option set.
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+<example_commands>
env.Jar(target = 'foo.jar', source = 'classes')
env.Jar(target = 'bar.jar',
@@ -567,8 +559,7 @@ env.Jar(target = 'bar.jar',
<term>
<function>env.Java()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
Builds one or more Java class files.
The sources may be any combination of explicit
<filename>.java</filename> files,
@@ -576,7 +567,7 @@ or directory trees which will be scanned
for <filename>.java</filename> files.
</para>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
SCons will parse each source <filename>.java</filename> file
to find the classes
(including inner classes)
@@ -587,7 +578,7 @@ The class files will be placed underneath
the specified target directory.
</para>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
SCons will also search each Java file
for the Java package name,
which it assumes can be found on a line
@@ -610,17 +601,17 @@ will generate a corresponding
class file.
</para>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
Examples:
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+<example_commands>
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">
+<para>
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,
@@ -632,7 +623,7 @@ 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">
+<example_commands>
env = Environment()
env['ENV']['LANG'] = 'en_GB.UTF-8'
</example_commands>
@@ -645,8 +636,7 @@ env['ENV']['LANG'] = 'en_GB.UTF-8'
<term>
<function>env.JavaH()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
Builds C header and source files for
implementing Java native methods.
The target can be either a directory
@@ -656,29 +646,29 @@ 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,
+by calling the <link 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>
+<function>Java</function>
builder method.
</para>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
If the construction variable
-<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-JAVACLASSDIR"><envar>$JAVACLASSDIR</envar></link>
+<link 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>
+<function>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">
+<para>
Examples:
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+<example_commands>
# builds java_native.h
classes = env.Java(target = 'classdir', source = 'src')
env.JavaH(target = 'java_native.h', source = classes)
@@ -701,10 +691,9 @@ env.JavaH(target = 'export',
<term>
<function>env.Library()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
A synonym for the
-<function xmlns="http://www.scons.org/dbxsd/v1.0">StaticLibrary</function>
+<function>StaticLibrary</function>
builder method.
</para>
</listitem>
@@ -716,11 +705,10 @@ builder method.
<term>
<function>env.LoadableModule()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
On most systems,
this is the same as
-<function xmlns="http://www.scons.org/dbxsd/v1.0">SharedLibrary</function>.
+<function>SharedLibrary</function>.
On Mac OS X (Darwin) platforms,
this creates a loadable module bundle.
</para>
@@ -733,10 +721,9 @@ this creates a loadable module bundle.
<term>
<function>env.M4()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
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
+This uses a default <link 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
@@ -744,7 +731,7 @@ when using the GNU version of m4.
Example:
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+<example_commands>
env.M4(target = 'foo.c', source = 'foo.c.m4')
</example_commands>
</listitem>
@@ -756,15 +743,14 @@ env.M4(target = 'foo.c', source = 'foo.c.m4')
<term>
<function>env.Moc()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
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.
+tool 'qt'. See the <link linkend="cv-QTDIR"><envar>$QTDIR</envar></link> variable for more information.
Example:
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+<example_commands>
env.Moc('foo.h') # generates moc_foo.cc
env.Moc('foo.cpp') # generates foo.moc
</example_commands>
@@ -777,48 +763,47 @@ env.Moc('foo.cpp') # generates foo.moc
<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
+ <listitem><para>
+This builder belongs to <link 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">
+<para>
<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">
+<example_commands>
# ...
env.MOFiles(['pl', 'en'])
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
<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">
+<example_commands>
# ...
env.MOFiles(LINGUAS_FILE = 1)
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
<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">
+<example_commands>
# ...
env.MOFiles(['pl', 'en'], LINGUAS_FILE = 1)
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
<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">
+<example_commands>
# ...
env['LINGUAS_FILE'] = 1
env.MOFiles()
@@ -832,17 +817,16 @@ Compile files for languages defined in <filename>LINGUAS</filename> file
<term>
<function>env.MSVSProject()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
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">
+<para>
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>
+<link linkend="cv-MSVS_VERSION"><envar>$MSVS_VERSION</envar></link>
in the Environment constructor).
For Visual Studio 6, it will generate a
<filename>.dsp</filename>
@@ -852,7 +836,7 @@ For Visual Studio 7 (.NET) and later versions, it will generate a
file.
</para>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
By default,
this also generates a solution file
for the specified project,
@@ -865,16 +849,16 @@ 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>,
+<function>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>
+<function>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
+<para>
+The <function>MSVSProject</function> builder
takes several lists of filenames
to be placed into the project file.
These are currently limited to
@@ -885,24 +869,24 @@ These are currently limited to
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,
+lists are added to the <link 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">
+<para>
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">
+<para>
In addition to the above lists of values,
the following values may be specified:
</para>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
<literal>target</literal>:
The name of the target
<filename>.dsp</filename>
@@ -912,12 +896,12 @@ 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>
+<link 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">
+<para>
<literal>variant</literal>:
The name of this particular variant.
For Visual Studio 7 projects,
@@ -933,13 +917,13 @@ 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>
+<function>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">
+<para>
<literal>buildtarget</literal>:
An optional string, node, or list of strings or nodes
(one per build variant), to tell the Visual Studio debugger
@@ -951,7 +935,7 @@ entries must match the number of
entries.
</para>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
<literal>runfile</literal>:
The name of the file that Visual Studio 7 and later
will run and debug.
@@ -964,28 +948,28 @@ the default is the same as the specified
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,
+<para>
+Note that because <application>SCons</application> always executes its build commands
+from the directory in which the <filename>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,
+than the <filename>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
+compiler option to the <link 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">
+<para>
Example usage:
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+<example_commands>
barsrcs = ['bar.cpp'],
barincs = ['bar.h'],
barlocalincs = ['StdAfx.h']
@@ -1013,17 +997,16 @@ env.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
<term>
<function>env.MSVSSolution()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
Builds a Microsoft Visual Studio solution file.
</para>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
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>
+<link linkend="cv-MSVS_VERSION"><envar>$MSVS_VERSION</envar></link>
in the construction environment).
For Visual Studio 6, it will generate a
<filename>.dsw</filename>
@@ -1034,19 +1017,19 @@ generate a
file.
</para>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
The following values must be specified:
</para>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
<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>
+<link 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">
+<para>
<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
@@ -1055,10 +1038,10 @@ 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">
+<para>
<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>
+<function>MSVSProject</function>
Builder,
to be placed into the solution file.
It should be noted that these file names are NOT added to the $SOURCES
@@ -1067,11 +1050,11 @@ 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">
+<para>
Example Usage:
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+<example_commands>
env.MSVSSolution(target = 'Bar' + env['MSVSSOLUTIONSUFFIX'],
projects = ['bar' + env['MSVSPROJECTSUFFIX']],
variant = 'Release')
@@ -1085,10 +1068,9 @@ env.MSVSSolution(target = 'Bar' + env['MSVSSOLUTIONSUFFIX'],
<term>
<function>env.Object()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
A synonym for the
-<function xmlns="http://www.scons.org/dbxsd/v1.0">StaticObject</function>
+<function>StaticObject</function>
builder method.
</para>
</listitem>
@@ -1100,41 +1082,39 @@ builder method.
<term>
<function>env.Package()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
Builds a Binary Package of the given source files.
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+<example_commands>
env.Package(source = FindInstalledFiles())
</example_commands>
-
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
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
+The former may be specified with the <varname>source</varname> parameter and may be left out,
+in which case the <function>FindInstalledFiles</function> function will collect
+all files that have an <function>Install</function> or <function>InstallAs</function> Builder attached.
+If the <varname>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">
+<para>
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.
+some of them can also be attached to files with the <function>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">
+<para>
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
+option or with the <envar>$PACKAGETYPE</envar> construction variable. Currently
the following packagers available:
</para>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
* msi - Microsoft Installer
* rpm - Redhat Package Manger
* ipkg - Itsy Package Management System
@@ -1146,11 +1126,11 @@ the following packagers available:
* src_zip - zip file source
</para>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
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">
+<example_commands>
env = Environment(tools=['default', 'packaging'])
env.Install('/bin/', 'my_program')
env.Package( NAME = 'foo',
@@ -1173,8 +1153,7 @@ env.Package( NAME = 'foo',
<term>
<function>env.PCH()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
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
@@ -1186,7 +1165,7 @@ 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">
+<example_commands>
env['PCH'] = env.PCH('StdAfx.cpp')[0]
</example_commands>
</listitem>
@@ -1198,21 +1177,20 @@ env['PCH'] = env.PCH('StdAfx.cpp')[0]
<term>
<function>env.PDF()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
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
+The suffix specified by the <link 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">
+<example_commands>
# builds from aaa.tex
env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
# builds bbb.pdf from bbb.dvi
@@ -1227,100 +1205,99 @@ env.PDF(target = 'bbb', source = 'bbb.dvi')
<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
+ <listitem><para>
+This builder belongs to <link linkend="t-msginit"><literal>msginit</literal></link> tool. The builder initializes missing
+<literal>PO</literal> file(s) if <link linkend="cv-POAUTOINIT"><envar>$POAUTOINIT</envar></link> is set. If
+<link linkend="cv-POAUTOINIT"><envar>$POAUTOINIT</envar></link> is not set (default), <function>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>
+<emphasis>you should not use <function>POInit</function> and use <link linkend="b-POUpdate"><function>POUpdate</function></link>
+instead</emphasis>. <link linkend="b-POUpdate"><function>POUpdate</function></link> chooses intelligently between
+<command>msgmerge(1)</command> and <command>msginit(1)</command>. <function>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
+<para>
+Target nodes defined through <function>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>
+The alias name may be changed through the <link 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>.
+<function>POInit</function> may be easily initialized by <command>scons po-create</command>.
</para>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
<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">
+<example_commands>
# ...
env.POInit(['en', 'pl']) # messages.pot --&gt; [en.po, pl.po]
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
<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">
+<example_commands>
# ...
env.POInit(['en', 'pl'], ['foo']) # foo.pot --&gt; [en.po, pl.po]
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
<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
+<filename>foo.pot</filename> but using <link linkend="cv-POTDOMAIN"><envar>$POTDOMAIN</envar></link> construction
variable:
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+<example_commands>
# ...
env.POInit(['en', 'pl'], POTDOMAIN='foo') # foo.pot --&gt; [en.po, pl.po]
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
<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">
+<example_commands>
# ...
env.POInit(LINGUAS_FILE = 1) # needs 'LINGUAS' file
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
<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">
+<example_commands>
# ...
env.POInit(['en', 'pl'], LINGUAS_FILE = 1)
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
<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">
+<example_commands>
# ...
env['POAUTOINIT'] = 1
env['LINGUAS_FILE'] = 1
env['POTDOMAIN'] = 'foo'
env.POInit()
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
which has same efect as:
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+<example_commands>
# ...
env.POInit(POAUTOINIT = 1, LINGUAS_FILE = 1, POTDOMAIN = 'foo')
</example_commands>
@@ -1333,21 +1310,20 @@ which has same efect as:
<term>
<function>env.PostScript()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
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
+The suffix specified by the <link 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">
+<example_commands>
# builds from aaa.tex
env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
# builds bbb.ps from bbb.dvi
@@ -1362,24 +1338,23 @@ env.PostScript(target = 'bbb', source = 'bbb.dvi')
<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
+ <listitem><para>
+The builder belongs to <link 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
+<link 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">
+<para>
<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
+<link 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
@@ -1387,38 +1362,38 @@ happens every time a source file has changed. In such case we invoke
not.</para></note>
</para>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
<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">
+<example_commands>
# 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">
+<para>
Then invoke scons few times:
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+<example_commands>
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">
+<para>
the results shall be as the comments above say.
</para>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
<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
+The <function>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:
+default target may also be overriden by setting <link linkend="cv-POTDOMAIN"><envar>$POTDOMAIN</envar></link> construction
+variable or providing it as an override to <function>POTUpdate</function> builder:
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+<example_commands>
# SConstruct script
env = Environment( tools = ['default', 'xgettext'] )
env['POTDOMAIN'] = "foo"
@@ -1426,49 +1401,49 @@ variable or providing it as an override to <function xmlns="http://www.scons.org
env.POTUpdate(POTDOMAIN = "bar", source = ["c.cpp", "d.cpp"]) # and bar.pot
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
<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">
+<example_commands>
# POTFILES.in in 'po/' subdirectory
../a.cpp
../b.cpp
# end of file
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
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>:
+sources is provided via <link linkend="cv-XGETTEXTFROM"><envar>$XGETTEXTFROM</envar></link>:
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+<example_commands>
# 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">
+<para>
<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
+You may use <link 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">
+<example_commands>
# POTFILES.in in 'po/' subdirectory
a.cpp
b.cpp
# end of file
</example_commands>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+<example_commands>
# 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">
+<para>
<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
@@ -1476,48 +1451,48 @@ 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">
+<para>
Let's create <filename>0/1/po/SConstruct</filename> script:
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+<example_commands>
# 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">
+<para>
and <filename>0/1/po/POTFILES.in</filename>:
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+<example_commands>
# POTFILES.in in '0/1/po/' subdirectory
a.cpp
# end of file
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
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">
+<example_commands>
/* 0/a.cpp */
gettext("Hello from ../../a.cpp")
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
and the second is <filename>0/1/a.cpp</filename>:
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+<example_commands>
/* 0/1/a.cpp */
gettext("Hello from ../a.cpp")
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
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">
+<example_commands>
# 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">
+<para>
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>.
@@ -1532,107 +1507,106 @@ then the <filename>messages.pot</filename> will contain
<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
+ <listitem><para>
+The builder belongs to <link 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>
+<link linkend="t-msginit"><literal>msginit</literal></link> tool and <link linkend="b-POInit"><function>POInit</function></link> builder (see also
+<link linkend="cv-POAUTOINIT"><envar>$POAUTOINIT</envar></link>). Note, that <function>POUpdate</function> <emphasis>does not add its
+targets to <literal>po-create</literal> alias</emphasis> as <link 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
+<para>
+Target nodes defined through <function>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
+through the <link 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">
+<para>
<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>),
+<filename>messages.pot</filename> template (see also <link 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>):
+<link linkend="b-POTUpdate"><function>POTUpdate</function></link>):
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+<example_commands>
# ...
env.POUpdate(['en','pl']) # messages.pot --&gt; [en.po, pl.po]
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
<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">
+<example_commands>
# ...
env.POUpdate(['en', 'pl'], ['foo']) # foo.pot --&gt; [en.po, pl.pl]
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
<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">
+<example_commands>
# ...
env.POUpdate(['en', 'pl'], POTDOMAIN='foo') # foo.pot -- &gt; [en.po, pl.pl]
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
<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">
+<example_commands>
# ...
env.POUpdate(LINGUAS_FILE = 1) # needs 'LINGUAS' file
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
<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">
+<example_commands>
# ...
env.POUpdate(LINGUAS_FILE = 1, source = ['foo'])
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
<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">
+<example_commands>
# 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">
+<para>
<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
+Use <link 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">
+<example_commands>
# ...
env.POUpdate(LINGUAS_FILE = 1, POAUTOINIT = 1)
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
<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">
+<example_commands>
# ...
env['POAUTOINIT'] = 1
env['LINGUAS_FILE'] = 1
@@ -1649,29 +1623,28 @@ pre-configured via environment.
<term>
<function>env.Program()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
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>
+<function>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)
+(specified by the <link 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;
+(specified by the <link 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">
+<example_commands>
env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
</example_commands>
</listitem>
@@ -1683,8 +1656,7 @@ env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
<term>
<function>env.RES()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
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
@@ -1697,7 +1669,7 @@ 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">
+<example_commands>
env.RES('resource.rc')
</example_commands>
</listitem>
@@ -1709,8 +1681,7 @@ env.RES('resource.rc')
<term>
<function>env.RMIC()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
Builds stub and skeleton class files
for remote objects
from Java <filename>.class</filename> files.
@@ -1719,16 +1690,16 @@ 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>
+<function>Java</function>
builder method.
</para>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
If the construction variable
-<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-JAVACLASSDIR"><envar>$JAVACLASSDIR</envar></link>
+<link 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>
+<function>RMIC</function>
builder method itself,
then the value of the variable
will be stripped from the
@@ -1736,7 +1707,7 @@ beginning of any <filename>.class </filename>
file names.
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+<example_commands>
classes = env.Java(target = 'classdir', source = 'src')
env.RMIC(target = 'outdir1', source = classes)
@@ -1756,8 +1727,7 @@ env.RMIC(target = 'outdir3',
<term>
<function>env.RPCGenClient()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
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
@@ -1766,7 +1736,7 @@ the command will be executed
in the source file's directory by default.
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+<example_commands>
# Builds src/rpcif_clnt.c
env.RPCGenClient('src/rpcif.x')
</example_commands>
@@ -1779,8 +1749,7 @@ env.RPCGenClient('src/rpcif.x')
<term>
<function>env.RPCGenHeader()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
Generates an RPC header (<filename>.h</filename>) file
from a specified RPC (<filename>.x</filename>) source file.
Because rpcgen only builds output files
@@ -1789,7 +1758,7 @@ the command will be executed
in the source file's directory by default.
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+<example_commands>
# Builds src/rpcif.h
env.RPCGenHeader('src/rpcif.x')
</example_commands>
@@ -1802,8 +1771,7 @@ env.RPCGenHeader('src/rpcif.x')
<term>
<function>env.RPCGenService()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
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
@@ -1812,7 +1780,7 @@ the command will be executed
in the source file's directory by default.
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+<example_commands>
# Builds src/rpcif_svc.c
env.RPCGenClient('src/rpcif.x')
</example_commands>
@@ -1825,8 +1793,7 @@ env.RPCGenClient('src/rpcif.x')
<term>
<function>env.RPCGenXDR()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
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
@@ -1835,7 +1802,7 @@ the command will be executed
in the source file's directory by default.
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+<example_commands>
# Builds src/rpcif_xdr.c
env.RPCGenClient('src/rpcif.x')
</example_commands>
@@ -1848,8 +1815,7 @@ env.RPCGenClient('src/rpcif.x')
<term>
<function>env.SharedLibrary()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
Builds a shared library
(<filename>.so</filename> on a POSIX system,
<filename>.dll</filename> on Windows)
@@ -1861,24 +1827,24 @@ 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;
+(specified by the <link 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;
+(specified by the <link 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">
+<example_commands>
env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
On Windows systems, the
-<function xmlns="http://www.scons.org/dbxsd/v1.0">SharedLibrary</function>
+<function>SharedLibrary</function>
builder method will always build an import
(<filename>.lib</filename>) library
in addition to the shared (<filename>.dll</filename>) library,
@@ -1887,9 +1853,9 @@ 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">
+<para>
On Cygwin systems, the
-<function xmlns="http://www.scons.org/dbxsd/v1.0">SharedLibrary</function>
+<function>SharedLibrary</function>
builder method will always build an import
(<filename>.dll.a</filename>) library
in addition to the shared (<filename>.dll</filename>) library,
@@ -1898,34 +1864,39 @@ if there is not already a <filename>.dll.a</filename> file explicitly
listed in the targets.
</para>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
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>
+<function>SharedObject</function>
builder method).
-<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+<filename>scons</filename>
will raise an error if there is any mismatch.
</para>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
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.
+For maximum portability, use the <function>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,
+<para>
+When the <link linkend="cv-SHLIBVERSION"><envar>$SHLIBVERSION</envar></link> construction variable is defined a versioned
+shared library is created. This modifies the <link 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
+are needed. <link 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">
+<example_commands>
+env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'], SHLIBVERSION='1.5.2')
+</example_commands>
+
+
+<para>
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 and libbar.so.2; on a Darwin (OSX) system
@@ -1933,28 +1904,28 @@ 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">
+<para>
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,
+("regsvr32" by default) is determined by <link linkend="cv-REGSVR"><envar>$REGSVR</envar></link> construction
+variable, and the flags passed are determined by <link linkend="cv-REGSVRFLAGS"><envar>$REGSVRFLAGS</envar></link>. By
+default, <link 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.
+<link 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">
+<example_commands>
env.SharedLibrary(target = 'bar',
source = ['bar.cxx', 'foo.obj'],
register=1)
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
will register <filename>bar.dll</filename> as a COM object
when it is done linking it.
</para>
@@ -1967,13 +1938,12 @@ when it is done linking it.
<term>
<function>env.SharedObject()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
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>
+<function>StaticObject</function>
builder method.
On some platforms building a shared object requires additional
compiler option
@@ -1988,21 +1958,21 @@ 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>)
+(specified by the <link linkend="cv-SHOBJPREFIX"><envar>$SHOBJPREFIX</envar></link> construction variable;
+by default, the same as <link 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)
+(specified by the <link 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">
+<example_commands>
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">
+<para>
Note that the source files will be scanned
according to the suffix mappings in the
<literal>SourceFileScanner</literal>
@@ -2019,8 +1989,7 @@ below, for more information.
<term>
<function>env.StaticLibrary()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
Builds a static library given one or more object files
or C, C++, D or Fortran source files.
If any source files are given,
@@ -2029,29 +1998,29 @@ 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;
+(specified by the <link 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;
+(specified by the <link 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">
+<example_commands>
env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
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>
+<function>StaticObject</function>
builder method).
-<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+<filename>scons</filename>
will raise an error if there is any mismatch.
</para>
</listitem>
@@ -2063,14 +2032,13 @@ will raise an error if there is any mismatch.
<term>
<function>env.StaticObject()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
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">
+<example_commands>
.asm assembly language file
.ASM assembly language file
.c C file
@@ -2101,24 +2069,24 @@ Source files must have one of the following extensions:
.SPP assembly language file + C pre-processor
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
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)
+(specified by the <link 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;
+(specified by the <link 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">
+<example_commands>
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">
+<para>
Note that the source files will be scanned
according to the suffix mappings in
<literal>SourceFileScanner</literal>
@@ -2135,28 +2103,27 @@ below, for more information.
<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 creates a single text file from another file or set of
-files by concatenating them with <envar xmlns="http://www.scons.org/dbxsd/v1.0">$LINESEPARATOR</envar> and replacing text
-using the <envar xmlns="http://www.scons.org/dbxsd/v1.0">$SUBST_DICT</envar> construction variable. Nested lists of source files
-are flattened. See also <function xmlns="http://www.scons.org/dbxsd/v1.0">Textfile</function>.
+ <listitem><para>
+The <function>Substfile</function> builder creates a single text file from another file or set of
+files by concatenating them with <envar>$LINESEPARATOR</envar> and replacing text
+using the <envar>$SUBST_DICT</envar> construction variable. Nested lists of source files
+are flattened. See also <function>Textfile</function>.
</para>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
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
+<para>
+The prefix and suffix specified by the <envar>$SUBSTFILEPREFIX</envar>
+and <envar>$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,
+<para>
+If a construction variable named <envar>$SUBST_DICT</envar> is present,
it may be either a Python dictionary or a sequence of (key,value) tuples.
If it is a dictionary it is converted into a list of tuples in an arbitrary order,
so if one key is a prefix of another key
@@ -2164,7 +2131,7 @@ or if one substitution could be further expanded by another subsitition,
it is unpredictable whether the expansion will occur.
</para>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
Any occurrences of a key in the source
are replaced by the corresponding value,
which may be a Python callable function or a string.
@@ -2173,7 +2140,7 @@ Strings are <emphasis>subst</emphasis>-expanded
and the result replaces the key.
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+<example_commands>
env = Environment(tools = ['default', 'textfile'])
env['prefix'] = '/usr/bin'
@@ -2225,13 +2192,12 @@ subst.Substfile('pgm2.c', [Value('#include "@foo@.h"'),
<term>
<function>env.Tar()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
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>
+<function>Tar</function>
builder method may be called multiple times
for a given target;
each additional call
@@ -2241,11 +2207,11 @@ 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>
+<filename>scons</filename>
knows about them from other Builder or function calls.
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+<example_commands>
env.Tar('src.tar', 'src')
# Create the stuff.tar file.
@@ -2271,29 +2237,28 @@ env.Tar('foo')
<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.
+ <listitem><para>
+The <function>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.
+<envar>$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
+<para>
+If present, the <envar>$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.
+see the <function>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
+<para>
+The prefix and suffix specified by the <envar>$TEXTFILEPREFIX</envar>
+and <envar>$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">
+<example_commands>
# builds/writes foo.txt
env.Textfile(target = 'foo.txt', source = ['Goethe', 42, 'Schiller'])
@@ -2342,50 +2307,49 @@ blob.txt
<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
+ <listitem><para>
+This pseudo-builder belongs to <link 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
+necessary). If <link 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.
+The variables <link linkend="cv-LINGUAS_FILE"><envar>$LINGUAS_FILE</envar></link> and <link linkend="cv-POTDOMAIN"><envar>$POTDOMAIN</envar></link> are taken into
+acount too. All other construction variables used by <link linkend="b-POTUpdate"><function>POTUpdate</function></link>, and
+<link linkend="b-POUpdate"><function>POUpdate</function></link> work here too.
</para>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
<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>
+a SCons script when invoking <function>Translate</function>
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+<example_commands>
# 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">
+<para>
<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">
+<example_commands>
# LINGUAS
en pl
#end
</example_commands>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+<example_commands>
# POTFILES.in
a.cpp
b.cpp
# end
</example_commands>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+<example_commands>
# SConscript
env = Environment( tools = ["default", "gettext"] )
env['POAUTOINIT'] = 1
@@ -2393,7 +2357,7 @@ env['XGETTEXTPATH'] = ['../']
env.Translate(LINGUAS_FILE = 1, XGETTEXTFROM = 'POTFILES.in')
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
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
@@ -2410,11 +2374,11 @@ 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">
+<para>
<emphasis>Example 3</emphasis>.
Let's prepare a development tree as below
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+<example_commands>
project/
+ SConstruct
+ build/
@@ -2425,11 +2389,11 @@ Let's prepare a development tree as below
+ POTFILES.in
+ LINGUAS
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
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">
+<example_commands>
# SConstruct
env = Environment( tools = ["default", "gettext"] )
VariantDir('build', 'src', duplicate = 0)
@@ -2437,23 +2401,23 @@ with <filename>build</filename> being variant directory. Write the top-level
SConscript('src/po/SConscript.i18n', exports = 'env')
SConscript('build/po/SConscript', exports = 'env')
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
the <filename>src/po/SConscript.i18n</filename> as
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+<example_commands>
# 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">
+<para>
and the <filename>src/po/SConscript</filename>
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+<example_commands>
# src/po/SConscript
Import('env')
env.MOFiles(LINGUAS_FILE = 1)
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
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
@@ -2463,7 +2427,7 @@ not be committed back to source repositories (e.g. <literal>MO</literal>
files).
</para>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
<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
@@ -2480,8 +2444,7 @@ running <command>scons '.'</command>.</para></note>
<term>
<function>env.TypeLibrary()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
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
@@ -2490,11 +2453,11 @@ 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">
+<example_commands>
env.TypeLibrary(source="foo.idl")
</example_commands>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<para>
Will create <filename>foo.tlb</filename>,
<filename>foo.h</filename>,
<filename>foo_i.c</filename>,
@@ -2512,22 +2475,21 @@ files.
<term>
<function>env.Uic()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
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
+files to the <function>Program</function>,
+<function>Library</function> and <function>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.
+See the <link linkend="cv-QTDIR"><envar>$QTDIR</envar></link> variable for more information.
Example:
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+<example_commands>
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']
@@ -2541,13 +2503,12 @@ env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
<term>
<function>env.Zip()</function>
</term>
- <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ <listitem><para>
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>
+<function>Zip</function>
builder method may be called multiple times
for a given target;
each additional call
@@ -2557,11 +2518,11 @@ 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>
+<filename>scons</filename>
knows about them from other Builder or function calls.
</para>
-<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+<example_commands>
env.Zip('src.zip', 'src')
# Create the stuff.zip file.
generated by cgit v0.12 at 2024-10-14 23:48:42 (GMT)