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

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 ⌖ 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 ⌖, 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']) Will execute as follows on a POSIX system: % scons -Q 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 And execute as follows on a Windows system: C:\>scons -Q 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 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 &t-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.

&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 &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 ⌖ 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 ⌖, 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 &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 ⌖ 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 ⌖, 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 &b-link-Object; Builder is a synonym for &b-link-StaticObject; and is completely equivalent.

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

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 ⌖ 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 ⌖, 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 &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 ⌖ 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 ⌖, 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 &b-link-Library; Builder is a synonym for &b-link-StaticLibrary; and is completely equivalent.

XXX PCH()

XXX RES()

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.

XXX CFile() XXX CFile() programlisting XXX CFile() screen

XXX CXXFILE() XXX CXXFILE() programlisting XXX CXXFILE() screen

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

XXX DVI() para XXX DVI() programlisting XXX DVI() screen

XXX PDF() para

XXX PostScript() para XXX PostScript() programlisting XXX PostScript() screen

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

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') % scons -Q . tar -c -f out1.tar file1 file2 tar -c -f out2.tar directory 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') % scons -Q . tar -c -z -f out.tar.gz directory 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') % scons -Q . tar -c -z -f out.tgz directory

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']) Your output will reflect the fact that an internal Python function is being used to create the output ZIP archive: % scons -Q . zip(["out.zip"], ["file1", "file2"]) If you're using Python version 1.5.2 to run &SCons;, then &SCons; will try to use an external &zip; program as follows: % scons -Q . zip /home/my/project/zip.out file1 file2

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

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

XXX The &Jar; builder object env = Environment() env.Java(target = 'classes', source = 'src') env.Jar(target = '', source = 'classes') XXX Jar() screen

XXX JavaH() para XXX JavaH() programlisting XXX JavaH() screen

XXX RMIC() para XXX RMIC() programlisting XXX RMIC() screen