Merged revisions 1441-1539 via svnmerge from

http://scons.tigris.org/svn/scons/branches/core

........
  r1441 | stevenknight | 2006-04-22 23:06:53 -0400 (Sat, 22 Apr 2006) | 1 line

  0.96.D397 - The scons command, branch 0.96.91.
........
  r1442 | stevenknight | 2006-04-27 00:45:12 -0400 (Thu, 27 Apr 2006) | 1 line

  0.96.D398 - The scons command, branch 0.96.92.
........
  r1443 | stevenknight | 2006-04-27 00:49:25 -0400 (Thu, 27 Apr 2006) | 1 line

  0.96.D399 - Taskmaster clean-ups in anticipation of refactoring speedups.
........
  r1450 | stevenknight | 2006-05-02 00:04:55 -0400 (Tue, 02 May 2006) | 1 line

  0.96.D400 - Fix VC+++ 2005 Express detection. (Atul Varma) Fix parsing Intel C compiler Li
........
  r1451 | stevenknight | 2006-05-02 01:14:24 -0400 (Tue, 02 May 2006) | 1 line

  0.96.D401 - Enhance ParseConfig() to understand -arch and -isysroot options. (Gary Oberbrun
........
  r1458 | stevenknight | 2006-05-02 23:21:04 -0400 (Tue, 02 May 2006) | 1 line

  0.96.D402 - Make strfunction handling consistent. (David Gruener)
........
  r1459 | stevenknight | 2006-05-02 23:37:08 -0400 (Tue, 02 May 2006) | 1 line

  0.96.D403 - Comment out the test of CVS checkout from the old tigris.org repository.
........
  r1460 | stevenknight | 2006-05-03 23:47:54 -0400 (Wed, 03 May 2006) | 1 line

  0.96.D404 - Preserve white space in display Action string. (David Gruener)
........
  r1461 | stevenknight | 2006-05-04 09:16:15 -0400 (Thu, 04 May 2006) | 1 line

  0.96.D405 - Add MergeFlags() and AddFlags() methods. (Greg Noel) Support recognizing compi
........
  r1462 | stevenknight | 2006-05-04 23:46:53 -0400 (Thu, 04 May 2006) | 1 line

  0.96.D406 - Fix stack trace when ParseFlags has a null string.
........
  r1464 | stevenknight | 2006-05-05 17:21:27 -0400 (Fri, 05 May 2006) | 1 line

  0.96.D408 - Fix the string displayed by InstallAs() when called through the default construc
........
  r1465 | stevenknight | 2006-05-05 18:30:28 -0400 (Fri, 05 May 2006) | 1 line

  0.96.D409 - Fix test/ParseConfig.py, broken in the previous checkin by ParseFlags() changes.
........
  r1466 | stevenknight | 2006-05-05 20:42:35 -0400 (Fri, 05 May 2006) | 1 line

  0.96.D407 - Avoid recursive calls to main() in SConf test programs. (Karol Pietrzak)
........
  r1467 | stevenknight | 2006-05-06 00:27:21 -0400 (Sat, 06 May 2006) | 1 line

  0.96.D410 - Catch errors from commands that ParseConfig() calls. (John Pye)
........
  r1468 | stevenknight | 2006-05-06 10:55:38 -0400 (Sat, 06 May 2006) | 1 line

  0.96.D411 - Significant taskmaster speedup by using reference counts, not list manipulation.
........
  r1469 | stevenknight | 2006-05-06 18:38:02 -0400 (Sat, 06 May 2006) | 1 line

  0.96.D413 - TeX improvements.
........
  r1471 | stevenknight | 2006-05-07 09:07:58 -0400 (Sun, 07 May 2006) | 2 lines

  Delete properties interfering with clean .jpg checkout.
........
  r1472 | stevenknight | 2006-05-07 09:23:54 -0400 (Sun, 07 May 2006) | 1 line

  0.96.D412 - Windows portability fixes for two tests and ParseConfig() execution.
........
  r1473 | stevenknight | 2006-05-07 09:30:11 -0400 (Sun, 07 May 2006) | 1 line

  0.96.D414 - Various man page and documentation updates.
........
  r1474 | stevenknight | 2006-05-07 23:53:12 -0400 (Sun, 07 May 2006) | 1 line

  0.96.D415 - Initial infrastructure for executing tests under QMTest. (Stefan Seefeld)
........
  r1476 | stevenknight | 2006-05-09 00:03:47 -0400 (Tue, 09 May 2006) | 1 line

  0.96.D416 - Fix QMTest infrastructure to avoid listing directories with no tests and to find
........
  r1477 | stevenknight | 2006-05-16 06:47:51 -0400 (Tue, 16 May 2006) | 1 line

  0.96.D417 - Fix Alias turning Entries into Nodes or Dirs too soon.
........
  r1478 | stevenknight | 2006-05-17 08:32:58 -0400 (Wed, 17 May 2006) | 1 line

  0.96.D418 - Next QMTest changes (including fixing copyrights).
........
  r1479 | stevenknight | 2006-05-18 05:07:06 -0400 (Thu, 18 May 2006) | 1 line

  0.96.D419 - Fix DVIPDF tests after recent changes.
........
  r1497 | stevenknight | 2006-05-23 08:47:01 -0400 (Tue, 23 May 2006) | 1 line

  0.96.D420 - Better error message when trying to build a file from an unknown sufix. (Gary O
........
  r1498 | stevenknight | 2006-05-23 09:38:52 -0400 (Tue, 23 May 2006) | 1 line

  0.96.D421 - Suppress duplicate entries in latest TeX patch. (Joel B. Mohler)
........
  r1499 | stevenknight | 2006-05-23 22:00:06 -0400 (Tue, 23 May 2006) | 1 line

  0.96.D422 - Add tests for tuple variable expansion. (Gary Oberbrunner)
........
  r1515 | stevenknight | 2006-06-12 06:44:24 -0400 (Mon, 12 Jun 2006) | 1 line

  0.96.D423 - More QMTest work: start giving runtest.py its own tests, more functionality for
........
  r1517 | stevenknight | 2006-06-21 07:34:30 -0400 (Wed, 21 Jun 2006) | 1 line

  0.96.D424 - Move test/Configure.py and test/Options.py to avoid confusion with similarly-nam
........
  r1518 | stevenknight | 2006-06-21 12:40:37 -0400 (Wed, 21 Jun 2006) | 1 line

  0.96.D425 - Change the QMTest infrastructure to use File naming, not Python. Rename tests w
........
  r1533 | stevenknight | 2006-07-23 20:10:08 -0400 (Sun, 23 Jul 2006) | 1 line

  0.96.D426 - Fix ramifications of changing when Node disambiguation happens.
........
  r1535 | stevenknight | 2006-07-24 06:40:43 -0400 (Mon, 24 Jul 2006) | 3 lines

  Initialized merge tracking via "svnmerge" with revisions "1-1534" from
  http://scons.tigris.org/svn/scons/trunk
........
  r1536 | stevenknight | 2006-07-24 21:45:40 -0400 (Mon, 24 Jul 2006) | 2 lines

  Remove svnmerge-integrated property to start over.
........
  r1538 | stevenknight | 2006-07-24 21:51:32 -0400 (Mon, 24 Jul 2006) | 3 lines

  Initialized merge tracking via "svnmerge" with revisions "1-1440" from
  http://scons.tigris.org/svn/scons/trunk
........

1 files changed, 283 insertions, 57 deletions

diff --git a/doc/man/scons.1 b/doc/man/scons.1
index 45d7a5b..49f9a30 100644
--- a/doc/man/scons.1
+++ b/doc/man/scons.1
@@ -2182,6 +2182,32 @@ env.Command('baz.out', 'baz.in',
 	     rename ])
 .EE
 
+Note that the
+.BR Command ()
+function will usually assume, by default,
+that the specified targets and/or sources are Files,
+if no other part of the configuration
+identifies what type of entry it is.
+If necessary, you can explicitly specify
+that targets or source nodes should
+be treated as directoriese
+by using the
+.BR Dir ()
+or
+.BR env.Dir ()
+functions:
+
+.ES
+env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET')
+
+env['DISTDIR'] = 'destination/directory'
+env.Command(env.Dir('$DISTDIR')), None, make_distdir)
+.EE
+
+(Also note that SCons will usually
+automatically create any directory necessary to hold a target file,
+so you normally don't need to create directories by hand.)
+
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
@@ -2782,6 +2808,56 @@ Returns a list of the target Node or Nodes.
 
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
+.RI env.MergeFlags( arg ", [" unique ])
+Merges the specified
+.I arg
+values to the construction envrionment's construction variables.
+If the
+.I arg
+argument is not a dictionary,
+it is converted to one by calling
+.B env.ParseFlags()
+on the argument
+before the values are merged.
+Note that
+.I arg
+must be a single value,
+so multiple strings must
+be passed in as a list,
+not as separate arguments to
+.BR env.MergeFlags ().
+
+By default, 
+duplicate values are eliminated;
+you can, however, specify
+.B unique=0
+to allow duplicate
+values to be added.
+When eliminating duplicate values,
+any construction variables that end with
+the string
+.B PATH
+keep the left-most unique value.
+All other construction variables keep
+the right-most unique value.
+
+Examples:
+
+.ES
+# Add an optimization flag to $CCFLAGS.
+env.MergeFlags('-O3')
+
+# Combine the flags returned from running pkg-config with an optimization
+# flag and merge the result into the construction variables.
+env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3'])
+
+env.MergeFlags(['-O3',
+               '!pkg-config gtk+-2.0 --cflags --libs',
+               '!pkg-config libpng12 --cflags --libs'])
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
 .RI NoClean( target ", ...)"
 .TP
 .RI env.NoClean( target ", ...)"
@@ -2836,7 +2912,9 @@ to modify the environment as specified by the output of
 .I command .
 The default
 .I function
-expects the output of a typical
+is
+.BR env.MergeFlags (),
+which expects the output of a typical
 .I *-config command
 (for example,
 .BR gtk-config )
@@ -2850,42 +2928,13 @@ you can specify
 to allow duplicate
 values to be added.
 
-By default,
-.BR -L ,
-.BR -l ,
-.BR -Wa ,
-.BR -Wl ,
-.BR -Wp ,
-.B -I
-and other options,
-are add to the
-.BR LIBPATH ,
-.BR LIBS ,
-.BR ASFLAGS ,
-.BR LINKFLAGS ,
-.BR CPPFLAGS ,
-.B CPPPATH
-and
-.B CCFLAGS
-construction variables,
-respectively.
-A returned
-.B -pthread
-option gets added to both the
-.B CCFLAGS
-and
-.B LINKFLAGS
-variables.
-A returned
-.B -framework
-option gets added to the
-.B LINKFLAGS
-variable.
-Any other strings not associated with options
-are assumed to be the names of libraries
-and added to the
-.B LIBS 
-construction variable.
+Interpreted options
+and the construction variables they affect
+are as specified for the
+.BR env.ParseFlags ()
+method (which thie method calls).
+See that method's description, below,
+for a table of options and construction variables.
 
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
@@ -2946,6 +2995,73 @@ function.
 
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
+.RI env.ParseFlags( flags ", ...)"
+Parses one or more strings containing
+typical command-line flags for GCC tool chains
+and returns a dictionary with the flag values
+separated into the appropriate SCons construction variables.
+This is intended as a companion to the
+.BR env.MergeFlags ()
+method, but allows for the values in the returned dictionary
+to be modified, if necessary,
+before merging them into the construction environment.
+(Note that
+.BR env.MergeFlags ()
+will call this method if its argument is not a dictionary,
+so it is usually not necessary to call
+.BR env.ParseFlags ()
+directly unless you want to manipulate the values.)
+
+If the first character in any string is
+an exclamation mark (!),
+the rest of the string is executed as a command,
+and the output from the command is
+parsed as GCC tool chain command-line flags
+and added to the resulting dictionary.
+
+Flag values are translated accordig to the prefix found,
+and added to the following construction variables:
+
+.ES
+-arch               CCFLAGS, LINKFLAGS
+-D                  CPPDEFINES
+-framework          FRAMEWORKS
+-frameworkdir=      FRAMEWORKPATH
+-include            CCFLAGS
+-isysroot           CCFLAGS, LINKFLAGS
+-I                  CPPPATH
+-l                  LIBS
+-L                  LIBPATH
+-mno-cygwin         CCFLAGS, LINKFLAGS
+-mwindows           LINKFLAGS
+-pthread            CCFLAGS, LINKFLAGS
+-Wa,                ASFLAGS, CCFLAGS
+-Wl,-rpath=         RPATH
+-Wl,-R,             RPATH
+-Wl,-R              RPATH
+-Wl,                LINKFLAGS
+-Wp,                CPPFLAGS
+-                   CCFLAGS
++                   CCFLAGS, LINKFLAGS
+.EE
+
+Any other strings not associated with options
+are assumed to be the names of libraries
+and added to the
+.B LIBS 
+construction variable.
+
+Examples (all of which produce the same result):
+
+.ES
+dict = env.ParseFlags('-O2 -Dfoo -Dbar=1')
+dict = env.ParseFlags('-O2', '-Dfoo', '-Dbar=1')
+dict = env.ParseFlags(['-O2', '-Dfoo -Dbar=1'])
+dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1')
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
 env.Perforce()
 A factory function that
 returns a Builder object
@@ -4425,10 +4541,13 @@ or a list of library names,
 in which case each library in the list
 will be checked for
 .IR symbol .
-The default
+If 
 .I symbol
-is "main",
-which just check if
+is not set or is
+.BR None ,
+then
+.BR Configure.CheckLib ()
+just checks if
 you can link against the specified
 .IR library .
 The optional
@@ -4442,7 +4561,6 @@ the default is "C".
 The default value for
 .I autoadd
 is 1.
-It is assumed, that the C-language is used.
 This method returns 1 on success and 0 on error.
 
 .TP 
@@ -4468,7 +4586,13 @@ header line being checked for.
 .I language
 may be one of 'C','c','CXX','cxx','C++' and 'c++'.
 .I call
-can be any valid expression (with a trailing ';'). The default is 'main();'.
+can be any valid expression (with a trailing ';').
+If
+.I call
+is not set,
+the default simply checks that you
+can link against the specified
+.IR library .
 .I autoadd
 specifies whether to add the library to the environment (only if the check 
 succeeds). This method returns 1 on success and 0 on error.
@@ -4705,13 +4829,30 @@ the construction variable will
 be added to the construction environment.
 .I validator
 is called to validate the value of the variable, and should take three
-arguments: key, value, and environment
+arguments: key, value, and environment.
+The recommended way to handle an invalid value is
+to raise an exception (see example below).
 .I converter
 is called to convert the value before putting it in the environment, and
-should take a single argument: value. Example:
+should take a single argument: value.
+The
+.I converter
+must return a value,
+which will be converted into a string
+before being validated by the
+.I validator
+(if any)
+and then added to the environment.
+
+Examples:
 
 .ES
 opts.Add('CC', 'The C compiler')
+
+def validate_color(key, val, env):
+    if not val in ['red', 'blue', 'yellow']:
+        raise "Invalid color value '%s'" % val
+opts.Add('COLOR', validator=valid_color)
 .EE
 
 .TP
@@ -5472,6 +5613,48 @@ and
 .I action
 arguments must not both be used for the same Builder.
 
+.IP source_ext_match
+When the specified
+.I action
+argument is a dictionary,
+the default behavior when a builder is passed
+multiple source files is to make sure that the
+extensions of all the source files match.
+If it is legal for this builder to be
+called with a list of source files with different extensions,
+this check can be suppressed by setting
+.B source_ext_match
+to
+.B None
+or some other non-true value.
+When
+.B source_ext_match
+is disable,
+.B scons
+will use the suffix of the first specified
+source file to select the appropriate action from the
+.I action
+dictionary.
+
+In the following example,
+the setting of
+.B source_ext_match
+prevents
+.B scons 
+from exiting with an error
+due to the mismatched suffixes of
+.B foo.in
+and
+.BR foo.extra .
+
+.ES
+b = Builder(action={'.in' : 'build $SOURCES > $TARGET'},
+            source_ext_match = None)
+
+env = Environment(BUILDERS = {'MyBuild':b})
+env.MyBuild('foo.out', ['foo.in', 'foo.extra'])
+.EE
+
 .IP env
 A construction environment that can be used
 to fetch source code using this Builder.
@@ -5535,6 +5718,21 @@ env = Environment(BUILDERS = {'MyBuild' : b})
 env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
 .EE
 
+.B WARNING:
+Python only keeps one current directory
+location for all of the threads.
+This means that use of the
+.B chdir
+argument
+will
+.I not
+work with the SCons
+.B -j
+option,
+because individual worker threads spawned
+by SCons interfere with each other
+when they start changing directory.
+
 .RE
 Any additional keyword arguments supplied
 when a Builder object is created
@@ -5694,9 +5892,18 @@ a = Action(build_it)
 
 If the action argument is not one of the above,
 None is returned.
+.PP
 
 The second, optional argument
-is a Python function that returns
+is used to define the output which is printed
+when the Action is actually performed.
+In the absence of this parameter, or if it's an
+empty string, a default output depending on the type of the action
+is used. For example, a command-line action will print
+the executed command. The argument is either a python function
+or a string.
+
+In the first case, it's a function that returns
 a string to be printed to describe the action being executed.
 Like a function to build a file,
 this function takes three arguments:
@@ -5713,6 +5920,13 @@ and
 .B source
 arguments may be lists of Node objects if there is
 more than one target file or source file.
+
+In the second case, you provide the string itself.
+The string typically contains variables, notably
+$TARGET(S) and $SOURCE(S), or consists of just a single
+variable, which is optionally defined somewhere else.
+SCons itself heavily uses the latter variant.
+
 Examples:
 
 .ES
@@ -5724,10 +5938,15 @@ def string_it(target, source, env):
     return "building '%s' from '%s'" % (target[0], source[0])
 
 # Use a positional argument.
-a = Action(build_it, string_it)
+f = Action(build_it, string_it)
+s = Action(build_it, "building '$TARGET' from '$SOURCE'")
 
 # Alternatively, use a keyword argument.
-a = Action(build_it, strfunction=string_it)
+f = Action(build_it, strfunction=string_it)
+s = Action(build_it, cmdstr="building '$TARGET' from '$SOURCE'")
+
+# You can provide a configurable variable.
+l = Action(build_it, '$STRINGIT')
 .EE
 
 The third, also optional argument
@@ -5748,16 +5967,12 @@ def build_it(target, source, env):
     open(target[0], 'w').write(env['XXX'])
     return 0
 
-def string_it(target, source):
-    return "building '%s' from '%s'" % (target[0], source[0])
-
 # Use positional arguments.
-a = Action(build_it, string_it, ['XXX'])
+a = Action(build_it, '$STRINGIT', ['XXX'])
 
 # Alternatively, use a keyword argument.
 a = Action(build_it, varlist=['XXX'])
 .EE
-.PP
 
 The
 .BR Action ()
@@ -5890,7 +6105,7 @@ that
 env = Environment(TMPBUILD = '/tmp/builddir')
 env.Command('foo.out', 'foo.in',
             [Mkdir('$TMPBUILD'),
-             Copy('$TMPBUILD', '${SOURCE.dir}')
+             Copy('$TMPBUILD', '${SOURCE.dir}'),
              "cd $TMPBUILD && make",
              Delete('$TMPBUILD')])
 .EE
@@ -6301,6 +6516,13 @@ Use
 to fetch the name of the file, and
 .B node.get_contents()
 to fetch contents of the file.
+Note that the file is
+.I not
+guaranteed to exist before the scanner is called,
+so the scanner function should check that
+if there's any chance that the scanned file
+might not exist
+(for example, if it's built from other files).
 
 The
 .B env
@@ -6348,10 +6570,14 @@ then it will be expanded
 into a list by the current environment.
 
 .IP path_function
-A Python function that takes
-two or three arguments:
-a construction environment, directory Node,
-and optional argument supplied
+A Python function that takes four or five arguments:
+a construction environment,
+a Node for the directory containing
+the SConscript file in which
+the first target was defined,
+a list of target nodes,
+a list of source nodes,
+and an optional argument supplied
 when the scanner was created.
 The
 .B path_function