diff options
Diffstat (limited to 'doc/generated/builders.gen')
| -rw-r--r-- | doc/generated/builders.gen | 2351 |
1 files changed, 2351 insertions, 0 deletions
diff --git a/doc/generated/builders.gen b/doc/generated/builders.gen new file mode 100644 index 0000000..2b033e4 --- /dev/null +++ b/doc/generated/builders.gen @@ -0,0 +1,2351 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + <!ENTITY % builders-mod SYSTEM "builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "variables.mod"> + %variables-mod; +]> + +<variablelist xmlns="http://www.scons.org/dbxsd/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> + <varlistentry id="b-CFile"> + <term> + <synopsis> + <function>CFile()</function> + </synopsis> + <synopsis> + <function>env.CFile()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Builds a C source file given a lex (<filename>.l</filename>) +or yacc (<filename>.y</filename>) input file. +The suffix specified by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-CFILESUFFIX"><envar>$CFILESUFFIX</envar></link> construction variable +(<filename>.c</filename> by default) +is automatically added to the target +if it is not already present. +Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +# builds foo.c +env.CFile(target = 'foo.c', source = 'foo.l') +# builds bar.c +env.CFile(target = 'bar', source = 'bar.y') +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="b-Command"> + <term> + <synopsis> + <function>Command()</function> + </synopsis> + <synopsis> + <function>env.Command()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The <function xmlns="http://www.scons.org/dbxsd/v1.0">Command</function> "Builder" is actually implemented +as a function that looks like a Builder, +but actually takes an additional argument of the action +from which the Builder should be made. +See the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-Command"><function>Command</function></link> function description +for the calling syntax and details. +</para> +</listitem> + </varlistentry> + <varlistentry id="b-CXXFile"> + <term> + <synopsis> + <function>CXXFile()</function> + </synopsis> + <synopsis> + <function>env.CXXFile()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Builds a C++ source file given a lex (<filename>.ll</filename>) +or yacc (<filename>.yy</filename>) +input file. +The suffix specified by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-CXXFILESUFFIX"><envar>$CXXFILESUFFIX</envar></link> construction variable +(<filename>.cc</filename> by default) +is automatically added to the target +if it is not already present. +Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +# builds foo.cc +env.CXXFile(target = 'foo.cc', source = 'foo.ll') +# builds bar.cc +env.CXXFile(target = 'bar', source = 'bar.yy') +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="b-DVI"> + <term> + <synopsis> + <function>DVI()</function> + </synopsis> + <synopsis> + <function>env.DVI()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Builds a <filename>.dvi</filename> file +from a <filename>.tex</filename>, +<filename>.ltx</filename> or <filename>.latex</filename> input file. +If the source file suffix is <filename>.tex</filename>, +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +will examine the contents of the file; +if the string +<literal>\documentclass</literal> +or +<literal>\documentstyle</literal> +is found, the file is assumed to be a LaTeX file and +the target is built by invoking the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-LATEXCOM"><envar>$LATEXCOM</envar></link> command line; +otherwise, the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-TEXCOM"><envar>$TEXCOM</envar></link> command line is used. +If the file is a LaTeX file, +the +<function xmlns="http://www.scons.org/dbxsd/v1.0">DVI</function> +builder method will also examine the contents +of the +<filename>.aux</filename> +file and invoke the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-BIBTEX"><envar>$BIBTEX</envar></link> command line +if the string +<literal>bibdata</literal> +is found, +start <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-MAKEINDEX"><envar>$MAKEINDEX</envar></link> to generate an index if a +<filename>.ind</filename> +file is found +and will examine the contents +<filename>.log</filename> +file and re-run the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-LATEXCOM"><envar>$LATEXCOM</envar></link> command +if the log file says it is necessary. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The suffix <filename>.dvi</filename> +(hard-coded within TeX itself) +is automatically added to the target +if it is not already present. +Examples: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +# builds from aaa.tex +env.DVI(target = 'aaa.dvi', source = 'aaa.tex') +# builds bbb.dvi +env.DVI(target = 'bbb', source = 'bbb.ltx') +# builds from ccc.latex +env.DVI(target = 'ccc.dvi', source = 'ccc.latex') +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="b-Install"> + <term> + <synopsis> + <function>Install()</function> + </synopsis> + <synopsis> + <function>env.Install()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Installs one or more source files or directories +in the specified target, +which must be a directory. +The names of the specified source files or directories +remain the same within the destination directory. The +sources may be given as a string or as a node returned by +a builder. +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.Install('/usr/local/bin', source = ['foo', 'bar']) +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="b-InstallAs"> + <term> + <synopsis> + <function>InstallAs()</function> + </synopsis> + <synopsis> + <function>env.InstallAs()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Installs one or more source files or directories +to specific names, +allowing changing a file or directory name +as part of the installation. +It is an error if the +target +and +source +arguments list different numbers of files or directories. +</para> +</listitem> + </varlistentry> + <varlistentry id="b-InstallVersionedLib"> + <term> + <synopsis> + <function>InstallVersionedLib()</function> + </synopsis> + <synopsis> + <function>env.InstallVersionedLib()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Installs a versioned shared library. The <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHLIBVERSION"><envar>$SHLIBVERSION</envar></link> +construction variable should be defined in the environment +to confirm the version number in the library name. +The symlinks appropriate to the architecture will be generated. +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.InstallAs(target = '/usr/local/bin/foo', + source = 'foo_debug') +env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'], + source = ['libFOO.a', 'libBAR.a']) +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="b-Jar"> + <term> + <synopsis> + <function>Jar()</function> + </synopsis> + <synopsis> + <function>env.Jar()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Builds a Java archive (<filename>.jar</filename>) file +from the specified list of sources. +Any directories in the source list +will be searched for <filename>.class</filename> files). +Any <filename>.java</filename> files in the source list +will be compiled to <filename>.class</filename> files +by calling the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-Java"><function>Java</function></link> Builder. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +If the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-JARCHDIR"><envar>$JARCHDIR</envar></link> value is set, the +<application xmlns="http://www.scons.org/dbxsd/v1.0">jar</application> +command will change to the specified directory using the +<option>-C</option> +option. +If <envar xmlns="http://www.scons.org/dbxsd/v1.0">$JARCHDIR</envar> is not set explicitly, +<application xmlns="http://www.scons.org/dbxsd/v1.0">SCons</application> will use the top of any subdirectory tree +in which Java <filename>.class</filename> +were built by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-Java"><function>Java</function></link> Builder. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +If the contents any of the source files begin with the string +<literal>Manifest-Version</literal>, +the file is assumed to be a manifest +and is passed to the +<application xmlns="http://www.scons.org/dbxsd/v1.0">jar</application> +command with the +<option>m</option> +option set. +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.Jar(target = 'foo.jar', source = 'classes') + +env.Jar(target = 'bar.jar', + source = ['bar1.java', 'bar2.java']) +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="b-Java"> + <term> + <synopsis> + <function>Java()</function> + </synopsis> + <synopsis> + <function>env.Java()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Builds one or more Java class files. +The sources may be any combination of explicit +<filename>.java</filename> files, +or directory trees which will be scanned +for <filename>.java</filename> files. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +SCons will parse each source <filename>.java</filename> file +to find the classes +(including inner classes) +defined within that file, +and from that figure out the +target <filename>.class</filename> files that will be created. +The class files will be placed underneath +the specified target directory. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +SCons will also search each Java file +for the Java package name, +which it assumes can be found on a line +beginning with the string +<literal>package</literal> +in the first column; +the resulting <filename>.class</filename> files +will be placed in a directory reflecting +the specified package name. +For example, +the file +<filename>Foo.java</filename> +defining a single public +<classname>Foo</classname> +class and +containing a package name of +<classname>sub.dir</classname> +will generate a corresponding +<filename>sub/dir/Foo.class</filename> +class file. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Examples: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.Java(target = 'classes', source = 'src') +env.Java(target = 'classes', source = ['src1', 'src2']) +env.Java(target = 'classes', source = ['File1.java', 'File2.java']) +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Java source files can use the native encoding for the underlying OS. +Since SCons compiles in simple ASCII mode by default, +the compiler will generate warnings about unmappable characters, +which may lead to errors as the file is processed further. +In this case, the user must specify the <literal>LANG</literal> +environment variable to tell the compiler what encoding is used. +For portibility, it's best if the encoding is hard-coded +so that the compile will work if it is done on a system +with a different encoding. +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env = Environment() +env['ENV']['LANG'] = 'en_GB.UTF-8' +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="b-JavaH"> + <term> + <synopsis> + <function>JavaH()</function> + </synopsis> + <synopsis> + <function>env.JavaH()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Builds C header and source files for +implementing Java native methods. +The target can be either a directory +in which the header files will be written, +or a header file name which +will contain all of the definitions. +The source can be the names of <filename>.class</filename> files, +the names of <filename>.java</filename> files +to be compiled into <filename>.class</filename> files +by calling the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-Java"><function>Java</function></link> builder method, +or the objects returned from the +<function xmlns="http://www.scons.org/dbxsd/v1.0">Java</function> +builder method. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +If the construction variable +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-JAVACLASSDIR"><envar>$JAVACLASSDIR</envar></link> +is set, either in the environment +or in the call to the +<function xmlns="http://www.scons.org/dbxsd/v1.0">JavaH</function> +builder method itself, +then the value of the variable +will be stripped from the +beginning of any <filename>.class</filename> file names. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Examples: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +# builds java_native.h +classes = env.Java(target = 'classdir', source = 'src') +env.JavaH(target = 'java_native.h', source = classes) + +# builds include/package_foo.h and include/package_bar.h +env.JavaH(target = 'include', + source = ['package/foo.class', 'package/bar.class']) + +# builds export/foo.h and export/bar.h +env.JavaH(target = 'export', + source = ['classes/foo.class', 'classes/bar.class'], + JAVACLASSDIR = 'classes') +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="b-Library"> + <term> + <synopsis> + <function>Library()</function> + </synopsis> + <synopsis> + <function>env.Library()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +A synonym for the +<function xmlns="http://www.scons.org/dbxsd/v1.0">StaticLibrary</function> +builder method. +</para> +</listitem> + </varlistentry> + <varlistentry id="b-LoadableModule"> + <term> + <synopsis> + <function>LoadableModule()</function> + </synopsis> + <synopsis> + <function>env.LoadableModule()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +On most systems, +this is the same as +<function xmlns="http://www.scons.org/dbxsd/v1.0">SharedLibrary</function>. +On Mac OS X (Darwin) platforms, +this creates a loadable module bundle. +</para> +</listitem> + </varlistentry> + <varlistentry id="b-M4"> + <term> + <synopsis> + <function>M4()</function> + </synopsis> + <synopsis> + <function>env.M4()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Builds an output file from an M4 input file. +This uses a default <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-M4FLAGS"><envar>$M4FLAGS</envar></link> value of +<option>-E</option>, +which considers all warnings to be fatal +and stops on the first warning +when using the GNU version of m4. +Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.M4(target = 'foo.c', source = 'foo.c.m4') +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="b-Moc"> + <term> + <synopsis> + <function>Moc()</function> + </synopsis> + <synopsis> + <function>env.Moc()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Builds an output file from a moc input file. Moc input files are either +header files or cxx files. This builder is only available after using the +tool 'qt'. See the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-QTDIR"><envar>$QTDIR</envar></link> variable for more information. +Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.Moc('foo.h') # generates moc_foo.cc +env.Moc('foo.cpp') # generates foo.moc +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="b-MOFiles"> + <term> + <synopsis> + <function>MOFiles()</function> + </synopsis> + <synopsis> + <function>env.MOFiles()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +This builder belongs to <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="t-msgfmt"><literal>msgfmt</literal></link> tool. The builder compiles +<literal>PO</literal> files to <literal>MO</literal> files. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<emphasis>Example 1</emphasis>. +Create <filename>pl.mo</filename> and <filename>en.mo</filename> by compiling +<filename>pl.po</filename> and <filename>en.po</filename>: +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> + # ... + env.MOFiles(['pl', 'en']) +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<emphasis>Example 2</emphasis>. +Compile files for languages defined in <filename>LINGUAS</filename> file: +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> + # ... + env.MOFiles(LINGUAS_FILE = 1) +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<emphasis>Example 3</emphasis>. +Create <filename>pl.mo</filename> and <filename>en.mo</filename> by compiling +<filename>pl.po</filename> and <filename>en.po</filename> plus files for +languages defined in <filename>LINGUAS</filename> file: +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> + # ... + env.MOFiles(['pl', 'en'], LINGUAS_FILE = 1) +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<emphasis>Example 4</emphasis>. +Compile files for languages defined in <filename>LINGUAS</filename> file +(another version): +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> + # ... + env['LINGUAS_FILE'] = 1 + env.MOFiles() +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="b-MSVSProject"> + <term> + <synopsis> + <function>MSVSProject()</function> + </synopsis> + <synopsis> + <function>env.MSVSProject()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Builds a Microsoft Visual Studio project file, +and by default builds a solution file as well. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +This builds a Visual Studio project file, based on the version of +Visual Studio that is configured (either the latest installed version, +or the version specified by +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-MSVS_VERSION"><envar>$MSVS_VERSION</envar></link> +in the Environment constructor). +For Visual Studio 6, it will generate a +<filename>.dsp</filename> +file. +For Visual Studio 7 (.NET) and later versions, it will generate a +<filename>.vcproj</filename> +file. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +By default, +this also generates a solution file +for the specified project, +a +<filename>.dsw</filename> +file for Visual Studio 6 +or a +<filename>.sln</filename> +file for Visual Studio 7 (.NET). +This behavior may be disabled by specifying +<literal>auto_build_solution=0</literal> +when you call +<function xmlns="http://www.scons.org/dbxsd/v1.0">MSVSProject</function>, +in which case you presumably want to +build the solution file(s) +by calling the +<function xmlns="http://www.scons.org/dbxsd/v1.0">MSVSSolution</function> +Builder (see below). +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The <function xmlns="http://www.scons.org/dbxsd/v1.0">MSVSProject</function> builder +takes several lists of filenames +to be placed into the project file. +These are currently limited to +<literal>srcs</literal>, +<literal>incs</literal>, +<literal>localincs</literal>, +<literal>resources</literal>, +and +<literal>misc</literal>. +These are pretty self-explanatory, but it should be noted that these +lists are added to the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SOURCES"><envar>$SOURCES</envar></link> construction variable as strings, +NOT as SCons File Nodes. This is because they represent file +names to be added to the project file, not the source files used to +build the project file. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The above filename lists are all optional, +although at least one must be specified +for the resulting project file to be non-empty. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +In addition to the above lists of values, +the following values may be specified: +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<literal>target</literal>: +The name of the target +<filename>.dsp</filename> +or +<filename>.vcproj</filename> +file. +The correct +suffix for the version of Visual Studio must be used, +but the +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-MSVSPROJECTSUFFIX"><envar>$MSVSPROJECTSUFFIX</envar></link> +construction variable +will be defined to the correct value (see example below). +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<literal>variant</literal>: +The name of this particular variant. +For Visual Studio 7 projects, +this can also be a list of variant names. +These are typically things like "Debug" or "Release", but really +can be anything you want. +For Visual Studio 7 projects, +they may also specify a target platform +separated from the variant name by a +<literal>|</literal> +(vertical pipe) +character: +<literal>Debug|Xbox</literal>. +The default target platform is Win32. +Multiple calls to +<function xmlns="http://www.scons.org/dbxsd/v1.0">MSVSProject</function> +with different variants are allowed; +all variants will be added to the project file with their appropriate +build targets and sources. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<literal>buildtarget</literal>: +An optional string, node, or list of strings or nodes +(one per build variant), to tell the Visual Studio debugger +what output target to use in what build variant. +The number of +<literal>buildtarget</literal> +entries must match the number of +<literal>variant</literal> +entries. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<literal>runfile</literal>: +The name of the file that Visual Studio 7 and later +will run and debug. +This appears as the value of the +<literal>Output</literal> +field in the resutling Visual Studio project file. +If this is not specified, +the default is the same as the specified +<literal>buildtarget</literal> +value. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Note that because <application xmlns="http://www.scons.org/dbxsd/v1.0">SCons</application> always executes its build commands +from the directory in which the <filename xmlns="http://www.scons.org/dbxsd/v1.0">SConstruct</filename> file is located, +if you generate a project file in a different directory +than the <filename xmlns="http://www.scons.org/dbxsd/v1.0">SConstruct</filename> directory, +users will not be able to double-click +on the file name in compilation error messages +displayed in the Visual Studio console output window. +This can be remedied by adding the +Visual C/C++ +<literal>/FC</literal> +compiler option to the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-CCFLAGS"><envar>$CCFLAGS</envar></link> variable +so that the compiler will print +the full path name of any +files that cause compilation errors. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Example usage: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +barsrcs = ['bar.cpp'], +barincs = ['bar.h'], +barlocalincs = ['StdAfx.h'] +barresources = ['bar.rc','resource.h'] +barmisc = ['bar_readme.txt'] + +dll = env.SharedLibrary(target = 'bar.dll', + source = barsrcs) + +env.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'], + srcs = barsrcs, + incs = barincs, + localincs = barlocalincs, + resources = barresources, + misc = barmisc, + buildtarget = dll, + variant = 'Release') +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="b-MSVSSolution"> + <term> + <synopsis> + <function>MSVSSolution()</function> + </synopsis> + <synopsis> + <function>env.MSVSSolution()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Builds a Microsoft Visual Studio solution file. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +This builds a Visual Studio solution file, +based on the version of Visual Studio that is configured +(either the latest installed version, +or the version specified by +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-MSVS_VERSION"><envar>$MSVS_VERSION</envar></link> +in the construction environment). +For Visual Studio 6, it will generate a +<filename>.dsw</filename> +file. +For Visual Studio 7 (.NET), it will +generate a +<filename>.sln</filename> +file. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The following values must be specified: +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<literal>target</literal>: +The name of the target .dsw or .sln file. The correct +suffix for the version of Visual Studio must be used, but the value +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-MSVSSOLUTIONSUFFIX"><envar>$MSVSSOLUTIONSUFFIX</envar></link> +will be defined to the correct value (see example below). +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<literal>variant</literal>: +The name of this particular variant, or a list of variant +names (the latter is only supported for MSVS 7 solutions). These are +typically things like "Debug" or "Release", but really can be anything +you want. For MSVS 7 they may also specify target platform, like this +"Debug|Xbox". Default platform is Win32. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<literal>projects</literal>: +A list of project file names, or Project nodes returned by calls to the +<function xmlns="http://www.scons.org/dbxsd/v1.0">MSVSProject</function> +Builder, +to be placed into the solution file. +It should be noted that these file names are NOT added to the $SOURCES +environment variable in form of files, but rather as strings. This +is because they represent file names to be added to the solution file, +not the source files used to build the solution file. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Example Usage: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.MSVSSolution(target = 'Bar' + env['MSVSSOLUTIONSUFFIX'], + projects = ['bar' + env['MSVSPROJECTSUFFIX']], + variant = 'Release') +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="b-Object"> + <term> + <synopsis> + <function>Object()</function> + </synopsis> + <synopsis> + <function>env.Object()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +A synonym for the +<function xmlns="http://www.scons.org/dbxsd/v1.0">StaticObject</function> +builder method. +</para> +</listitem> + </varlistentry> + <varlistentry id="b-Package"> + <term> + <synopsis> + <function>Package()</function> + </synopsis> + <synopsis> + <function>env.Package()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Builds a Binary Package of the given source files. +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.Package(source = FindInstalledFiles()) +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Builds software distribution packages. +Packages consist of files to install and packaging information. +The former may be specified with the <varname xmlns="http://www.scons.org/dbxsd/v1.0">source</varname> parameter and may be left out, +in which case the <function xmlns="http://www.scons.org/dbxsd/v1.0">FindInstalledFiles</function> function will collect +all files that have an <function xmlns="http://www.scons.org/dbxsd/v1.0">Install</function> or <function xmlns="http://www.scons.org/dbxsd/v1.0">InstallAs</function> Builder attached. +If the <varname xmlns="http://www.scons.org/dbxsd/v1.0">target</varname> is not specified +it will be deduced from additional information given to this Builder. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The packaging information is specified +with the help of construction variables documented below. +This information is called a tag to stress that +some of them can also be attached to files with the <function xmlns="http://www.scons.org/dbxsd/v1.0">Tag</function> function. +The mandatory ones will complain if they were not specified. +They vary depending on chosen target packager. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The target packager may be selected with the "PACKAGETYPE" command line +option or with the <envar xmlns="http://www.scons.org/dbxsd/v1.0">$PACKAGETYPE</envar> construction variable. Currently +the following packagers available: +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> + * msi - Microsoft Installer + * rpm - Redhat Package Manger + * ipkg - Itsy Package Management System + * tarbz2 - compressed tar + * targz - compressed tar + * zip - zip file + * src_tarbz2 - compressed tar source + * src_targz - compressed tar source + * src_zip - zip file source +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +An updated list is always available under the "package_type" option when +running "scons --help" on a project that has packaging activated. +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env = Environment(tools=['default', 'packaging']) +env.Install('/bin/', 'my_program') +env.Package( NAME = 'foo', + VERSION = '1.2.3', + PACKAGEVERSION = 0, + PACKAGETYPE = 'rpm', + LICENSE = 'gpl', + SUMMARY = 'balalalalal', + DESCRIPTION = 'this should be really really long', + X_RPM_GROUP = 'Application/fu', + SOURCE_URL = 'http://foo.org/foo-1.2.3.tar.gz' + ) +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="b-PCH"> + <term> + <synopsis> + <function>PCH()</function> + </synopsis> + <synopsis> + <function>env.PCH()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Builds a Microsoft Visual C++ precompiled header. +Calling this builder method +returns a list of two targets: the PCH as the first element, and the object +file as the second element. Normally the object file is ignored. +This builder method is only +provided when Microsoft Visual C++ is being used as the compiler. +The PCH builder method is generally used in +conjuction with the PCH construction variable to force object files to use +the precompiled header: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env['PCH'] = env.PCH('StdAfx.cpp')[0] +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="b-PDF"> + <term> + <synopsis> + <function>PDF()</function> + </synopsis> + <synopsis> + <function>env.PDF()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Builds a <filename>.pdf</filename> file +from a <filename>.dvi</filename> input file +(or, by extension, a <filename>.tex</filename>, +<filename>.ltx</filename>, +or +<filename>.latex</filename> input file). +The suffix specified by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-PDFSUFFIX"><envar>$PDFSUFFIX</envar></link> construction variable +(<filename>.pdf</filename> by default) +is added automatically to the target +if it is not already present. Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +# builds from aaa.tex +env.PDF(target = 'aaa.pdf', source = 'aaa.tex') +# builds bbb.pdf from bbb.dvi +env.PDF(target = 'bbb', source = 'bbb.dvi') +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="b-POInit"> + <term> + <synopsis> + <function>POInit()</function> + </synopsis> + <synopsis> + <function>env.POInit()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +This builder belongs to <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="t-msginit"><literal>msginit</literal></link> tool. The builder initializes missing +<literal>PO</literal> file(s) if <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-POAUTOINIT"><envar>$POAUTOINIT</envar></link> is set. If +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-POAUTOINIT"><envar>$POAUTOINIT</envar></link> is not set (default), <function xmlns="http://www.scons.org/dbxsd/v1.0">POInit</function> prints instruction for +user (that is supposed to be a translator), telling how the +<literal>PO</literal> file should be initialized. In normal projects +<emphasis>you should not use <function xmlns="http://www.scons.org/dbxsd/v1.0">POInit</function> and use <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-POUpdate"><function>POUpdate</function></link> +instead</emphasis>. <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-POUpdate"><function>POUpdate</function></link> chooses intelligently between +<command>msgmerge(1)</command> and <command>msginit(1)</command>. <function xmlns="http://www.scons.org/dbxsd/v1.0">POInit</function> +always uses <command>msginit(1)</command> and should be regarded as builder for +special purposes or for temporary use (e.g. for quick, one time initialization +of a bunch of <literal>PO</literal> files) or for tests. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Target nodes defined through <function xmlns="http://www.scons.org/dbxsd/v1.0">POInit</function> are not built by default (they're +<literal>Ignore</literal>d from <literal>'.'</literal> node) but are added to +special <literal>Alias</literal> (<literal>'po-create'</literal> by default). +The alias name may be changed through the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-POCREATE_ALIAS"><envar>$POCREATE_ALIAS</envar></link> +construction variable. All <literal>PO</literal> files defined through +<function xmlns="http://www.scons.org/dbxsd/v1.0">POInit</function> may be easily initialized by <command>scons po-create</command>. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<emphasis>Example 1</emphasis>. +Initialize <filename>en.po</filename> and <filename>pl.po</filename> from +<filename>messages.pot</filename>: +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> + # ... + env.POInit(['en', 'pl']) # messages.pot --> [en.po, pl.po] +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<emphasis>Example 2</emphasis>. +Initialize <filename>en.po</filename> and <filename>pl.po</filename> from +<filename>foo.pot</filename>: +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> + # ... + env.POInit(['en', 'pl'], ['foo']) # foo.pot --> [en.po, pl.po] +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<emphasis>Example 3</emphasis>. +Initialize <filename>en.po</filename> and <filename>pl.po</filename> from +<filename>foo.pot</filename> but using <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-POTDOMAIN"><envar>$POTDOMAIN</envar></link> construction +variable: +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> + # ... + env.POInit(['en', 'pl'], POTDOMAIN='foo') # foo.pot --> [en.po, pl.po] +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<emphasis>Example 4</emphasis>. +Initialize <literal>PO</literal> files for languages defined in +<filename>LINGUAS</filename> file. The files will be initialized from template +<filename>messages.pot</filename>: +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> + # ... + env.POInit(LINGUAS_FILE = 1) # needs 'LINGUAS' file +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<emphasis>Example 5</emphasis>. +Initialize <filename>en.po</filename> and <filename>pl.pl</filename> +<literal>PO</literal> files plus files for languages defined in +<filename>LINGUAS</filename> file. The files will be initialized from template +<filename>messages.pot</filename>: +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> + # ... + env.POInit(['en', 'pl'], LINGUAS_FILE = 1) +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<emphasis>Example 6</emphasis>. +You may preconfigure your environment first, and then initialize +<literal>PO</literal> files: +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> + # ... + env['POAUTOINIT'] = 1 + env['LINGUAS_FILE'] = 1 + env['POTDOMAIN'] = 'foo' + env.POInit() +</example_commands> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +which has same efect as: +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> + # ... + env.POInit(POAUTOINIT = 1, LINGUAS_FILE = 1, POTDOMAIN = 'foo') +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="b-PostScript"> + <term> + <synopsis> + <function>PostScript()</function> + </synopsis> + <synopsis> + <function>env.PostScript()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Builds a <filename>.ps</filename> file +from a <filename>.dvi</filename> input file +(or, by extension, a <filename>.tex</filename>, +<filename>.ltx</filename>, +or +<filename>.latex</filename> input file). +The suffix specified by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-PSSUFFIX"><envar>$PSSUFFIX</envar></link> construction variable +(<filename>.ps</filename> by default) +is added automatically to the target +if it is not already present. Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +# builds from aaa.tex +env.PostScript(target = 'aaa.ps', source = 'aaa.tex') +# builds bbb.ps from bbb.dvi +env.PostScript(target = 'bbb', source = 'bbb.dvi') +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="b-POTUpdate"> + <term> + <synopsis> + <function>POTUpdate()</function> + </synopsis> + <synopsis> + <function>env.POTUpdate()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The builder belongs to <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="t-xgettext"><literal>xgettext</literal></link> tool. The builder updates target +<literal>POT</literal> file if exists or creates one if it doesn't. The node is +not built by default (i.e. it is <literal>Ignore</literal>d from +<literal>'.'</literal>), but only on demand (i.e. when given +<literal>POT</literal> file is required or when special alias is invoked). This +builder adds its targe node (<filename>messages.pot</filename>, say) to a +special alias (<literal>pot-update</literal> by default, see +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-POTUPDATE_ALIAS"><envar>$POTUPDATE_ALIAS</envar></link>) so you can update/create them easily with +<command>scons pot-update</command>. The file is not written until there is no +real change in internationalized messages (or in comments that enter +<literal>POT</literal> file). +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<note> <para>You may see <command>xgettext(1)</command> being invoked by the +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="t-xgettext"><literal>xgettext</literal></link> tool even if there is no real change in internationalized +messages (so the <literal>POT</literal> file is not being updated). This +happens every time a source file has changed. In such case we invoke +<command>xgettext(1)</command> and compare its output with the content of +<literal>POT</literal> file to decide whether the file should be updated or +not.</para></note> +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<emphasis>Example 1.</emphasis> +Let's create <filename>po/</filename> directory and place following +<filename>SConstruct</filename> script there: +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> + # SConstruct in 'po/' subdir + env = Environment( tools = ['default', 'xgettext'] ) + env.POTUpdate(['foo'], ['../a.cpp', '../b.cpp']) + env.POTUpdate(['bar'], ['../c.cpp', '../d.cpp']) +</example_commands> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Then invoke scons few times: +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> + user@host:$ scons # Does not create foo.pot nor bar.pot + user@host:$ scons foo.pot # Updates or creates foo.pot + user@host:$ scons pot-update # Updates or creates foo.pot and bar.pot + user@host:$ scons -c # Does not clean foo.pot nor bar.pot. +</example_commands> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +the results shall be as the comments above say. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<emphasis>Example 2.</emphasis> +The <function xmlns="http://www.scons.org/dbxsd/v1.0">POTUpdate</function> builder may be used with no target specified, in which +case default target <filename>messages.pot</filename> will be used. The +default target may also be overriden by setting <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-POTDOMAIN"><envar>$POTDOMAIN</envar></link> construction +variable or providing it as an override to <function xmlns="http://www.scons.org/dbxsd/v1.0">POTUpdate</function> builder: +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> + # SConstruct script + env = Environment( tools = ['default', 'xgettext'] ) + env['POTDOMAIN'] = "foo" + env.POTUpdate(source = ["a.cpp", "b.cpp"]) # Creates foo.pot ... + env.POTUpdate(POTDOMAIN = "bar", source = ["c.cpp", "d.cpp"]) # and bar.pot +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<emphasis>Example 3.</emphasis> +The sources may be specified within separate file, for example +<filename>POTFILES.in</filename>: +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> + # POTFILES.in in 'po/' subdirectory + ../a.cpp + ../b.cpp + # end of file +</example_commands> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The name of the file (<filename>POTFILES.in</filename>) containing the list of +sources is provided via <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-XGETTEXTFROM"><envar>$XGETTEXTFROM</envar></link>: +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> + # SConstruct file in 'po/' subdirectory + env = Environment( tools = ['default', 'xgettext'] ) + env.POTUpdate(XGETTEXTFROM = 'POTFILES.in') +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<emphasis>Example 4.</emphasis> +You may use <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-XGETTEXTPATH"><envar>$XGETTEXTPATH</envar></link> to define source search path. Assume, for +example, that you have files <filename>a.cpp</filename>, +<filename>b.cpp</filename>, <filename>po/SConstruct</filename>, +<filename>po/POTFILES.in</filename>. Then your <literal>POT</literal>-related +files could look as below: +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> + # POTFILES.in in 'po/' subdirectory + a.cpp + b.cpp + # end of file +</example_commands> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> + # SConstruct file in 'po/' subdirectory + env = Environment( tools = ['default', 'xgettext'] ) + env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH='../') +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<emphasis>Example 5.</emphasis> +Multiple search directories may be defined within a list, i.e. +<literal>XGETTEXTPATH = ['dir1', 'dir2', ...]</literal>. The order in the list +determines the search order of source files. The path to the first file found +is used. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Let's create <filename>0/1/po/SConstruct</filename> script: +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> + # SConstruct file in '0/1/po/' subdirectory + env = Environment( tools = ['default', 'xgettext'] ) + env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../', '../../']) +</example_commands> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +and <filename>0/1/po/POTFILES.in</filename>: +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> + # POTFILES.in in '0/1/po/' subdirectory + a.cpp + # end of file +</example_commands> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Write two <filename>*.cpp</filename> files, the first one is +<filename>0/a.cpp</filename>: +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> + /* 0/a.cpp */ + gettext("Hello from ../../a.cpp") +</example_commands> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +and the second is <filename>0/1/a.cpp</filename>: +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> + /* 0/1/a.cpp */ + gettext("Hello from ../a.cpp") +</example_commands> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +then run scons. You'll obtain <literal>0/1/po/messages.pot</literal> with the +message <literal>"Hello from ../a.cpp"</literal>. When you reverse order in +<varname>$XGETTEXTFOM</varname>, i.e. when you write SConscript as +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> + # SConstruct file in '0/1/po/' subdirectory + env = Environment( tools = ['default', 'xgettext'] ) + env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../../', '../']) +</example_commands> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +then the <filename>messages.pot</filename> will contain +<literal>msgid "Hello from ../../a.cpp"</literal> line and not +<literal>msgid "Hello from ../a.cpp"</literal>. +</para> + +</listitem> + </varlistentry> + <varlistentry id="b-POUpdate"> + <term> + <synopsis> + <function>POUpdate()</function> + </synopsis> + <synopsis> + <function>env.POUpdate()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The builder belongs to <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="t-msgmerge"><literal>msgmerge</literal></link> tool. The builder updates +<literal>PO</literal> files with <command>msgmerge(1)</command>, or initializes +missing <literal>PO</literal> files as described in documentation of +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="t-msginit"><literal>msginit</literal></link> tool and <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-POInit"><function>POInit</function></link> builder (see also +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-POAUTOINIT"><envar>$POAUTOINIT</envar></link>). Note, that <function xmlns="http://www.scons.org/dbxsd/v1.0">POUpdate</function> <emphasis>does not add its +targets to <literal>po-create</literal> alias</emphasis> as <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-POInit"><function>POInit</function></link> +does. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Target nodes defined through <function xmlns="http://www.scons.org/dbxsd/v1.0">POUpdate</function> are not built by default +(they're <literal>Ignore</literal>d from <literal>'.'</literal> node). Instead, +they are added automatically to special <literal>Alias</literal> +(<literal>'po-update'</literal> by default). The alias name may be changed +through the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-POUPDATE_ALIAS"><envar>$POUPDATE_ALIAS</envar></link> construction variable. You can easilly +update <literal>PO</literal> files in your project by <command>scons +po-update</command>. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<emphasis>Example 1.</emphasis> +Update <filename>en.po</filename> and <filename>pl.po</filename> from +<filename>messages.pot</filename> template (see also <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-POTDOMAIN"><envar>$POTDOMAIN</envar></link>), +assuming that the later one exists or there is rule to build it (see +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-POTUpdate"><function>POTUpdate</function></link>): +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> + # ... + env.POUpdate(['en','pl']) # messages.pot --> [en.po, pl.po] +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<emphasis>Example 2.</emphasis> +Update <filename>en.po</filename> and <filename>pl.po</filename> from +<filename>foo.pot</filename> template: +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> + # ... + env.POUpdate(['en', 'pl'], ['foo']) # foo.pot --> [en.po, pl.pl] +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<emphasis>Example 3.</emphasis> +Update <filename>en.po</filename> and <filename>pl.po</filename> from +<filename>foo.pot</filename> (another version): +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> + # ... + env.POUpdate(['en', 'pl'], POTDOMAIN='foo') # foo.pot -- > [en.po, pl.pl] +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<emphasis>Example 4.</emphasis> +Update files for languages defined in <filename>LINGUAS</filename> file. The +files are updated from <filename>messages.pot</filename> template: +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> + # ... + env.POUpdate(LINGUAS_FILE = 1) # needs 'LINGUAS' file +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<emphasis>Example 5.</emphasis> +Same as above, but update from <filename>foo.pot</filename> template: +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> + # ... + env.POUpdate(LINGUAS_FILE = 1, source = ['foo']) +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<emphasis>Example 6.</emphasis> +Update <filename>en.po</filename> and <filename>pl.po</filename> plus files for +languages defined in <filename>LINGUAS</filename> file. The files are updated +from <filename>messages.pot</filename> template: +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> + # produce 'en.po', 'pl.po' + files defined in 'LINGUAS': + env.POUpdate(['en', 'pl' ], LINGUAS_FILE = 1) +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<emphasis>Example 7.</emphasis> +Use <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-POAUTOINIT"><envar>$POAUTOINIT</envar></link> to automatically initialize <literal>PO</literal> file +if it doesn't exist: +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> + # ... + env.POUpdate(LINGUAS_FILE = 1, POAUTOINIT = 1) +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<emphasis>Example 8.</emphasis> +Update <literal>PO</literal> files for languages defined in +<filename>LINGUAS</filename> file. The files are updated from +<filename>foo.pot</filename> template. All necessary settings are +pre-configured via environment. +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> + # ... + env['POAUTOINIT'] = 1 + env['LINGUAS_FILE'] = 1 + env['POTDOMAIN'] = 'foo' + env.POUpdate() +</example_commands> + +</listitem> + </varlistentry> + <varlistentry id="b-Program"> + <term> + <synopsis> + <function>Program()</function> + </synopsis> + <synopsis> + <function>env.Program()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Builds an executable given one or more object files +or C, C++, D, or Fortran source files. +If any C, C++, D or Fortran source files are specified, +then they will be automatically +compiled to object files using the +<function xmlns="http://www.scons.org/dbxsd/v1.0">Object</function> +builder method; +see that builder method's description for +a list of legal source file suffixes +and how they are interpreted. +The target executable file prefix +(specified by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-PROGPREFIX"><envar>$PROGPREFIX</envar></link> construction variable; nothing by default) +and suffix +(specified by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-PROGSUFFIX"><envar>$PROGSUFFIX</envar></link> construction variable; +by default, <filename>.exe</filename> on Windows systems, +nothing on POSIX systems) +are automatically added to the target if not already present. +Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f']) +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="b-RES"> + <term> + <synopsis> + <function>RES()</function> + </synopsis> + <synopsis> + <function>env.RES()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Builds a Microsoft Visual C++ resource file. +This builder method is only provided +when Microsoft Visual C++ or MinGW is being used as the compiler. The +<filename>.res</filename> +(or +<filename>.o</filename> +for MinGW) suffix is added to the target name if no other suffix is given. +The source +file is scanned for implicit dependencies as though it were a C file. +Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.RES('resource.rc') +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="b-RMIC"> + <term> + <synopsis> + <function>RMIC()</function> + </synopsis> + <synopsis> + <function>env.RMIC()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Builds stub and skeleton class files +for remote objects +from Java <filename>.class</filename> files. +The target is a directory +relative to which the stub +and skeleton class files will be written. +The source can be the names of <filename>.class</filename> files, +or the objects return from the +<function xmlns="http://www.scons.org/dbxsd/v1.0">Java</function> +builder method. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +If the construction variable +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-JAVACLASSDIR"><envar>$JAVACLASSDIR</envar></link> +is set, either in the environment +or in the call to the +<function xmlns="http://www.scons.org/dbxsd/v1.0">RMIC</function> +builder method itself, +then the value of the variable +will be stripped from the +beginning of any <filename>.class </filename> +file names. +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +classes = env.Java(target = 'classdir', source = 'src') +env.RMIC(target = 'outdir1', source = classes) + +env.RMIC(target = 'outdir2', + source = ['package/foo.class', 'package/bar.class']) + +env.RMIC(target = 'outdir3', + source = ['classes/foo.class', 'classes/bar.class'], + JAVACLASSDIR = 'classes') +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="b-RPCGenClient"> + <term> + <synopsis> + <function>RPCGenClient()</function> + </synopsis> + <synopsis> + <function>env.RPCGenClient()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Generates an RPC client stub (<filename>_clnt.c</filename>) file +from a specified RPC (<filename>.x</filename>) source file. +Because rpcgen only builds output files +in the local directory, +the command will be executed +in the source file's directory by default. +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +# Builds src/rpcif_clnt.c +env.RPCGenClient('src/rpcif.x') +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="b-RPCGenHeader"> + <term> + <synopsis> + <function>RPCGenHeader()</function> + </synopsis> + <synopsis> + <function>env.RPCGenHeader()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Generates an RPC header (<filename>.h</filename>) file +from a specified RPC (<filename>.x</filename>) source file. +Because rpcgen only builds output files +in the local directory, +the command will be executed +in the source file's directory by default. +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +# Builds src/rpcif.h +env.RPCGenHeader('src/rpcif.x') +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="b-RPCGenService"> + <term> + <synopsis> + <function>RPCGenService()</function> + </synopsis> + <synopsis> + <function>env.RPCGenService()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Generates an RPC server-skeleton (<filename>_svc.c</filename>) file +from a specified RPC (<filename>.x</filename>) source file. +Because rpcgen only builds output files +in the local directory, +the command will be executed +in the source file's directory by default. +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +# Builds src/rpcif_svc.c +env.RPCGenClient('src/rpcif.x') +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="b-RPCGenXDR"> + <term> + <synopsis> + <function>RPCGenXDR()</function> + </synopsis> + <synopsis> + <function>env.RPCGenXDR()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Generates an RPC XDR routine (<filename>_xdr.c</filename>) file +from a specified RPC (<filename>.x</filename>) source file. +Because rpcgen only builds output files +in the local directory, +the command will be executed +in the source file's directory by default. +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +# Builds src/rpcif_xdr.c +env.RPCGenClient('src/rpcif.x') +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="b-SharedLibrary"> + <term> + <synopsis> + <function>SharedLibrary()</function> + </synopsis> + <synopsis> + <function>env.SharedLibrary()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Builds a shared library +(<filename>.so</filename> on a POSIX system, +<filename>.dll</filename> on Windows) +given one or more object files +or C, C++, D or Fortran source files. +If any source files are given, +then they will be automatically +compiled to object files. +The static library prefix and suffix (if any) +are automatically added to the target. +The target library file prefix +(specified by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHLIBPREFIX"><envar>$SHLIBPREFIX</envar></link> construction variable; +by default, <filename>lib</filename> on POSIX systems, +nothing on Windows systems) +and suffix +(specified by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHLIBSUFFIX"><envar>$SHLIBSUFFIX</envar></link> construction variable; +by default, <filename>.dll</filename> on Windows systems, +<filename>.so</filename> on POSIX systems) +are automatically added to the target if not already present. +Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o']) +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +On Windows systems, the +<function xmlns="http://www.scons.org/dbxsd/v1.0">SharedLibrary</function> +builder method will always build an import +(<filename>.lib</filename>) library +in addition to the shared (<filename>.dll</filename>) library, +adding a <filename>.lib</filename> library with the same basename +if there is not already a <filename>.lib</filename> file explicitly +listed in the targets. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Any object files listed in the +<literal>source</literal> +must have been built for a shared library +(that is, using the +<function xmlns="http://www.scons.org/dbxsd/v1.0">SharedObject</function> +builder method). +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +will raise an error if there is any mismatch. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +On some platforms, there is a distinction between a shared library +(loaded automatically by the system to resolve external references) +and a loadable module (explicitly loaded by user action). +For maximum portability, use the <function xmlns="http://www.scons.org/dbxsd/v1.0">LoadableModule</function> builder for the latter. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +When the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHLIBVERSION"><envar>$SHLIBVERSION</envar></link> construction variable is defined a versioned +shared library is created. This modifies the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHLINKFLAGS"><envar>$SHLINKFLAGS</envar></link> as required, +adds the version number to the library name, and creates the symlinks that +are needed. <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHLIBVERSION"><envar>$SHLIBVERSION</envar></link> needs to be of the form X.Y.Z, where X +and Y are numbers, and Z is a number but can also contain letters to designate +alpha, beta, or release candidate patch levels. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +This builder may create multiple links to the library. On a POSIX system, +for the shared library libbar.so.2.3.1, the links created would be +libbar.so, libbar.so.2, and libbar.so.2.3; on a Darwin (OSX) system +the library would be libbar.2.3.1.dylib and the link would be +libbar.dylib. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +On Windows systems, specifying +<literal>register=1</literal> +will cause the <filename>.dll</filename> to be +registered after it is built using REGSVR32. +The command that is run +("regsvr32" by default) is determined by <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-REGSVR"><envar>$REGSVR</envar></link> construction +variable, and the flags passed are determined by <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-REGSVRFLAGS"><envar>$REGSVRFLAGS</envar></link>. By +default, <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-REGSVRFLAGS"><envar>$REGSVRFLAGS</envar></link> includes the <option>/s</option> option, +to prevent dialogs from popping +up and requiring user attention when it is run. If you change +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-REGSVRFLAGS"><envar>$REGSVRFLAGS</envar></link>, be sure to include the <option>/s</option> option. +For example, +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.SharedLibrary(target = 'bar', + source = ['bar.cxx', 'foo.obj'], + register=1) +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +will register <filename>bar.dll</filename> as a COM object +when it is done linking it. +</para> +</listitem> + </varlistentry> + <varlistentry id="b-SharedObject"> + <term> + <synopsis> + <function>SharedObject()</function> + </synopsis> + <synopsis> + <function>env.SharedObject()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Builds an object file for +inclusion in a shared library. +Source files must have one of the same set of extensions +specified above for the +<function xmlns="http://www.scons.org/dbxsd/v1.0">StaticObject</function> +builder method. +On some platforms building a shared object requires additional +compiler option +(e.g. <option>-fPIC</option> for gcc) +in addition to those needed to build a +normal (static) object, but on some platforms there is no difference between a +shared object and a normal (static) one. When there is a difference, SCons +will only allow shared objects to be linked into a shared library, and will +use a different suffix for shared objects. On platforms where there is no +difference, SCons will allow both normal (static) +and shared objects to be linked into a +shared library, and will use the same suffix for shared and normal +(static) objects. +The target object file prefix +(specified by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHOBJPREFIX"><envar>$SHOBJPREFIX</envar></link> construction variable; +by default, the same as <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-OBJPREFIX"><envar>$OBJPREFIX</envar></link>) +and suffix +(specified by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHOBJSUFFIX"><envar>$SHOBJSUFFIX</envar></link> construction variable) +are automatically added to the target if not already present. +Examples: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.SharedObject(target = 'ddd', source = 'ddd.c') +env.SharedObject(target = 'eee.o', source = 'eee.cpp') +env.SharedObject(target = 'fff.obj', source = 'fff.for') +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Note that the source files will be scanned +according to the suffix mappings in the +<literal>SourceFileScanner</literal> +object. +See the section "Scanner Objects," +below, for more information. +</para> +</listitem> + </varlistentry> + <varlistentry id="b-StaticLibrary"> + <term> + <synopsis> + <function>StaticLibrary()</function> + </synopsis> + <synopsis> + <function>env.StaticLibrary()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Builds a static library given one or more object files +or C, C++, D or Fortran source files. +If any source files are given, +then they will be automatically +compiled to object files. +The static library prefix and suffix (if any) +are automatically added to the target. +The target library file prefix +(specified by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-LIBPREFIX"><envar>$LIBPREFIX</envar></link> construction variable; +by default, <filename>lib</filename> on POSIX systems, +nothing on Windows systems) +and suffix +(specified by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-LIBSUFFIX"><envar>$LIBSUFFIX</envar></link> construction variable; +by default, <filename>.lib</filename> on Windows systems, +<filename>.a</filename> on POSIX systems) +are automatically added to the target if not already present. +Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o']) +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Any object files listed in the +<literal>source</literal> +must have been built for a static library +(that is, using the +<function xmlns="http://www.scons.org/dbxsd/v1.0">StaticObject</function> +builder method). +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +will raise an error if there is any mismatch. +</para> +</listitem> + </varlistentry> + <varlistentry id="b-StaticObject"> + <term> + <synopsis> + <function>StaticObject()</function> + </synopsis> + <synopsis> + <function>env.StaticObject()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Builds a static object file +from one or more C, C++, D, or Fortran source files. +Source files must have one of the following extensions: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> + .asm assembly language file + .ASM assembly language file + .c C file + .C Windows: C file + POSIX: C++ file + .cc C++ file + .cpp C++ file + .cxx C++ file + .cxx C++ file + .c++ C++ file + .C++ C++ file + .d D file + .f Fortran file + .F Windows: Fortran file + POSIX: Fortran file + C pre-processor + .for Fortran file + .FOR Fortran file + .fpp Fortran file + C pre-processor + .FPP Fortran file + C pre-processor + .m Object C file + .mm Object C++ file + .s assembly language file + .S Windows: assembly language file + ARM: CodeSourcery Sourcery Lite + .sx assembly language file + C pre-processor + POSIX: assembly language file + C pre-processor + .spp assembly language file + C pre-processor + .SPP assembly language file + C pre-processor +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The target object file prefix +(specified by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-OBJPREFIX"><envar>$OBJPREFIX</envar></link> construction variable; nothing by default) +and suffix +(specified by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-OBJSUFFIX"><envar>$OBJSUFFIX</envar></link> construction variable; +<filename>.obj</filename> on Windows systems, +<filename>.o</filename> on POSIX systems) +are automatically added to the target if not already present. +Examples: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.StaticObject(target = 'aaa', source = 'aaa.c') +env.StaticObject(target = 'bbb.o', source = 'bbb.c++') +env.StaticObject(target = 'ccc.obj', source = 'ccc.f') +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Note that the source files will be scanned +according to the suffix mappings in +<literal>SourceFileScanner</literal> +object. +See the section "Scanner Objects," +below, for more information. +</para> +</listitem> + </varlistentry> + <varlistentry id="b-Substfile"> + <term> + <synopsis> + <function>Substfile()</function> + </synopsis> + <synopsis> + <function>env.Substfile()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The <function xmlns="http://www.scons.org/dbxsd/v1.0">Substfile</function> builder generates a single text file +by concatenating the source files. +Nested lists of sources are flattened. +<envar xmlns="http://www.scons.org/dbxsd/v1.0">$LINESEPARATOR</envar> is used to separate the source files; +see the description of <function xmlns="http://www.scons.org/dbxsd/v1.0">Textfile</function> for details. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +If a single source file is present with an <filename>.in</filename> suffix, +the suffix is stripped and the remainder is used as the default target name. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The prefix and suffix specified by the <envar xmlns="http://www.scons.org/dbxsd/v1.0">$SUBSTFILEPREFIX</envar> +and <envar xmlns="http://www.scons.org/dbxsd/v1.0">$SUBSTFILESUFFIX</envar> construction variables +(the null string by default in both cases) +are automatically added to the target if they are not already present. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +If a construction variable named <envar xmlns="http://www.scons.org/dbxsd/v1.0">$SUBST_DICT</envar> is present, +it may be either a Python dictionary or a sequence of (key,value) tuples. +If the former, +the dictionary is converted into a list of tuples in an arbitrary order, +so if one key is a prefix of another key +or if one substitution could be further expanded by another subsitition, +it is unpredictible whether the expansion will occur. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Any occurences in the source of a key +are replaced by the corresponding value, +which may be a Python callable function or a string. +If a value is a function, +it is first called (with no arguments) to produce a string. +The string is <emphasis>subst</emphasis>-expanded +and the result replaces the key. +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env = Environment(tools = ['default', 'textfile']) + +env['prefix'] = '/usr/bin' +script_dict = {'@prefix@': '/bin', @exec_prefix@: '$prefix'} +env.Substfile('script.in', SUBST_DICT = script_dict) + +conf_dict = {'%VERSION%': '1.2.3', '%BASE%': 'MyProg'} +env.Substfile('config.h.in', conf_dict, SUBST_DICT = conf_dict) + +# UNPREDICTABLE - one key is a prefix of another +bad_foo = {'$foo': '$foo', '$foobar': '$foobar'} +env.Substfile('foo.in', SUBST_DICT = bad_foo) + +# PREDICTABLE - keys are applied longest first +good_foo = [('$foobar', '$foobar'), ('$foo', '$foo')] +env.Substfile('foo.in', SUBST_DICT = good_foo) + +# UNPREDICTABLE - one substitution could be futher expanded +bad_bar = {'@bar@': '@soap@', '@soap@': 'lye'} +env.Substfile('bar.in', SUBST_DICT = bad_bar) + +# PREDICTABLE - substitutions are expanded in order +good_bar = (('@bar@', '@soap@'), ('@soap@', 'lye')) +env.Substfile('bar.in', SUBST_DICT = good_bar) + +# the SUBST_DICT may be in common (and not an override) +substutions = {} +subst = Environment(tools = ['textfile'], SUBST_DICT = substitutions) +substitutions['@foo@'] = 'foo' +subst['SUBST_DICT']['@bar@'] = 'bar' +subst.Substfile('pgm1.c', [Value('#include "@foo@.h"'), + Value('#include "@bar@.h"'), + "common.in", + "pgm1.in" + ]) +subst.Substfile('pgm2.c', [Value('#include "@foo@.h"'), + Value('#include "@bar@.h"'), + "common.in", + "pgm2.in" + ]) + +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="b-Tar"> + <term> + <synopsis> + <function>Tar()</function> + </synopsis> + <synopsis> + <function>env.Tar()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Builds a tar archive of the specified files +and/or directories. +Unlike most builder methods, +the +<function xmlns="http://www.scons.org/dbxsd/v1.0">Tar</function> +builder method may be called multiple times +for a given target; +each additional call +adds to the list of entries +that will be built into the archive. +Any source directories will +be scanned for changes to +any on-disk files, +regardless of whether or not +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +knows about them from other Builder or function calls. +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.Tar('src.tar', 'src') + +# Create the stuff.tar file. +env.Tar('stuff', ['subdir1', 'subdir2']) +# Also add "another" to the stuff.tar file. +env.Tar('stuff', 'another') + +# Set TARFLAGS to create a gzip-filtered archive. +env = Environment(TARFLAGS = '-c -z') +env.Tar('foo.tar.gz', 'foo') + +# Also set the suffix to .tgz. +env = Environment(TARFLAGS = '-c -z', + TARSUFFIX = '.tgz') +env.Tar('foo') +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="b-Textfile"> + <term> + <synopsis> + <function>Textfile()</function> + </synopsis> + <synopsis> + <function>env.Textfile()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The <function xmlns="http://www.scons.org/dbxsd/v1.0">Textfile</function> builder generates a single text file. +The source strings constitute the lines; +nested lists of sources are flattened. +<envar xmlns="http://www.scons.org/dbxsd/v1.0">$LINESEPARATOR</envar> is used to separate the strings. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +If present, the <envar xmlns="http://www.scons.org/dbxsd/v1.0">$SUBST_DICT</envar> construction variable +is used to modify the strings before they are written; +see the <function xmlns="http://www.scons.org/dbxsd/v1.0">Substfile</function> description for details. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The prefix and suffix specified by the <envar xmlns="http://www.scons.org/dbxsd/v1.0">$TEXTFILEPREFIX</envar> +and <envar xmlns="http://www.scons.org/dbxsd/v1.0">$TEXTFILESUFFIX</envar> construction variables +(the null string and <filename>.txt</filename> by default, respectively) +are automatically added to the target if they are not already present. +Examples: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +# builds/writes foo.txt +env.Textfile(target = 'foo.txt', source = ['Goethe', 42, 'Schiller']) + +# builds/writes bar.txt +env.Textfile(target = 'bar', + source = ['lalala', 'tanteratei'], + LINESEPARATOR='|*') + +# nested lists are flattened automatically +env.Textfile(target = 'blob', + source = ['lalala', ['Goethe', 42 'Schiller'], 'tanteratei']) + +# files may be used as input by wraping them in File() +env.Textfile(target = 'concat', # concatenate files with a marker between + source = [File('concat1'), File('concat2')], + LINESEPARATOR = '====================\n') + +Results are: +foo.txt + ....8<---- + Goethe + 42 + Schiller + ....8<---- (no linefeed at the end) + +bar.txt: + ....8<---- + lalala|*tanteratei + ....8<---- (no linefeed at the end) + +blob.txt + ....8<---- + lalala + Goethe + 42 + Schiller + tanteratei + ....8<---- (no linefeed at the end) +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="b-Translate"> + <term> + <synopsis> + <function>Translate()</function> + </synopsis> + <synopsis> + <function>env.Translate()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +This pseudo-builder belongs to <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="t-gettext"><literal>gettext</literal></link> toolset. The builder extracts +internationalized messages from source files, updates <literal>POT</literal> +template (if necessary) and then updates <literal>PO</literal> translations (if +necessary). If <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-POAUTOINIT"><envar>$POAUTOINIT</envar></link> is set, missing <literal>PO</literal> files +will be automatically created (i.e. without translator person intervention). +The variables <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-LINGUAS_FILE"><envar>$LINGUAS_FILE</envar></link> and <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-POTDOMAIN"><envar>$POTDOMAIN</envar></link> are taken into +acount too. All other construction variables used by <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-POTUpdate"><function>POTUpdate</function></link>, and +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-POUpdate"><function>POUpdate</function></link> work here too. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<emphasis>Example 1</emphasis>. +The simplest way is to specify input files and output languages inline in +a SCons script when invoking <function xmlns="http://www.scons.org/dbxsd/v1.0">Translate</function> +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +# SConscript in 'po/' directory +env = Environment( tools = ["default", "gettext"] ) +env['POAUTOINIT'] = 1 +env.Translate(['en','pl'], ['../a.cpp','../b.cpp']) +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<emphasis>Example 2</emphasis>. +If you wish, you may also stick to conventional style known from +<productname>autotools</productname>, i.e. using +<filename>POTFILES.in</filename> and <filename>LINGUAS</filename> files +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +# LINGUAS +en pl +#end +</example_commands> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +# POTFILES.in +a.cpp +b.cpp +# end +</example_commands> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +# SConscript +env = Environment( tools = ["default", "gettext"] ) +env['POAUTOINIT'] = 1 +env['XGETTEXTPATH'] = ['../'] +env.Translate(LINGUAS_FILE = 1, XGETTEXTFROM = 'POTFILES.in') +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +The last approach is perhaps the recommended one. It allows easily split +internationalization/localization onto separate SCons scripts, where a script +in source tree is responsible for translations (from sources to +<literal>PO</literal> files) and script(s) under variant directories are +responsible for compilation of <literal>PO</literal> to <literal>MO</literal> +files to and for installation of <literal>MO</literal> files. The "gluing +factor" synchronizing these two scripts is then the content of +<filename>LINGUAS</filename> file. Note, that the updated +<literal>POT</literal> and <literal>PO</literal> files are usually going to be +committed back to the repository, so they must be updated within the source +directory (and not in variant directories). Additionaly, the file listing of +<filename>po/</filename> directory contains <filename>LINGUAS</filename> file, +so the source tree looks familiar to translators, and they may work with the +project in their usual way. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<emphasis>Example 3</emphasis>. +Let's prepare a development tree as below +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> + project/ + + SConstruct + + build/ + + src/ + + po/ + + SConscript + + SConscript.i18n + + POTFILES.in + + LINGUAS +</example_commands> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +with <filename>build</filename> being variant directory. Write the top-level +<filename>SConstruct</filename> script as follows +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> + # SConstruct + env = Environment( tools = ["default", "gettext"] ) + VariantDir('build', 'src', duplicate = 0) + env['POAUTOINIT'] = 1 + SConscript('src/po/SConscript.i18n', exports = 'env') + SConscript('build/po/SConscript', exports = 'env') +</example_commands> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +the <filename>src/po/SConscript.i18n</filename> as +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> + # src/po/SConscript.i18n + Import('env') + env.Translate(LINGUAS_FILE=1, XGETTEXTFROM='POTFILES.in', XGETTEXTPATH=['../']) +</example_commands> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +and the <filename>src/po/SConscript</filename> +</para> +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> + # src/po/SConscript + Import('env') + env.MOFiles(LINGUAS_FILE = 1) +</example_commands> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Such setup produces <literal>POT</literal> and <literal>PO</literal> files +under source tree in <filename>src/po/</filename> and binary +<literal>MO</literal> files under variant tree in +<filename>build/po/</filename>. This way the <literal>POT</literal> and +<literal>PO</literal> files are separated from other output files, which must +not be committed back to source repositories (e.g. <literal>MO</literal> +files). +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +<note><para>In above example, the <literal>PO</literal> files are not updated, +nor created automatically when you issue <command>scons '.'</command> command. +The files must be updated (created) by hand via <command>scons +po-update</command> and then <literal>MO</literal> files can be compiled by +running <command>scons '.'</command>.</para></note> +</para> + +</listitem> + </varlistentry> + <varlistentry id="b-TypeLibrary"> + <term> + <synopsis> + <function>TypeLibrary()</function> + </synopsis> + <synopsis> + <function>env.TypeLibrary()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Builds a Windows type library (<filename>.tlb</filename>) +file from an input IDL file (<filename>.idl</filename>). +In addition, it will build the associated inteface stub and +proxy source files, +naming them according to the base name of the <filename>.idl</filename> file. +For example, +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.TypeLibrary(source="foo.idl") +</example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Will create <filename>foo.tlb</filename>, +<filename>foo.h</filename>, +<filename>foo_i.c</filename>, +<filename>foo_p.c</filename> +and +<filename>foo_data.c</filename> +files. +</para> +</listitem> + </varlistentry> + <varlistentry id="b-Uic"> + <term> + <synopsis> + <function>Uic()</function> + </synopsis> + <synopsis> + <function>env.Uic()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Builds a header file, an implementation file and a moc file from an ui file. +and returns the corresponding nodes in the above order. +This builder is only available after using the tool 'qt'. Note: you can +specify <filename>.ui</filename> files directly as source +files to the <function xmlns="http://www.scons.org/dbxsd/v1.0">Program</function>, +<function xmlns="http://www.scons.org/dbxsd/v1.0">Library</function> and <function xmlns="http://www.scons.org/dbxsd/v1.0">SharedLibrary</function> builders +without using this builder. Using this builder lets you override the standard +naming conventions (be careful: prefixes are always prepended to names of +built files; if you don't want prefixes, you may set them to ``). +See the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-QTDIR"><envar>$QTDIR</envar></link> variable for more information. +Example: +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.Uic('foo.ui') # -> ['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'] +</example_commands> +</listitem> + </varlistentry> + <varlistentry id="b-Zip"> + <term> + <synopsis> + <function>Zip()</function> + </synopsis> + <synopsis> + <function>env.Zip()</function> + </synopsis> + </term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Builds a zip archive of the specified files +and/or directories. +Unlike most builder methods, +the +<function xmlns="http://www.scons.org/dbxsd/v1.0">Zip</function> +builder method may be called multiple times +for a given target; +each additional call +adds to the list of entries +that will be built into the archive. +Any source directories will +be scanned for changes to +any on-disk files, +regardless of whether or not +<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> +knows about them from other Builder or function calls. +</para> + +<example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> +env.Zip('src.zip', 'src') + +# Create the stuff.zip file. +env.Zip('stuff', ['subdir1', 'subdir2']) +# Also add "another" to the stuff.tar file. +env.Zip('stuff', 'another') +</example_commands> +</listitem> + </varlistentry> +</variablelist> |