<!--

  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>

   <programlisting>
      env = Environment()
      hello = env.Program('hello.c')
      env.Program('goodbye.c')
      Default(hello)
   </programlisting>

   <para>

   This &SConstruct; file knows how to build two programs,
   &hello; and &goodbye;,
   but only builds the
   &hello program by default:

   </para>

   <literallayout>
      % <userinput>scons</userinput>
      cc -c hello.c -o hello.o
      cc -o hello hello.o
      % <userinput>scons</userinput>
      % <userinput>scons goodbye</userinput>
      cc -c goodbye.c -o goodbye.o
      cc -o goodbye goodbye.o
      %
   </literallayout>

   <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>

   <literallayout>
      % <userinput>scons .</userinput>
      cc -c goodbye.c -o goodbye.o
      cc -o goodbye goodbye.o
      cc -c hello.c -o hello.o
      cc -o hello hello.o
      %
   </literallayout>

   <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>

   <programlisting>
      env = Environment()
      prog1 = env.Program('prog1.c')
      Default(prog1)
      prog2 = env.Program('prog2.c')
      prog3 = env.Program('prog3.c')
      Default(prog3)
   </programlisting>

   <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>

   <literallayout>
      % <userinput>scons</userinput>
      cc -c prog1.c -o prog1.o
      cc -o prog1 prog1.o
      cc -c prog3.c -o prog3.o
      cc -o prog3 prog3.o
      % <userinput>scons .</userinput>
      cc -c prog2.c -o prog2.o
      cc -o prog2 prog2.o
      %
   </literallayout>

   <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>

   <programlisting>
      env = Environment()
      prog1 = env.Program('prog1.c')
      prog2 = env.Program('prog2.c')
      Default(None)
   </programlisting>

   <para>

   Which would produce build output like:

   </para>

   <literallayout>
      % <userinput>scons</userinput>
      scons: *** No targets specified and no Default() targets found.  Stop.
      % <userinput>scons .</userinput>
      cc -c prog1.c -o prog1.o
      cc -o prog1 prog1.o
      cc -c prog2.c -o prog2.o
      cc -o prog2 prog2.o
      %
   </literallayout>