Branch for User's Guide changes.

1 files changed, 216 insertions, 0 deletions

diff --git a/doc/user/default.in b/doc/user/default.in
new file mode 100644
index 0000000..dbe6ecd
--- /dev/null
+++ b/doc/user/default.in
@@ -0,0 +1,216 @@
+<!--
+
+  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.
+
+-->
+
+<!--
+
+=head1 Default targets
+
+Until now, we've demonstrated invoking Cons with an explicit target
+to build:
+
+  % cons hello
+
+Normally, Cons does not build anything unless a target is specified,
+but specifying '.' (the current directory) will build everything:
+
+  % cons		# does not build anything
+
+  % cons .		# builds everything under the top-level directory
+
+Adding the C<Default> method to any F<Construct> or F<Conscript> file will add
+the specified targets to a list of default targets.  Cons will build
+these defaults if there are no targets specified on the command line.
+So adding the following line to the top-level F<Construct> file will mimic
+Make's typical behavior of building everything by default:
+
+  Default '.';
+
+The following would add the F<hello> and F<goodbye> commands (in the
+same directory as the F<Construct> or F<Conscript> file) to the default list:
+
+  Default qw(
+	hello
+	goodbye
+  );
+
+The C<Default> method may be used more than once to add targets to the
+default list.
+
+-->
+
+   <para>
+
+   As mentioned previously,
+   &SCons; will build every target
+   in or below the current directory
+   by default--that is, when you don't
+   explicitly specify one or more targets
+   on the command line.
+   Sometimes, however, you may want
+   to specify explicitly that only
+   certain programs should be built by default.
+   You do this with the &Default; function:
+
+   </para>
+
+   <scons_example name="ex1">
+      <file name="SConstruct" printme="1">
+      env = Environment()
+      hello = env.Program('hello.c')
+      env.Program('goodbye.c')
+      Default(hello)
+      </file>
+      <file name="hello.c">
+      hello.c
+      </file>
+      <file name="goodbye.c">
+      goodbye.c
+      </file>
+   </scons_example>
+
+   <para>
+
+   This &SConstruct; file knows how to build two programs,
+   &hello; and &goodbye;,
+   but only builds the
+   &hello; program by default:
+
+   </para>
+
+   <scons_output example="ex1">
+      <command>scons</command>
+      <command>scons</command>
+      <command>scons goodbye</command>
+   </scons_output>
+
+   <para>
+
+   Note that, even when you use the &Default;
+   function in your &SConstruct; file,
+   you can still explicitly specify the current directory
+   (<literal>.</literal>) on the command line
+   to tell &SCons; to build
+   everything in (or below) the current directory:
+
+   </para>
+
+   <scons_output example="ex1">
+      <command>scons .</command>
+   </scons_output>
+
+   <para>
+
+   You can also call the &Default;
+   function more than once,
+   in which case each call
+   adds to the list of targets to be built by default:
+
+   </para>
+
+   <scons_example name="ex2">
+      <file name="SConstruct" printme="1">
+      env = Environment()
+      prog1 = env.Program('prog1.c')
+      Default(prog1)
+      prog2 = env.Program('prog2.c')
+      prog3 = env.Program('prog3.c')
+      Default(prog3)
+      </file>
+      <file name="prog1.c">
+      prog1.c
+      </file>
+      <file name="prog2.c">
+      prog2.c
+      </file>
+      <file name="prog3.c">
+      prog3.c
+      </file>
+   </scons_example>
+
+   <para>
+
+   Or you can specify more than one target
+   in a single call to the &Default; function:
+
+   </para>
+
+   <programlisting>
+      env = Environment()
+      prog1 = env.Program('prog1.c')
+      prog2 = env.Program('prog2.c')
+      prog3 = env.Program('prog3.c')
+      Default(prog1, prog3)
+   </programlisting>
+
+   <para>
+
+   Either of these last two examples
+   will build only the
+   <application>prog1</application>
+   and
+   <application>prog3</application>
+   programs by default:
+
+   </para>
+
+   <scons_output example="ex2">
+      <command>scons</command>
+      <command>scons .</command>
+   </scons_output>
+
+   <para>
+
+   Lastly, if for some reason you don't want
+   any targets built by default,
+   you can use the Python <literal>None</literal>
+   variable:
+
+   </para>
+
+   <scons_example name="ex3">
+      <file name="SConstruct" printme="1">
+      env = Environment()
+      prog1 = env.Program('prog1.c')
+      prog2 = env.Program('prog2.c')
+      Default(None)
+      </file>
+      <file name="prog1.c">
+      prog1.c
+      </file>
+      <file name="prog2.c">
+      prog2.c
+      </file>
+   </scons_example>
+
+   <para>
+
+   Which would produce build output like:
+
+   </para>
+
+   <scons_output example="ex3">
+      <command>scons</command>
+      <command>scons .</command>
+   </scons_output>