Updates to README from W. Trevor King

2 files changed, 99 insertions, 98 deletions

diff --git a/README b/README
index faa48dd..d8fa7b5 100644
--- a/README
+++ b/README
@@ -70,6 +70,43 @@ INSTALLATION REQUIREMENTS
 Nothing special.
 
 
+EXECUTING SCONS WITHOUT INSTALLING
+==================================
+
+You can execute the local SCons directly from the src/ subdirectory by
+first setting the SCONS_LIB_DIR environment variable to the local
+src/engine subdirectory, and then executing the local src/script/scons.py
+script to populate the build/scons/ subdirectory.  You would do this as
+follows on a Linux or UNIX system (using sh or a derivative like bash or
+ksh):
+
+        $ setenv MYSCONS=`pwd`/src
+        $ setenv SCONS_LIB_DIR=$MYSCONS/engine
+        $ python $MYSCONS/script/scons.py [arguments]
+
+Or on Windows:
+
+        C:\scons>set MYSCONS=%cd%\src
+        C:\scons>set SCONS_LIB_DIR=%MYSCONS%\engine
+        C:\scons>python %MYSCONS%\script\scons.py [arguments]
+
+An alternative approach is to skip the above and use:
+
+        $ python bootstrap.py [arguments]
+
+bootstrap.py keeps the src/ subdirectory free of compiled Python (*.pyc or
+*.pyo) files by copying the necessary SCons files to a local bootstrap/
+subdirectory and executing it from there.
+
+You can use the -C option to have SCons change directory to another
+location where you already have a build configuration set up.
+
+    $ python bootstrap.py -C /some/other/location [arguments]
+
+For simplicity in the following examples, we will only show the
+bootstrap.py approach.
+
+
 INSTALLATION
 ============
 
@@ -87,34 +124,25 @@ the build/scons/ subdirectory.  (For an easier way to install SCons,
 without having to populate this directory, use the scons-{version}.tar.gz
 or scons-{version}.zip package.)
 
+Populate build/scons/ using a pre-installed SCons
+-------------------------------------------------
+
 If you already have an appropriate version of SCons installed on your
 system, populate the build/scons/ directory by running:
 
         $ scons build/scons
 
+Populate build/scons/ using the SCons source
+--------------------------------------------
+
 You can also use this version of SCons to populate its own build directory
-by using a supplied bootstrap.py script:
+by using a supplied bootstrap.py script (see the section above about
+EXECUTING SCONS WITHOUT INSTALLING):
 
         $ python bootstrap.py build/scons
 
-The bootstrap.py keeps the src/ subdirectory free of compiled Python
-(*.pyc or *.pyo) files by copying the necessary SCons files to a local
-bootstrap/ subdirectory and executing it from there.
-
-You can also execute the local SCons directly from the src/ subdirectory
-by first setting the SCONS_LIB_DIR environment variable to the local
-src/engine subdirectory, and then executing the local src/script/scons.py
-script to populate the build/scons/ subdirectory.  You would do this as
-follows on a Linux or UNIX system (using sh or a derivative like bash
-or ksh):
-
-        $ export SCONS_LIB_DIR=`pwd`/src/engine
-        $ python src/script/scons.py build/scons
-
-Or as follows on Windows:
-        
-        C:\scons\>set SCONS_LIB_DIR=%cd%\src\engine
-        C:\scons\>python src\script\scons.py build/scons
+Install the built SCons files
+-----------------------------
 
 Any of the above commands will populate the build/scons/ directory with
 the necessary files and directory structure to use the Python-standard
@@ -123,7 +151,7 @@ setup script as follows on Linux or UNIX:
         # cd build/scons
         # python setup.py install
 
-And on Windows:
+Or on Windows:
 
         C:\scons\>cd build\scons
         C:\scons\build\scons>python setup.py install
@@ -218,36 +246,15 @@ modules that make up SCons.  The src/script/scons.py wrapper script exists
 mainly to find the appropriate build engine library and then execute it.
 
 In order to make your own changes locally and test them by hand, simply
-edit modules in the local src/engine/SCons subdirectory tree and either
-use the local bootstrap.py script:
+edit modules in the local src/engine/SCons subdirectory tree and use the
+local bootstrap.py script (see the section above about EXECUTING SCONS
+WITHOUT INSTALLING):
 
     $ python bootstrap.py [arguments]
 
-Or set the SCONS_LIB_DIR to point to the src/engine/SCons directory and
-then execute the src/script/scons.py script.  Here is one way you can
-set up environment variables to do this on a UNIX or Linux system:
-
-    $ setenv MYSCONS=`pwd`/src
-    $ setenv SCONS_LIB_DIR=$MYSCONS/engine
-    $ python $MYSCONS/script/scons.py [arguments]
-
-Or on Windows:
-
-    C:\scons>set MYSCONS=%cd%\src
-    C:\scons>set SCONS_LIB_DIR=%MYSCONS%\engine
-    C:\scons>python %MYSCONS%\script\scons.py [arguments]
-
-You can use the -C option to have SCons change directory to another
-location where you already have a build configuration set up (for example,
-if the SCons configuration for your project seems to be blocked by
-an SCons bug, and you want to see if a patch you make actually fixes
-that bug):
-
-    $ python bootstrap.py -C /some/other/location [arguments]
-
-Lastly, if you want to be able to just execute your modified version
-of SCons from the command line, you can make it executable and add its
-directory to your $PATH like so:
+If you want to be able to just execute your modified version of SCons from
+the command line, you can make it executable and add its directory to your
+$PATH like so:
 
     $ chmod 755 src/script/scons.py
     $ export PATH=$PATH:`pwd`/src/script
@@ -394,36 +401,37 @@ an SCons bug, and you decide you want to fix it and submit the patch.
 Here's one possible way to go about doing that (using UNIX/Linux as the
 development platform, Windows users can translate as appropriate)):
 
-    --  Change to the top of your checked-out SCons tree and set
-        $SCONS_LIB_DIR to point to its build engine:
-
-            $ setenv SCONS_LIB_DIR=`pwd`/src
+    --  Change to the top of your checked-out SCons tree.
 
     --  Confirm that the bug still exists in this version of SCons
         by using the -C option to run the broken build:
 
-            $ python script/scons.py -C /home/me/broken_project .
+            $ python bootstrap.py -C /home/me/broken_project .
 
     --  Fix the bug in SCons by editing appropriate module files
         underneath src/engine/SCons.
 
     --  Confirm that you've fixed the bug affecting your project:
 
-            $ python script/scons.py -C /home/me/broken_project .
+            $ python bootstrap.py -C /home/me/broken_project .
 
     --  Test to see if your fix had any unintended side effects
         that break existing functionality:
 
-            $ python runtest.py -a
+            $ python runtest.py -a -o test.log
 
         Be patient, there are more than 700 test scripts in the
-        whole suite.
+        whole suite.  If you are on UNIX/Linux, you can use:
+
+            $ python runtest.py -a | tee test.log
+
+        instead so you can monitor progress from your terminal.
 
         If any test scripts fail, they will be listed in a summary at
-        the end of the run.  Some test scripts may also report NO RESULT
-        because (for example) your local system is the wrong type or
-        doesn't have some installed utilities necessary to run the
-        script.  In general, you can ignore the NO RESULT list.
+        the end of the log file.  Some test scripts may also report
+        NO RESULT because (for example) your local system is the wrong
+        type or doesn't have some installed utilities necessary to run
+        the script.  In general, you can ignore the NO RESULT list.
 
     --  Cut-and-paste the list of failed tests into a file:
 
@@ -453,8 +461,8 @@ development platform, Windows users can translate as appropriate)):
         you originally put in, and didn't introduce any *additional*
         unintended side effects that broke other tests:
 
-            $ python script/scons.py -C /home/me/broken_project .
-            $ python runtest.py -a
+            $ python bootstrap.py -C /home/me/broken_project .
+            $ python runtest.py -a -o test.log
 
         If you find any newly-broken tests, add them to your "failed.txt"
         file and go back to the previous step.
@@ -476,25 +484,11 @@ you can build everything by simply running it:
         $ scons
 
 If you don't have SCons version 0.96.93 later already installed on your
-system, you can use the supplied bootstrap.py script:
+system, you can use the supplied bootstrap.py script (see the section
+above about EXECUTING SCONS WITHOUT INSTALLING):
 
         $ python bootstrap.py build/scons
 
-The bootstrap.py keeps the src/ subdirectory free of compiled Python
-(*.pyc or *.pyo) files by copying the necessary SCons files to a local
-bootstrap/ subdirectory and executing it from there.
-
-You can also build this version of SCons by hand with a little more
-typing.  On UNIX or Linux (using sh or a derivative like bash or ksh):
-
-        $ export SCONS_LIB_DIR=`pwd`/src/engine
-        $ python src/script/scons.py
-
-On Windows:
-        
-        C:\scons\>set SCONS_LIB_DIR=%cd%\src\engine
-        C:\scons\>python src/script/scons.py
-
 Depending on the utilities installed on your system, any or all of the
 following packages will be built:
 
@@ -788,4 +782,3 @@ With plenty of help from the SCons Development team:
         Anthony Roach
         Greg Spencer
         Christoph Wiedemann
-
diff --git a/src/CHANGES.txt b/src/CHANGES.txt
index e1e2724..7b5805d 100644
--- a/src/CHANGES.txt
+++ b/src/CHANGES.txt
@@ -13,6 +13,10 @@ RELEASE 2.0.0.alpha.20100508 - Sat, 08 May 2010 14:29:17 -0700
 
     - Fix XML in documentation.
 
+  From W. Trevor King:
+
+    - Revisions to README.
+
   From Steven Knight:
 
     - Provide forward compatibility for the 'profile' module.
@@ -35,6 +39,10 @@ RELEASE 2.0.0.alpha.20100508 - Sat, 08 May 2010 14:29:17 -0700
 
     - Add a '-3' option to runtest to print 3.x incompatibility warnings.
 
+    - Convert most old-style classes into new-style classes.
+
+    - Update deprecation warnings; most now become errors.
+
   From Greg Noel:
 
     - Apply numerous Python fixers to update code to more modern idioms.
@@ -129,7 +137,7 @@ RELEASE 1.2.0.d20100117 - Sun, 17 Jan 2010 14:26:59 -0800
   From William Deegan:
     - Final merge from vs_revamp branch to main
 
-    - Added definition and usage of HOST_OS, HOST_ARCH, TARGET_OS, 
+    - Added definition and usage of HOST_OS, HOST_ARCH, TARGET_OS,
       TARGET_ARCH, currently only defined/used by Visual Studio
       Compilers. This will be rolled out to other platforms/tools
       in the future.
@@ -160,7 +168,7 @@ RELEASE 1.2.0.d20100117 - Sun, 17 Jan 2010 14:26:59 -0800
 
     - Avoid adding -gphobos to a command line multiple times
       when initializing use of the DMD compiler.
-  
+
   From Jason Kenney:
 
     - Sugguested HOST/TARGET OS/ARCH separation.
@@ -212,7 +220,7 @@ RELEASE 1.2.0.d20100117 - Sun, 17 Jan 2010 14:26:59 -0800
       use the output to find files TeX creates. This allows the MiKTeX
       installations to find the created files
 
-    - Notify user of Latex errors that would get buried in the 
+    - Notify user of Latex errors that would get buried in the
       Latex output
 
     - Remove LATEXSUFFIXES from environments that don't initialize Tex.
@@ -220,8 +228,8 @@ RELEASE 1.2.0.d20100117 - Sun, 17 Jan 2010 14:26:59 -0800
     - Add support for the glosaaries package for glossaries and acronyms
 
     - Fix problem that pdftex, latex, and pdflatex tools by themselves did
-      not create the actions for bibtex, makeindex,... by creating them 
-      and other environment settings in one routine called by all four 
+      not create the actions for bibtex, makeindex,... by creating them
+      and other environment settings in one routine called by all four
       tex tools.
 
     - Fix problem with filenames of sideeffects when the user changes
@@ -524,7 +532,7 @@ RELEASE 1.1.0 - Thu, 09 Oct 2008 08:33:47 -0700
     - Add CheckCC, CheckCXX, CheckSHCC and CheckSHCXX tests to
       configuration contexts.
 
-    - Have the --profile= argument use the much faster cProfile module 
+    - Have the --profile= argument use the much faster cProfile module
       (if it's available in the running Python version).
 
     - Reorder MSVC compilation arguments so the /Fo is first.
@@ -689,7 +697,7 @@ RELEASE 1.0.0 - XXX
 
     - In RPCGEN tests, ignore stderr messages from older versions of
       rpcgen on some versions of Mac OS X.
-   
+
     - Fix typos in man page descriptions of Tag() and Package(), and in
       the scons-time man page.
 
@@ -735,7 +743,7 @@ RELEASE 1.0.0 - Sat, 09 Aug 2008 12:19:44 -0700
           object, its UnknownOptions() method, and its associated
           BoolVariable(), EnumVariable(), ListVariable(), PackageVariable()
           and PathVariable() functions.
-          
+
        -  Document the Progress() function.
 
        -  Reorganize the chapter and sections describing the different
@@ -1420,7 +1428,7 @@ RELEASE 0.97.0d20070809 - Fri, 10 Aug 2007 10:51:27 -0500
 
   - Fix expansion of $TARGET, $TARGETS, $SOURCE and $SOURCES keywords in
     Visual C/C++ PDB file names.
-    
+
   - Fix locating Visual C/C++ PDB files in build directories.
 
   - Support an env.AddMethod() method and an AddMethod() global function
@@ -1719,7 +1727,7 @@ RELEASE 0.96.94 - Sun, 07 Jan 2007 18:36:20 -0600
 
   From Paul:
 
-  - When compiling resources under MinGW, make sure there's a space 
+  - When compiling resources under MinGW, make sure there's a space
     between the --include-dir option and its argument.
 
   From Jay Kint:
@@ -1995,7 +2003,7 @@ RELEASE 0.96.93 - Mon, 06 Nov 2006 00:44:11 -0600
 
   - Add an env.ParseFlags() method that provides separate logic for
     parsing GNU tool chain flags into a dictionary.
-    
+
   - Add an env.MergeFlags() method to apply an arbitrary dictionary
     of flags to a construction environment's variables.
 
@@ -2040,7 +2048,7 @@ RELEASE 0.96.93 - Mon, 06 Nov 2006 00:44:11 -0600
 
   From Dobes Vandermeer:
 
-  - Let the src_dir option to the SConscript() function affect all the 
+  - Let the src_dir option to the SConscript() function affect all the
     the source file paths, instead of treating all source files paths
     as relative to the SConscript directory itself.
 
@@ -4252,7 +4260,7 @@ RELEASE 0.12 - Thu, 27 Mar 2003 23:52:09 -0600
 
   - Change the documentation to correctly describe that the -f option
     doesn't change to the directory in which the specified file lives.
-    
+
   - Support changing directories locally with SConscript directory
     path names relative to any SConstruct file specified with -f.
     This allows you to build in another directory by simply changing
@@ -4628,7 +4636,7 @@ RELEASE 0.08 - Mon, 15 Jul 2002 12:08:51 -0500
 
   - Removed the "shared" keyword argument from the Object and
     Library builders.
-    
+
   - Added separated StaticObject, SharedObject, StaticLibrary and
     SharedLibrary builders.  Made Object and Library synonyms for
     StaticObject and StaticLibrary, respectively.
@@ -4903,7 +4911,7 @@ RELEASE 0.07 - Thu,  2 May 2002 13:37:16 -0500
   - Fix so that Nodes can be passed to SConscript files.
 
   From Moshe Zadka:
-  
+
   - Changes for official Debian packaging.
 
 
@@ -4970,7 +4978,7 @@ RELEASE 0.06 - Thu, 28 Mar 2002 01:24:29 -0600
   From Anthony Roach:
 
   - Fix:  Construction variables with values of 0 were incorrectly
-    interpolated as ''. 
+    interpolated as ''.
 
   - Support env['VAR'] to fetch construction variable values.
 
@@ -5189,15 +5197,15 @@ RELEASE 0.03 - Fri, 11 Jan 2002 01:09:30 -0600
 
   - Fetch the location of the Microsoft Visual C++ compiler(s) from
     the Registry, instead of hard-coding the location.
-    
+
   - Made Scanner objects take Nodes, not path names.
-    
+
   - Have the C Scanner cache the #include file names instead of
     (re-)scanning the file each time it's called.
 
   - Created a separate class for parent "nodes" of file system roots,
     eliminating the need for separate is-parent-null checks everywhere.
-    
+
   - Removed defined __hash__() and __cmp() methods from FS.Entry, in
     favor of Python's more efficient built-in identity comparisons.
 
@@ -5243,7 +5251,7 @@ RELEASE 0.02 - Sun, 23 Dec 2001 19:05:09 -0600
   - Made Default() accept Nodes as arguments.
 
   - Changed Export() to make it easier to use.
-  
+
   - Added the Import() and Return() methods.