summaryrefslogtreecommitdiffstats
path: root/doc/user/builders-built-in.in
diff options
context:
space:
mode:
Diffstat (limited to 'doc/user/builders-built-in.in')
-rw-r--r--doc/user/builders-built-in.in950
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 &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>
-
- <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 &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>
-
- <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>