# Built-In Builders

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

## Programs: the &Program; Builder

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:

    Program('prog', 'file1.o')

Will create the &prog; executable on a POSIX system, the &prog_exe; executable on a Windows system.

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:

    env = Environment(PROGPREFIX='my', PROGSUFFIX='.xxx')
    env.Program('prog', ['file1.o', 'file2.o'])

Will create a program named `myprog.xxx` regardless of the system on which it is run.

If you omit the &target;, the base of the first input file name specified becomes the base of the target program created. For example:

    Program(['hello.c', 'goodbye.c'])

Will create the &hello; executable on a POSIX system, the &hello_exe; executable on a Windows system.

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:

env = Environment(LIBS = ['foo1', 'foo2'], LIBPATH = ['/usr/dir1', 'dir2']) env.Program(['hello.c', 'goodbye.c'])
int hello() { printf("Hello, world!\n"); }
int goodbye() { printf("Goodbye, world!\n"); }

Will execute as follows on a POSIX system:

scons -Q

And execute as follows on a Windows system:

scons -Q

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.

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.

Other relevant construction variables include those used by the &b-link-Object; builders to affect how the source files specified as input to the `Program` builders are turned into object files; see the next section.

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.

## Object-File Builders

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

### The &StaticObject; Builder

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:

    StaticObject('file', 'file.c')

Will create the &file_o; object file on a POSIX system, the &file_obj; executable on a Windows system.

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:

    env = Environment(OBJPREFIX='my', OBJSUFFIX='.xxx')
    env.StaticObject('file', 'file.c')

Will create an object file named `myfile.xxx` regardless of the system on which it is run.

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:

    StaticObject('file.c')

Will create the &file_o; executable on a POSIX system, the &file_obj; executable on a Windows system.

### The &SharedObject; Builder

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:

    SharedObject('file', 'file.c')

Will create the &file_o; object file on a POSIX system, the &file_obj; executable on a Windows system.

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:

    env = Environment(SHOBJPREFIX='my', SHOBJSUFFIX='.xxx')
    env.SharedObject('file', 'file.c')

Will create an object file named `myfile.xxx` regardless of the system on which it is run.

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:

    SharedObject('file.c')

Will create the &file_o; executable on a POSIX system, the &file_obj; executable on a Windows system.

### The &Object; Builder

The &b-link-Object; Builder is a synonym for &b-link-StaticObject; and is completely equivalent.

## Library Builders

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

### The &StaticLibrary; Builder

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:

    StaticLibrary('foo', ['file1.c', 'file2.c'])

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:

    env = Environment(LIBPREFIX='my', LIBSUFFIX='.xxx')
    env.StaticLibrary('lib', ['file1.o', 'file2.o'])

Will create an object file named `mylib.xxx` regardless of the system on which it is run.

    StaticLibrary('foo', ['file1.c', 'file2.c'])

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:

    StaticLibrary(['file.c', 'another.c'])

Will create the &libfile_a; library on a POSIX system, the &file_lib; library on a Windows system.

### The &SharedLibrary; Builder

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:

    SharedLibrary('foo', ['file1.c', 'file2.c'])

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:

    env = Environment(SHLIBPREFIX='my', SHLIBSUFFIX='.xxx')
    env.SharedLibrary('shared', ['file1.o', 'file2.o'])

Will create an object file named `myshared.xxx` regardless of the system on which it is run.

    SharedLibrary('foo', ['file1.c', 'file2.c'])

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:

    SharedLibrary(['file.c', 'another.c'])

Will create the &libfile_so; library on a POSIX system, the &file_dll; library on a Windows system.

### The &Library; Builder

The &b-link-Library; Builder is a synonym for &b-link-StaticLibrary; and is completely equivalent.

## Pre-Compiled Headers: the &PCH; Builder

XXX PCH()

## Microsoft Visual C++ Resource Files: the &RES; Builder

XXX RES()

## Source Files

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.

### The &CFile; Builder

XXX CFile()

    XXX CFile() programlisting

    XXX CFile() screen

### The &CXXFile; Builder

XXX CXXFILE()

    XXX CXXFILE() programlisting

    XXX CXXFILE() screen

## Documents

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

### The &DVI; Builder

XXX DVI() para

    XXX DVI() programlisting

    XXX DVI() screen

### The &PDF; Builder

XXX PDF() para

### The &PostScript; Builder

XXX PostScript() para

    XXX PostScript() programlisting

    XXX PostScript() screen

## Archives

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

### The &Tar; Builder

The &b-link-Tar; Builder object uses the &tar; utility to create archives of files and/or directory trees:

env = Environment() env.Tar('out1.tar', ['file1', 'file2']) env.Tar('out2', 'directory')
file1
file2
directory/file3
scons -Q .

One common requirement when creating a &tar; archive is to create a compressed archive using the `-z` 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 `-c` 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:

env = Environment(TARFLAGS = '-c -z') env.Tar('out.tar.gz', 'directory')
directory/file
scons -Q .

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:

env = Environment(TARFLAGS = '-c -z', TARSUFFIX = '.tgz') env.Tar('out', 'directory')
directory/file
scons -Q .

### The &Zip; Builder

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:

env = Environment() env.Zip('out', ['file1', 'file2'])
file1
file2

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

scons -Q .

## Java

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

### Building Class Files: the &Java; Builder

The &b-link-Java; builder takes one or more input `.java` files and turns them into one or more `.class` files Unlike most builders, however, the &Java; builder takes target and source directories, not files, as input.

    env = Environment()
    env.Java(target = 'classes', source = 'src')

The &Java; builder will then search the specified source directory tree for all `.java` files, and pass any out-of-date

    XXX Java() screen

### The &Jar; Builder

XXX The &Jar; builder object

    env = Environment()
    env.Java(target = 'classes', source = 'src')
    env.Jar(target = '', source = 'classes')

    XXX Jar() screen

### Building C header and stub files: the &JavaH; Builder

XXX JavaH() para

    XXX JavaH() programlisting

    XXX JavaH() screen

### Building RMI stub and skeleton class files: the &RMIC; Builder

XXX RMIC() para

    XXX RMIC() programlisting

    XXX RMIC() screen