Merged revisions 2725-2865 via svnmerge from

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

........
  r2731 | stevenknight | 2008-04-01 09:22:37 -0700 (Tue, 01 Apr 2008) | 4 lines

  Fix test/Interactive/version.py, which still had the old hard-coded
  Copyright string, by moving the test copy of the Copyright string
  into QMTest/TestSCons.py, where it's available to all test scripts.
........
  r2732 | stevenknight | 2008-04-02 13:28:32 -0700 (Wed, 02 Apr 2008) | 3 lines

  Issues 317, 323, 329:  Ignore the -d, -e and -w options, which we're
  not going to implement.
........
  r2734 | stevenknight | 2008-04-05 07:50:49 -0700 (Sat, 05 Apr 2008) | 2 lines

  Fix bootstrap.py for pre-2.3 versions of Python, which don't have __file__.
........
  r2735 | stevenknight | 2008-04-05 07:54:44 -0700 (Sat, 05 Apr 2008) | 2 lines

  Fix the non-breaking-hyphen regular expression(s) for Python 1.5.
........
  r2736 | garyo | 2008-04-05 19:15:52 -0700 (Sat, 05 Apr 2008) | 1 line

  Added Users Guide section for AddMethod.
........
  r2737 | stevenknight | 2008-04-08 09:43:31 -0700 (Tue, 08 Apr 2008) | 3 lines

  Don't raise strings as exceptions in the exception-handling unit tests.
  That's now deprecated Python behavior.
........
  r2738 | stevenknight | 2008-04-08 10:36:00 -0700 (Tue, 08 Apr 2008) | 5 lines

  Address a serious inefficiency in Java builds by moving the pre-build
  check for whether source files exist from the Node class to the Executor
  class, so we only have to perform the check once when building a whole
  bunch of targets from a whole bunch of sources.
........
  r2739 | stevenknight | 2008-04-08 13:53:44 -0700 (Tue, 08 Apr 2008) | 2 lines

  Add a backwards-compatibility version of the "itertools" module.
........
  r2740 | stevenknight | 2008-04-08 14:12:05 -0700 (Tue, 08 Apr 2008) | 2 lines

  Issue 1961:  speed up SCons.Util.to_String*() functions.  (Benoit Belley)
........
  r2741 | stevenknight | 2008-04-08 14:15:36 -0700 (Tue, 08 Apr 2008) | 2 lines

  Use the itertools.izip() method for some key Node.FS methods.  (Benoit Belley)
........
  r2742 | stevenknight | 2008-04-08 14:35:35 -0700 (Tue, 08 Apr 2008) | 2 lines

  Issues 1961:  use izip() instead of zip() where possible (Benoit Belley)
........
  r2743 | stevenknight | 2008-04-08 14:48:08 -0700 (Tue, 08 Apr 2008) | 3 lines

  Issue 1961:  more efficient get_contents() implementation for Python
  function Actions.  (Benoit Belley)
........
  r2744 | stevenknight | 2008-04-08 17:55:30 -0700 (Tue, 08 Apr 2008) | 3 lines

  Issue 1961:  make SCons.Node.* state variables global in Taskmaster.py so
  we avoid unneceesary attribute fetches.  (Benoit Belley)
........
  r2745 | stevenknight | 2008-04-08 20:40:31 -0700 (Tue, 08 Apr 2008) | 2 lines

  Issue 1961:  Optimize the code in Node.get_binfo().  (Benoit Belley)
........
  r2746 | stevenknight | 2008-04-08 21:05:17 -0700 (Tue, 08 Apr 2008) | 3 lines

  Issue 1961:  Enhance the backwards-compatibility sets() module with the
  ability to compare sets.  (Benoit Belley)
........
  r2747 | stevenknight | 2008-04-08 22:11:20 -0700 (Tue, 08 Apr 2008) | 2 lines

  Issue 1961:  Optimize Executor.scan().  (Benoit Belley)
........
  r2748 | stevenknight | 2008-04-08 22:17:55 -0700 (Tue, 08 Apr 2008) | 3 lines

  Python 1.5 compatibility:  use for p in paths.keys() for dictionaries.
  (Benoit Belley)
........
  r2749 | stevenknight | 2008-04-08 22:54:02 -0700 (Tue, 08 Apr 2008) | 10 lines

  Issue 1961:  additional build optimizations:
  --  Make taskmastertrace output more useful and readable.
  --  Move dependency cycle checking to avoid re-doing it.
  --  Have Nodes use sets, not dictionaries, to track various things.
  --  Eliminate intermediate function calls from fetching Node children.
  --  Add a Task.needs_execute() method to avoid doing that check over and
      over as part of needs_execute().
  --  Remove the unused Node.found_includes attribute.
  (Benoit Belley)
........
  r2750 | stevenknight | 2008-04-09 14:47:44 -0700 (Wed, 09 Apr 2008) | 4 lines

  Make target Java .class files depend *only* on the input .java files as
  their sources when determining if they require rebuilding.  This eliminates
  O(NxM) checking for every single edge in a big, overly-connected DAG mesh.
........
  r2751 | stevenknight | 2008-04-09 16:58:41 -0700 (Wed, 09 Apr 2008) | 2 lines

  Remove 0.95 and 0.96* release notes.
........
  r2752 | stevenknight | 2008-04-10 02:24:50 -0700 (Thu, 10 Apr 2008) | 2 lines

  Issue 1956:  Fix --debug=stree printing its tree twice.  (Benoit Belley)
........
  r2753 | stevenknight | 2008-04-10 02:33:28 -0700 (Thu, 10 Apr 2008) | 2 lines

  Issue 1896:  Add support for the GDC D language compiler.  (Matthew Wesley)
........
  r2754 | stevenknight | 2008-04-10 02:39:24 -0700 (Thu, 10 Apr 2008) | 2 lines

  Fix tabs.
........
  r2755 | stevenknight | 2008-04-10 02:41:50 -0700 (Thu, 10 Apr 2008) | 3 lines

  Issue 1964:  Fix passing variable names in a list to Return() (as
  already documented in the man page!)  (Mike Wake)
........
  r2756 | stevenknight | 2008-04-10 02:55:40 -0700 (Thu, 10 Apr 2008) | 2 lines

  Support the ability to download 2.6 candidate releases (e.g. 2.6a2).
........
  r2757 | stevenknight | 2008-04-10 02:58:35 -0700 (Thu, 10 Apr 2008) | 3 lines

  Issue 1669:  Fix the ability to use LoadableModule() under MinGW.
  (Johan Boule)
........
  r2758 | stevenknight | 2008-04-10 03:03:15 -0700 (Thu, 10 Apr 2008) | 3 lines

  Update the test/Interactive/tree.py script for Benoit's fix to
  remove duplicate tree printing.
........
  r2759 | stevenknight | 2008-04-10 06:43:44 -0700 (Thu, 10 Apr 2008) | 3 lines

  Fix Tool/dmd.py when no D compiler is installed -- we don't want to
  search for a path if the result is None.
........
  r2760 | GregNoel | 2008-04-10 15:30:34 -0700 (Thu, 10 Apr 2008) | 1 line

  Issue 2009: separate Debug.caller() by functionality
........
  r2761 | stevenknight | 2008-04-11 04:47:25 -0700 (Fri, 11 Apr 2008) | 3 lines

  Issue 1882:  Add the scons.bat directory to %PATH% so it can find python.exe.
  (Anatoly Techtonik)
........
  r2762 | stevenknight | 2008-04-11 09:15:22 -0700 (Fri, 11 Apr 2008) | 4 lines

  Issues 1835,1901:  fix the ability to list a source file multiple
  times for a target by making sure we only store unique entries in the
  .sconsign file.
........
  r2763 | stevenknight | 2008-04-11 10:58:26 -0700 (Fri, 11 Apr 2008) | 4 lines

  Issue 1882:  Fix earlier patch to scons.bat by adding ~dp0;~dp0.. to
  the front of %PATH%, and only executing endlocal on NT-based systems.
  (Anatoly Techtonik)
........
  r2764 | stevenknight | 2008-04-11 13:06:29 -0700 (Fri, 11 Apr 2008) | 4 lines

  Add a Variables object and {Bool,Envum,List,Package,Path}Variable()
  functions as a first step towards eventually deprecating the
  Options object and {Bool,Envum,List,Package,Path}Option() functions.
........
  r2765 | stevenknight | 2008-04-11 18:13:53 -0700 (Fri, 11 Apr 2008) | 3 lines

  Issue 1962:  Capture a test case for ListActions that contain a
  command-line string containing unicode, and Python FunctionAction.
........
  r2766 | stevenknight | 2008-04-11 22:03:14 -0700 (Fri, 11 Apr 2008) | 3 lines

  Issue 1933:  expect .py files generated by the SWIG -python option
  to be in the same (sub)directory as the target.
........
  r2767 | stevenknight | 2008-04-12 06:41:57 -0700 (Sat, 12 Apr 2008) | 2 lines

  Remove the SCons.Options package in favor of the new SCons.Variables package.
........
  r2768 | stevenknight | 2008-04-12 13:33:52 -0700 (Sat, 12 Apr 2008) | 5 lines

  Issue 1971:  Move the incorporation of $CCFLAGS and $SHCCFLAGS directly
  into the C++ command lines (${SHCXX,CXX}COM) instead of through indirect
  expansion of $CXXFLAGS and $SHCXXFLAGS.  This requires removing -fPIC
  from the default setting of $SHCXXFLAGS under the GNU toolchain.
........
  r2769 | stevenknight | 2008-04-13 07:01:27 -0700 (Sun, 13 Apr 2008) | 3 lines

  Fix __all__ definitions in the Variables/*Variable.py file that were
  cause epydoc to blow up when generating developer documentation.
........
  r2770 | stevenknight | 2008-04-13 11:47:49 -0700 (Sun, 13 Apr 2008) | 3 lines

  Add variables= keyword argument to Environment() creation as a first
  step towards deprecating options=.
........
  r2771 | stevenknight | 2008-04-13 11:54:19 -0700 (Sun, 13 Apr 2008) | 2 lines

  Correct underscore-instead-of-hyphen misspellings in option names.
........
  r2772 | bdbaddog | 2008-04-13 17:39:21 -0700 (Sun, 13 Apr 2008) | 3 lines

  Changes to fix 15 tests which were failing on cygwin.
........
  r2773 | GregNoel | 2008-04-13 22:31:07 -0700 (Sun, 13 Apr 2008) | 1 line

  Various fixes to tests on Darwin using 1.5.2
........
  r2774 | stevenknight | 2008-04-14 15:00:44 -0700 (Mon, 14 Apr 2008) | 2 lines

  Python 1.5.2 fix in new test/SWIG/subdir.py script (use the -classic option).
........
  r2775 | belley | 2008-04-14 18:02:40 -0700 (Mon, 14 Apr 2008) | 32 lines

  Dont use KeyboardInterrupt to stop a build! [Issue 1907]

  SCons would often hang after pressing Ctrl-C. I started investigating and I
  realized that most of the Python libraries are not really safe with respect to
  asynchronous exceptions. Although,there are enough try/finally blocks to handle
  exceptions thrown synchronously by the library code, the Python libraries are
  not always protected against exceptions being thrown asynchronously, such as a
  KeyboardInterrupt being thrown at a completely random location.

  For example, the function Queue.empty() does not protect its mutex with a
  try/finally block. If the KeyboardInterrupt exception gets thrown while the
  mutex is held, any further attempt to access the Queue will lead to dead-lock
  (explaining why SCons hangs sometimes after pressing CTRL-C). Even the
  threading.Condition condition variables are not async-exception safe. It
  therefore seems a lost battle to try to stop a build by raising an exception.

  Instead, I have implemented a signal handler that tells the Jobs (and its
  associated Taskmaster) to stop the build. I have been careful to wait after the
  .sconsign file has been written back to re-install the default SIGINT signal
  handler that raises a KeyboardInterrupt exception.

  This patch is submitted against changeset 2773 of branches/core. The
  regression test suite has been run on RHEL4 using Pyhon 2.5.1 and
  1.5.2. My team has been using an SCons build with this patch for a
  while now on Windows, Linux and OSX.

  See:
  http://scons.tigris.org/issues/show_bug.cgi?id=1907

  Benoit Belley
........
  r2777 | cournape | 2008-04-14 20:11:56 -0700 (Mon, 14 Apr 2008) | 3 lines

  Initialized merge tracking via "svnmerge" with revisions "1-2776" from
  http://scons.tigris.org/svn/scons/branches/fortran_refactor
........
  r2788 | stevenknight | 2008-04-14 22:09:27 -0700 (Mon, 14 Apr 2008) | 2 lines

  Fix the print the "script" line in the --version output.
........
  r2789 | stevenknight | 2008-04-14 22:18:27 -0700 (Mon, 14 Apr 2008) | 2 lines

  Add a __COPYRIGHT__ line.
........
  r2790 | stevenknight | 2008-04-14 22:20:39 -0700 (Mon, 14 Apr 2008) | 3 lines

  Issue 2008:  in checkpoint releases, use a '.' to separate (e.g.) 0.98.0
  from 0d20080414.
........
  r2817 | belley | 2008-04-15 06:44:21 -0700 (Tue, 15 Apr 2008) | 13 lines

  TestSCons.up_to_date() should use match_re_dotall

  I changed TestSCons.up_to_date() to use match_re_dotall instead of
  match_exact. This is necessary so that I can call up_to_date() with
  the TestSCons.deprecated_python_expr error message in one of my test.

  Note that TestSCons.not_up_to_date() is already using match_re_dotall.

  Ran the test suite on both Python 2.5.1 and 1.5.2.

  Benoit
........
  r2818 | belley | 2008-04-15 12:10:52 -0700 (Tue, 15 Apr 2008) | 10 lines

  Improved the multiple-parents.py test to also tests the following
  cases:

  d) Some children are ignored
  e) Some children are pre-requesites
  f) Some sources are missing

  The test still passes. No extra bug were found.
........
  r2850 | stevenknight | 2008-04-16 11:15:24 -0700 (Wed, 16 Apr 2008) | 4 lines

  Fix problems with the __del__() method referencing other module functions
  through global variables, which can get deleted out from under us at
  shutdown.
........
  r2851 | stevenknight | 2008-04-16 11:17:07 -0700 (Wed, 16 Apr 2008) | 4 lines

  Fix use of --interactive with -u/-U/-D and VariantDir() by making the
  method that cleans Node states between interactive commands aware of
  the alter_targets() method that tells us about an associated VariantDir().
........

9 files changed, 322 insertions, 75 deletions

diff --git a/doc/SConscript b/doc/SConscript
index 0c8f070..a2174ea 100644
--- a/doc/SConscript
+++ b/doc/SConscript
@@ -480,7 +480,7 @@ else:
 
     epydoc_commands = [
         Delete('$OUTDIR'),
-        '$EPYDOC $EPYDOCFLAGS --output $OUTDIR --docformat=restructuredText --name SCons --url http://www.scons.org/ $SOURCES',
+        '$EPYDOC $EPYDOCFLAGS --debug --output $OUTDIR --docformat=restructuredText --name SCons --url http://www.scons.org/ $SOURCES',
         Touch('$TARGET'),
     ]
 
diff --git a/doc/man/scons.1 b/doc/man/scons.1
index 98e12e6..25a17fd 100644
--- a/doc/man/scons.1
+++ b/doc/man/scons.1
@@ -3891,16 +3891,16 @@ The options supported are:
 .TP 6
 .B cache_debug
 .TP 6
-which corresponds to --cache_debug;
+which corresponds to --cache-debug;
 .TP 6
 .B cache_disable
-which corresponds to --cache_disable;
+which corresponds to --cache-disable;
 .TP 6
 .B cache_force
-which corresponds to --cache_force;
+which corresponds to --cache-force;
 .TP 6
 .B cache_show
-which corresponds to --cache_show;
+which corresponds to --cache-show;
 .TP 6
 .B clean
 which corresponds to -c, --clean and --remove;
@@ -6882,25 +6882,27 @@ if not conf.CheckQt('/usr/lib/qt'):
 env = conf.Finish() 
 .EE
 
-.SS Construction Variable Options
+.SS Command-Line Construction Variables
 
-Often when building software, various options need to be specified at build
-time that are not known when the SConstruct/SConscript files are
-written. For example, libraries needed for the build may be in non-standard
+Often when building software,
+some variables must be specified at build time.
+For example, libraries needed for the build may be in non-standard
 locations, or site-specific compiler options may need to be passed to the
 compiler. 
 .B scons
-provides an Options object for overridding construction variables
+provides a
+.B Variables
+object to support overriding construction variables
 on the command line:
 .ES
 $ scons VARIABLE=foo
 .EE
 The variable values can also be specified in a text-based SConscript file.
-To create an Options object, call the Options() function:
+To create a Variables object, call the Variables() function:
 
 .TP
-.RI Options([ files "], [" args ])
-This creates an Options object that will read construction variables from
+.RI Variables([ files "], [" args ])
+This creates a Variables object that will read construction variables from
 the file or list of filenames specified in
 .IR files .
 If no files are specified,
@@ -6920,16 +6922,16 @@ specified on the command line.
 Example:
 
 .ES
-opts = Options('custom.py')
-opts = Options('overrides.py', ARGUMENTS)
-opts = Options(None, {FOO:'expansion', BAR:7})
+vars = Variables('custom.py')
+vars = Variables('overrides.py', ARGUMENTS)
+vars = Variables(None, {FOO:'expansion', BAR:7})
 .EE
 
-Options objects have the following methods:
+Variables objects have the following methods:
 
 .TP
 .RI Add( key ", [" help ", " default ", " validator ", " converter ])
-This adds a customizable construction variable to the Options object. 
+This adds a customizable construction variable to the Variables object. 
 .I key
 is the name of the variable. 
 .I help 
@@ -6962,19 +6964,19 @@ and then added to the environment.
 Examples:
 
 .ES
-opts.Add('CC', 'The C compiler')
+vars.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)
+vars.Add('COLOR', validator=valid_color)
 .EE
 
 .TP
-.RI AddOptions( list )
+.RI AddVariables( list )
 A wrapper script that adds
 multiple customizable construction variables
-to an Options object.
+to a Variables object.
 .I list
 is a list of tuple or list objects
 that contain the arguments
@@ -6983,7 +6985,7 @@ for an individual call to the
 method.
 
 .ES
-opt.AddOptions(
+opt.AddVariables(
        ('debug', '', 0),
        ('CC', 'The C compiler'),
        ('VALIDATE', 'An option for testing validation',
@@ -6998,23 +7000,23 @@ This updates a construction environment
 with the customized construction variables.
 Any specified variables that are
 .I not
-configured for the Options object
+configured for the Variables object
 will be saved and may be
 retrieved with the
-.BR UnknownOptions ()
+.BR UnknownVariables ()
 method, below.
 
 Normally this method is not called directly,
-but is called indirectly by passing the Options object to
+but is called indirectly by passing the Variables object to
 the Environment() function:
 
 .ES
-env = Environment(options=opts)
+env = Environment(variables=vars)
 .EE
 
 .IP
 The text file(s) that were specified
-when the Options object was created
+when the Variables object was created
 are executed as Python scripts,
 and the values of (global) Python variables set in the file
 are added to the construction environment.
@@ -7026,34 +7028,34 @@ CC = 'my_cc'
 .EE
 
 .TP
-.RI UnknownOptions( )
+.RI UnknownVariables( )
 Returns a dictionary containing any
 variables that were specified
 either in the files or the dictionary
-with which the Options object was intialized,
-but for which the Options object was
+with which the Variables object was initialized,
+but for which the Variables object was
 not configured.
 
 .ES
-env = Environment(options=opts)
-for key, value in opts.UnknownOptions():
+env = Environment(variables=vars)
+for key, value in vars.UnknownVariables():
     print "unknown variable:  %s=%s" % (key, value)
 .EE
 
 .TP
 .RI Save( filename ", " env )
-This saves the currently set options into a script file named  
+This saves the currently set variables into a script file named  
 .I filename
 that can be used on the next invocation to automatically load the current
-settings.  This method combined with the Options method can be used to
-support caching of options between runs.
+settings.  This method combined with the Variables method can be used to
+support caching of variables between runs.
 
 .ES
 env = Environment()
-opts = Options(['options.cache', 'custom.py'])
-opts.Add(...)
-opts.Update(env)
-opts.Save('options.cache', env)
+vars = Variables(['variables.cache', 'custom.py'])
+vars.Add(...)
+vars.Update(env)
+vars.Save('variables.cache', env)
 .EE
 
 .TP
@@ -7079,12 +7081,12 @@ and return
 function).
 
 .ES
-Help(opts.GenerateHelpText(env))
-Help(opts.GenerateHelpText(env, sort=cmp))
+Help(vars.GenerateHelpText(env))
+Help(vars.GenerateHelpText(env, sort=cmp))
 .EE
 
 .TP
-.RI FormatOptionHelpText( env ", " opt ", " help ", " default ", " actual )
+.RI FormatVariableHelpText( env ", " opt ", " help ", " default ", " actual )
 This method returns a formatted string
 containing the printable help text
 for one option.
@@ -7106,17 +7108,17 @@ string if you want the entries separated.
 def my_format(env, opt, help, default, actual):
     fmt = "\n%s: default=%s actual=%s (%s)\n"
     return fmt % (opt, default. actual, help)
-opts.FormatOptionHelpText = my_format
+vars.FormatVariableHelpText = my_format
 .EE
 
-To make it more convenient to work with customizable Options,
+To make it more convenient to work with customizable Variables,
 .B scons
 provides a number of functions
 that make it easy to set up
-various types of Options:
+various types of Variables:
 
 .TP
-.RI BoolOption( key ", " help ", " default )
+.RI BoolVariable( key ", " help ", " default )
 Return a tuple of arguments
 to set up a Boolean option.
 The option will use
@@ -7149,7 +7151,7 @@ and
 as false.
 
 .TP
-.RI EnumOption( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
+.RI EnumVariable( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
 Return a tuple of arguments
 to set up an option
 whose value may be one
@@ -7196,7 +7198,7 @@ and all input values will be
 converted to lower case.
 
 .TP
-.RI ListOption( key ", " help ", " default ", " names ", [", map ])
+.RI ListVariable( key ", " help ", " default ", " names ", [", map ])
 Return a tuple of arguments
 to set up an option
 whose value may be one or more
@@ -7230,7 +7232,7 @@ in the
 list.
 
 .TP
-.RI PackageOption( key ", " help ", " default )
+.RI PackageVariable( key ", " help ", " default )
 Return a tuple of arguments
 to set up an option
 whose value is a path name
@@ -7268,7 +7270,7 @@ or
 to disable use of the specified option.
 
 .TP
-.RI PathOption( key ", " help ", " default ", [" validator ])
+.RI PathVariable( key ", " help ", " default ", [" validator ])
 Return a tuple of arguments
 to set up an option
 whose value is expected to be a path name.
@@ -7288,18 +7290,18 @@ verify that the specified path
 is acceptable.
 SCons supplies the
 following ready-made validators:
-.BR PathOption.PathExists
+.BR PathVariable.PathExists
 (the default),
 which verifies that the specified path exists;
-.BR PathOption.PathIsFile ,
+.BR PathVariable.PathIsFile ,
 which verifies that the specified path is an existing file;
-.BR PathOption.PathIsDir ,
+.BR PathVariable.PathIsDir ,
 which verifies that the specified path is an existing directory;
-.BR PathOption.PathIsDirCreate ,
+.BR PathVariable.PathIsDirCreate ,
 which verifies that the specified path is a directory
 and will create the specified directory if the path does not exist;
 and
-.BR PathOption.PathAccept ,
+.BR PathVariable.PathAccept ,
 which simply accepts the specific path name argument without validation,
 and which is suitable if you want your users
 to be able to specify a directory path that will be
@@ -7309,7 +7311,7 @@ You may supply your own
 function,
 which must take three arguments
 .RI ( key ,
-the name of the options variable to be set;
+the name of the variable to be set;
 .IR val ,
 the specified value being checked;
 and
@@ -7321,27 +7323,27 @@ if the specified value is not acceptable.
 .RE
 These functions make it
 convenient to create a number
-of options with consistent behavior
+of variables with consistent behavior
 in a single call to the
-.B AddOptions
+.B AddVariables
 method:
 
 .ES
-opts.AddOptions(
-    BoolOption('warnings', 'compilation with -Wall and similiar', 1),
-    EnumOption('debug', 'debug output and symbols', 'no'
+vars.AddVariables(
+    BoolVariable('warnings', 'compilation with -Wall and similiar', 1),
+    EnumVariable('debug', 'debug output and symbols', 'no'
                allowed_values=('yes', 'no', 'full'),
                map={}, ignorecase=0),  # case sensitive
-    ListOption('shared',
+    ListVariable('shared',
                'libraries to build as shared libraries',
                'all',
                names = list_of_libs),
-    PackageOption('x11',
+    PackageVariable('x11',
                   'use X11 installed here (yes = search some places)',
                   'yes'),
-    PathOption('qtdir', 'where the root of Qt is installed', qtdir),
-    PathOption('foopath', 'where the foo library is installed', foopath,
-               PathOption.PathIsDir),
+    PathVariable('qtdir', 'where the root of Qt is installed', qtdir),
+    PathVariable('foopath', 'where the foo library is installed', foopath,
+               PathVariable.PathIsDir),
 
 )
 .EE
@@ -9460,10 +9462,10 @@ The following would allow the C compiler to be specified on the command
 line or in the file custom.py. 
 
 .ES
-opts = Options('custom.py')
-opts.Add('CC', 'The C compiler.')
-env = Environment(options=opts)
-Help(opts.GenerateHelpText(env))
+vars = Variables('custom.py')
+vars.Add('CC', 'The C compiler.')
+env = Environment(variables=vars)
+Help(vars.GenerateHelpText(env))
 .EE
 
 The user could specify the C compiler on the command line:
diff --git a/doc/scons.mod b/doc/scons.mod
index 739be58..ad20b7b 100644
--- a/doc/scons.mod
+++ b/doc/scons.mod
@@ -148,6 +148,7 @@
 <!ENTITY AddPostAction "<function>AddPostAction</function>">
 <!ENTITY AddPreAction "<function>AddPreAction</function>">
 <!ENTITY AddOptions "<function>AddOptions</function>">
+<!ENTITY AddVariables "<function>AddVariables</function>">
 <!ENTITY Alias "<function>Alias</function>">
 <!ENTITY Aliases "<function>Aliases</function>">
 <!ENTITY AlwaysBuild "<function>AlwaysBuild</function>">
@@ -155,6 +156,7 @@
 <!ENTITY AppendENVPath "<function>AppendENVPath</function>">
 <!ENTITY AppendUnique "<function>AppendUnique</function>">
 <!ENTITY BoolOption "<function>BoolOption</function>">
+<!ENTITY BoolVariable "<function>BoolVariable</function>">
 <!ENTITY Build "<function>Build</function>">
 <!ENTITY CacheDir "<function>CacheDir</function>">
 <!ENTITY Chmod "<function>Chmod</function>">
@@ -172,6 +174,7 @@
 <!ENTITY Dump "<function>Dump</function>">
 <!ENTITY Entry "<function>Entry</function>">
 <!ENTITY EnumOption "<function>EnumOption</function>">
+<!ENTITY EnumVariable "<function>EnumVariable</function>">
 <!ENTITY Environment "<function>Environment</function>">
 <!ENTITY Execute "<function>Execute</function>">
 <!ENTITY Export "<function>Export</function>">
@@ -188,6 +191,7 @@
 <!ENTITY InstallAs "<function>InstallAs</function>">
 <!ENTITY Link "<function>Link</function>">
 <!ENTITY ListOption "<function>ListOption</function>">
+<!ENTITY ListVariable "<function>ListVariable</function>">
 <!ENTITY Local "<function>Local</function>">
 <!ENTITY Mkdir "<function>Mkdir</function>">
 <!ENTITY Module "<function>Module</function>">
@@ -196,7 +200,9 @@
 <!ENTITY NoCache "<function>NoCache</function>">
 <!ENTITY Objects "<function>Objects</function>">
 <!ENTITY Options "<function>Options</function>">
+<!ENTITY Variables "<function>Variables</function>">
 <!ENTITY PackageOption "<function>PackageOption</function>">
+<!ENTITY PackageVariable "<function>PackageVariable</function>">
 <!ENTITY ParseConfig "<function>ParseConfig</function>">
 <!ENTITY PathOption "<function>PathOption</function>">
 <!ENTITY PathOption_PathAccept "<function>PathOption.PathAccept</function>">
@@ -204,6 +210,12 @@
 <!ENTITY PathOption_PathIsDir "<function>PathOption.PathIsDir</function>">
 <!ENTITY PathOption_PathIsDirCreate "<function>PathOption.PathIsDirCreate</function>">
 <!ENTITY PathOption_PathIsFile "<function>PathOption.PathIsFile</function>">
+<!ENTITY PathVariable "<function>PathVariable</function>">
+<!ENTITY PathVariable_PathAccept "<function>PathVariable.PathAccept</function>">
+<!ENTITY PathVariable_PathExists "<function>PathVariable.PathExists</function>">
+<!ENTITY PathVariable_PathIsDir "<function>PathVariable.PathIsDir</function>">
+<!ENTITY PathVariable_PathIsDirCreate "<function>PathVariable.PathIsDirCreate</function>">
+<!ENTITY PathVariable_PathIsFile "<function>PathVariable.PathIsFile</function>">
 <!ENTITY Precious "<function>Precious</function>">
 <!ENTITY Prepend "<function>Prepend</function>">
 <!ENTITY PrependENVPath "<function>PrependENVPath</function>">
diff --git a/doc/user/MANIFEST b/doc/user/MANIFEST
index 565298f..b3106af 100644
--- a/doc/user/MANIFEST
+++ b/doc/user/MANIFEST
@@ -1,4 +1,5 @@
 actions.xml
+add-method.xml
 alias.xml
 ant.xml
 builders.xml
diff --git a/doc/user/README b/doc/user/README
new file mode 100644
index 0000000..7bca314
--- /dev/null
+++ b/doc/user/README
@@ -0,0 +1,19 @@
+# __COPYRIGHT__
+
+When adding a new file, add it to main.xml and MANIFEST.
+
+To build the .xml files from the .in files:
+  scons -D . BUILDDOC=1
+
+Writing examples: here's a simple template.
+
+ <scons_example name="Foo">
+   <file name="SConstruct">
+    env = Environment()
+    print env.Dump("CC")
+   </file>
+ </scons_example>
+
+ <scons_output example="Foo">
+    <scons_output_command>scons -Q</scons_output_command>
+ </scons_output>
diff --git a/doc/user/add-method.in b/doc/user/add-method.in
new file mode 100644
index 0000000..853b9a8
--- /dev/null
+++ b/doc/user/add-method.in
@@ -0,0 +1,105 @@
+<!--
+
+  __COPYRIGHT__
+
+  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>
+
+  The env.AddMethod(function, [name]) function is used to add a method
+  to an environment.  It's typically used to add a "pseudo-builder" or
+  wrap up a call to multiple builders.  In the first example, we want
+  to install the program into the standard bin dir, but also copy it
+  into a local install/bin dir that might be used to build a package
+  from.
+
+  </para>
+
+  <scons_example name="ex1">
+     <file name="SConstruct" printme="1">
+     def install_in_bin_dirs(env, source):
+         """Install source in both bin dirs"""
+         i1 = env.Install("$BIN", source)
+         i2 = env.Install("$LOCALBIN", source)
+         return [i1[0], i2][0] # Return a list, like a normal builder
+     env = Environment(BIN='/usr/bin', LOCALBIN='#install/bin')
+     env.AddMethod(install_in_bin_dirs, "InstallInBinDirs")
+     env.InstallInBinDirs(Program('hello.c')) # installs hello in both bin dirs     
+     </file>
+     <file name="hello.c">
+     int main() { printf("Hello, world!\n"); }
+     </file>
+  </scons_example>
+
+  <para>
+  This produces the following:
+  </para>
+
+  <scons_output example="ex1">
+    <scons_output_command>scons -Q</scons_output_command>
+  </scons_output>
+
+  <para>
+
+  It also gives more flexibility in parsing arguments than you can get
+  with a builder.  The next example shows a pseudo-builder with a
+  named argument that modifies the filename, and a separate argument
+  for the resource file (rather than having the builder figure it out
+  by file extension).  Also this example demonstrates using the global
+  AddMethod function to add a method to the global Environment class,
+  so it will be used in all subsequently created environments.
+
+  </para>
+
+  <scons_example name="ex2">
+     <file name="SConstruct" printme="1">
+     import sys;
+     def BuildTestProg(env, testfile, resourcefile, testdir="tests"):
+         """Build the test program;
+         prepends "test_" to src and target, and puts target into testdir."""
+         srcfile="test_%s.c"%testfile
+         if sys.platform=='win32':
+             target="%s/test_%s$EXESUFFIX"%(testdir,[testfile, resourcefile])
+         else:
+             target="%s/test_%s$EXESUFFIX"%(testdir,testfile)
+         p = env.Program(target, srcfile)
+         return p
+     AddMethod(Environment, BuildTestProg)
+
+     # Now use it
+     env=Environment()
+     env.BuildTestProg('stuff', resourcefile='res.rc')
+     </file>
+     <file name="test_stuff.c">
+     int main() { printf("Hello, world!\n"); }
+     </file>
+  </scons_example>
+
+  <para>
+  This produces the following (on Linux, anyway; Windows would include the
+  resource file):
+  </para>
+
+  <scons_output example="ex2">
+    <scons_output_command>scons -Q</scons_output_command>
+  </scons_output>
+
diff --git a/doc/user/add-method.xml b/doc/user/add-method.xml
new file mode 100644
index 0000000..22f5f1a
--- /dev/null
+++ b/doc/user/add-method.xml
@@ -0,0 +1,100 @@
+<!--
+
+  __COPYRIGHT__
+
+  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>
+
+  The env.AddMethod(function, [name]) function is used to add a method
+  to an environment.  It's typically used to add a "pseudo-builder" or
+  wrap up a call to multiple builders.  In the first example, we want
+  to install the program into the standard bin dir, but also copy it
+  into a local install/bin dir that might be used to build a package
+  from.
+
+  </para>
+
+  <programlisting>
+     def install_in_bin_dirs(env, source):
+         """Install source in both bin dirs"""
+         i1 = env.Install("$BIN", source)
+         i2 = env.Install("$LOCALBIN", source)
+         return [i1[0], i2][0] # Return a list, like a normal builder
+     env = Environment(BIN='/usr/bin', LOCALBIN='#install/bin')
+     env.AddMethod(install_in_bin_dirs, "InstallInBinDirs")
+     env.InstallInBinDirs(Program('hello.c')) # installs hello in both bin dirs     
+  </programlisting>
+
+  <para>
+  This produces the following:
+  </para>
+
+  <screen>
+    % <userinput>scons -Q</userinput>
+    cc -o hello.o -c hello.c
+    cc -o hello hello.o
+    Install file: "hello" as "install/bin/hello"
+  </screen>
+
+  <para>
+
+  It also gives more flexibility in parsing arguments than you can get
+  with a builder.  The next example shows a pseudo-builder with a
+  named argument that modifies the filename, and a separate argument
+  for the resource file (rather than having the builder figure it out
+  by file extension).  Also this example demonstrates using the global
+  AddMethod function to add a method to the global Environment class,
+  so it will be used in all subsequently created environments.
+
+  </para>
+
+  <programlisting>
+     import sys
+     def BuildTestProg(env, testfile, resourcefile, testdir="tests"):
+         """Build the test program;
+         prepends "test_" to src and target, and puts target into testdir."""
+         srcfile="test_%s.c"%testfile
+         if sys.platform=='win32':
+             target="%s/test_%s$EXESUFFIX"%(testdir,[testfile, resourcefile])
+         else:
+             target="%s/test_%s$EXESUFFIX"%(testdir,testfile)
+         p = env.Program(target, srcfile)
+         return p
+     AddMethod(Environment, BuildTestProg)
+
+     # Now use it
+     env=Environment()
+     env.BuildTestProg('stuff', resourcefile='res.rc')
+  </programlisting>
+
+  <para>
+  This produces the following (on Linux, anyway; Windows would include the
+  resource file):
+  </para>
+
+  <screen>
+    % <userinput>scons -Q</userinput>
+    cc -o test_stuff.o -c test_stuff.c
+    cc -o tests/test_stuff test_stuff.o
+  </screen>
+
diff --git a/doc/user/main.in b/doc/user/main.in
index 4095e6b..8981b14 100644
--- a/doc/user/main.in
+++ b/doc/user/main.in
@@ -51,6 +51,7 @@
     <!ENTITY builders-built-in SYSTEM "builders-built-in.xml">
     <!ENTITY builders-commands SYSTEM "builders-commands.xml">
     <!ENTITY builders-writing SYSTEM "builders-writing.xml">
+    <!ENTITY add-method SYSTEM "add-method.xml">
     <!ENTITY caching SYSTEM "caching.xml">
     <!ENTITY command-line SYSTEM "command-line.xml">
     <!ENTITY copyright SYSTEM "copyright.xml">
@@ -138,8 +139,6 @@
 
   XXX Progress()
 
-  XXX AddMethod()
-
   XXX - - diskcheck=
 
   XXX site_scons
@@ -295,6 +294,11 @@
     &builders-commands;
   </chapter>
 
+  <chapter id="chap-add-method">
+    <title>Pseudo-Builders:  the AddMethod function</title>
+    &add-method;
+  </chapter>
+
   <!--
 
   XXX Action()
diff --git a/doc/user/main.xml b/doc/user/main.xml
index 4095e6b..8981b14 100644
--- a/doc/user/main.xml
+++ b/doc/user/main.xml
@@ -51,6 +51,7 @@
     <!ENTITY builders-built-in SYSTEM "builders-built-in.xml">
     <!ENTITY builders-commands SYSTEM "builders-commands.xml">
     <!ENTITY builders-writing SYSTEM "builders-writing.xml">
+    <!ENTITY add-method SYSTEM "add-method.xml">
     <!ENTITY caching SYSTEM "caching.xml">
     <!ENTITY command-line SYSTEM "command-line.xml">
     <!ENTITY copyright SYSTEM "copyright.xml">
@@ -138,8 +139,6 @@
 
   XXX Progress()
 
-  XXX AddMethod()
-
   XXX - - diskcheck=
 
   XXX site_scons
@@ -295,6 +294,11 @@
     &builders-commands;
   </chapter>
 
+  <chapter id="chap-add-method">
+    <title>Pseudo-Builders:  the AddMethod function</title>
+    &add-method;
+  </chapter>
+
   <!--
 
   XXX Action()