Anonymous avatar Anonymous committed d088280

Merged revisions 1826-1882 via svnmerge from
http://scons.tigris.org/svn/scons/branches/core

........
r1828 | stevenknight | 2007-02-12 13:29:17 -0600 (Mon, 12 Feb 2007) | 1 line

0.96.D588 - Speed up Builder suffix-matching.
........
r1829 | stevenknight | 2007-02-14 08:12:32 -0600 (Wed, 14 Feb 2007) | 1 line

0.96.D589 - The scons command, branch 0.96.94.
........
r1830 | stevenknight | 2007-02-14 09:49:44 -0600 (Wed, 14 Feb 2007) | 1 line

0.96.D590 - Fix the scons-doc .tar.gz file packaging.
........
r1835 | stevenknight | 2007-02-15 11:03:20 -0600 (Thu, 15 Feb 2007) | 1 line

0.96.D591 - Update the release HOWTO.
........
r1836 | stevenknight | 2007-02-15 13:39:24 -0600 (Thu, 15 Feb 2007) | 1 line

0.96.D592 - The scons command, branch 0.96.95.
........
r1837 | stevenknight | 2007-02-15 18:34:18 -0600 (Thu, 15 Feb 2007) | 1 line

0.96.D593 - Back out (comment out) Windows registry installer changes.
........
r1838 | stevenknight | 2007-02-16 10:37:28 -0600 (Fri, 16 Feb 2007) | 1 line

0.96.D594 - Update Debian packaging to remove hard-coded references to Python 2.2. (Jean-Baptiste Lab)
........
r1839 | stevenknight | 2007-02-20 09:34:23 -0600 (Tue, 20 Feb 2007) | 1 line

0.96.D595 - Documentation fixes. In the construction variable appendix, use cross-referenced links to entries.
........
r1840 | stevenknight | 2007-02-21 05:11:35 -0600 (Wed, 21 Feb 2007) | 1 line

0.96.D596 - Handle Java '.class' attributes after non-word tokens without assuming it introduces an inner class.
........
r1841 | stevenknight | 2007-02-21 22:33:28 -0600 (Wed, 21 Feb 2007) | 1 line

0.96.D597 - CPPDEFINES regression
........
r1842 | stevenknight | 2007-02-22 14:19:10 -0600 (Thu, 22 Feb 2007) | 1 line

0.96.D598 - Do not detect a Java anonymous class when the first non-skipped token after "new" is a closing brace.
........
r1843 | stevenknight | 2007-02-23 10:45:06 -0600 (Fri, 23 Feb 2007) | 1 line

0.96.D599 - Better [Errno 21] Is a directory error message.
........
r1844 | stevenknight | 2007-02-23 13:32:11 -0600 (Fri, 23 Feb 2007) | 1 line

0.96.D600 - Fix expansion of non-Node objects within a PathList (maximum recursion / unhashable type bug).
........
r1847 | stevenknight | 2007-03-02 00:12:27 -0600 (Fri, 02 Mar 2007) | 1 line

0.96.D601 - Generate SCons API documentation from the docstrings using epydoc.
........
r1848 | stevenknight | 2007-03-02 14:10:06 -0600 (Fri, 02 Mar 2007) | 1 line

0.96.D602 - Fix use of custom include and lib paths with Visual Studio 8. (Richard Viney)
........
r1849 | stevenknight | 2007-03-03 01:00:22 -0600 (Sat, 03 Mar 2007) | 1 line

0.96.D603 - Man page fix: ParseDepends(). User's Guide updates: NoCache(), Clean(), fix CPPDEFINES output, markers for to-be-documented features, white space clean-up.
........
r1850 | stevenknight | 2007-03-06 02:29:08 -0600 (Tue, 06 Mar 2007) | 1 line

0.96.D604 - Fix use of --debug=presub with the Actions for our out-of-the-box Builders.
........
r1851 | stevenknight | 2007-03-06 09:10:43 -0600 (Tue, 06 Mar 2007) | 1 line

0.96.D605 - User Guide updates: --random, AlwaysBuild(), --tree=, --debug=presub, --debug=stacktrace.
........
r1852 | stevenknight | 2007-03-06 15:38:06 -0600 (Tue, 06 Mar 2007) | 1 line

0.96.D606 - Have the Intel toolchain use the default smart linking logic. (Dmitry Grigorenko and Gary Oberbrunner)
........
r1853 | stevenknight | 2007-03-06 17:56:44 -0600 (Tue, 06 Mar 2007) | 1 line

0.96.D607 - Fix tests: ActionTests.py for presub change, command detection in test/Intel/icpc-link.py.
........
r1854 | stevenknight | 2007-03-08 09:35:25 -0600 (Thu, 08 Mar 2007) | 1 line

0.96.D608 - Better selection of .NET Framework SDK paths. (Richard Viney)
........
r1855 | stevenknight | 2007-03-08 10:34:37 -0600 (Thu, 08 Mar 2007) | 1 line

0.96.D609 - Don't re-run TeX if the triggering strings (\makeindex, \bibliography, \tableofcontents) are commented out. (Matthias Troffaes)
........
r1856 | stevenknight | 2007-03-09 16:18:36 -0600 (Fri, 09 Mar 2007) | 1 line

0.96.D610 - Teach the new PathList module to handle nested lists within CPPPATH and the like.
........
r1857 | stevenknight | 2007-03-10 23:30:29 -0600 (Sat, 10 Mar 2007) | 1 line

0.96.D611 - Qt builders_used failure.
........
r1858 | stevenknight | 2007-03-11 15:33:34 -0500 (Sun, 11 Mar 2007) | 1 line

0.96.D612 - Document limitations of --implicit-cache w.r.t. CPPPATH/LIBPATH/etc.
........
r1859 | stevenknight | 2007-03-11 21:11:26 -0500 (Sun, 11 Mar 2007) | 1 line

0.96.D613 - Document --debug=findlibs and --taskmastertrace in the User's Guide.
........
r1860 | stevenknight | 2007-03-12 13:28:42 -0500 (Mon, 12 Mar 2007) | 1 line

0.96.D614 - Remove deleted cons file from the User's Guide MANIFEST. Fix epydoc API build if the build directory is outside the current directory.
........
r1861 | stevenknight | 2007-03-13 13:03:56 -0500 (Tue, 13 Mar 2007) | 2 lines

Ignore '*.pyc' files in the compat/ subdirectory.
........
r1862 | stevenknight | 2007-03-13 19:08:19 -0500 (Tue, 13 Mar 2007) | 1 line

0.96.D615 - Fix use of $VAR expansions within CPPPATH/LIBPATH values when the expansion is itself a Dir node concatenated with a string.
........
r1866 | stevenknight | 2007-03-16 01:46:10 -0500 (Fri, 16 Mar 2007) | 1 line

0.96.D616 - Back off to the 0.96.94 of Builder.py (with some performance improvements).
........
r1867 | stevenknight | 2007-03-16 11:20:39 -0500 (Fri, 16 Mar 2007) | 1 line

0.96.D617 - Fix an unnamed variable error if we can't map the Visual Studio version to a default framework version.
........
r1868 | stevenknight | 2007-03-16 12:08:18 -0500 (Fri, 16 Mar 2007) | 1 line

0.96.D618 - Quote the MSVS build target in command lines to handle spaces target name. (Jeff Mahovsky)
........
r1869 | stevenknight | 2007-03-16 13:30:06 -0500 (Fri, 16 Mar 2007) | 1 line

0.96.D619 - Portability fixes for tests run on Windows.
........
r1870 | stevenknight | 2007-03-20 00:18:04 -0500 (Tue, 20 Mar 2007) | 1 line

0.96.D620 - Windows portability fixes: test scripts and infrastructure, detect vcexpress.exe.
........
r1871 | garyo | 2007-03-21 18:32:54 -0500 (Wed, 21 Mar 2007) | 1 line

Fix bug where site_scons dir was added to sys.path as relative, not absolute. Added test case. Bug reported by Timothy Woods; thanks for the test case!
........
r1872 | stevenknight | 2007-03-22 09:43:23 -0500 (Thu, 22 Mar 2007) | 1 line

0.96.D622 - Add mention of site_scons fix to src/CHANGES.txt.
........
r1873 | stevenknight | 2007-04-02 23:49:36 -0500 (Mon, 02 Apr 2007) | 1 line

0.96.D623 - Parallel build dependencies with multiple entries in children. (Adam Simpkins)
........
r1874 | stevenknight | 2007-04-04 07:45:05 -0500 (Wed, 04 Apr 2007) | 1 line

0.96.D624 - Make all necessary LaTeX auxiliary files Precious, so bibliography contents aren't affected by whether the auxiliary files exist or not. (Joel B. Mohler)
........
r1875 | stevenknight | 2007-04-04 13:15:39 -0500 (Wed, 04 Apr 2007) | 1 line

0.96.D625 - Fix --debug-time value when -j option is used.
........
r1876 | stevenknight | 2007-04-09 19:40:08 -0500 (Mon, 09 Apr 2007) | 1 line

0.96.D626 - Fix man page example of propagating external user environment. Eliminate cut-and-paste sentence in NoCache() description. (Helmut Grohne, Joe Bloggs) [Issue 1626] [Issue 1627]
........
r1877 | stevenknight | 2007-04-09 23:20:14 -0500 (Mon, 09 Apr 2007) | 1 line

0.96.D627 - Re-run latex after bibtex runs. (Rob Managan)
........
r1878 | stevenknight | 2007-04-11 23:38:17 -0500 (Wed, 11 Apr 2007) | 1 line

0.96.D628 - Fix typo in the User's Guide. [issue 1600]
........
r1879 | stevenknight | 2007-04-12 01:06:35 -0500 (Thu, 12 Apr 2007) | 1 line

0.96.D629 - Avoid name conflicts with compat/ modules (specifically _subprocess.py).
........
r1880 | stevenknight | 2007-04-12 01:33:42 -0500 (Thu, 12 Apr 2007) | 1 line

0.96.D630 - Portability fixes and other improvements in test scripts.
........
r1882 | stevenknight | 2007-04-13 16:42:02 -0500 (Fri, 13 Apr 2007) | 1 line

0.96.D631 - The scons command, branch 0.96.96.
........

Comments (0)

Files changed (157)

HOWTO/release.txt

 
             download.php:   new version number
 
+            includes/templates.php:
+                            update $latestrelease
+
             includes/versions.php:
                             update $stablerelease and/or $latestrelease
-                            add new version number do $docversions[],
-                            SHIFT $docversions[] INDEX NUMBERS :-(
+                            add new version number to $docversions[],
+                            IMPORTANT:  SHIFT $docversions[] INDEX NUMBERS :-(
 
             index.php:      announcement on the home page
                             remove out-of-date announcements
         [point your browser to http://www.scons.org/]
 
 
-    Update the tigris.org web site:
+    Update the project pages at tigris.org:
 
         svn co http://scons.tigris.org/svn/scons/trunk
 

QMTest/TestSCons.py

 # to what we expect.  (If we derived the version number from the same
 # data driving the build we might miss errors if the logic breaks.)
 
-SConsVersion = '0.96.94'
+SConsVersion = '0.96.96'
 
 __all__.extend([ 'TestSCons',
                  'python',
 
         self.QT = self.workpath(dir)
         self.QT_LIB = 'myqt'
-        self.QT_MOC = '%s %s' % (python, self.workpath(dir, 'bin', 'mymoc.py'))
-        self.QT_UIC = '%s %s' % (python, self.workpath(dir, 'bin', 'myuic.py'))
+        self.QT_MOC = '%s %s' % (_python_, self.workpath(dir, 'bin', 'mymoc.py'))
+        self.QT_UIC = '%s %s' % (_python_, self.workpath(dir, 'bin', 'myuic.py'))
         self.QT_LIB_DIR = self.workpath(dir, 'lib')
 
     def Qt_create_SConstruct(self, place):
         """Returns a full path to the executable (MSDEV or devenv)
         for the specified version of Visual Studio.
         """
-        sub_path = {
-            '6.0' : ['Common', 'MSDev98', 'Bin', 'MSDEV.COM'],
-            '7.0' : ['Common7', 'IDE', 'devenv.com'],
-            '7.1' : ['Common7', 'IDE', 'devenv.com'],
-            '8.0' : ['Common7', 'IDE', 'devenv.com'],
+        common_msdev98_bin_msdev_com = ['Common', 'MSDev98', 'Bin', 'MSDEV.COM']
+        common7_ide_devenv_com       = ['Common7', 'IDE', 'devenv.com']
+        common7_ide_vcexpress_exe    = ['Common7', 'IDE', 'VCExpress.exe']
+        sub_paths = {
+            '6.0' : [
+                common_msdev98_bin_msdev_com,
+            ],
+            '7.0' : [
+                common7_ide_devenv_com,
+            ],
+            '7.1' : [
+                common7_ide_devenv_com,
+            ],
+            '8.0' : [
+                common7_ide_devenv_com,
+                common7_ide_vcexpress_exe,
+            ],
         }
         from SCons.Tool.msvs import get_msvs_install_dirs
         vs_path = get_msvs_install_dirs(version)['VSINSTALLDIR']
-        return apply(os.path.join, [vs_path] + sub_path[version])
+        for sp in sub_paths[version]:
+            p = apply(os.path.join, [vs_path] + sp)
+            if os.path.exists(p):
+                return p
+        return apply(os.path.join, [vs_path] + sub_paths[version][0])
 
 # In some environments, $AR will generate a warning message to stderr
 # if the library doesn't previously exist and is being created.  One
     --  (Optional.)  Install from a pre-packaged SCons package that
         does not require distutils:
 
-            Red Hat Linux       scons-0.96.94.noarch.rpm
+            Red Hat Linux       scons-0.96.96.noarch.rpm
 
-            Debian GNU/Linux    scons_0.96.94_all.deb
-                                (or use apt-get)
+            Debian GNU/Linux    use apt-get to get the official package
 
-            Windows             scons-0.96.94.win32.exe
+            Windows             scons-0.96.96.win32.exe
 
     --  (Recommended.)  Download the latest distutils package from the
         following URL:
 
 By default, the above commands will do the following:
 
-    --  Install the version-numbered "scons-0.96.94" and "sconsign-0.96.94"
+    --  Install the version-numbered "scons-0.96.96" and "sconsign-0.96.96"
         scripts in the default system script directory (/usr/bin or
         C:\Python*\Scripts, for example).  This can be disabled by
         specifying the "--no-version-script" option on the command
         if you want to install and experiment with a new version before
         making it the default on your system.  On UNIX or Linux systems,
         you can have the "scons" and "sconsign" scripts be hard links or
-        symbolic links to the "scons-0.96.94" and "sconsign-0.96.94" scripts
+        symbolic links to the "scons-0.96.96" and "sconsign-0.96.96" scripts
         by specifying the "--hardlink-scons" or "--symlink-scons"
         options on the command line.
 
-    --  Install "scons-0.96.94.bat" and "scons.bat" wrapper scripts in the
+    --  Install "scons-0.96.96.bat" and "scons.bat" wrapper scripts in the
         Python prefix directory on Windows (C:\Python*, for example).
         This can be disabled by specifying the "--no-install-bat" option
         on the command line.  On UNIX or Linux systems, the
-        "--install-bat" option may be specified to have "scons-0.96.94.bat"
+        "--install-bat" option may be specified to have "scons-0.96.96.bat"
         and "scons.bat" files installed in the default system script
         directory, which is useful if you want to install SCons in a
         shared file system directory that can be used to execute SCons
 
     --  Install the SCons build engine (a Python module) in an
         appropriate version-numbered SCons library directory
-        (/usr/lib/scons-0.96.94 or C:\Python*\scons-0.96.94, for example).
+        (/usr/lib/scons-0.96.96 or C:\Python*\scons-0.96.96, for example).
         See below for more options related to installing the build
         engine library.
 
 
             $ python runtest.py -a
 
-        Be patient, there are more than 500 test scripts in the
+        Be patient, there are more than 700 test scripts in the
         whole suite.
 
         If any test scripts fail, they will be listed in a summary at
 Depending on the utilities installed on your system, any or all of the
 following packages will be built:
 
-        build/dist/scons-0.96.94-1.noarch.rpm
-        build/dist/scons-0.96.94-1.src.rpm
-        build/dist/scons-0.96.94.linux-i686.tar.gz
-        build/dist/scons-0.96.94.tar.gz
-        build/dist/scons-0.96.94.win32.exe
-        build/dist/scons-0.96.94.zip
-        build/dist/scons-doc-0.96.94.tar.gz
-        build/dist/scons-local-0.96.94.tar.gz
-        build/dist/scons-local-0.96.94.zip
-        build/dist/scons-src-0.996.94tar.gz
-        build/dist/scons-src-0.96.94.zip
-        build/dist/scons_0.96.94-1_all.deb
+        build/dist/scons-0.96.96-1.noarch.rpm
+        build/dist/scons-0.96.96-1.src.rpm
+        build/dist/scons-0.96.96.linux-i686.tar.gz
+        build/dist/scons-0.96.96.tar.gz
+        build/dist/scons-0.96.96.win32.exe
+        build/dist/scons-0.96.96.zip
+        build/dist/scons-doc-0.96.96.tar.gz
+        build/dist/scons-local-0.96.96.tar.gz
+        build/dist/scons-local-0.96.96.zip
+        build/dist/scons-src-0.96.96.tar.gz
+        build/dist/scons-src-0.96.96.zip
+        build/dist/scons_0.96.96-1_all.deb
 
 The SConstruct file is supposed to be smart enough to avoid trying to
 build packages for which you don't have the proper utilities installed.
         Chad Austin
         Charles Crain
         Steve Leblanc
+        Greg Noel
         Gary Oberbrunner
         Anthony Roach
         Greg Spencer
 import time
 
 project = 'scons'
-default_version = '0.96.94'
+default_version = '0.96.96'
 copyright = "Copyright (c) %s The SCons Foundation" % copyright_years
 
 SConsignFile()
                             'sconsign.1',
                             'scons-time.1',
                             'script/scons.bat',
-                            'script/scons-post-install.py',
+                            #'script/scons-post-install.py',
                             'setup.cfg',
                             'setup.py',
                           ],
                     ])
 
         old = os.path.join('lib', 'scons', '')
-        new = os.path.join('lib', 'python2.2', 'site-packages', '')
+        new = os.path.join('lib', 'python' + python_ver, 'site-packages', '')
         def xxx(s, old=old, new=new):
             if s[:len(old)] == old:
                 s = new + s[len(old):]

bin/scons-proc.py

 base_sys_path = [os.getcwd() + '/build/test-tar-gz/lib/scons'] + sys.path
 
 helpstr = """\
-Usage: scons-varlist.py [--man|--sgml] \
+Usage: scons-proc.py [--man|--sgml] \
                         [-b file(s)] [-t file(s)] [-v file(s)] [infile ...]
 Options:
   -b file(s)        dump builder information to the specified file(s)
  *
  * Look in aesub(5) for more information about command substitutions.
  */
-build_command = "python2.4 ${Source bootstrap.py} -Y${SUBSTitute : \\ -Y $Search_Path} date='${DAte %Y/%m/%d %H:%M:%S}' developer=${DEVeloper} version=${VERsion} change=${Change}";
+build_command = "python2.1 ${Source bootstrap.py} -Y${SUBSTitute : \\ -Y $Search_Path} date='${DAte %Y/%m/%d %H:%M:%S}' developer=${DEVeloper} version=${VERsion} change=${Change}";
 
 /*
  * SCons removes its targets before constructing them, which qualifies it
-scons (0.96-94) unstable; urgency=low
+scons (0.96-96) unstable; urgency=low
 
   * Pre-release of eighth beta release.
 
- -- Steven Knight <knight@baldmt.com>  Sun, 07 Jan 2007 18:36:20 -0600
+ -- Steven Knight <knight@baldmt.com>  Thu, 12 Apr 2007 12:36:25 -0500
 
 
 scons (0.96-1) unstable; urgency=low
 Section: devel
 Priority: optional
 Maintainer: Moshe Zadka <moshez@debian.org>
-Build-Depends-Indep: debhelper (>> 2.0.0), python2.2-dev
+Build-Depends-Indep: debhelper (>> 2.0.0), python-dev (>> 2.2)
 Standards-Version: 3.5.6
 
 Package: scons
 Architecture: all
-Depends: python2.2
+Depends: python (>> 2.2)
 Description: A replacement for Make
  SCons is an Open Source software construction tool--that is, a build
  tool; an improved substitute for the classic Make utility; a better
 usr/bin
-usr/lib/python2.2/site-packages
 usr/share/doc/scons
 usr/share/man/man1
 fi
 
 NAME=scons
+PYTHON_VERSION=`python -V 2>&1| cut -d" " -f2 | cut -d"." -f0-2`
+PYTHON_EXE_NAME=`which python$PYTHON_VERSION`
 case "$1" in
         configure|abort-upgrade|abort-remove|abort-deconfigure)
                 dpkg --listfiles $NAME | grep '\.py$' | \
-                     xargs -n 1 /usr/bin/python2.2 -c 'import py_compile,sys;py_compile.compile(sys.argv[1])'
+                     xargs -n 1 $PYTHON_EXE_NAME -c 'import py_compile,sys;py_compile.compile(sys.argv[1])'
                 dpkg --listfiles $NAME | grep '\.py$' | \
-                     xargs -n 1 /usr/bin/python2.2 -O -c 'import py_compile,sys;py_compile.compile(sys.argv[1])'
+                     xargs -n 1 $PYTHON_EXE_NAME -O -c 'import py_compile,sys;py_compile.compile(sys.argv[1])'
         ;;
 esac
 # Overridable variables added to support building test .deb files
 # as part of routine SCons builds.  --SK
 BUILDDEB_OPTIONS=
-PYTHON=/usr/bin/python2.2
+PYTHON_VERSION=`python -V 2>&1| cut -d" " -f2 | cut -d"." -f0-2`
+PYTHON_PATH=/usr/bin/python
+PYTHON=$(PYTHON_PATH)$(PYTHON_VERSION)
 #######
 
 # Uncomment this to turn on verbose mode.
 	@# already exist on our non-Debian test build systems.  Hence,
 	@# we do a lot of mkdir -p and rm -f here...  --SK
 	@########
-	mkdir -p debian/scons/usr/lib/python2.2/site-packages/
-	rm -rf debian/scons/usr/lib/python2.2/site-packages/SCons
-	cp -r build/lib/SCons debian/scons/usr/lib/python2.2/site-packages/
+	mkdir -p debian/scons/usr/lib/python$(PYTHON_VERSION)/site-packages/
+	rm -rf debian/scons/usr/lib/python$(PYTHON_VERSION)/site-packages/SCons
+	cp -r build/lib/SCons debian/scons/usr/lib/python$(PYTHON_VERSION)/site-packages/
 
 	mkdir -p debian/scons/usr/bin/
 	rm -f debian/scons/usr/bin/scons
 # if lynx is available to do the dump.
 #
 fig2dev = whereis('fig2dev')
+epydoc = whereis('epydoc')
 groff = whereis('groff')
 lynx = whereis('lynx')
 man2html = whereis('man2html')
         tar_deps.append(html)
         tar_list.append(html)
 
+if epydoc:
+    # XXX Should be in common with reading the same thing in
+    # the SConstruct file.
+    e = os.path.join('#src', 'engine')
+    manifest_in = File(os.path.join(e, 'MANIFEST.in')).rstr()
+    sources = map(lambda x: x[:-1], open(manifest_in).readlines())
+    sources = filter(lambda x: string.find(x, 'Optik') == -1, sources)
+    sources = filter(lambda x: string.find(x, 'Platform') == -1, sources)
+    sources = filter(lambda x: string.find(x, 'Tool') == -1, sources)
+    # XXX
+    sources = filter(lambda x: string.find(x, 'Options') == -1, sources)
+
+    e = os.path.join(build, '..', 'scons', 'engine')
+    sources = map(lambda x, e=e: os.path.join(e, x), sources)
+
+    epydoc_commands = [
+        Delete('$OUTDIR'),
+        '$EPYDOC $EPYDOCFLAGS --output $OUTDIR --docformat=restructuredText --name SCons --url http://www.scons.org/ $SOURCES',
+        Touch('$TARGET'),
+    ]
+
+    htmldir = os.path.join(build, 'HTML', 'scons-api')
+    env.Command('${OUTDIR}/index.html', sources, epydoc_commands,
+                EPYDOC=epydoc, EPYDOCFLAGS='--html', OUTDIR=htmldir)
+    tar_deps.append(htmldir)
+    tar_list.append(htmldir)
+
+    # PDF and PostScript and TeX are built from the
+    # same invocation.
+    api_dir = os.path.join(build, 'scons-api')
+    api_pdf = os.path.join(api_dir, 'api.pdf')
+    api_ps = os.path.join(api_dir, 'api.ps')
+    api_tex = os.path.join(api_dir, 'api.tex')
+    api_targets = [api_pdf, api_ps, api_tex]
+    env.Command(api_targets, sources, epydoc_commands,
+                EPYDOC=epydoc, EPYDOCFLAGS='--pdf', OUTDIR=api_dir)
+    Local(api_targets)
+
+    pdf_install = os.path.join(build, 'PDF', 'scons-api.pdf')
+    env.InstallAs(pdf_install, api_pdf)
+    tar_deps.append(pdf_install)
+    tar_list.append(pdf_install)
+    Local(pdf_install)
+
+    ps_install = os.path.join(build, 'PS', 'scons-api.ps')
+    env.InstallAs(ps_install, api_ps)
+    tar_deps.append(ps_install)
+    tar_list.append(ps_install)
+    Local(ps_install)
+
 #
 # Now actually create the tar file of the documentation,
 # for easy distribution to the web site.
 #
 if tar_deps:
-    tar_list = string.join(map(lambda x: x[11:], tar_list))
+    tar_list = string.join(map(lambda x, b=build+'/': string.replace(x, b, ''),
+                           tar_list))
     env.Command(doc_tar_gz, tar_deps,
-                "tar cf${TAR_HFLAG} - -C build/doc %s | gzip > $TARGET" % tar_list)
+                "tar cf${TAR_HFLAG} - -C %s %s | gzip > $TARGET" % (build, tar_list))
     Local(doc_tar_gz)
 
 .ES
 import os
-env = Environment(ENV = os.environ['PATH'])
+env = Environment(ENV = os.environ)
 .EE
 
 This comes at the expense of making your build
 
 .TP
 --debug=time
-Prints various time profiling information: the time spent
-executing each build command, the total build time, the total time spent
-executing build commands, the total time spent executing SConstruct and
-SConscript files, and the total time spent executing SCons itself.
+Prints various time profiling information:
+the time spent executing each individual build command;
+the total build time (time SCons ran from beginning to end);
+the total time spent reading and executing SConscript files;
+the total time spent SCons itself spend running
+(that is, not counting reading and executing SConscript files);
+and both the total time spent executing all build commands
+and the elapsed wall-clock time spent executing those build commands.
+(When
+.B scons
+is executed without the
+.B -j
+option,
+the elapsed wall-clock time will typically
+be slightly longer than the total time spent
+executing all the build commands,
+due to the SCons processing that takes place
+in between executing each command.
+When
+.B scons
+is executed
+.I with
+the
+.B -j
+option,
+and your build configuration allows good parallelization,
+the elapsed wall-clock time should
+be significantly smaller than the
+total time spent executing all the build commands,
+since multiple build commands and
+intervening SCons processing
+should take place in parallel.)
 
 .TP
 --debug=tree
 or if a file really does exist
 where the SCons configuration expects a directory).
 
-.\" .TP
-.\" -e, --environment-overrides
-.\" Variables from the execution environment override construction
-.\" variables from the SConscript files.
-
-.TP
-.RI -f " file" ", --file=" file ", --makefile=" file ", --sconstruct=" file
-Use 
-.I file 
-as the initial SConscript file.
-
-.TP 
--h, --help
-Print a local help message for this build, if one is defined in
-the SConscript file(s), plus a line that describes the 
-.B -H
-option for command-line option help.  If no local help message
-is defined, prints the standard help message about command-line
-options.  Exits after displaying the appropriate message.
-
-.TP
--H, --help-options
-Print the standard help message about command-line options and
-exit.
-
-.TP
--i, --ignore-errors
-Ignore all errors from commands executed to rebuild files.
-
-.TP 
-.RI -I " directory" ", --include-dir=" directory
-Specifies a 
-.I directory
-to search for
-imported Python modules.  If several 
-.B -I
-options
-are used, the directories are searched in the order specified.
-
-.TP 
-.RI --no-site-dir
-Prevents the automatic addition of the standard
-.I site_scons
-dir to
-.IR sys.path .
-Also prevents loading the
-.I site_scons/site_init.py
-module if it exists, and prevents adding
-.I site_scons/site_tools
-to the toolpath.
-
-.TP
---implicit-cache
-Cache implicit dependencies. This can cause 
-.B scons
-to miss changes in the implicit dependencies in cases where a new implicit
-dependency is added earlier in the implicit dependency search path
-(e.g. CPPPATH) than a current implicit dependency with the same name.
-
-.TP
---implicit-deps-changed
-Force SCons to ignore the cached implicit dependencies. This causes the
-implicit dependencies to be rescanned and recached. This implies
-.BR --implicit-cache .
-
-.TP
---implicit-deps-unchanged
-Force SCons to ignore changes in the implicit dependencies.
-This causes cached implicit dependencies to always be used.
-This implies 
-.BR --implicit-cache .
-
-.TP
-.RI -j " N" ", --jobs=" N
-Specifies the number of jobs (commands) to run simultaneously.
-If there is more than one 
-.B -j 
-option, the last one is effective.
-.\" ??? If the 
-.\" .B -j 
-.\" option
-.\" is specified without an argument,
-.\" .B scons 
-.\" will not limit the number of
-.\" simultaneous jobs.
-
-.TP
--k, --keep-going
-Continue as much as possible after an error.  The target that
-failed and those that depend on it will not be remade, but other
-targets specified on the command line will still be processed.
-
-.\" .TP
-.\" .RI  -l " N" ", --load-average=" N ", --max-load=" N
-.\" No new jobs (commands) will be started if
-.\" there are other jobs running and the system load
-.\" average is at least 
-.\" .I N
-.\" (a floating-point number).
-
 .TP
 .RI --duplicate= ORDER
 There are three ways to duplicate files in a build tree: hard links,
 SCons will attempt to duplicate files using
 the mechanisms in the specified order.
 
+.\" .TP
+.\" -e, --environment-overrides
+.\" Variables from the execution environment override construction
+.\" variables from the SConscript files.
+
+.TP
+.RI -f " file" ", --file=" file ", --makefile=" file ", --sconstruct=" file
+Use 
+.I file 
+as the initial SConscript file.
+
+.TP 
+-h, --help
+Print a local help message for this build, if one is defined in
+the SConscript file(s), plus a line that describes the 
+.B -H
+option for command-line option help.  If no local help message
+is defined, prints the standard help message about command-line
+options.  Exits after displaying the appropriate message.
+
+.TP
+-H, --help-options
+Print the standard help message about command-line options and
+exit.
+
+.TP
+-i, --ignore-errors
+Ignore all errors from commands executed to rebuild files.
+
+.TP 
+.RI -I " directory" ", --include-dir=" directory
+Specifies a 
+.I directory
+to search for
+imported Python modules.  If several 
+.B -I
+options
+are used, the directories are searched in the order specified.
+
+.TP
+--implicit-cache
+Cache implicit dependencies.
+This causes
+.B scons
+to use the implicit (scanned) dependencies
+from the last time it was run
+instead of scanning the files for implicit dependencies.
+This can significantly speed up SCons,
+but with the following limitations:
+.IP
+.B scons
+will not detect changes to implicit dependency search paths
+(e.g.
+.BR CPPPATH ", " LIBPATH )
+that would ordinarily
+cause different versions of same-named files to be used.
+.IP
+.B scons
+will miss changes in the implicit dependencies
+in cases where a new implicit
+dependency is added earlier in the implicit dependency search path
+(e.g.
+.BR CPPPATH ", " LIBPATH )
+than a current implicit dependency with the same name.
+
+.TP
+--implicit-deps-changed
+Forces SCons to ignore the cached implicit dependencies. This causes the
+implicit dependencies to be rescanned and recached. This implies
+.BR --implicit-cache .
+
+.TP
+--implicit-deps-unchanged
+Force SCons to ignore changes in the implicit dependencies.
+This causes cached implicit dependencies to always be used.
+This implies 
+.BR --implicit-cache .
+
+.TP
+.RI -j " N" ", --jobs=" N
+Specifies the number of jobs (commands) to run simultaneously.
+If there is more than one 
+.B -j 
+option, the last one is effective.
+.\" ??? If the 
+.\" .B -j 
+.\" option
+.\" is specified without an argument,
+.\" .B scons 
+.\" will not limit the number of
+.\" simultaneous jobs.
+
+.TP
+-k, --keep-going
+Continue as much as possible after an error.  The target that
+failed and those that depend on it will not be remade, but other
+targets specified on the command line will still be processed.
+
+.\" .TP
+.\" .RI  -l " N" ", --load-average=" N ", --max-load=" N
+.\" No new jobs (commands) will be started if
+.\" there are other jobs running and the system load
+.\" average is at least 
+.\" .I N
+.\" (a floating-point number).
+
 .\"
 .\" .TP
 .\" --list-derived
 No execute.  Print the commands that would be executed to build
 any out-of-date target files, but do not execute the commands.
 
+.TP 
+.RI --no-site-dir
+Prevents the automatic addition of the standard
+.I site_scons
+dir to
+.IR sys.path .
+Also prevents loading the
+.I site_scons/site_init.py
+module if it exists, and prevents adding
+.I site_scons/site_tools
+to the toolpath.
+
 .\" .TP
 .\" .RI -o " file" ", --old-file=" file ", --assume-old=" file
 .\" Do not rebuild 
 method has been activated.
 The specified targets may be a list
 or an individual target.
-Multiple calls to
-.BR NoCache ()
-are legal,
-and prevent each specified target
-from being removed by calls to the
-.B -c
-option.
 
 Multiple files should be specified
 either as separate arguments to the
 
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
-.RI ParseDepends( filename ", [" must_exist ])
-.TP
-.RI env.ParseDepends( filename ", [" must_exist " " only_one ])
+.RI ParseDepends( filename ", [" must_exist ", " only_one ])
+.TP
+.RI env.ParseDepends( filename ", [" must_exist ", " only_one ])
 Parses the contents of the specified
 .I filename
 as a list of dependencies in the style of
 .I filename
 does not exist.
 The optional
-.I must_exit
+.I must_exist
 argument may be set to a non-zero
 value to have
 scons
 
 -->
 
+<!ENTITY config "<literal>--config</literal>">
 <!ENTITY debug-explain "<literal>--debug=explain</literal>">
+<!ENTITY debug-findlibs "<literal>--debug=findlibs</literal>">
+<!ENTITY debug-includes "<literal>--debug=includes</literal>">
+<!ENTITY debug-presub "<literal>--debug=presub</literal>">
+<!ENTITY debug-stacktrace "<literal>--debug=stacktrace</literal>">
 <!ENTITY implicit-cache "<literal>--implicit-cache</literal>">
 <!ENTITY implicit-deps-changed "<literal>--implicit-deps-changed</literal>">
 <!ENTITY implicit-deps-unchanged "<literal>--implicit-deps-unchanged</literal>">
+<!ENTITY profile "<literal>--profile</literal>">
+<!ENTITY taskmastertrace "<literal>--taskmastertrace</literal>">
+<!ENTITY tree "<literal>--tree</literal>">
 <!ENTITY Q "<literal>-Q</literal>">
 
 <!--
 -->
 
 <!ENTITY Add "<function>Add</function>">
+<!ENTITY AddPostAction "<function>AddPostAction</function>">
+<!ENTITY AddPreAction "<function>AddPreAction</function>">
 <!ENTITY AddOptions "<function>AddOptions</function>">
 <!ENTITY Alias "<function>Alias</function>">
 <!ENTITY Aliases "<function>Aliases</function>">
+<!ENTITY AlwaysBuild "<function>AlwaysBuild</function>">
 <!ENTITY Append "<function>Append</function>">
+<!ENTITY AppendENVPath "<function>AppendENVPath</function>">
+<!ENTITY AppendUnique "<function>AppendUnique</function>">
 <!ENTITY BoolOption "<function>BoolOption</function>">
 <!ENTITY Build "<function>Build</function>">
 <!ENTITY CacheDir "<function>CacheDir</function>">
 <!ENTITY Execute "<function>Execute</function>">
 <!ENTITY Export "<function>Export</function>">
 <!ENTITY File "<function>File</function>">
+<!ENTITY FindFile "<function>FindFile</function>">
 <!ENTITY Finish "<function>Finish</function>">
 <!ENTITY GenerateHelpText "<function>GenerateHelpText</function>">
 <!ENTITY GetOption "<function>GetOption</function>">
 <!ENTITY Module "<function>Module</function>">
 <!ENTITY Move "<function>Move</function>">
 <!ENTITY NoClean "<function>NoClean</function>">
+<!ENTITY NoCache "<function>NoCache</function>">
 <!ENTITY Objects "<function>Objects</function>">
 <!ENTITY Options "<function>Options</function>">
 <!ENTITY PackageOption "<function>PackageOption</function>">
 <!ENTITY PathOption_PathIsFile "<function>PathOption.PathIsFile</function>">
 <!ENTITY Precious "<function>Precious</function>">
 <!ENTITY Prepend "<function>Prepend</function>">
+<!ENTITY PrependENVPath "<function>PrependENVPath</function>">
+<!ENTITY PrependUnique "<function>PrependUnique</function>">
 <!ENTITY Replace "<function>Replace</function>">
 <!ENTITY Repository "<function>Repository</function>">
 <!ENTITY Return "<function>Return</function>">
 <!ENTITY Salt "<function>Salt</function>">
 <!ENTITY SetBuildSignatureType "<function>SetBuildSignatureType</function>">
 <!ENTITY SetContentSignatureType "<function>SetContentSignatureType</function>">
+<!ENTITY SideEffect "<function>SideEffect</function>">
 <!ENTITY SourceSignature "<function>SourceSignature</function>">
 <!ENTITY SourceSignatures "<function>SourceSignatures</function>">
 <!ENTITY Split "<function>Split</function>">

doc/user/MANIFEST

 caching.sgml
 command-line.sgml
 cons.pl
-cons.sgml
 copyright.sgml
 depends.sgml
 ENV.sgml

doc/user/builders-built-in.in

 
     &SCons; provides separate Builder objects
     to create static and shared object files.
-    The distinction becomes especially important when 
+    The distinction becomes especially important when
     archiving object files into different types of libraries.
 
     </para>
 
     <para>
 
-    XXX
+    XXX PCH()
 
     </para>
 
 
     <para>
 
-    XXX
+    XXX RES()
 
     </para>
 
 
       <para>
 
-      XXX
+      XXX CFile()
 
       </para>
 
       <programlisting>
-        XXX
+        XXX CFile() programlisting
       </programlisting>
 
       <screen>
-        XXX
+        XXX CFile() screen
       </screen>
 
     </section>
 
       <para>
 
-      XXX
+      XXX CXXFILE()
 
       </para>
 
       <programlisting>
-        XXX
+        XXX CXXFILE() programlisting
       </programlisting>
 
       <screen>
-        XXX
+        XXX CXXFILE() screen
       </screen>
 
     </section>
 
       <para>
 
-      XXX
+      XXX DVI() para
 
       </para>
 
       <programlisting>
-        XXX
+        XXX DVI() programlisting
       </programlisting>
 
       <screen>
-        XXX
+        XXX DVI() screen
       </screen>
 
     </section>
 
       <para>
 
-      XXX
+      XXX PDF() para
 
       </para>
 
 
       <para>
 
-      XXX
+      XXX PostScript() para
 
       </para>
 
       <programlisting>
-        XXX
+        XXX PostScript() programlisting
       </programlisting>
 
       <screen>
-        XXX
+        XXX PostScript() screen
       </screen>
 
     </section>
       </para>
 
       <screen>
-        XXX
+        XXX Java() screen
       </screen>
 
     </section>
 
       <para>
 
-      The &Jar; builder object XXX
+      XXX The &Jar; builder object
 
       </para>
 
       </programlisting>
 
       <screen>
-        XXX
+        XXX Jar() screen
       </screen>
 
     </section>
 
       <para>
 
-      XXX
+      XXX JavaH() para
 
       </para>
 
       <programlisting>
-        XXX
+        XXX JavaH() programlisting
       </programlisting>
 
       <screen>
-        XXX
+        XXX JavaH() screen
       </screen>
 
     </section>
 
       <para>
 
-      XXX
+      XXX RMIC() para
 
       </para>
 
       <programlisting>
-        XXX
+        XXX RMIC() programlisting
       </programlisting>
 
       <screen>
-        XXX
+        XXX RMIC() screen
       </screen>
 
     </section>

doc/user/builders-built-in.sgml

 
     &SCons; provides separate Builder objects
     to create static and shared object files.
-    The distinction becomes especially important when 
+    The distinction becomes especially important when
     archiving object files into different types of libraries.
 
     </para>
 
     <para>
 
-    XXX
+    XXX PCH()
 
     </para>
 
 
     <para>
 
-    XXX
+    XXX RES()
 
     </para>
 
 
       <para>
 
-      XXX
+      XXX CFile()
 
       </para>
 
       <programlisting>
-        XXX
+        XXX CFile() programlisting
       </programlisting>
 
       <screen>
-        XXX
+        XXX CFile() screen
       </screen>
 
     </section>
 
       <para>
 
-      XXX
+      XXX CXXFILE()
 
       </para>
 
       <programlisting>
-        XXX
+        XXX CXXFILE() programlisting
       </programlisting>
 
       <screen>
-        XXX
+        XXX CXXFILE() screen
       </screen>
 
     </section>
 
       <para>
 
-      XXX
+      XXX DVI() para
 
       </para>
 
       <programlisting>
-        XXX
+        XXX DVI() programlisting
       </programlisting>
 
       <screen>
-        XXX
+        XXX DVI() screen
       </screen>
 
     </section>
 
       <para>
 
-      XXX
+      XXX PDF() para
 
       </para>
 
 
       <para>
 
-      XXX
+      XXX PostScript() para
 
       </para>
 
       <programlisting>
-        XXX
+        XXX PostScript() programlisting
       </programlisting>
 
       <screen>
-        XXX
+        XXX PostScript() screen
       </screen>
 
     </section>
       </para>
 
       <screen>
-        XXX
+        XXX Java() screen
       </screen>
 
     </section>
 
       <para>
 
-      The &Jar; builder object XXX
+      XXX The &Jar; builder object
 
       </para>
 
       </programlisting>
 
       <screen>
-        XXX
+        XXX Jar() screen
       </screen>
 
     </section>
 
       <para>
 
-      XXX
+      XXX JavaH() para
 
       </para>
 
       <programlisting>
-        XXX
+        XXX JavaH() programlisting
       </programlisting>
 
       <screen>
-        XXX
+        XXX JavaH() screen
       </screen>
 
     </section>
 
       <para>
 
-      XXX
+      XXX RMIC() para
 
       </para>
 
       <programlisting>
-        XXX
+        XXX RMIC() programlisting
       </programlisting>
 
       <screen>
-        XXX
+        XXX RMIC() screen
       </screen>
 
     </section>

doc/user/builders-writing.in

       generator is being called to contribute to a build signature,
       as opposed to actually executing the command.
 
-      <!-- XXX NEED MORE HERE -->
+      <!-- XXX NEED MORE HERE, describe generators use in signatures -->
 
       </para>
       </listitem>
     </scons_output>
 
     <programlisting>
-       bld = Builder(action = 'XXX',
+       bld = Builder(action = 'my_command',
                      suffix = '.foo',
                      src_suffix = '.input',
                      emitter = 'MY_EMITTER')
 
     <para>
 
-    XXX
+    XXX para
 
     </para>
 
     <scons_example name="ex8">
        <file name="SConstruct" printme="1">
        env = Environment()
-       #env.SourceCode('.', env.BitKeeper('XXX'))
+       #env.SourceCode('.', env.BitKeeper('my_command'))
        env.Program('hello.c')
        </file>
        <file name="hello.c">

doc/user/builders-writing.sgml

       generator is being called to contribute to a build signature,
       as opposed to actually executing the command.
 
-      <!-- XXX NEED MORE HERE -->
+      <!-- XXX NEED MORE HERE, describe generators use in signatures -->
 
       </para>
       </listitem>
     </screen>
 
     <programlisting>
-       bld = Builder(action = 'XXX',
+       bld = Builder(action = 'my_command',
                      suffix = '.foo',
                      src_suffix = '.input',
                      emitter = 'MY_EMITTER')
 
     <para>
 
-    XXX
+    XXX para
 
     </para>
 
     <scons_example name="ex8">
        <file name="SConstruct" printme="1">
        env = Environment()
-       #env.SourceCode('.', env.BitKeeper('XXX'))
+       #env.SourceCode('.', env.BitKeeper('my_command'))
        env.Program('hello.c')
        </file>
        <file name="hello.c">

doc/user/caching.in

     every time a file is built,
     it is stored in the shared cache directory
     along with its MD5 build signature.
+      <footnote>
+      <para>
+      Actually, the MD5 signature is used as the name of the file
+      in the shared cache directory in which the contents are stored.
+      </para>
+      </footnote>
     On subsequent builds,
     before an action is invoked to build a file,
     &SCons; will check the shared cache directory
     <para>
 
     One potential drawback to using a shared cache
-    is that your build output can be inconsistent
-    from invocation to invocation,
+    is that the output printed by &SCons;
+    can be inconsistent from invocation to invocation,
     because any given file may be rebuilt one time
     and retrieved from the shared cache the next time.
     This can make analyzing build output more difficult,
   </section>
 
   <section>
-  <title>Not Retrieving Files From a Shared Cache</title>
+  <title>Not Using the Shared Cache for Specific Files</title>
+
+    <para>
+
+    You may want to disable caching for certain
+    specific files in your configuration.
+    For example, if you only want to put
+    executable files in a central cache,
+    but not the intermediate object files,
+    you can use the &NoCache;
+    function to specify that the
+    object files should not be cached:
+
+    </para>
+
+    <scons_example name="ex-NoCache">
+       <file name="SConstruct" printme="1">
+       env = Environment()
+       obj = env.Object('hello.c')
+       env.Program('hello.c')
+       CacheDir('cache')
+       NoCache('hello.o')
+       </file>
+       <file name="hello.c">
+       hello.c
+       </file>
+       <directory name="cache">
+       </directory>
+    </scons_example>
+
+    <para>
+
+    Then when you run &scons; after cleaning
+    the built targets,
+    it will recompile the object file locally
+    (since it doesn't exist in the shared cache directory),
+    but still realize that the shared cache directory
+    contains an up-to-date executable program
+    that can be retrieved instead of re-linking:
+
+    </para>
+
+    <!--
+
+    <scons_output example="ex1">
+      <scons_output_command>scons -Q</scons_output_command>
+      <scons_output_command>scons -Q -c</scons_output_command>
+      <scons_output_command>scons -Q</scons_output_command>
+    </scons_output>
+
+    -->
+
+    <screen>
+      % <userinput>scons -Q</userinput>
+      cc -o hello.o -c hello.c
+      cc -o hello hello.o
+      % <userinput>scons -Q -c</userinput>
+      Removed hello.o
+      Removed hello
+      % <userinput>scons -Q</userinput>
+      cc -o hello.o -c hello.c
+      Retrieved `hello' from cache
+    </screen>
+
+  </section>
+
+  <section>
+  <title>Disabling the Shared Cache</title>
 
     <para>
 
     In this case, you can use the
     the <literal>--cache-force</literal> option
     to tell &SCons; to put all derived files in the cache,
-    even if the files had already been built
-    by a previous invocation:
+    even if the files already exist in your local tree
+    from having been built by a previous invocation:
 
     </para>
 
       <scons_output_command>scons -Q -c</scons_output_command>
       <scons_output_command>scons -Q --cache-disable</scons_output_command>
       <scons_output_command>scons -Q --cache-force</scons_output_command>
-      <scons_output_command>scons -Q -c</scons_output_command>
       <scons_output_command>scons -Q</scons_output_command>
     </scons_output>
 
     demonstrates that the <literal>--cache-disable</literal>
     option avoids putting the built
     <filename>hello.o</filename>
-    and 
+    and
     <filename>hello</filename> files in the cache,
     but after using the <literal>--cache-force</literal> option,
     the files have been put in the cache
     </para>
 
   </section>
+
+  <section>
+  <title>Minimizing Cache Contention:  the <literal>--random</literal> Option</title>
+
+    <para>
+
+    If you allow multiple builds to update the
+    shared cache directory simultaneously,
+    two builds that occur at the same time
+    can sometimes start "racing"
+    with one another to build the same files
+    in the same order.
+    If, for example,
+    you are linking multiple files into an executable program:
+
+    </para>
+
+    <scons_example name="ex-random">
+       <file name="SConstruct" printme="1">
+       Program('prog',
+               ['f1.c', 'f2.c', 'f3.c', 'f4.c', 'f5.c'])
+       </file>
+       <file name="f1.c">f1.c</file>
+       <file name="f2.c">f2.c</file>
+       <file name="f3.c">f3.c</file>
+       <file name="f4.c">f4.c</file>
+       <file name="f5.c">f5.c</file>
+       <file name="f6.c">f6.c</file>
+    </scons_example>
+
+    <para>
+
+    &SCons; will normally build the input object files
+    on which the program depends in their normal, sorted order:
+
+    </para>
+
+    <scons_output example="ex-random">
+      <scons_output_command>scons -Q</scons_output_command>
+    </scons_output>
+
+    <para>
+
+    But if two such builds take place simultaneously,
+    they may each look in the cache at nearly the same
+    time and both decide that <filename>f1.o</filename>
+    must be rebuilt and pushed into the shared cache directory,
+    then both decide that <filename>f2.o</filename>
+    must be rebuilt (and pushed into the shared cache directory),
+    then both decide that <filename>f3.o</filename>
+    must be rebuilt...
+    This won't cause any actual build problems--both
+    builds will succeed,
+    generate correct output files,
+    and populate the cache--but
+    it does represent wasted effort.
+
+    </para>
+
+    <para>
+
+    To alleviate such contention for the cache,
+    you can use the <literal>--random</literal> command-line option
+    to tell &SCons; to build dependencies
+    in a random order:
+
+    </para>
+
+    <!--
+
+    The following <screen> output was generated by this:
+
+    <scons_output example="ex-random">
+      <scons_output_command>scons -Q - -random</scons_output_command>
+    </scons_output>
+
+    We captured it directly here to guarantee a "random" order,
+    guarding against the potential for - -random to happen
+    to return things in the original sorted order.
+
+    -->
+
+    <screen>
+      % <userinput>scons -Q --random</userinput>
+      cc -o f3.o -c f3.c
+      cc -o f1.o -c f1.c
+      cc -o f5.o -c f5.c
+      cc -o f2.o -c f2.c
+      cc -o f4.o -c f4.c
+      cc -o prog f1.o f2.o f3.o f4.o f5.o
+    </screen>
+
+    <para>
+
+    Multiple builds using the <literal>--random</literal> option
+    will usually build their dependencies in different,
+    random orders,
+    which minimizes the chances for a lot of
+    contention for same-named files
+    in the shared cache directory.
+    Multiple simultaneous builds might still race to try to build
+    the same target file on occasion,
+    but long sequences of inefficient contention
+    should be rare.
+
+    </para>
+
+    <para>
+
+    Note, of course,
+    the <literal>--random</literal> option
+    will cause the output that &SCons; prints
+    to be inconsistent from invocation to invocation,
+    which may be an issue when
+    trying to compare output from different build runs.
+
+    </para>
+
+  </section>
+
+  <!--
+
+  <section>
+  <title>Troubleshooting Shared Caching:  the &cache-debug; Option</title>
+
+    <para>
+
+    XXX describe the - - cache-debug option
+    XXX maybe point to the troubleshooting appendix?
+
+    </para>
+
+  </section>
+
+  -->
+
+  <!--
+
+  <section>
+
+    <para>
+
+    XXX describe CacheDir management:  monitoring, deleting, etc.
+
+    </para>
+
+  </section>
+
+  -->

doc/user/caching.sgml

     every time a file is built,
     it is stored in the shared cache directory
     along with its MD5 build signature.
+      <footnote>
+      <para>
+      Actually, the MD5 signature is used as the name of the file
+      in the shared cache directory in which the contents are stored.
+      </para>
+      </footnote>
     On subsequent builds,
     before an action is invoked to build a file,
     &SCons; will check the shared cache directory
     <para>
 
     One potential drawback to using a shared cache
-    is that your build output can be inconsistent
-    from invocation to invocation,
+    is that the output printed by &SCons;
+    can be inconsistent from invocation to invocation,
     because any given file may be rebuilt one time
     and retrieved from the shared cache the next time.
     This can make analyzing build output more difficult,
   </section>
 
   <section>
-  <title>Not Retrieving Files From a Shared Cache</title>
+  <title>Not Using the Shared Cache for Specific Files</title>
+
+    <para>
+
+    You may want to disable caching for certain
+    specific files in your configuration.
+    For example, if you only want to put
+    executable files in a central cache,
+    but not the intermediate object files,
+    you can use the &NoCache;
+    function to specify that the
+    object files should not be cached:
+
+    </para>
+
+    <programlisting>
+       env = Environment()
+       obj = env.Object('hello.c')
+       env.Program('hello.c')
+       CacheDir('cache')
+       NoCache('hello.o')
+    </programlisting>
+
+    <para>
+
+    Then when you run &scons; after cleaning
+    the built targets,
+    it will recompile the object file locally
+    (since it doesn't exist in the shared cache directory),
+    but still realize that the shared cache directory
+    contains an up-to-date executable program
+    that can be retrieved instead of re-linking:
+
+    </para>
+
+    <!--
+
+    <scons_output example="ex1">
+      <scons_output_command>scons -Q</scons_output_command>
+      <scons_output_command>scons -Q -c</scons_output_command>
+      <scons_output_command>scons -Q</scons_output_command>
+    </scons_output>
+
+    -->
+
+    <screen>
+      % <userinput>scons -Q</userinput>
+      cc -o hello.o -c hello.c
+      cc -o hello hello.o
+      % <userinput>scons -Q -c</userinput>
+      Removed hello.o
+      Removed hello
+      % <userinput>scons -Q</userinput>
+      cc -o hello.o -c hello.c
+      Retrieved `hello' from cache
+    </screen>
+
+  </section>
+
+  <section>
+  <title>Disabling the Shared Cache</title>
 
     <para>
 
     In this case, you can use the
     the <literal>--cache-force</literal> option
     to tell &SCons; to put all derived files in the cache,
-    even if the files had already been built
-    by a previous invocation:
+    even if the files already exist in your local tree
+    from having been built by a previous invocation:
 
     </para>
 
       cc -o hello hello.o
       % <userinput>scons -Q --cache-force</userinput>
       scons: `.' is up to date.
-      % <userinput>scons -Q -c</userinput>
-      Removed hello.o
-      Removed hello
       % <userinput>scons -Q</userinput>
-      Retrieved `hello.o' from cache
-      Retrieved `hello' from cache
+      scons: `.' is up to date.
     </screen>
 
     <para>
     demonstrates that the <literal>--cache-disable</literal>
     option avoids putting the built
     <filename>hello.o</filename>
-    and 
+    and
     <filename>hello</filename> files in the cache,
     but after using the <literal>--cache-force</literal> option,
     the files have been put in the cache
     </para>
 
   </section>
+
+  <section>
+  <title>Minimizing Cache Contention:  the <literal>--random</literal> Option</title>
+
+    <para>
+
+    If you allow multiple builds to update the
+    shared cache directory simultaneously,
+    two builds that occur at the same time
+    can sometimes start "racing"
+    with one another to build the same files
+    in the same order.
+    If, for example,
+    you are linking multiple files into an executable program:
+
+    </para>
+
+    <programlisting>
+       Program('prog',
+               ['f1.c', 'f2.c', 'f3.c', 'f4.c', 'f5.c'])
+    </programlisting>
+
+    <para>
+
+    &SCons; will normally build the input object files
+    on which the program depends in their normal, sorted order:
+
+    </para>
+
+    <screen>
+      % <userinput>scons -Q</userinput>
+      cc -o f1.o -c f1.c
+      cc -o f2.o -c f2.c
+      cc -o f3.o -c f3.c
+      cc -o f4.o -c f4.c
+      cc -o f5.o -c f5.c
+      cc -o prog f1.o f2.o f3.o f4.o f5.o
+    </screen>
+
+    <para>
+
+    But if two such builds take place simultaneously,
+    they may each look in the cache at nearly the same
+    time and both decide that <filename>f1.o</filename>
+    must be rebuilt and pushed into the shared cache directory,
+    then both decide that <filename>f2.o</filename>
+    must be rebuilt (and pushed into the shared cache directory),
+    then both decide that <filename>f3.o</filename>
+    must be rebuilt...
+    This won't cause any actual build problems--both
+    builds will succeed,
+    generate correct output files,
+    and populate the cache--but
+    it does represent wasted effort.
+
+    </para>
+
+    <para>
+
+    To alleviate such contention for the cache,
+    you can use the <literal>--random</literal> command-line option
+    to tell &SCons; to build dependencies
+    in a random order:
+
+    </para>
+
+    <!--
+
+    The following <screen> output was generated by this:
+
+    <scons_output example="ex-random">
+      <scons_output_command>scons -Q - -random</scons_output_command>
+    </scons_output>
+
+    We captured it directly here to guarantee a "random" order,
+    guarding against the potential for - -random to happen
+    to return things in the original sorted order.
+
+    -->
+
+    <screen>
+      % <userinput>scons -Q --random</userinput>
+      cc -o f3.o -c f3.c
+      cc -o f1.o -c f1.c
+      cc -o f5.o -c f5.c
+      cc -o f2.o -c f2.c
+      cc -o f4.o -c f4.c
+      cc -o prog f1.o f2.o f3.o f4.o f5.o
+    </screen>
+
+    <para>
+
+    Multiple builds using the <literal>--random</literal> option
+    will usually build their dependencies in different,
+    random orders,
+    which minimizes the chances for a lot of
+    contention for same-named files
+    in the shared cache directory.
+    Multiple simultaneous builds might still race to try to build
+    the same target file on occasion,
+    but long sequences of inefficient contention
+    should be rare.
+
+    </para>
+
+    <para>
+
+    Note, of course,
+    the <literal>--random</literal> option
+    will cause the output that &SCons; prints
+    to be inconsistent from invocation to invocation,
+    which may be an issue when
+    trying to compare output from different build runs.
+
+    </para>
+
+  </section>
+
+  <!--
+
+  <section>
+  <title>Troubleshooting Shared Caching:  the &cache-debug; Option</title>
+
+    <para>
+
+    XXX describe the - - cache-debug option
+    XXX maybe point to the troubleshooting appendix?
+
+    </para>
+
+  </section>
+
+  -->
+
+  <!--
+
+  <section>
+
+    <para>
+
+    XXX describe CacheDir management:  monitoring, deleting, etc.
+
+    </para>
+
+  </section>
+
+  -->

doc/user/command-line.sgml

 
     <screen>
       % <userinput>scons -Q</userinput>
-      cc -o bar.o -c -D['RELEASE_BUILD=', 1] bar.c
-      cc -o foo.o -c -D['RELEASE_BUILD=', 1] foo.c
+      cc -o bar.o -c -DRELEASE_BUILD=1 bar.c
+      cc -o foo.o -c -DRELEASE_BUILD=1 foo.c
       cc -o foo foo.o bar.o
     </screen>
 
 
     <screen>
       % <userinput>scons -Q</userinput>
-      cc -o bar.o -c -D['RELEASE_BUILD=', 0] bar.c
-      cc -o foo.o -c -D['RELEASE_BUILD=', 0] foo.c
+      cc -o bar.o -c -DRELEASE_BUILD=0 bar.c
+      cc -o foo.o -c -DRELEASE_BUILD=0 foo.c
       cc -o foo foo.o bar.o
     </screen>
 
 
       <screen>
         % <userinput>scons -Q RELEASE=yes foo.o</userinput>
-        cc -o foo.o -c -D['RELEASE_BUILD=', True] foo.c
+        cc -o foo.o -c -DRELEASE_BUILD=True foo.c
       </screen>
 
       <screen>
         % <userinput>scons -Q RELEASE=t foo.o</userinput>
-        cc -o foo.o -c -D['RELEASE_BUILD=', True] foo.c
+        cc -o foo.o -c -DRELEASE_BUILD=True foo.c
       </screen>
 
       <para>
 
       <screen>
         % <userinput>scons -Q RELEASE=no foo.o</userinput>
-        cc -o foo.o -c -D['RELEASE_BUILD=', False] foo.c
+        cc -o foo.o -c -DRELEASE_BUILD=False foo.c
       </screen>
 
       <screen>
         % <userinput>scons -Q RELEASE=f foo.o</userinput>
-        cc -o foo.o -c -D['RELEASE_BUILD=', False] foo.c
+        cc -o foo.o -c -DRELEASE_BUILD=False foo.c
       </screen>
 
       <para>
         % <userinput>scons -Q PACKAGE=/usr/local/location foo.o</userinput>
         cc -o foo.o -c -DPACKAGE="/usr/local/location" foo.c
         % <userinput>scons -Q PACKAGE=yes foo.o</userinput>
-        cc -o foo.o -c -D['PACKAGE="', True, '"'] foo.c
+        cc -o foo.o -c -DPACKAGE="True" foo.c
         % <userinput>scons -Q PACKAGE=no foo.o</userinput>
-        cc -o foo.o -c -D['PACKAGE="', False, '"'] foo.c
+        cc -o foo.o -c -DPACKAGE="False" foo.c
       </screen>
 
     </section>

doc/user/cons.in

-<!--
-
-  __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>
-
-   XXX
-
- </para>
-
- <section>
- <title>Differences Between &Cons; and &SCons;</title>
-
-   <para>
-
-   XXX
-
-   </para>
-
- </section>
-
- <section>
- <title>Advantages of &SCons; Over &Cons;</title>
-
-   <para>
-
-   XXX
-
-   </para>
-
- </section>

doc/user/cons.sgml

-<!--
-
-  __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>
-
-   XXX
-
- </para>
-
- <section>
- <title>Differences Between &Cons; and &SCons;</title>
-
-   <para>
-
-   XXX
-
-   </para>
-
- </section>
-
- <section>
- <title>Advantages of &SCons; Over &Cons;</title>
-
-   <para>
-
-   XXX
-
-   </para>