Merge commit 'upstream/1.2.0.d20091224'

1 files changed, 949 insertions, 0 deletions

diff --git a/doc/user/builders-built-in.xml b/doc/user/builders-built-in.xml
new file mode 100644
index 0000000..bee5b38
--- /dev/null
+++ b/doc/user/builders-built-in.xml
@@ -0,0 +1,949 @@
+<!--
+
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 The SCons Foundation
+
+  Permission is hereby granted, free of charge, to any person obtaining
+  a copy of this software and associated documentation files (the
+  "Software"), to deal in the Software without restriction, including
+  without limitation the rights to use, copy, modify, merge, publish,
+  distribute, sublicense, and/or sell copies of the Software, and to
+  permit persons to whom the Software is furnished to do so, subject to
+  the following conditions:
+
+  The above copyright notice and this permission notice shall be included
+  in all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+  KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+  WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+-->
+
+  <para>
+
+  &SCons; provides the ability to build a lot of different
+  types of files right "out of the box."
+  So far, we've been using &SCons;' ability to build
+  programs, objects and libraries to
+  illustrate much of the underlying functionality of &SCons;
+  This section will describe all of the different
+  types of files that you can build with &SCons;,
+  and the built-in &Builder; objects used to build them.
+  By default, all of the  &Builder; objects in this section
+  can be built either with or without an explicit
+  construction environment.
+
+  </para>
+
+  <section>
+  <title>Programs:  the &Program; Builder</title>
+
+    <para>
+
+    As we've seen, the &b-link-Program; Builder
+    is used to build an executable program.
+    The &source; argument is one or more
+    source-code files or object files,
+    and the &target; argument is the
+    name of the executable program name to be created.
+    For example:
+
+    </para>
+
+    <programlisting>
+      Program('prog', 'file1.o')
+    </programlisting>
+
+    <para>
+
+    Will create the &prog;
+    executable on a POSIX system,
+    the &prog_exe; executable on a Windows system.
+
+    </para>
+
+    <para>
+
+    The target file's prefix and suffix may be omitted,
+    and the values from the
+    &cv-link-PROGPREFIX;
+    and
+    &cv-link-PROGSUFFIX;
+    construction variables
+    will be appended appropriately.
+    For example:
+
+    </para>
+
+    <programlisting>
+      env = Environment(PROGPREFIX='my', PROGSUFFIX='.xxx')
+      env.Program('prog', ['file1.o', 'file2.o'])
+    </programlisting>
+
+    <para>
+
+    Will create a program named
+    <filename>myprog.xxx</filename>
+    regardless of the system on which it is run.
+
+    </para>
+
+    <para>
+
+    If you omit the &target;,
+    the base of the first input
+    file name specified
+    becomes the base of the target
+    program created.
+    For example:
+
+    </para>
+
+    <programlisting>
+      Program(['hello.c', 'goodbye.c'])
+    </programlisting>
+
+    <para>
+
+    Will create the &hello;
+    executable on a POSIX system,
+    the &hello_exe; executable on a Windows system.
+
+    </para>
+
+    <para>
+
+    Two construction variables control what libraries
+    will be linked with the resulting program.
+    The &cv-link-LIBS; variable is a list of the names of
+    libraries that will be linked into any programs,
+    and the &cv-link-LIBPATH; variables is a list of
+    directories that will be searched for
+    the specified libraries.
+    &SCons; will construct the right command-line
+    options for the running system.
+    For example:
+
+    </para>
+
+    <programlisting>
+      env = Environment(LIBS = ['foo1', 'foo2'],
+                        LIBPATH = ['/usr/dir1', 'dir2'])
+      env.Program(['hello.c', 'goodbye.c'])
+    </programlisting>
+
+    <para>
+
+    Will execute as follows on a POSIX system:
+
+    </para>
+
+    <screen>
+      % <userinput>scons -Q</userinput>
+      cc -o goodbye.o -c goodbye.c
+      cc -o hello.o -c hello.c
+      cc -o hello hello.o goodbye.o -L/usr/dir1 -Ldir2 -lfoo1 -lfoo2
+    </screen>
+
+    <para>
+
+    And execute as follows on a Windows system:
+
+    </para>
+
+    <screen>
+      C:\><userinput>scons -Q</userinput>
+      
+      scons: warning: No installed VCs
+      File "&lt;stdin&gt;", line 67, in __call__
+      
+      scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
+      File "&lt;stdin&gt;", line 67, in __call__
+      
+      scons: warning: No installed VCs
+      File "&lt;stdin&gt;", line 67, in __call__
+      
+      scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
+      File "&lt;stdin&gt;", line 67, in __call__
+      cl /Fogoodbye.obj /c goodbye.c /nologo
+      cl /Fohello.obj /c hello.c /nologo
+      link /nologo /OUT:hello.exe /LIBPATH:\usr\dir1 /LIBPATH:dir2 foo1.lib foo2.lib hello.obj goodbye.obj
+    </screen>
+
+    <para>
+
+    The &cv-LIBS; construction variable
+    is turned into command line options
+    by appending the &cv-link-LIBLINKPREFIX; and &cv-link-LIBLINKSUFFIX;
+    construction variables to the beginning and end,
+    respectively, of each specified library.
+
+    </para>
+
+    <para>
+
+    The &cv-LIBPATH; construction variable
+    is turned into command line options
+    by appending the &cv-link-LIBDIRPREFIX; and &cv-link-LIBDIRSUFFIX;
+    construction variables to the beginning and end,
+    respectively, of each specified library.
+
+    </para>
+
+    <para>
+
+    Other relevant construction variables
+    include those used by the &b-link-Object;
+    builders to affect how the
+    source files specified as input to the &t-Program;
+    builders are turned into object files;
+    see the next section.
+
+    </para>
+
+    <para>
+
+    The command line used to control how a program is linked
+    is specified by the &cv-link-LINKCOM; construction variable.
+    By default, it uses the
+    &cv-link-LINK; construction variable
+    and the &cv-link-LINKFLAGS; construction variable.
+
+    </para>
+
+  </section>
+
+  <section>
+  <title>Object-File Builders</title>
+
+    <para>
+
+    &SCons; provides separate Builder objects
+    to create static and shared object files.
+    The distinction becomes especially important when
+    archiving object files into different types of libraries.
+
+    </para>
+
+    <section>
+    <title>The &StaticObject; Builder</title>
+
+      <para>
+
+      The &b-link-StaticObject; Builder
+      is used to build an object file
+      suitable for static linking into a program,
+      or for inclusion in a static library.
+      The &source; argument is a single source-code file,
+      and the &target; argument is the
+      name of the static object file to be created.
+      For example:
+
+      </para>
+
+      <programlisting>
+        StaticObject('file', 'file.c')
+      </programlisting>
+
+      <para>
+
+      Will create the &file_o;
+      object file on a POSIX system,
+      the &file_obj; executable on a Windows system.
+
+      </para>
+
+      <para>
+
+      The target file's prefix and suffix may be omitted,
+      and the values from the
+      &cv-link-OBJPREFIX;
+      and
+      &cv-link-OBJSUFFIX;
+      construction variables
+      will be appended appropriately.
+      For example:
+
+      </para>
+
+      <programlisting>
+        env = Environment(OBJPREFIX='my', OBJSUFFIX='.xxx')
+        env.StaticObject('file', 'file.c')
+      </programlisting>
+
+      <para>
+
+      Will create an object file named
+      <filename>myfile.xxx</filename>
+      regardless of the system on which it is run.
+
+      </para>
+
+      <para>
+
+      If you omit the &target;,
+      the base of the first input
+      file name specified
+      beomces the base of the name
+      of the static object file to be created.
+      For example:
+
+      </para>
+
+      <programlisting>
+        StaticObject('file.c')
+      </programlisting>
+
+      <para>
+
+      Will create the &file_o;
+      executable on a POSIX system,
+      the &file_obj; executable on a Windows system.
+
+      </para>
+
+    </section>
+
+    <section>
+    <title>The &SharedObject; Builder</title>
+
+      <para>
+
+      The &b-link-SharedObject; Builder
+      is used to build an object file
+      suitable for shared linking into a program,
+      or for inclusion in a shared library.
+      The &source; argument is a single source-code file,
+      and the &target; argument is the
+      name of the shared object file to be created.
+      For example:
+
+      </para>
+
+      <programlisting>
+        SharedObject('file', 'file.c')
+      </programlisting>
+
+      <para>
+
+      Will create the &file_o;
+      object file on a POSIX system,
+      the &file_obj; executable on a Windows system.
+
+      </para>
+
+      <para>
+
+      The target file's prefix and suffix may be omitted,
+      and the values from the
+      &cv-link-SHOBJPREFIX;
+      and
+      &cv-link-SHOBJSUFFIX;
+      construction variables
+      will be appended appropriately.
+      For example:
+
+      </para>
+
+      <programlisting>
+        env = Environment(SHOBJPREFIX='my', SHOBJSUFFIX='.xxx')
+        env.SharedObject('file', 'file.c')
+      </programlisting>
+
+      <para>
+
+      Will create an object file named
+      <filename>myfile.xxx</filename>
+      regardless of the system on which it is run.
+
+      </para>
+
+      <para>
+
+      If you omit the &target;,
+      the base of the first input
+      file name specified
+      becomes the base of the name
+      of the shared object file to be created.
+      For example:
+
+      </para>
+
+      <programlisting>
+        SharedObject('file.c')
+      </programlisting>
+
+      <para>
+
+      Will create the &file_o;
+      executable on a POSIX system,
+      the &file_obj; executable on a Windows system.
+
+      </para>
+
+    </section>
+
+    <section>
+    <title>The &Object; Builder</title>
+
+      <para>
+
+      The &b-link-Object; Builder is a synonym for &b-link-StaticObject;
+      and is completely equivalent.
+
+      </para>
+
+    </section>
+
+  </section>
+
+  <section>
+  <title>Library Builders</title>
+
+    <para>
+
+    &SCons; provides separate Builder objects
+    to create static and shared libraries.
+
+    </para>
+
+    <section>
+    <title>The &StaticLibrary; Builder</title>
+
+      <para>
+
+      The &b-link-StaticLibrary; Builder
+      is used to create a library
+      suitable for static linking into a program.
+      The &source; argument is one or more
+      source-code files or object files,
+      and the &target; argument is the
+      name of the static library to be created.
+      For example:
+
+      </para>
+
+      <programlisting>
+        StaticLibrary('foo', ['file1.c', 'file2.c'])
+      </programlisting>
+
+      <para>
+
+      The target file's prefix and suffix may be omitted,
+      and the values from the
+      &cv-link-LIBPREFIX;
+      and
+      &cv-link-LIBSUFFIX;
+      construction variables
+      will be appended appropriately.
+      For example:
+
+      </para>
+
+      <programlisting>
+        env = Environment(LIBPREFIX='my', LIBSUFFIX='.xxx')
+        env.StaticLibrary('lib', ['file1.o', 'file2.o'])
+      </programlisting>
+
+      <para>
+
+      Will create an object file named
+      <filename>mylib.xxx</filename>
+      regardless of the system on which it is run.
+
+      </para>
+
+      <programlisting>
+        StaticLibrary('foo', ['file1.c', 'file2.c'])
+      </programlisting>
+
+      <para>
+
+      If you omit the &target;,
+      the base of the first input
+      file name specified
+      becomes the base of the name of the static object file to be created.
+      For example:
+
+      </para>
+
+      <programlisting>
+        StaticLibrary(['file.c', 'another.c'])
+      </programlisting>
+
+      <para>
+
+      Will create the &libfile_a;
+      library on a POSIX system,
+      the &file_lib; library on a Windows system.
+
+      </para>
+
+    </section>
+
+    <section>
+    <title>The &SharedLibrary; Builder</title>
+
+      <para>
+
+      The &b-link-SharedLibrary; Builder
+      is used to create a shared library
+      suitable for linking with a program.
+      The &source; argument is one or more
+      source-code files or object files,
+      and the &target; argument is the
+      name of the shared library to be created.
+      For example:
+
+      </para>
+
+      <programlisting>
+        SharedLibrary('foo', ['file1.c', 'file2.c'])
+      </programlisting>
+
+      <para>
+
+      The target file's prefix and suffix may be omitted,
+      and the values from the
+      &cv-link-SHLIBPREFIX;
+      and
+      &cv-link-SHLIBSUFFIX;
+      construction variables
+      will be appended appropriately.
+      For example:
+
+      </para>
+
+      <programlisting>
+        env = Environment(SHLIBPREFIX='my', SHLIBSUFFIX='.xxx')
+        env.SharedLibrary('shared', ['file1.o', 'file2.o'])
+      </programlisting>
+
+      <para>
+
+      Will create an object file named
+      <filename>myshared.xxx</filename>
+      regardless of the system on which it is run.
+
+      </para>
+
+      <programlisting>
+        SharedLibrary('foo', ['file1.c', 'file2.c'])
+      </programlisting>
+
+      <para>
+
+      If you omit the &target;,
+      the base of the first input
+      file name specified
+      becomes the base of the name of the shared library to be created.
+      For example:
+
+      </para>
+
+      <programlisting>
+        SharedLibrary(['file.c', 'another.c'])
+      </programlisting>
+
+      <para>
+
+      Will create the &libfile_so;
+      library on a POSIX system,
+      the &file_dll; library on a Windows system.
+
+      </para>
+
+    </section>
+
+    <section>
+    <title>The &Library; Builder</title>
+
+      <para>
+
+      The &b-link-Library; Builder is a synonym for &b-link-StaticLibrary;
+      and is completely equivalent.
+
+      </para>
+
+    </section>
+
+  </section>
+
+  <section>
+  <title>Pre-Compiled Headers:  the &PCH; Builder</title>
+
+    <para>
+
+    XXX PCH()
+
+    </para>
+
+  </section>
+
+  <section>
+  <title>Microsoft Visual C++ Resource Files: the &RES; Builder</title>
+
+    <para>
+
+    XXX RES()
+
+    </para>
+
+  </section>
+
+  <section>
+  <title>Source Files</title>
+
+    <para>
+
+    By default
+    &SCons; supports two Builder objects
+    that know how to build source files
+    from other input files.
+    These are typically invoked "internally"
+    to turn files that need preprocessing into other source files.
+
+    </para>
+
+    <section>
+    <title>The &CFile; Builder</title>
+
+      <para>
+
+      XXX CFile()
+
+      </para>
+
+      <programlisting>
+        XXX CFile() programlisting
+      </programlisting>
+
+      <screen>
+        XXX CFile() screen
+      </screen>
+
+    </section>
+
+    <section>
+    <title>The &CXXFile; Builder</title>
+
+      <para>
+
+      XXX CXXFILE()
+
+      </para>
+
+      <programlisting>
+        XXX CXXFILE() programlisting
+      </programlisting>
+
+      <screen>
+        XXX CXXFILE() screen
+      </screen>
+
+    </section>
+
+  </section>
+
+  <section>
+  <title>Documents</title>
+
+    <para>
+
+    &SCons; provides a number of Builder objects
+    for creating different types of documents.
+
+    </para>
+
+    <section>
+    <title>The &DVI; Builder</title>
+
+      <para>
+
+      XXX DVI() para
+
+      </para>
+
+      <programlisting>
+        XXX DVI() programlisting
+      </programlisting>
+
+      <screen>
+        XXX DVI() screen
+      </screen>
+
+    </section>
+
+    <section>
+    <title>The &PDF; Builder</title>
+
+      <para>
+
+      XXX PDF() para
+
+      </para>
+
+    </section>
+
+    <section>
+    <title>The &PostScript; Builder</title>
+
+      <para>
+
+      XXX PostScript() para
+
+      </para>
+
+      <programlisting>
+        XXX PostScript() programlisting
+      </programlisting>
+
+      <screen>
+        XXX PostScript() screen
+      </screen>
+
+    </section>
+
+  </section>
+
+  <section>
+  <title>Archives</title>
+
+    <para>
+
+    &SCons; provides Builder objects
+    for creating two different types of archive files.
+
+    </para>
+
+    <section>
+    <title>The &Tar; Builder</title>
+
+      <para>
+
+      The &b-link-Tar; Builder object uses the &tar;
+      utility to create archives of files
+      and/or directory trees:
+
+      </para>
+
+      <programlisting>
+        env = Environment()
+        env.Tar('out1.tar', ['file1', 'file2'])
+        env.Tar('out2', 'directory')
+      </programlisting>
+
+      <screen>
+        % <userinput>scons -Q .</userinput>
+        tar -c -f out1.tar file1 file2
+        tar -c -f out2.tar directory
+      </screen>
+
+      <para>
+
+      One common requirement when creating a &tar; archive
+      is to create a compressed archive using the
+      <option>-z</option> option.
+      This is easily handled by specifying
+      the value of the &cv-link-TARFLAGS; variable
+      when you create the construction environment.
+      Note, however, that the <option>-c</option> used to
+      to instruct &tar; to create the archive
+      is part of the default value of &cv-TARFLAGS;,
+      so you need to set it both options:
+
+      </para>
+
+      <programlisting>
+        env = Environment(TARFLAGS = '-c -z')
+        env.Tar('out.tar.gz', 'directory')
+      </programlisting>
+
+      <screen>
+        % <userinput>scons -Q .</userinput>
+        tar -c -z -f out.tar.gz directory
+      </screen>
+
+      <para>
+
+      you may also wish to set the value of the
+      &cv-link-TARSUFFIX; construction variable
+      to your desired suffix for compress &tar; archives,
+      so that &SCons; can append it to the target file name
+      without your having to specify it explicitly:
+
+      </para>
+
+      <programlisting>
+        env = Environment(TARFLAGS = '-c -z',
+                          TARSUFFIX = '.tgz')
+        env.Tar('out', 'directory')
+      </programlisting>
+
+      <screen>
+        % <userinput>scons -Q .</userinput>
+        tar -c -z -f out.tgz directory
+      </screen>
+
+    </section>
+
+    <section>
+    <title>The &Zip; Builder</title>
+
+      <para>
+
+      The &b-link-Zip; Builder object creates archives of files
+      and/or directory trees in the ZIP file format.
+      Python versions 1.6 or later
+      contain an internal &zipfile; module
+      that &SCons; will use.
+      In this case, given the following
+      &SConstruct; file:
+
+      </para>
+
+      <programlisting>
+        env = Environment()
+        env.Zip('out', ['file1', 'file2'])
+      </programlisting>
+
+      <para>
+
+      Your output will reflect the fact
+      that an internal Python function
+      is being used to create the output ZIP archive:
+
+      </para>
+
+      <screen>
+        % <userinput>scons -Q .</userinput>
+        zip(["out.zip"], ["file1", "file2"])
+      </screen>
+
+      <para>
+
+      If you're using Python version 1.5.2 to run &SCons;,
+      then &SCons; will try to use an external
+      &zip; program as follows:
+
+      </para>
+
+      <screen>
+        % <userinput>scons -Q .</userinput>
+        zip /home/my/project/zip.out file1 file2
+      </screen>
+
+    </section>
+
+  </section>
+
+  <section>
+  <title>Java</title>
+
+    <para>
+
+    &SCons; provides Builder objects
+    for creating various types of Java output files.
+
+    </para>
+
+    <section>
+    <title>Building Class Files:  the &Java; Builder</title>
+
+      <para>
+
+      The &b-link-Java; builder takes one or more input
+      <filename>.java</filename> files
+      and turns them into one or more
+      <filename>.class</filename> files
+      Unlike most builders, however,
+      the &Java; builder takes
+      target and source <emphasis>directories</emphasis>,
+      not files, as input.
+
+      </para>
+
+      <programlisting>
+        env = Environment()
+        env.Java(target = 'classes', source = 'src')
+      </programlisting>
+
+      <para>
+
+      The &Java; builder will then
+      search the specified source directory
+      tree for all <filename>.java</filename> files,
+      and pass any out-of-date
+
+      </para>
+
+      <screen>
+        XXX Java() screen
+      </screen>
+
+    </section>
+
+    <section>
+    <title>The &Jar; Builder</title>
+
+      <para>
+
+      XXX The &Jar; builder object
+
+      </para>
+
+      <programlisting>
+        env = Environment()
+        env.Java(target = 'classes', source = 'src')
+        env.Jar(target = '', source = 'classes')
+      </programlisting>
+
+      <screen>
+        XXX Jar() screen
+      </screen>
+
+    </section>
+
+    <section>
+    <title>Building C header and stub files:  the &JavaH; Builder</title>
+
+      <para>
+
+      XXX JavaH() para
+
+      </para>
+
+      <programlisting>
+        XXX JavaH() programlisting
+      </programlisting>
+
+      <screen>
+        XXX JavaH() screen
+      </screen>
+
+    </section>
+
+    <section>
+    <title>Building RMI stub and skeleton class files:  the &RMIC; Builder</title>
+
+      <para>
+
+      XXX RMIC() para
+
+      </para>
+
+      <programlisting>
+        XXX RMIC() programlisting
+      </programlisting>
+
+      <screen>
+        XXX RMIC() screen
+      </screen>
+
+    </section>
+
+  </section>