path: root/doc/user/builders-built-in.sgml

<!--

  __COPYRIGHT__

  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>
      cl /nologo /c goodbye.c /Fogoodbye.obj
      cl /nologo /c hello.c /Fohello.obj
      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>