Add BUILD_TARGETS, COMMAND_LINE_TARGETS and DEFAULT_TARGETS variables.

4 files changed, 607 insertions, 14 deletions

diff --git a/doc/man/scons.1 b/doc/man/scons.1
index ff2864c..453ff66 100644
--- a/doc/man/scons.1
+++ b/doc/man/scons.1
@@ -2374,6 +2374,13 @@ Later calls to
 will add to the (now empty) default-target list
 like normal.
 
+The current list of targets added using the
+.BR Default ()
+function or method is available in the
+.B DEFAULT_TARGETS
+list;
+see below.
+
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
 .RI DefaultEnvironment([ args ])
@@ -3567,6 +3574,147 @@ or the user's current PATHEXT
 (os.environ['PATHEXT'])
 by default.
 
+.SS SConscript Variables
+In addition to the global functions and methods,
+.B scons
+supports a number of Python variables
+that can be used in SConscript files
+to affect how you want the build to be performed.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+ARGUMENTS
+A dictionary of all the
+.IR keyword = value
+arguments specified on the command line.
+The dictionary is not in order,
+and if a given keyword has
+more than one value assigned to it
+on the command line,
+the last (right-most) value is
+the one in the
+.B ARGUMENTS
+dictionary.
+
+.ES
+if ARGUMENTS.get('debug', 0):
+    env = Environment(CCFLAGS = '-g')
+else:
+    env = Environment()
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+BUILD_TARGETS
+A list of the targets which
+.B scons
+will actually try to build,
+regardless of whether they were specified on
+the command line or via the
+.BR Default ()
+function or method.
+The elements of this list may be strings
+.I or
+nodes, so you should run the list through the Python
+.B str
+function to make sure any Node path names
+are converted to strings.
+
+Because this list may be taken from the
+list of targets specified using the
+.BR Default ()
+function or method,
+the contents of the list may change
+on each successive call to
+.BR Default ().
+See the
+.B DEFAULT_TARGETS
+list, below,
+for additional information.
+
+.ES
+if 'foo' in BUILD_TARGETS:
+    print "Don't forget to test the `foo' program!"
+if 'special/program' in BUILD_TARGETS:
+    SConscript('special')
+.EE
+.IP
+Note that the
+.B BUILD_TARGETS
+list only contains targets expected listed
+on the command line or via calls to the
+.BR Default ()
+function or method.
+It does
+.I not
+contain all dependent targets that will be built as
+a result of making the sure the explicitly-specified
+targets are up to date.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+COMMAND_LINE_TARGETS
+A list of the targets explicitly specified on
+the command line.
+If there are no targets specified on the command line,
+the list is empty.
+This can be used, for example,
+to take specific actions only
+when a certain target or targets
+is explicitly being built:
+
+.ES
+if 'foo' in COMMAND_LINE_TARGETS:
+    print "Don't forget to test the `foo' program!"
+if 'special/program' in COMMAND_LINE_TARGETS:
+    SConscript('special')
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+DEFAULT_TARGETS
+A list of the target
+.I nodes
+that have been specified using the
+.BR Default ()
+function or method.
+The elements of the list are nodes,
+so you need to run them through the Python
+.B str
+function to get at the path name for each Node.
+
+.ES
+print str(DEFAULT_TARGETS[0])
+if 'foo' in map(str, DEFAULT_TARGETS):
+    print "Don't forget to test the `foo' program!"
+.EE
+.IP
+The contents of the
+.B DEFAULT_TARGETS
+list change on on each successive call to the
+.BR Default ()
+function:
+
+.ES
+print map(str, DEFAULT_TARGETS)   # originally []
+Default('foo')
+print map(str, DEFAULT_TARGETS)   # now a node ['foo']
+Default('bar')
+print map(str, DEFAULT_TARGETS)   # now a node ['foo', 'bar']
+Default(None)
+print map(str, DEFAULT_TARGETS)   # back to []
+.EE
+.IP
+Consequently, be sure to use
+.B DEFAULT_TARGETS
+only after you've made all of your
+.BR Default ()
+calls,
+or else simply be careful of the order
+of these statements in your SConscript files
+so that you don't look for a specific
+default target before it's actually been added to the list.
+
 .SS Construction Variables
 .\" XXX From Gary Ruben, 23 April 2002:
 .\" I think it would be good to have an example with each construction
diff --git a/doc/scons.mod b/doc/scons.mod
index d9b955f..443be67 100644
--- a/doc/scons.mod
+++ b/doc/scons.mod
@@ -174,6 +174,9 @@
 -->
 
 <!ENTITY ARGUMENTS "<varname>ARGUMENTS</varname>">
+<!ENTITY BUILD_TARGETS "<varname>BUILD_TARGETS</varname>">
+<!ENTITY COMMAND_LINE_TARGETS "<varname>COMMAND_LINE_TARGETS</varname>">
+<!ENTITY DEFAULT_TARGETS "<varname>DEFAULT_TARGETS</varname>">
 
 
 
diff --git a/doc/user/command-line.in b/doc/user/command-line.in
index 09ee8ce..9367c09 100644
--- a/doc/user/command-line.in
+++ b/doc/user/command-line.in
@@ -73,12 +73,71 @@
   </section>
 
   <section>
+  <title>Getting at Command-Line Targets</title>
+
+    <para>
+
+    &SCons; supports a &COMMAND_LINE_TARGETS; variable
+    that lets you get at the list of targets that the
+    user specified on the command line.
+    You can use the targets to manipulate the
+    build in any way you wish.
+    As a simple example,
+    suppose that you want to print a reminder
+    to the user whenever a specific program is built.
+    You can do this by checking for the
+    target in the &COMMAND_LINE_TARGETS; list:
+
+    </para>
+
+    <scons_example name="COMMAND_LINE_TARGETS">
+      <file name="SConstruct" printme="1">
+      if 'bar' in COMMAND_LINE_TARGETS:
+          print "Don't forget to copy `bar' to the archive!"
+      Default(Program('foo.c'))
+      Program('bar.c')
+      </file>
+      <file name="foo.c">
+      foo.c
+      </file>
+      <file name="bar.c">
+      foo.c
+      </file>
+    </scons_example>
+
+    <para>
+
+    Then, running &SCons; with the default target
+    works as it always does,
+    but explicity specifying the &bar; target
+    on the command line generates the warning message:
+
+    </para>
+
+    <scons_output example="COMMAND_LINE_TARGETS">
+      <command>scons -Q</command>
+      <command>scons -Q bar</command>
+    </scons_output>
+
+    <para>
+
+    Another practical use for the &COMMAND_LINE_TARGETS; variable
+    might be to speed up a build
+    by only reading certain subsidiary &SConscript;
+    files if a specific target is requested.
+
+    </para>
+
+  </section>
+
+  <section>
   <title>Controlling the Default Targets</title>
 
     <para>
 
     One of the most basic things you can control
-    is which targets &SCons; will build by default.
+    is which targets &SCons; will build by default--that is,
+    when there are no targets specified on the command line.
     As mentioned previously,
     &SCons; will normally build every target
     in or below the current directory
@@ -276,22 +335,182 @@
        <command>scons -Q .</command>
     </scons_output>
 
-  </section>
+    <section>
+    <title>Getting at the List of Default Targets</title>
+
+      <para>
+
+      &SCons; supports a &DEFAULT_TARGETS; variable
+      that lets you get at the current list of default targets.
+      The &DEFAULT_TARGETS variable has
+      two important differences from the &COMMAND_LINE_TARGETS; variable.
+      First, the &DEFAULT_TARGETS; variable is a list of
+      internal &SCons; nodes,
+      so you need to convert the list elements to strings
+      if you want to print them or look for a specific target name.
+      Fortunately, you can do this easily
+      by using the Python <function>map</function> function
+      to run the list through <function>str</function>:
 
-  <!--
+      </para>
+
+      <scons_example name="DEFAULT_TARGETS_1">
+         <file name="SConstruct" printme="1">
+         prog1 = Program('prog1.c')
+         Default(prog1)
+         print "DEFAULT_TARGETS is", map(str, DEFAULT_TARGETS)
+         </file>
+         <file name="prog1.c">
+         prog1.c
+         </file>
+      </scons_example>
+
+      <para>
+
+      (Keep in mind that all of the manipulation of the
+      &DEFAULT_TARGETS; list takes place during the
+      first phase when &SCons; is reading up the &SConscript; files,
+      which is obvious if 
+      we leave off the <literal>-Q</literal> flag when we run &SCons;:)
+
+      </para>
+
+      <scons_output example="DEFAULT_TARGETS_1">
+         <command>scons</command>
+      </scons_output>
+
+      <para>
+
+      Second,
+      the contents of the &DEFAULT_TARGETS; list change
+      in response to calls to the &Default: function,
+      as you can see from the following &SConstruct; file:
+
+      </para>
+
+      <scons_example name="DEFAULT_TARGETS_2">
+         <file name="SConstruct" printme="1">
+         prog1 = Program('prog1.c')
+         Default(prog1)
+         print "DEFAULT_TARGETS is now", map(str, DEFAULT_TARGETS)
+         prog2 = Program('prog2.c')
+         Default(prog2)
+         print "DEFAULT_TARGETS is now", map(str, DEFAULT_TARGETS)
+         </file>
+         <file name="prog1.c">
+         prog1.c
+         </file>
+         <file name="prog2.c">
+         prog2.c
+         </file>
+      </scons_example>
+
+      <para>
+
+      Which yields the output:
+
+      </para>
+
+      <scons_output example="DEFAULT_TARGETS_2">
+         <command>scons</command>
+      </scons_output>
+
+      <para>
+
+      In practice, this simply means that you
+      need to pay attention to the order in
+      which you call the &Default; function
+      and refer to the &DEFAULT_TARGETS; list,
+      to make sure that you don't examine the
+      list before you've added the default targets
+      you expect to find in it.
+
+      </para>
+
+    </section>
+
+  </section>
 
   <section>
-  <title>Getting at Command-Line Targets</title>
+  <title>Getting at the List of Build Targets, Regardless of Origin</title>
 
     <para>
 
-    XXX
+    We've already been introduced to the
+    &COMMAND_LINE_TARGETS; variable,
+    which contains a list of targets specified on the command line,
+    and the &DEFAULT_TARGETS; variable,
+    which contains a list of targets specified
+    via calls to the &Default; method or function.
+    Sometimes, however,
+    you want a list of whatever targets
+    &SCons; will try to build,
+    regardless of whether the targets came from the
+    command line or a &Default; call.
+    You could code this up by hand, as follows:
 
     </para>
 
-  </section>
+    <sconstruct>
+      if COMMAND_LINE_TARGETS:
+          targets = COMMAND_LINE_TARGETS
+      else:
+          targets = DEFAULT_TARGETS
+    </sconstruct>
 
-  -->
+    <para>
+
+    &SCons;, however, provides a convenient
+    &BUILD_TARGETS; variable
+    that eliminates the need for this by-hand manipulation.
+    Essentially, the &BUILD_TARGETS; variable
+    contains a list of the command-line targets,
+    if any were specified,
+    and if no command-line targets were specified,
+    it contains a list of the targets specified
+    via the &Default; method or function.
+
+    </para>
+
+    <para>
+
+    Because &BUILD_TARGETS; may contain a list of &SCons; nodes,
+    you must convert the list elements to strings
+    if you want to print them or look for a specific target name,
+    just like the &DEFAULT_TARGETS; list:
+
+    </para>
+
+    <scons_example name="BUILD_TARGETS_1">
+      <file name="SConstruct" printme="1">
+      prog1 = Program('prog1.c')
+      Program('prog2.c')
+      Default(prog1)
+      print "BUILD_TARGETS is", map(str, BUILD_TARGETS)
+      </file>
+      <file name="prog1.c">
+      prog1.c
+      </file>
+      <file name="prog2.c">
+      prog2.c
+      </file>
+    </scons_example>
+
+    <para>
+
+    Notice how the value of &BUILD_TARGETS;
+    changes depending on whether a target is
+    specified on the command line:
+
+    </para>
+
+    <scons_output example="BUILD_TARGETS_1">
+      <command>scons -Q</command>
+      <command>scons -Q prog2</command>
+      <command>scons -Q -c .</command>
+    </scons_output>
+
+  </section>
 
   <section>
   <title>Command-Line <varname>variable</varname>=<varname>value</varname> Build Options</title>
diff --git a/doc/user/command-line.sgml b/doc/user/command-line.sgml
index 3377b69..f6f219c 100644
--- a/doc/user/command-line.sgml
+++ b/doc/user/command-line.sgml
@@ -72,12 +72,68 @@
   </section>
 
   <section>
+  <title>Getting at Command-Line Targets</title>
+
+    <para>
+
+    &SCons; supports a &COMMAND_LINE_TARGETS; variable
+    that lets you get at the list of targets that the
+    user specified on the command line.
+    You can use the targets to manipulate the
+    build in any way you wish.
+    As a simple example,
+    suppose that you want to print a reminder
+    to the user whenever a specific program is built.
+    You can do this by checking for the
+    target in the &COMMAND_LINE_TARGETS; list:
+
+    </para>
+
+    <programlisting>
+      if 'bar' in COMMAND_LINE_TARGETS:
+          print "Don't forget to copy `bar' to the archive!"
+      Default(Program('foo.c'))
+      Program('bar.c')
+    </programlisting>
+
+    <para>
+
+    Then, running &SCons; with the default target
+    works as it always does,
+    but explicity specifying the &bar; target
+    on the command line generates the warning message:
+
+    </para>
+
+    <literallayout>
+      % <userinput>scons -Q</userinput>
+      cc -c -o foo.o foo.c
+      cc -o foo foo.o
+      % <userinput>scons -Q bar</userinput>
+      Don't forget to copy `bar' to the archive!
+      cc -c -o bar.o bar.c
+      cc -o bar bar.o
+    </literallayout>
+
+    <para>
+
+    Another practical use for the &COMMAND_LINE_TARGETS; variable
+    might be to speed up a build
+    by only reading certain subsidiary &SConscript;
+    files if a specific target is requested.
+
+    </para>
+
+  </section>
+
+  <section>
   <title>Controlling the Default Targets</title>
 
     <para>
 
     One of the most basic things you can control
-    is which targets &SCons; will build by default.
+    is which targets &SCons; will build by default--that is,
+    when there are no targets specified on the command line.
     As mentioned previously,
     &SCons; will normally build every target
     in or below the current directory
@@ -259,22 +315,189 @@
        cc -o prog2 prog2.o
     </literallayout>
 
-  </section>
+    <section>
+    <title>Getting at the List of Default Targets</title>
+
+      <para>
+
+      &SCons; supports a &DEFAULT_TARGETS; variable
+      that lets you get at the current list of default targets.
+      The &DEFAULT_TARGETS variable has
+      two important differences from the &COMMAND_LINE_TARGETS; variable.
+      First, the &DEFAULT_TARGETS; variable is a list of
+      internal &SCons; nodes,
+      so you need to convert the list elements to strings
+      if you want to print them or look for a specific target name.
+      Fortunately, you can do this easily
+      by using the Python <function>map</function> function
+      to run the list through <function>str</function>:
+
+      </para>
+
+      <programlisting>
+         prog1 = Program('prog1.c')
+         Default(prog1)
+         print "DEFAULT_TARGETS is", map(str, DEFAULT_TARGETS)
+      </programlisting>
 
-  <!--
+      <para>
+
+      (Keep in mind that all of the manipulation of the
+      &DEFAULT_TARGETS; list takes place during the
+      first phase when &SCons; is reading up the &SConscript; files,
+      which is obvious if 
+      we leave off the <literal>-Q</literal> flag when we run &SCons;:)
+
+      </para>
+
+      <literallayout>
+         % <userinput>scons</userinput>
+         scons: Reading SConscript files ...
+         DEFAULT_TARGETS is ['prog1']
+         scons: done reading SConscript files.
+         scons: Building targets ...
+         cc -c -o prog1.o prog1.c
+         cc -o prog1 prog1.o
+         scons: done building targets.
+      </literallayout>
+
+      <para>
+
+      Second,
+      the contents of the &DEFAULT_TARGETS; list change
+      in response to calls to the &Default;: function,
+      as you can see from the following &SConstruct; file:
+
+      </para>
+
+      <programlisting>
+         prog1 = Program('prog1.c')
+         Default(prog1)
+         print "DEFAULT_TARGETS is now", map(str, DEFAULT_TARGETS)
+         prog2 = Program('prog2.c')
+         Default(prog2)
+         print "DEFAULT_TARGETS is now", map(str, DEFAULT_TARGETS)
+      </programlisting>
+
+      <para>
+
+      Which yields the output:
+
+      </para>
+
+      <literallayout>
+         % <userinput>scons</userinput>
+         scons: Reading SConscript files ...
+         DEFAULT_TARGETS is now ['prog1']
+         DEFAULT_TARGETS is now ['prog1', 'prog2']
+         scons: done reading SConscript files.
+         scons: Building targets ...
+         cc -c -o prog1.o prog1.c
+         cc -o prog1 prog1.o
+         cc -c -o prog2.o prog2.c
+         cc -o prog2 prog2.o
+         scons: done building targets.
+      </literallayout>
+
+      <para>
+
+      In practice, this simply means that you
+      need to pay attention to the order in
+      which you call the &Default; function
+      and refer to the &DEFAULT_TARGETS; list,
+      to make sure that you don't examine the
+      list before you've added the default targets
+      you expect to find in it.
+
+      </para>
+
+    </section>
+
+  </section>
 
   <section>
-  <title>Getting at Command-Line Targets</title>
+  <title>Getting at the List of Build Targets, Regardless of Origin</title>
 
     <para>
 
-    XXX
+    We've already been introduced to the
+    &COMMAND_LINE_TARGETS; variable,
+    which contains a list of targets specified on the command line,
+    and the &DEFAULT_TARGETS; variable,
+    which contains a list of targets specified
+    via calls to the &Default; method or function.
+    Sometimes, however,
+    you want a list of whatever targets
+    &SCons; will try to build,
+    regardless of whether the targets came from the
+    command line or a &Default; call.
+    You could code this up by hand, as follows:
 
     </para>
 
-  </section>
+    <programlisting>
+      if COMMAND_LINE_TARGETS:
+          targets = COMMAND_LINE_TARGETS
+      else:
+          targets = DEFAULT_TARGETS
+    </programlisting>
+
+    <para>
+
+    &SCons;, however, provides a convenient
+    &BUILD_TARGETS; variable
+    that eliminates the need for this by-hand manipulation.
+    Essentially, the &BUILD_TARGETS; variable
+    contains a list of the command-line targets,
+    if any were specified,
+    and if no command-line targets were specified,
+    it contains a list of the targets specified
+    via the &Default; method or function.
+
+    </para>
+
+    <para>
+
+    Because &BUILD_TARGETS; may contain a list of &SCons; nodes,
+    you must convert the list elements to strings
+    if you want to print them or look for a specific target name,
+    just like the &DEFAULT_TARGETS; list:
+
+    </para>
+
+    <programlisting>
+      prog1 = Program('prog1.c')
+      Program('prog2.c')
+      Default(prog1)
+      print "BUILD_TARGETS is", map(str, BUILD_TARGETS)
+    </programlisting>
+
+    <para>
+
+    Notice how the value of &BUILD_TARGETS;
+    changes depending on whether a target is
+    specified on the command line:
+
+    </para>
+
+    <literallayout>
+      % <userinput>scons -Q</userinput>
+      BUILD_TARGETS is ['prog1']
+      cc -c -o prog1.o prog1.c
+      cc -o prog1 prog1.o
+      % <userinput>scons -Q prog2</userinput>
+      BUILD_TARGETS is ['prog2']
+      cc -c -o prog2.o prog2.c
+      cc -o prog2 prog2.o
+      % <userinput>scons -Q -c .</userinput>
+      BUILD_TARGETS is ['.']
+      Removed prog1.o
+      Removed prog1
+      Removed prog2.o
+      Removed prog2
+    </literallayout>
 
-  -->
+  </section>
 
   <section>
   <title>Command-Line <varname>variable</varname>=<varname>value</varname> Build Options</title>