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().
........

1 files changed, 72 insertions, 70 deletions

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: