&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 &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
$PROGPREFIX
and
$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 &LIBS; variable is a list of the names of
libraries that will be linked into any programs,
and the &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 -c -o goodbye.o goodbye.c
cc -c -o hello.o 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 &LIBS; construction variable
is turned into command line options
by appending the &LIBLINKPREFIX; and &LIBLINKSUFFIX;
construction variables to the beginning and end,
respectively, of each specified library.
The &LIBPATH; construction variable
is turned into command line options
by appending the &LIBDIRPREFIX; and &LIBDIRSUFFIX;
construction variables to the beginning and end,
respectively, of each specified library.
Other relevant construction variables
include those used by the &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 &LINKCOM; construction variable.
By default, it uses the
&LINK; construction variable
and the &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 &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
$OBJPREFIX
and
$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 &SharedObject; Builder
The &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
$SHOBJPREFIX
and
$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 &Object; Builder
The &Object; Builder is a synonym for &StaticObject;
and is completely equivalent.
Library Builders
&SCons; provides separate Builder objects
to create static and shared libraries.
The &StaticLibrary; Builder
The &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
$LIBPREFIX
and
$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 &SharedLibrary; Builder
The &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
$SHLIBPREFIX
and
$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 &Library; Builder
The &Library; Builder is a synonym for &StaticLibrary;
and is completely equivalent.
Pre-Compiled Headers: the &PCH; Builder
XXX
Microsoft Visual C++ Resource Files: the &RES; Builder
XXX
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
XXX
XXX
The &CXXFile; Builder
XXX
XXX
XXX
Documents
&SCons; provides a number of Builder objects
for creating different types of documents.
The &DVI; Builder
XXX
XXX
XXX
The &PDF; Builder
XXX
The &PostScript; Builder
XXX
XXX
XXX
Archives
&SCons; provides Builder objects
for creating two different types of archive files.
The &Tar; Builder
The &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
option.
This is easily handled by specifying
the value of the &TARFLAGS; variable
when you create the construction environment.
Note, however, that the used to
to instruct &tar; to create the archive
is part of the default value of &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
&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 &Zip; Builder
The &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
Java
&SCons; provides Builder objects
for creating various types of Java output files.
Building Class Files: the &Java; Builder
The &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
The &Jar; Builder
The &Jar; builder object XXX
env = Environment()
env.Java(target = 'classes', source = 'src')
env.Jar(target = '', source = 'classes')
XXX
Building C header and stub files: the &JavaH; Builder
XXX
XXX
XXX
Building RMI stub and skeleton class files: the &RMIC; Builder
XXX
XXX
XXX