<?xml version='1.0'?>

<!--
SPDX-FileCopyrightText: Copyright The SCons Foundation (https://scons.org)
SPDX-License-Identifier: MIT
SPDX-FileType: DOCUMENTATION

This file is processed by the bin/SConsDoc.py module.
-->

<!DOCTYPE sconsdoc [
    <!ENTITY % scons SYSTEM "../scons.mod">
    %scons;

    <!ENTITY % builders-mod SYSTEM "../generated/builders.mod">
    %builders-mod;
    <!ENTITY % functions-mod SYSTEM "../generated/functions.mod">
    %functions-mod;
    <!ENTITY % tools-mod SYSTEM "../generated/tools.mod">
    %tools-mod;
    <!ENTITY % variables-mod SYSTEM "../generated/variables.mod">
    %variables-mod;

]>

<chapter id="chap-builders-built-in"
         xmlns="http://www.scons.org/dbxsd/v1.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">

<!-- TOOD: placeholder file, not currently included in build -->

<title>Built-In Builders</title>

  <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 id="sect-build-program">
  <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>

    <scons_example name="buildersbuiltin_libs">
      <file name="SConstruct" printme="1">
env = Environment(LIBS=['foo1', 'foo2'], LIBPATH=['/usr/dir1', 'dir2'])
env.Program(['hello.c', 'goodbye.c'])
      </file>
      <file name="hello.c">
int hello() { printf("Hello, world!\n"); }
      </file>
      <file name="goodbye.c">
int goodbye() { printf("Goodbye, world!\n"); }
      </file>
    </scons_example>

    <para>

    Will execute as follows on a POSIX system:

    </para>

    <scons_output example="buildersbuiltin_libs" os="posix" suffix="1">
      <scons_output_command>scons -Q</scons_output_command>
    </scons_output>

    <para>

    And execute as follows on a Windows system:

    </para>

    <scons_output example="buildersbuiltin_libs" os="win32" suffix="2">
      <scons_output_command>scons -Q</scons_output_command>
    </scons_output>

    <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 <literal>Program</literal>
    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 id="sect-build-objfiles">
  <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 id="sect-build-staticobj">
    <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 id="sect-build-sharedobj">
    <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 id="sect-build-obj">
    <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 id="sect-build-libraries">
  <title>Library Builders</title>

    <para>

    &SCons; provides separate Builder objects
    to create static and shared libraries.

    </para>

    <section id="sect-build-staticlib">
    <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 id="sect-build-sharedlib">
    <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 id="sect-build-lib">
    <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 id="sect-build-pch">
  <title>Pre-Compiled Headers:  the &PCH; Builder</title>

    <para>

    XXX PCH()

    </para>

  </section>

  <section id="sect-build-res">
  <title>&MSVC; Resource Files: the &RES; Builder</title>

    <para>

    XXX RES()

    </para>

  </section>

  <section id="sect-srcfiles">
  <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 id="sect-build-cfile">
    <title>The &CFile; Builder</title>

      <para>

      XXX CFile()

      </para>

      <programlisting>
XXX CFile() programlisting
      </programlisting>

      <screen>
XXX CFile() screen
      </screen>

    </section>

    <section id="sect-build-cxxfile">
    <title>The &CXXFile; Builder</title>

      <para>

      XXX CXXFILE()

      </para>

      <programlisting>
XXX CXXFILE() programlisting
      </programlisting>

      <screen>
XXX CXXFILE() screen
      </screen>

    </section>

  </section>

  <section id="sect-doc-builders">
  <title>Documents</title>

    <para>

    &SCons; provides a number of Builder objects
    for creating different types of documents.

    </para>

    <section id="sect-build-dvi">
    <title>The &DVI; Builder</title>

      <para>

      XXX DVI() para

      </para>

      <programlisting>
XXX DVI() programlisting
      </programlisting>

      <screen>
XXX DVI() screen
      </screen>

    </section>

    <section id="sect-build-pdf">
    <title>The &PDF; Builder</title>

      <para>

      XXX PDF() para

      </para>

    </section>

    <section id="sect-build-postscript">
    <title>The &PostScript; Builder</title>

      <para>

      XXX PostScript() para

      </para>

      <programlisting>
XXX PostScript() programlisting
      </programlisting>

      <screen>
XXX PostScript() screen
      </screen>

    </section>

  </section>

  <section id="sect-archives">
  <title>Archives</title>

    <para>

    &SCons; provides Builder objects
    for creating two different types of archive files.

    </para>

    <section id="sect-build-tar">
    <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>

      <scons_example name="buildersbuiltin_ex1">
        <file name="SConstruct" printme="1">
env = Environment()
env.Tar('out1.tar', ['file1', 'file2'])
env.Tar('out2', 'directory')
        </file>
        <file name="file1">
file1
        </file>
        <file name="file2">
file2
        </file>
        <file name="directory/file3">
directory/file3
        </file>
      </scons_example>

      <scons_output example="buildersbuiltin_ex1" os="posix" suffix="1">
        <scons_output_command>scons -Q .</scons_output_command>
      </scons_output>

      <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>

      <scons_example name="buildersbuiltin_ex2">
        <file name="SConstruct" printme="1">
env = Environment(TARFLAGS = '-c -z')
env.Tar('out.tar.gz', 'directory')
        </file>
        <file name="directory/file">
directory/file
        </file>
      </scons_example>

      <scons_output example="buildersbuiltin_ex2" os="posix" suffix="1">
        <scons_output_command>scons -Q .</scons_output_command>
      </scons_output>

      <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>

      <scons_example name="buildersbuiltin_ex3">
        <file name="SConstruct" printme="1">
env = Environment(TARFLAGS='-c -z', TARSUFFIX='.tgz')
env.Tar('out', 'directory')
        </file>
        <file name="directory/file">
directory/file
        </file>
      </scons_example>

      <scons_output example="buildersbuiltin_ex3" os="posix" suffix="1">
        <scons_output_command>scons -Q .</scons_output_command>
      </scons_output>

    </section>

    <section id="sect-build-zip">
    <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>

      <scons_example name="buildersbuiltin_ex4">
        <file name="SConstruct" printme="1">
env = Environment()
env.Zip('out', ['file1', 'file2'])
        </file>
        <file name="file1">
file1
        </file>
        <file name="file2">
file2
        </file>
      </scons_example>

      <para>

      Your output will reflect the fact
      that an internal Python function
      is being used to create the output ZIP archive:

      </para>

      <scons_output example="buildersbuiltin_ex4" os="posix" suffix="1">
        <scons_output_command>scons -Q .</scons_output_command>
      </scons_output>

    </section>

  </section>

  <section id="sect-java-builders">
  <title>Java</title>

    <para>

    &SCons; provides Builder objects
    for creating various types of Java output files.

    </para>

    <section id="sect-build-java">
    <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 id="sect-build-jar">
    <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 id="sect-build-javah">
    <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 id="sect-build-rmic">
    <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>

</chapter>
