diff options
Diffstat (limited to 'doc/user/builders-built-in.in')
| -rw-r--r-- | doc/user/builders-built-in.in | 950 |
1 files changed, 0 insertions, 950 deletions
diff --git a/doc/user/builders-built-in.in b/doc/user/builders-built-in.in deleted file mode 100644 index 3b5b981..0000000 --- a/doc/user/builders-built-in.in +++ /dev/null @@ -1,950 +0,0 @@ -<!-- - - __COPYRIGHT__ - - 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 ⌖ 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 ⌖, - 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="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="libs" os="posix"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - And execute as follows on a Windows system: - - </para> - - <scons_output example="libs" os="win32"> - <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 &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 ⌖ 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 ⌖, - 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 ⌖ 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 ⌖, - 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 ⌖ 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 ⌖, - 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 ⌖ 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 ⌖, - 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> - - <scons_example name="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="ex1" os="posix"> - <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="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="ex2" os="posix"> - <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="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="ex3" os="posix"> - <scons_output_command>scons -Q .</scons_output_command> - </scons_output> - - </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> - - <scons_example name="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="ex4" os="posix"> - <scons_output_command>scons -Q .</scons_output_command> - </scons_output> - - </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> |