Commits

Anonymous committed 0fe3d9c

Branch for User's Guide updates.

Comments (0)

Files changed (30)

     for f in pf + cf:
         u[f] = 1
     for f in df:
-        del u[f]
+        try:
+            del u[f]
+        except KeyError:
+            pass
     sfiles = filter(lambda x: x[-9:] != '.aeignore' and x[-9:] != '.sconsign',
                     u.keys())
 
 
 -->
 
+<!ENTITY Aegis "<application>Aegis</application>">
 <!ENTITY Autoconf "<application>Autoconf</application>">
 <!ENTITY Cons "<application>Cons</application>">
 <!ENTITY gcc "<application>gcc</application>">
+<!ENTITY Jam "<application>Jam</application>">
 <!ENTITY Make "<application>Make</application>">
 <!ENTITY Makepp "<application>Make++</application>">
+<!ENTITY ranlib "<application>ranlib</application>">
 <!ENTITY SCons "<application>SCons</application>">
 <!ENTITY scons "<application>scons</application>">
 <!ENTITY ScCons "<application>ScCons</application>">
+<!ENTITY tar "<application>tar</application>">
+<!ENTITY touch "<application>touch</application>">
+<!ENTITY zip "<application>zip</application>">
 
 
 <!--
 
 <!--
 
-  File names.
+  File and directory names.
 
 -->
 
+<!ENTITY build "<filename>build</filename>">
 <!ENTITY Makefile "<filename>Makefile</filename>">
 <!ENTITY Makefiles "<filename>Makefiles</filename>">
 <!ENTITY SConscript "<filename>SConscript</filename>">
 <!ENTITY Sconstruct "<filename>Sconstruct</filename>">
 <!ENTITY sconstruct "<filename>sconstruct</filename>">
 <!ENTITY sconsign "<filename>.sconsign</filename>">
+<!ENTITY src "<filename>src</filename>">
 
 
 
 <!ENTITY Repository "<function>Repository</function>">
 <!ENTITY RuleSet "<function>RuleSet</function>">
 <!ENTITY Salt "<function>Salt</function>">
+<!ENTITY SetBuildSignatureType "<function>SetBuildSignatureType</function>">
+<!ENTITY SetContentSignatureType "<function>SetContentSignatureType</function>">
 <!ENTITY SourceSignature "<function>SourceSignature</function>">
+<!ENTITY SourceSignatures "<function>SourceSignatures</function>">
 <!ENTITY Split "<function>Split</function>">
+<!ENTITY TargetSignatures "<function>TargetSignatures</function>">
 <!ENTITY Task "<function>Task</function>">
 
+<!ENTITY str "<function>str</function>">
+<!ENTITY zipfile "<function>zipfile</function>">
+
 <!-- Obsolete, but referenced in old documents.  -->
 <!ENTITY Cache "<function>Cache</function>">
 
 <!ENTITY BUILDERS "<varname>BUILDERS</varname>">
 <!ENTITY SCANNERMAP "<varname>SCANNERMAP</varname>">
 <!ENTITY SCANNERS "<varname>SCANNERS</varname>">
+<!ENTITY TARFLAGS "<varname>TARFLAGS</varname>">
+<!ENTITY TARSUFFIX "<varname>TARSUFFIX</varname>">
 
 
 
 <!ENTITY CC "<varname>CC</varname>">
 <!ENTITY CCFLAGS "<varname>CCFLAGS</varname>">
 <!ENTITY LIBPATH "<varname>LIBPATH</varname>">
+<!ENTITY LIBS "<varname>LIBS</varname>">
 <!ENTITY PYTHONPATH "<varname>PYTHONPATH</varname>">
 <!ENTITY SCONSFLAGS "<varname>SCONSFLAGS</varname>">
 
 
 <!--
 
+  Function and method arguments.
+
+-->
+
+<!ENTITY build_dir "<varname>build_dir</varname>">
+<!ENTITY source "<varname>source</varname>">
+<!ENTITY target "<varname>target</varname>">
+
+
+
+<!--
+
   Builder and Scanner objects.
 
 -->
 <!ENTITY BuildDir "<function>BuildDir</function>">
 <!ENTITY CFile "<function>CFile</function>">
 <!ENTITY CXXFile "<function>CXXFile</function>">
+<!ENTITY DVI "<function>DVI</function>">
+<!ENTITY Jar "<function>Jar</function>">
+<!ENTITY Java "<function>Java</function>">
+<!ENTITY JavaH "<function>JavaH</function>">
 <!ENTITY Library "<function>Library</function>">
 <!ENTITY Object "<function>Object</function>">
 <!ENTITY PCH "<function>PCH</function>">
 <!ENTITY PostScript "<function>PostScript</function>">
 <!ENTITY Program "<function>Program</function>">
 <!ENTITY RES "<function>RES</function>">
+<!ENTITY RMIC "<function>RMIC</function>">
 <!ENTITY SharedLibrary "<function>SharedLibrary</function>">
 <!ENTITY SharedObject "<function>SharedObject</function>">
 <!ENTITY StaticLibrary "<function>StaticLibrary</function>">
 <!ENTITY StaticObject "<function>StaticObject</function>">
+<!ENTITY Tar "<function>Tar</function>">
+<!ENTITY Zip "<function>Zip</function>">
 
 <!-- Obsolete, but referenced in old documents.  -->
 <!ENTITY MakeBuilder "<function>Make</function>">
 
 -->
 
+<!ENTITY buildfunc "<literal>builder function</literal>">
+
 <!ENTITY ConsEnv "<literal>Construction Environment</literal>">
 <!ENTITY ConsEnvs "<literal>Construction Environments</literal>">
 <!ENTITY Consenv "<literal>Construction environment</literal>">
 
 <!ENTITY Dictionary "<literal>Dictionary</literal>">
 
+<!ENTITY Emitter "<literal>Emitter</literal>">
+<!ENTITY emitter "<literal>emitter</literal>">
+<!ENTITY Generator "<literal>Generator</literal>">
+<!ENTITY generator "<literal>generator</literal>">
+
+<!ENTITY signature "<literal>signature</literal>">
+<!ENTITY buildsignature "<literal>build signature</literal>">
+
 <!--
 
   File and program names used in examples.
 
 -->
 
+<!ENTITY common1_c "<application>common1.c</application>">
+<!ENTITY common2_c "<application>common2.c</application>">
 <!ENTITY goodbye "<application>goodbye</application>">
 <!ENTITY hello "<application>hello</application>">
 <!ENTITY hello_c "<filename>hello.c</filename>">
+<!ENTITY hello_exe "<filename>hello.exe</filename>">
 <!ENTITY hello_h "<filename>hello.h</filename>">
+<!ENTITY hello_o "<filename>hello.o</filename>">
+<!ENTITY prog "<filename>prog</filename>">
+<!ENTITY prog_c "<filename>prog.c</filename>">
+<!ENTITY prog_exe "<filename>prog.exe</filename>">
 <!ENTITY stdio_h "<filename>stdio.h</filename>">

doc/user/actions.sgml

 
  <para>
 
-   X
+   XXX
 
  </para>
 
  <section>
- <title>X</title>
+ <title>XXX</title>
 
    <para>
 
-   X
+   XXX
 
    </para>
 

doc/user/ant.sgml

+<!--
+
+  Copyright (c) 2001, 2002, 2003 Steven Knight
+
+  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>
+
+   XXX
+
+ </para>
+
+ <section>
+ <title>XXX</title>
+
+   <para>
+
+   XXX
+
+   </para>
+
+ </section>

doc/user/builders-built-in.sgml

+<!--
+
+  Copyright (c) 2001, 2002, 2003 Steven Knight
+
+  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.
+
+  </para>
+
+  <section>
+  <title>Programs:  the &Program; Builder</title>
+
+    <para>
+
+    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 &target; argument is the
+    name of the executable program name to be created.
+    For example:
+
+    </para>
+
+    <programlisting>
+      env = Environment()
+      env.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
+    $PROGPREFIX
+    and
+    $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
+    because the base of the target
+    program created.
+    For example:
+
+    </para>
+
+    <programlisting>
+      env = Environment()
+      env.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>
+
+  </section>
+
+  <section>
+  <title>Object-File Builders</title>
+
+    <para>
+
+    &SCons; provides separate Builder objects
+    to create both static and shared object files.
+
+    </para>
+
+    <section>
+    <title>The &StaticObject; Builder</title>
+
+      <para>
+
+      XXX
+
+      </para>
+
+      <programlisting>
+        XXX
+      </programlisting>
+
+      <literallayout>
+        XXX
+      </literallayout>
+
+    </section>
+
+    <section>
+    <title>The &SharedObject; Builder</title>
+
+      <para>
+
+      XXX
+
+      </para>
+
+      <programlisting>
+        XXX
+      </programlisting>
+
+      <literallayout>
+        XXX
+      </literallayout>
+
+    </section>
+
+    <section>
+    <title>The &Object; Builder</title>
+
+      <para>
+
+      XXX
+
+      </para>
+
+      <programlisting>
+        XXX
+      </programlisting>
+
+      <para>
+
+      Creates a static object file.
+
+      </para>
+
+    </section>
+
+  </section>
+
+  <section>
+  <title>Library Builders</title>
+
+    <para>
+
+    &SCons; provides separate Builder objects
+    to create both static and shared libraries.
+
+    </para>
+
+    <section>
+    <title>The &StaticLibrary; Builder</title>
+
+      <para>
+
+      XXX
+
+      </para>
+
+      <programlisting>
+        XXX
+      </programlisting>
+
+      <literallayout>
+        XXX
+      </literallayout>
+
+    </section>
+
+    <section>
+    <title>The &SharedLibrary; Builder</title>
+
+      <para>
+
+      XXX
+
+      </para>
+
+    </section>
+
+    <section>
+    <title>The &Library; Builder</title>
+
+      <para>
+
+      XXX
+
+      </para>
+
+      <programlisting>
+        XXX
+      </programlisting>
+
+      <literallayout>
+        XXX
+      </literallayout>
+
+      <para>
+
+      Creates a static library file.
+
+      </para>
+
+    </section>
+
+  </section>
+
+  <section>
+  <title>Pre-Compiled Headers:  the &PCH; Builder</title>
+
+    <para>
+
+    XXX
+
+    </para>
+
+  </section>
+
+  <section>
+  <title>Microsoft Visual C++ Resource Files: the &RES; Builder</title>
+
+    <para>
+
+    XXX
+
+    </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.
+
+    </para>
+
+    <section>
+    <title>The &CFile; Builder</title>
+
+      <para>
+
+      XXX
+
+      </para>
+
+      <programlisting>
+        XXX
+      </programlisting>
+
+      <literallayout>
+        XXX
+      </literallayout>
+
+    </section>
+
+    <section>
+    <title>The &CXXFile; Builder</title>
+
+      <para>
+
+      XXX
+
+      </para>
+
+      <programlisting>
+        XXX
+      </programlisting>
+
+      <literallayout>
+        XXX
+      </literallayout>
+
+    </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
+
+      </para>
+
+      <programlisting>
+        XXX
+      </programlisting>
+
+      <literallayout>
+        XXX
+      </literallayout>
+
+    </section>
+
+    <section>
+    <title>The &PDF; Builder</title>
+
+      <para>
+
+      XXX
+
+      </para>
+
+    </section>
+
+    <section>
+    <title>The &PostScript; Builder</title>
+
+      <para>
+
+      XXX
+
+      </para>
+
+      <programlisting>
+        XXX
+      </programlisting>
+
+      <literallayout>
+        XXX
+      </literallayout>
+
+    </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 &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>
+
+      <literallayout>
+        % <userinput>scons .</userinput>
+        tar -c -f out1.tar file1 file2
+        tar -c -f out2.tar directory
+      </literallayout>
+
+      <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 &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 &TARFLAGS;,
+      so you need to set it both options:
+
+      </para>
+
+      <programlisting>
+        env = Environment(TARFLAGS = '-c -z')
+        env.Tar('out.tar.gz', 'directory')
+      </programlisting>
+
+      <literallayout>
+        % <userinput>scons .</userinput>
+        tar -c -z -f out.tar.gz directory
+      </literallayout>
+
+      <para>
+
+      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:
+
+      </para>
+
+      <programlisting>
+        env = Environment(TARFLAGS = '-c -z',
+                          TARSUFFIX = '.tgz')
+        env.Tar('out', 'directory')
+      </programlisting>
+
+      <literallayout>
+        % <userinput>scons .</userinput>
+        tar -c -z -f out.tgz directory
+      </literallayout>
+
+    </section>
+
+    <section>
+    <title>The &Zip; Builder</title>
+
+      <para>
+
+      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:
+
+      </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>
+
+      <literallayout>
+        % <userinput>scons .</userinput>
+        zip("out.zip", ["file1", "file2"])
+      </literallayout>
+
+      <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>
+
+      <literallayout>
+        % <userinput>scons .</userinput>
+        zip /home/my/project/zip.out file1 file2
+      </literallayout>
+
+    </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 &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>
+
+      <literallayout>
+        XXX
+      </literallayout>
+
+    </section>
+
+    <section>
+    <title>The &Jar; Builder</title>
+
+      <para>
+
+      The &Jar; builder object XXX
+
+      </para>
+
+      <programlisting>
+        env = Environment()
+        env.Java(target = 'classes', source = 'src')
+        env.Jar(target = '', source = 'classes')
+      </programlisting>
+
+      <literallayout>
+        XXX
+      </literallayout>
+
+    </section>
+
+    <section>
+    <title>Building C header and stub files:  the &JavaH; Builder</title>
+
+      <para>
+
+      XXX
+
+      </para>
+
+      <programlisting>
+        XXX
+      </programlisting>
+
+      <literallayout>
+        XXX
+      </literallayout>
+
+    </section>
+
+    <section>
+    <title>Building RMI stub and skeleton class files:  the &RMIC; Builder</title>
+
+      <para>
+
+      XXX
+
+      </para>
+
+      <programlisting>
+        XXX
+      </programlisting>
+
+      <literallayout>
+        XXX
+      </literallayout>
+
+    </section>
+
+  </section>

doc/user/builders-commands.sgml

+<!--
+
+  Copyright (c) 2001, 2002, 2003 Steven Knight
+
+  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.
+
+-->
+
+  <!--
+
+  =head2 The C<Command> method
+
+
+  The C<Command> method is called as follows:
+
+    Command $env <target>, <inputs>, <build action>;
+
+  The target is made dependent upon the list of input files specified, and the
+  inputs must be built successfully or Cons will not attempt to build the
+  target.
+
+  To specify a command with multiple targets, you can specify a reference to a
+  list of targets. In Perl, a list reference can be created by enclosing a
+  list in square brackets. Hence the following command:
+
+    Command $env ['foo.h', 'foo.c'], 'foo.template', q(
+  	gen %1
+    );
+
+  could be used in a case where the command C<gen> creates two files, both
+  F<foo.h> and F<foo.c>.
+
+  -->
+
+  <para>
+
+  Creating a &Builder; and attaching it to a &consenv;
+  allows for a lot of flexibility when you
+  want to re-use actions
+  to build multiple files of the same type.
+  This can, however, be cumbersome
+  if you only need to execute one specific command
+  to build a single file (or group of files).
+  For these situations, &SCons; supports a
+  &Command; &Builder; that arranges
+  for a specific action to be executed
+  to build a specific file or files.
+  This looks a lot like the other builders
+  (like &Program;, &Object;, etc.),
+  but takes as an additional argument
+  the command to be executed to build the file:
+
+  </para>
+
+  <programlisting>
+     env = Environment()
+     env.Command('foo.out', 'foo.in', "sed 's/x/y/' < $TARGET > $SOURCE")
+  </programlisting>
+
+  <literallayout>
+    % <userinput>scons .</userinput>
+    sed 's/x/y' < foo.in > foo.out
+  </literallayout>
+
+  <para>
+
+  This is often more convenient than
+  creating a &Builder; object
+  and adding it to the &BUILDERS; variable
+  of a &consenv;
+
+  </para>
+
+  <para>
+
+  Note that the action you 
+
+  </para>
+
+  <programlisting>
+     env = Environment()
+     def build(target, source, env)
+         XXX
+         return None
+     env.Command('foo.out', 'foo.in', build)
+  </programlisting>
+
+  <literallayout>
+    % <userinput>scons .</userinput>
+    build("foo.out", "foo.in")
+  </literallayout>

doc/user/builders-writing.sgml

+<!--
+
+  Copyright (c) 2001, 2002, 2003 Steven Knight
+
+  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.
+
+-->
+
+<!--
+
+=head2 Adding new methods
+
+For slightly more demanding changes, you may wish to add new methods to the
+C<cons> package. Here's an example of a very simple extension,
+C<InstallScript>, which installs a tcl script in a requested location, but
+edits the script first to reflect a platform-dependent path that needs to be
+installed in the script:
+
+  # cons::InstallScript - Create a platform dependent version of a shell
+  # script by replacing string ``#!your-path-here'' with platform specific
+  # path $BIN_DIR.
+
+  sub cons::InstallScript {
+	my ($env, $dst, $src) = @_;
+	Command $env $dst, $src, qq(
+		sed s+your-path-here+$BIN_DIR+ %< > %>
+		chmod oug+x %>
+	);
+  }
+
+Notice that this method is defined directly in the C<cons> package (by
+prefixing the name with C<cons::>). A change made in this manner will be
+globally visible to all environments, and could be called as in the
+following example:
+
+  InstallScript $env "$BIN/foo", "foo.tcl";
+
+For a small improvement in generality, the C<BINDIR> variable could be
+passed in as an argument or taken from the construction environment-,-as
+C<%BINDIR>.
+
+
+=head2 Overriding methods
+
+Instead of adding the method to the C<cons> name space, you could define a
+new package which inherits existing methods from the C<cons> package and
+overrides or adds others. This can be done using Perl's inheritance
+mechanisms.
+
+The following example defines a new package C<cons::switch> which
+overrides the standard C<Library> method. The overridden method builds
+linked library modules, rather than library archives. A new
+constructor is provided. Environments created with this constructor
+will have the new library method; others won't.
+
+  package cons::switch;
+  BEGIN {@ISA = 'cons'}
+
+  sub new {
+	shift;
+	bless new cons(@_);
+  }
+
+  sub Library {
+	my($env) = shift;
+	my($lib) = shift;
+	my(@objs) = Objects $env @_;
+	Command $env $lib, @objs, q(
+		%LD -r %LDFLAGS %< -o %>
+	);
+  }
+
+This functionality could be invoked as in the following example:
+
+  $env = new cons::switch(@overrides);
+  ...
+  Library $env 'lib.o', 'foo.c', 'bar.c';
+
+-->
+
+  <para>
+
+  Although &SCons; provides many useful methods
+  for building common software products:
+  programs, libraries, documents.
+  you frequently want to be
+  able to build some other type of file
+  not supported directly by &SCons;
+  Fortunately, &SCons; makes it very easy
+  to define your own &Builder; objects
+  for any custom file types you want to build.
+  (In fact, the &SCons; interfaces for creating
+  &Builder; objects are flexible enough and easy enough to use
+  that all of the the &SCons; built-in &Builder; objects
+  are created the mechanisms described in this section.)
+
+  </para>
+
+  <section>
+  <title>Writing Builders That Execute External Commands</title>
+
+    <para>
+
+    The simplest &Builder; to create is
+    one that executes an external command.
+    For example, if we want to build
+    an output file by running the contents
+    of the input file through a command named
+    <literal>foobuild</literal>,
+    creating that &Builder; might look like:
+
+    </para>
+
+    <programlisting>
+       bld = Builder(action = 'foobuild < $TARGET > $SOURCE')
+    </programlisting>
+
+    <para>
+
+    All the above line does is create a free-standing
+    &Builder; object.
+    The next section will show us how to actually use it.
+
+    </para>
+
+  </section>
+
+  <section>
+  <title>Attaching a Builder to a &ConsEnv;</title>
+
+    <para>
+
+    A &Builder; object isn't useful
+    until it's attached to a &consenv;
+    so that we can call it to arrange
+    for files to be built.
+    This is done through the &BUILDERS;
+    &consvar; in an environment.
+    The &BUILDERS; variable is a Python dictionary
+    that maps the names by which you want to call
+    various &Builder; objects to the objects themselves.
+    For example, if we want to call the
+    &Builder; we just defined by the name
+    <function>Foo</function>,
+    our &SConstruct; file might look like:
+
+    </para>
+
+    <programlisting>
+       bld = Builder(action = 'foobuild < $TARGET > $SOURCE')
+       env = Environment(BUILDERS = {'Foo' : bld})
+    </programlisting>
+
+    <para>
+
+    With the &Builder; so attached to our &consenv;
+    we can now actually call it like so:
+
+    </para>
+
+    <programlisting>
+       env.Foo('file.foo', 'file.input')
+    </programlisting>
+
+    <para>
+
+    Then when we run &SCons; it looks like:
+
+    </para>
+
+    <literallayout>
+      % <userinput>scons</userinput>
+      foobuild < file.input > file.foo
+    </literallayout>
+
+    <para>
+
+    Note, however, that the default &BUILDERS;
+    variable in a &consenv;
+    comes with a default set of &Builder; objects
+    already defined:
+    &Program;, &Library;, etc.
+    And when we explicitly set the &BUILDERS; variable
+    when we create the &consenv;,
+    the default &Builder;s are no longer part of
+    the environment:
+
+    </para>
+
+    <programlisting>
+       bld = Builder(action = 'foobuild < $TARGET > $SOURCE')
+       env = Environment(BUILDERS = {'Foo' : bld})
+       env.Foo('file.foo', 'file.input')
+       env.Program('hello.c')
+    </programlisting>
+
+    <literallayout>
+      % <userinput>scons</userinput>
+      scons: Reading SConscript files ...
+      other errors
+      Traceback (most recent call last):
+        File "/usr/lib/scons/SCons/Script/__init__.py", line 901, in main
+          _main()
+        File "/usr/lib/scons/SCons/Script/__init__.py", line 762, in _main
+          SCons.Script.SConscript.SConscript(script)
+        File "/usr/lib/scons/SCons/Script/SConscript.py", line 207, in SConscript
+          exec _file_ in stack[-1].globals
+        File "SConstruct", line 4, in ?
+          env.Program('hello.c')
+      scons: Environment instance has no attribute 'Program'
+    </literallayout>
+
+    <para>
+
+    To be able use both our own defined &Builder; objects
+    and the default &Builder; objects in the same &consenv;,
+    you can either add to the &BUILDERS; variable
+    using the &Append; function:
+
+    </para>
+
+    <programlisting>
+       env = Environment()
+       bld = Builder(action = 'foobuild < $TARGET > $SOURCE')
+       env.Append(BUILDERS = {'Foo' : bld})
+       env.Foo('file.foo', 'file.input')
+       env.Program('hello.c')
+    </programlisting>
+
+    <para>
+
+    Or you can explicitly set the appropriately-named
+    key in the &BUILDERS; dictionary:
+
+    </para>
+
+    <programlisting>
+       env = Environment()
+       bld = Builder(action = 'foobuild < $TARGET > $SOURCE')
+       env['BUILDERS']['Foo'] = bld
+       env.Foo('file.foo', 'file.input')
+       env.Program('hello.c')
+    </programlisting>
+
+    <para>
+
+    Either way, the same &consenv;
+    can then use both the newly-defined
+    <function>Foo</function> &Builder;
+    and the default &Program; &Builder;:
+
+    </para>
+
+    <literallayout>
+      % <userinput>scons</userinput>
+      foobuild < file.input > file.foo
+      cc -c hello.c -o hello.o
+      cc -o hello hello.o
+    </literallayout>
+
+  </section>
+
+  <section>
+  <title>Letting &SCons; Handle The File Suffixes</title>
+
+    <para>
+
+    By supplying additional information
+    when you create a &Builder;,
+    you can let &SCons; add appropriate file
+    suffixes to the target and/or the source file.
+    For example, rather than having to specify
+    explicitly that you want the <literal>Foo</literal>
+    &Builder; to build the <literal>file.foo</literal>
+    target file from the <literal>file.input</literal> source file,
+    you can give the <literal>.foo</literal>
+    and <literal>.input</literal> suffixes to the &Builder;,
+    making for more compact and readable calls to
+    the <literal>Foo</literal> &Builder;:
+
+    </para>
+
+    <programlisting>
+       bld = Builder(action = 'foobuild < $TARGET > $SOURCE',
+                     suffix = '.foo',
+                     src_suffix = '.input')
+       env = Environment(BUILDERS = {'Foo' : bld})
+       env.Foo('file1')
+       env.Foo('file2')
+    </programlisting>
+
+    <literallayout>
+      % <userinput>scons</userinput>
+      foobuild < file1.input > file1.foo
+      foobuild < file2.input > file2.foo
+    </literallayout>
+
+    <para>
+
+    You can also supply a <literal>prefix</literal> keyword argument
+    if it's appropriate to have &SCons; append a prefix
+    to the beginning of target file names.
+
+    </para>
+
+  </section>
+
+  <section>
+  <title>Builders That Execute Python Functions</title>
+
+    <para>
+
+    In &SCons;, you don't have to call an external command
+    to build a file.
+    You can, instead, define a Python function
+    that a &Builder; object can invoke
+    to build your target file (or files).
+    Such a &buildfunc; definition looks like:
+
+    </para>
+
+    <programlisting>
+       def build_function(target, source, env):
+           # XXX
+           return None
+    </programlisting>
+
+    <para>
+
+    The arguments of a &buildfunc; are:
+
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+      <term>target</term>
+
+      <listitem>
+      <para>
+
+      A list of Node objects representing
+      the target or targets to be
+      built by this builder function.
+      The file names of these target(s)
+      may be extracted using the Python &str; funcion.
+
+      </para>
+      </listitem>
+      </varlistentry>
+
+      <varlistentry>
+      <term>source</term>
+
+      <listitem>
+      <para>
+
+      A list of Node objects representing
+      the sources to be
+      used by this builder function to build the targets.
+      The file names of these source(s)
+      may be extracted using the Python &str; funcion.
+
+      </para>
+      </listitem>
+      </varlistentry>
+
+      <varlistentry>
+      <term>env</term>
+
+      <listitem>
+      <para>
+
+      The &consenv; used for building the target(s).
+      The builder function may use any of the
+      environment's construction variables
+      in any way to affect how it builds the targets.
+
+      </para>
+      </listitem>
+      </varlistentry>
+
+    </variablelist>
+
+    <para>
+
+    The builder function must
+    return a <literal>0</literal> or <literal>None</literal> value
+    if the target(s) are built successfully.
+    The builder function
+    may raise an exception
+    or return any non-zero value
+    to indicate that the build is unsuccessful,
+
+    </para>
+
+    <para>
+
+    Once you've defined the Python function
+    that will build your target file,
+    defining a &Builder; object for it is as
+    simple as specifying the name of the function,
+    instead of an external command,
+    as the &Builder;'s
+    <literal>action</literal>
+    argument:
+
+    </para>
+
+    <programlisting>
+       def build_function(target, source, env):
+           # XXX
+           return None
+       bld = Builder(action = build_function,
+                     suffix = '.foo',
+                     src_suffix = '.input')
+       env = Environment(BUILDERS = {'Foo' : bld})
+       env.Foo('file')
+    </programlisting>
+
+    <para>
+
+    And notice that the output changes slightly,
+    reflecting the fact that a Python function,
+    not an external command,
+    is now called to build the target file:
+
+    </para>
+
+    <literallayout>
+      % <userinput>scons</userinput>
+      build_function("file.foo", "file.input")
+    </literallayout>
+
+  </section>
+
+  <section>
+  <title>Builders That Create Actions Using a &Generator;</title>
+
+    <para>
+
+    &SCons; Builder objects can create an action "on the fly"
+    by using a function called a &generator;.
+    This provides a great deal of flexibility XXX
+    A &generator; looks like:
+
+    </para>
+
+    <programlisting>
+       def generate_actions(source, target, env, for_signature):
+           return XXX
+    </programlisting>
+
+    <para>
+
+    The arguments of a &generator; are:
+
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+      <term>source</term>
+
+      <listitem>
+      <para>
+
+      A list of Node objects representing
+      the sources to be built
+      by the command or other action
+      generated by this function.
+      The file names of these source(s)
+      may be extracted using the Python &str; funcion.
+
+      </para>
+      </listitem>
+
+      </varlistentry>
+
+      <varlistentry>
+      <term>target</term>
+
+      <listitem>
+      <para>
+
+      A list of Node objects representing
+      the target or targets to be built
+      by the command or other action
+      generated by this function.
+      The file names of these target(s)
+      may be extracted using the Python &str; funcion.
+
+      </para>
+      </listitem>
+
+      </varlistentry>
+
+      <varlistentry>
+      <term>env</term>
+
+      <listitem>
+      <para>
+
+      The &consenv; used for building the target(s).
+      The generator may use any of the
+      environment's construction variables
+      in any way to determine what command
+      or other action to return.
+
+      </para>
+      </listitem>
+
+      </varlistentry>
+
+      <varlistentry>
+      <term>for_signature</term>
+
+      <listitem>
+      <para>
+
+      A flag that specifies whether the
+      generator is being called to contribute to a build signature,
+      as opposed to actually executing the command.
+
+      XXX
+
+      </para>
+      </listitem>
+
+      </varlistentry>
+
+    </variablelist>
+
+    <para>
+
+    The &generator; must return a
+    command string or other action that will be used to
+    build the specified target(s) from the specified source(s).
+
+    </para>
+
+    <para>
+
+    Once you've defined a &generator;,
+    you create a &Builder; to use it
+    by specifying the generator keyword argument
+    instead of <literal>action</literal>.
+
+    </para>
+
+    <programlisting>
+       bld = Builder(generator = generate_actions,
+                     suffix = '.foo',
+                     src_suffix = '.input')
+       env = Environment(BUILDERS = {'Foo' : bld})
+       env.Foo('file')
+    </programlisting>
+
+    <literallayout>
+      % <userinput>scons</userinput>
+      XXX
+    </literallayout>
+
+    <para>
+
+    Note that it's illegal to specify both an
+    <literal>action</literal>
+    and a
+    <literal>generator</literal>
+    for a &Builder;.
+
+    </para>
+
+  </section>
+
+  <section>
+  <title>Builders That Modify the Target or Source Lists Using an &Emitter;</title>
+
+    <para>
+
+    &SCons; supports the ability for a Builder to modify the
+    lists of target(s) from the specified source(s).
+
+    </para>
+
+    <programlisting>
+       def modify_targets(XXX):
+           return XXX
+       bld = Builder(action = 'XXX',
+                     suffix = '.foo',
+                     src_suffix = '.input',
+                     emitter = modify_targets)
+       env = Environment(BUILDERS = {'Foo' : bld})
+       env.Foo('file')
+    </programlisting>
+
+    <literallayout>
+      % <userinput>scons</userinput>
+      XXX
+    </literallayout>
+
+    <programlisting>
+       bld = Builder(action = 'XXX',
+                     suffix = '.foo',
+                     src_suffix = '.input',
+                     emitter = 'MY_EMITTER')
+       def modify1(XXX):
+           return XXX
+       def modify2(XXX):
+           return XXX
+       env1 = Environment(BUILDERS = {'Foo' : bld},
+                          MY_EMITTER = modify1)
+       env2 = Environment(BUILDERS = {'Foo' : bld},
+                          MY_EMITTER = modify2)
+       env1.Foo('file1')
+       env2.Foo('file2')
+    </programlisting>
+
+  </section>
+
+  <section>
+  <title>Builders That Use Other Builders</title>
+
+    <para>
+
+    XXX
+
+    </para>
+
+    <programlisting>
+       env = Environment()
+       env.SourceCode('.', env.BitKeeper('XXX')
+       env.Program('hello.c')
+    </programlisting>
+
+    <literallayout>
+      % <userinput>scons</userinput>
+      XXX
+    </literallayout>
+
+  </section>

doc/user/builders.sgml

-<!--
-
-  Copyright (c) 2001, 2002, 2003 Steven Knight
-
-  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.
-
--->
-
-<!--
-
-=head2 Adding new methods
-
-For slightly more demanding changes, you may wish to add new methods to the
-C<cons> package. Here's an example of a very simple extension,
-C<InstallScript>, which installs a tcl script in a requested location, but
-edits the script first to reflect a platform-dependent path that needs to be
-installed in the script:
-
-  # cons::InstallScript - Create a platform dependent version of a shell
-  # script by replacing string ``#!your-path-here'' with platform specific
-  # path $BIN_DIR.
-
-  sub cons::InstallScript {
-	my ($env, $dst, $src) = @_;
-	Command $env $dst, $src, qq(
-		sed s+your-path-here+$BIN_DIR+ %< > %>
-		chmod oug+x %>
-	);
-  }
-
-Notice that this method is defined directly in the C<cons> package (by
-prefixing the name with C<cons::>). A change made in this manner will be
-globally visible to all environments, and could be called as in the
-following example:
-
-  InstallScript $env "$BIN/foo", "foo.tcl";
-
-For a small improvement in generality, the C<BINDIR> variable could be
-passed in as an argument or taken from the construction environment-,-as
-C<%BINDIR>.
-
-
-=head2 Overriding methods
-
-Instead of adding the method to the C<cons> name space, you could define a
-new package which inherits existing methods from the C<cons> package and
-overrides or adds others. This can be done using Perl's inheritance
-mechanisms.
-
-The following example defines a new package C<cons::switch> which
-overrides the standard C<Library> method. The overridden method builds
-linked library modules, rather than library archives. A new
-constructor is provided. Environments created with this constructor
-will have the new library method; others won't.
-
-  package cons::switch;
-  BEGIN {@ISA = 'cons'}
-
-  sub new {
-	shift;
-	bless new cons(@_);
-  }
-
-  sub Library {
-	my($env) = shift;
-	my($lib) = shift;
-	my(@objs) = Objects $env @_;
-	Command $env $lib, @objs, q(
-		%LD -r %LDFLAGS %< -o %>
-	);
-  }
-
-This functionality could be invoked as in the following example:
-
-  $env = new cons::switch(@overrides);
-  ...
-  Library $env 'lib.o', 'foo.c', 'bar.c';
-
--->
-
-  <para>
-
-    &SCons; provides many useful methods
-    for building common software products:
-    programs, libraries, documents.
-    Frequently, however, you want to be
-    able to build some other type of file
-    not supported directly by &SCons;
-    Fortunately, &SCons; makes it very easy
-    to define your own &Builder; objects
-    for any custom file types you want to build.
-
-  </para>
-
-  <section>
-  <title>Builders That Execute External Commands</title>
-
-    <para>
-
-    The simplest &Builder; to create is
-    one that executes an external command.
-    For example, if we want to build
-    an output file by running the contents
-    of the input file through a command named
-    <literal>foobuild</literal>,
-    creating that &Builder; might look like:
-
-    </para>
-
-    <programlisting>
-       bld = Builder(action = 'foobuild < $TARGET > $SOURCE')
-    </programlisting>
-
-  </section>
-
-  <section>
-  <title>Attaching a Builder to a &ConsEnv;</title>
-
-    <para>
-
-    A &Builder; object by itself, though,
-    isn't useful until it's attached to a &consenv;
-    so that we can call it to arrange
-    for files to be built.
-    This is done through the &BUILDERS;
-    &consvar; in an environment.
-    The &BUILDERS; variable is a Python dictionary
-    that maps the names by which you want to call various &Builder;
-    to the &Builder; objects themselves.
-    For example, if we want to call the
-    &Builder; we defined by the name
-    <function>Foo</function>,
-    our &SConstruct; file might look like:
-
-    </para>
-
-    <programlisting>
-       bld = Builder(action = 'foobuild < $TARGET > $SOURCE')
-       env = Environment(BUILDERS = {'Foo' : bld})
-       env.Foo('file.foo', 'file.input')
-    </programlisting>
-
-    <para>
-
-    Then when we run &SCons; it looks like:
-
-    </para>
-
-    <literallayout>
-      % <userinput>scons</userinput>
-      foobuild < file.input > file.foo
-    </literallayout>
-
-    <para>
-
-    Note, however, that the default &BUILDERS;
-    variable in a &consenv;
-    comes with a default set of &Builder; objects
-    already defined:
-    &Program;, &Library;, etc.
-    And when we explicitly set the &BUILDERS; variable
-    when we create the &consenv;,
-    the default &Builder;s are no longer part of
-    the environment:
-
-    </para>
-
-    <programlisting>
-       bld = Builder(action = 'foobuild < $TARGET > $SOURCE')
-       env = Environment(BUILDERS = {'Foo' : bld})
-       env.Foo('file.foo', 'file.input')
-       env.Program('hello.c')
-    </programlisting>
-
-    <literallayout>
-      % <userinput>scons</userinput>
-      scons: Reading SConscript files ...
-      other errors
-      Traceback (most recent call last):
-        File "/usr/lib/scons/SCons/Script/__init__.py", line 901, in main
-          _main()
-        File "/usr/lib/scons/SCons/Script/__init__.py", line 762, in _main
-          SCons.Script.SConscript.SConscript(script)
-        File "/usr/lib/scons/SCons/Script/SConscript.py", line 207, in SConscript
-          exec _file_ in stack[-1].globals
-        File "SConstruct", line 4, in ?
-          env.Program('hello.c')
-      scons: Environment instance has no attribute 'Program'
-    </literallayout>
-
-    <para>
-
-    To be able use both our own defined &Builder; objects
-    and the default &Builder; objects in the same &consenv;,
-    you can either add to the &BUILDERS; variable
-    using the &Append; function:
-
-    </para>
-
-    <programlisting>
-       env = Environment()
-       bld = Builder(action = 'foobuild < $TARGET > $SOURCE')
-       env.Append(BUILDERS = {'Foo' : bld})
-       env.Foo('file.foo', 'file.input')
-       env.Program('hello.c')
-    </programlisting>
-
-    <para>
-
-    Or you can explicitly set the appropriately-named
-    key in the &BUILDERS; dictionary:
-
-    </para>
-
-    <programlisting>
-       env = Environment()
-       bld = Builder(action = 'foobuild < $TARGET > $SOURCE')
-       env['BUILDERS']['Foo'] = bld
-       env.Foo('file.foo', 'file.input')
-       env.Program('hello.c')
-    </programlisting>
-
-    <para>
-
-    Either way, the same &consenv;
-    can then use both the newly-defined
-    <function>Foo</function> &Builder;
-    and the default &Program; &Builder;:
-
-    </para>
-
-    <literallayout>
-      % <userinput>scons</userinput>
-      foobuild < file.input > file.foo
-      cc -c hello.c -o hello.o
-      cc -o hello hello.o
-    </literallayout>
-
-  </section>
-
-  <section>
-  <title>Letting &SCons; Handle The File Suffixes</title>
-
-    <para>
-
-    By supplying additional information
-    when you create a &Builder;,
-    you can let &SCons; add appropriate file
-    suffixes to the target and/or the source file.
-    For example, rather than having to specify
-    explicitly that you want the <literal>Foo</literal>
-    &Builder; to build the <literal>file.foo</literal>
-    target file from the <literal>file.input</literal> source file,
-    you can give the <literal>.foo</literal>
-    and <literal>.input</literal> suffixes to the &Builder;,
-    making for more compact and readable calls to
-    the <literal>Foo</literal> &Builder;:
-
-    </para>
-
-    <programlisting>
-       bld = Builder(action = 'foobuild < $TARGET > $SOURCE',
-                     suffix = '.foo',
-                     src_suffix = '.input')
-       env = Environment(BUILDERS = {'Foo' : bld})
-       env.Foo('file1')
-       env.Foo('file2')
-    </programlisting>
-
-    <literallayout>
-      % <userinput>scons</userinput>
-      foobuild < file1.input > file1.foo
-      foobuild < file2.input > file2.foo
-    </literallayout>
-
-    <para>
-
-    You can also supply a <literal>prefix</literal> keyword argument
-    if it's appropriate to have &SCons; append a prefix
-    to the beginning of target file names.
-
-    </para>
-
-  </section>
-
-  <section>
-  <title>Builders That Execute Python Functions</title>
-
-    <para>
-
-    In &SCons;, you don't have to call an external command
-    to build a file.
-    You can, instead, define a Python function
-    that a &Builder; object can invoke
-    to build your target file (or files).
-
-    </para>
-
-    <programlisting>
-       def build_function(target, source, env):
-           # XXX
-           return None
-    </programlisting>
-
-    <para>
-
-    XXX explain the function
-    XXX define the arguments
-
-    </para>
-
-    <para>
-
-    Once you've defined the Python function
-    that will build your target file,
-    defining a &Builder; object for it is as
-    simple as specifying the name of the function,
-    instead of an external command,
-    as the &Builder;'s
-    <literal>action</literal>
-    argument:
-
-    </para>
-
-    <programlisting>
-       def build_function(target, source, env):
-           # XXX
-           return None
-       bld = Builder(action = build_function,
-                     suffix = '.foo',
-                     src_suffix = '.input')
-       env = Environment(BUILDERS = {'Foo' : bld})
-       env.Foo('file')
-    </programlisting>
-
-    <para>
-
-    And notice that the output changes slightly,
-    reflecting the fact that a Python function,
-    not an external command,
-    is now called to build the target file:
-
-    </para>
-
-    <literallayout>
-      % <userinput>scons</userinput>
-      build_function("file.foo", "file.input")
-    </literallayout>
-
-  </section>
-
-  <section>
-  <title>Builders That Generate Actions</title>
-
-    <para>
-
-    X
-
-    </para>
-
-    <programlisting>
-       def generate_actions(XXX):
-           return XXX
-       bld = Builder(generator = generate_actions,
-                     suffix = '.foo',
-                     src_suffix = '.input')
-       env = Environment(BUILDERS = {'Foo' : bld})
-       env.Foo('file')
-    </programlisting>
-
-    <literallayout>
-      % <userinput>scons</userinput>
-      XXX
-    </literallayout>
-
-    <para>
-
-    Note that it's illegal to specify both an
-    <literal>action</literal>
-    and a
-    <literal>generator</literal>
-    for a &Builder;.
-
-    </para>
-
-  </section>
-
-  <section>
-  <title>Builders That Modify the Target List</title>
-
-    <para>
-
-    X
-
-    </para>
-
-    <programlisting>
-       def modify_targets(XXX):
-           return XXX
-       bld = Builder(action = 'XXX',
-                     suffix = '.foo',
-                     src_suffix = '.input',
-                     emitter = modify_targets)
-       env = Environment(BUILDERS = {'Foo' : bld})
-       env.Foo('file')
-    </programlisting>
-
-    <literallayout>
-      % <userinput>scons</userinput>
-      XXX
-    </literallayout>
-
-    <programlisting>
-       bld = Builder(action = 'XXX',
-                     suffix = '.foo',
-                     src_suffix = '.input',
-                     emitter = 'MY_EMITTER')
-       def modify1(XXX):
-           return XXX
-       def modify2(XXX):
-           return XXX
-       env1 = Environment(BUILDERS = {'Foo' : bld},
-                          MY_EMITTER = modify1)
-       env2 = Environment(BUILDERS = {'Foo' : bld},
-                          MY_EMITTER = modify2)
-       env1.Foo('file1')
-       env2.Foo('file2')
-    </programlisting>
-
-  </section>
-
-  <section>
-  <title>Builders That Use Other Builders</title>
-
-    <para>
-
-    X
-
-    </para>
-
-    <programlisting>
-       env = Environment()
-       env.SourceCode('.', env.BitKeeper('XXX')
-       env.Program('hello.c')
-    </programlisting>
-
-    <literallayout>
-      % <userinput>scons</userinput>
-      XXX
-    </literallayout>
-
-  </section>

doc/user/caching.sgml

       cc -c hello.c -o hello.o
       cc -o hello hello.o
       % <userinput>scons -c</userinput>
+      Removed hello.o
+      Removed hello
       % <userinput>scons</userinput>
       Retrieved `hello.o' from cache
       Retrieved `hello' from cache

doc/user/command.sgml

-<!--
-
-  Copyright (c) 2001, 2002, 2003 Steven Knight
-
-  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.
-
--->
-
-<!--
-
-=head2 The C<Command> method
-
-
-The C<Command> method is called as follows: