diff options
author | William Deegan <bill@baddogconsulting.com> | 2015-03-24 06:05:11 (GMT) |
---|---|---|
committer | William Deegan <bill@baddogconsulting.com> | 2015-03-24 06:05:11 (GMT) |
commit | be0ee2179a7c9db85e518e626612d0ae0918c790 (patch) | |
tree | 32f03b48553087f1f1d37a1ee8356a8906209cc1 /doc/generated/builders.gen | |
parent | 976a3d27a47bf69eb886a92be06a09d7face2f55 (diff) | |
download | SCons-be0ee2179a7c9db85e518e626612d0ae0918c790.zip SCons-be0ee2179a7c9db85e518e626612d0ae0918c790.tar.gz SCons-be0ee2179a7c9db85e518e626612d0ae0918c790.tar.bz2 |
added more info to the section on InstallVersionedLib(). fixed having InstallAs example in the text for InstallVersionedLib()
Diffstat (limited to 'doc/generated/builders.gen')
-rw-r--r-- | doc/generated/builders.gen | 879 |
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 --> [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 --> [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 --> [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 --> [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 --> [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 -- > [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') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc'] env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'), source = 'foo.ui') # -> ['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. |