summaryrefslogtreecommitdiff
path: root/doc/user/builders-built-in.xml
diff options
context:
space:
mode:
Diffstat (limited to 'doc/user/builders-built-in.xml')
-rw-r--r--doc/user/builders-built-in.xml949
1 files changed, 949 insertions, 0 deletions
diff --git a/doc/user/builders-built-in.xml b/doc/user/builders-built-in.xml
new file mode 100644
index 0000000..bee5b38
--- /dev/null
+++ b/doc/user/builders-built-in.xml
@@ -0,0 +1,949 @@
+<!--
+
+ Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 The SCons Foundation
+
+ 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>
+
+ scons: warning: No installed VCs
+ File "&lt;stdin&gt;", line 67, in __call__
+
+ scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
+ File "&lt;stdin&gt;", line 67, in __call__
+
+ scons: warning: No installed VCs
+ File "&lt;stdin&gt;", line 67, in __call__
+
+ scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
+ File "&lt;stdin&gt;", line 67, in __call__
+ cl /Fogoodbye.obj /c goodbye.c /nologo
+ cl /Fohello.obj /c hello.c /nologo
+ 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>