Update various OS X README files for 3.3.0.

4 files changed, 163 insertions, 59 deletions

diff --git a/Mac/BuildScript/README.txt b/Mac/BuildScript/README.txt
index de2f5cb..fa04b97 100644
--- a/Mac/BuildScript/README.txt
+++ b/Mac/BuildScript/README.txt
@@ -8,70 +8,125 @@ $DESTROOT, massages that installation to remove .pyc files and such, creates
 an Installer package from the installation plus other files in ``resources`` 
 and ``scripts`` and placed that on a ``.dmg`` disk image.
 
-As of Python 2.7.x and 3.2, PSF practice is to build two installer variants
-for each release:
+As of Python 3.3.0, PSF practice is to build two installer variants
+for each release.
 
 1.  32-bit-only, i386 and PPC universal, capable on running on all machines
-    supported by Mac OS X 10.3.9 through (at least) 10.6::
+    supported by Mac OS X 10.5 through (at least) 10.8::
 
-        python build-installer.py \
-            --sdk-path=/Developer/SDKs/MacOSX10.4u.sdk \
+        /usr/bin/python build-installer.py \
+            --sdk-path=/Developer/SDKs/MacOSX10.5.sdk \
             --universal-archs=32-bit \
-            --dep-target=10.3 
-            # These are the current default options
+            --dep-target=10.5
 
     - builds the following third-party libraries
 
-        * Bzip2
-        * Zlib 1.2.3
-        * GNU Readline (GPL)
-        * SQLite 3
-        * NCurses
-        * Oracle Sleepycat DB 4.8 (Python 2.x only)
+        * NCurses 5.9 (http://bugs.python.org/issue15037)
+        * SQLite 3.7.13
+        * XZ 5.0.3
+
+    - uses system-supplied versions of third-party libraries
+
+        * readline module links with Apple BSD editline (libedit)
 
     - requires ActiveState ``Tcl/Tk 8.4`` (currently 8.4.19) to be installed for building
 
-    - current target build environment:
-        
-        * Mac OS X 10.5.8 PPC or Intel
-        * Xcode 3.1.4 (or later)
-        * ``MacOSX10.4u`` SDK (later SDKs do not support PPC G3 processors)
-        * ``MACOSX_DEPLOYMENT_TARGET=10.3``
-        * Apple ``gcc-4.0``
-        * Python 2.n (n >= 4) for documentation build with Sphinx
+    - recommended build environment:
+
+        * Mac OS X 10.5.8 Intel or PPC
+        * Xcode 3.1.4
+        * ``MacOSX10.5`` SDK
+        * ``MACOSX_DEPLOYMENT_TARGET=10.5``
+        * Apple ``gcc-4.2``
+        * system Python 2.5 for documentation build with Sphinx
 
     - alternate build environments:
 
-        * Mac OS X 10.4.11 with Xcode 2.5
-        * Mac OS X 10.6.6 with Xcode 3.2.5
+        * Mac OS X 10.6.8 with Xcode 3.2.6
             - need to change ``/System/Library/Frameworks/{Tcl,Tk}.framework/Version/Current`` to ``8.4``
+        * Note Xcode 4.* does not support building for PPC so cannot be used for this build
 
 2.  64-bit / 32-bit, x86_64 and i386 universal, for OS X 10.6 (and later)::
 
-        python build-installer.py \
+        /usr/bin/python build-installer.py \
             --sdk-path=/Developer/SDKs/MacOSX10.6.sdk \
             --universal-archs=intel \
             --dep-target=10.6
 
+    - builds the following third-party libraries
+
+        * NCurses 5.9 (http://bugs.python.org/issue15037)
+        * SQLite 3.7.13
+        * XZ 5.0.3
+
     - uses system-supplied versions of third-party libraries
-    
+
         * readline module links with Apple BSD editline (libedit)
-        * builds Oracle Sleepycat DB 4.8 (Python 2.x only)
 
     - requires ActiveState Tcl/Tk 8.5.9 (or later) to be installed for building
 
-    - current target build environment:
-        
-        * Mac OS X 10.6.6 (or later)
-        * Xcode 3.2.5 (or later)
+    - recommended build environment:
+
+        * Mac OS X 10.6.8 (or later)
+        * Xcode 3.2.6
         * ``MacOSX10.6`` SDK
         * ``MACOSX_DEPLOYMENT_TARGET=10.6``
         * Apple ``gcc-4.2``
-        * Python 2.n (n >= 4) for documentation build with Sphinx
+        * system Python 2.6 for documentation build with Sphinx
 
     - alternate build environments:
 
-        * none
+        * none.  Xcode 4.x currently supplies two C compilers.
+          ``llvm-gcc-4.2.1`` has been found to miscompile Python 3.3.x and
+          produce a non-functional Python executable.  As it appears to be
+          considered a migration aid by Apple and is not likely to be fixed,
+          its use should be avoided.  The other compiler, ``clang``, has been
+          undergoing rapid development.  While it appears to have become
+          production-ready in the most recent Xcode 4 releases (Xcode 4.4.1
+          as of this writing), there are still some open issues when
+          building Python and there has not yet been the level of exposure in
+          production environments that the Xcode 3 gcc-4.2 compiler has had.
+
+
+*   For Python 2.7.x and 3.2.x, the 32-bit-only installer was configured to
+    support Mac OS X 10.3.9 through (at least) 10.6.  Because it is
+    believed that there are few systems still running OS X 10.3 or 10.4
+    and because it has become increasingly difficult to test and
+    support the differences in these earlier systems, as of Python 3.3.0 the PSF
+    32-bit installer no longer supports them.  For reference in building such
+    an installer yourself, the details are::
+
+        /usr/bin/python build-installer.py \
+            --sdk-path=/Developer/SDKs/MacOSX10.4u.sdk \
+            --universal-archs=32-bit \
+            --dep-target=10.3 
+
+    - builds the following third-party libraries
+
+        * Bzip2
+        * NCurses
+        * GNU Readline (GPL)
+        * SQLite 3
+        * XZ
+        * Zlib 1.2.3
+        * Oracle Sleepycat DB 4.8 (Python 2.x only)
+
+    - requires ActiveState ``Tcl/Tk 8.4`` (currently 8.4.19) to be installed for building
+
+    - recommended build environment:
+        
+        * Mac OS X 10.5.8 PPC or Intel
+        * Xcode 3.1.4 (or later)
+        * ``MacOSX10.4u`` SDK (later SDKs do not support PPC G3 processors)
+        * ``MACOSX_DEPLOYMENT_TARGET=10.3``
+        * Apple ``gcc-4.0``
+        * system Python 2.5 for documentation build with Sphinx
+
+    - alternate build environments:
+
+        * Mac OS X 10.6.8 with Xcode 3.2.6
+            - need to change ``/System/Library/Frameworks/{Tcl,Tk}.framework/Version/Current`` to ``8.4``
+
 
 
 General Prerequisites
@@ -87,6 +142,11 @@ General Prerequisites
 * It is safest to start each variant build with an empty source directory
   populated with a fresh copy of the untarred source.
 
+* It is recommended that you remove any existing installed version of the
+  Python being built::
+
+      sudo rm -rf /Library/Frameworks/Python.framework/Versions/n.n
+
 
 The Recipe
 ----------
@@ -107,9 +167,9 @@ Building other universal installers
 ...................................
 
 It is also possible to build a 4-way universal installer that runs on 
-OS X Leopard or later::
+OS X 10.5 Leopard or later::
 
-  python 2.6 /build-installer.py \
+    /usr/bin/python /build-installer.py \
         --dep-target=10.5
         --universal-archs=all
         --sdk-path=/Developer/SDKs/MacOSX10.5.sdk
@@ -120,7 +180,8 @@ also that you are building on at least OS X 10.5.  4-way includes
 variants can only be run on G5 machines running 10.5.  Note that,
 while OS X 10.6 is only supported on Intel-based machines, it is possible
 to run ``ppc`` (32-bit) executables unmodified thanks to the Rosetta ppc
-emulation in OS X 10.5 and 10.6.
+emulation in OS X 10.5 and 10.6.  The 4-way installer variant must be
+built with Xcode 3.  It is not regularly built or tested.
 
 Other ``--universal-archs`` options are ``64-bit`` (``x86_64``, ``ppc64``),
 and ``3-way`` (``ppc``, ``i386``, ``x86_64``).  None of these options
@@ -133,15 +194,21 @@ Testing
 Ideally, the resulting binaries should be installed and the test suite run
 on all supported OS X releases and architectures.  As a practical matter,
 that is generally not possible.  At a minimum, variant 1 should be run on
-at least one Intel, one PPC G4, and one PPC G3 system and one each of 
-OS X 10.6, 10.5, 10.4, and 10.3.9.  Not all tests run on 10.3.9.
-Variant 2 should be run on 10.6 in both 32-bit and 64-bit modes.::
+a PPC G4 system with OS X 10.5 and at least one Intel system running OS X
+10.8, 10.7, 10.6, or 10.5.  Variant 2 should be run on 10.8, 10.7, and 10.6
+systems in both 32-bit and 64-bit modes.::
 
-    arch -i386 /usr/local/bin/pythonn.n -m test.regrtest -w -u all 
-    arch -X86_64 /usr/local/bin/pythonn.n -m test.regrtest -w -u all
+    /usr/local/bin/pythonn.n -m test -w -u all,-largefile
+    /usr/local/bin/pythonn.n-32 -m test -w -u all
     
 Certain tests will be skipped and some cause the interpreter to fail
 which will likely generate ``Python quit unexpectedly`` alert messages
-to be generated at several points during a test run.  These can
-be ignored.
+to be generated at several points during a test run.  These are normal
+during testing and can be ignored.
+
+It is also recommend to launch IDLE and verify that it is at least
+functional.  Double-click on the IDLE app icon in ``/Applications/Pythonn.n``.
+It should also be tested from the command line::
+
+    /usr/local/bin/idlen.n
 
diff --git a/Mac/BuildScript/resources/ReadMe.txt b/Mac/BuildScript/resources/ReadMe.txt
index f1beda0..9ac52d0 100644
--- a/Mac/BuildScript/resources/ReadMe.txt
+++ b/Mac/BuildScript/resources/ReadMe.txt
@@ -5,8 +5,15 @@ $ARCHITECTURES.
 Installation requires approximately $INSTALL_SIZE MB of disk space,
 ignore the message that it will take zero bytes.
 
-You must install onto your current boot disk, even though the
-installer does not enforce this, otherwise things will not work.
+If you are attempting to install on an OS X 10.8 system, you may
+see a message that Python can't be installed because it is from an
+unidentified developer.  This is because this Python installer
+package is not yet compatible with the Gatekeeper security feature
+introduced in OS X 10.8.  To allow Python to be installed, you
+can override the Gatekeeper policy for this install.  In the Finder,
+instead of double-clicking, control-click or right click the "Python"
+installer package icon.  Then select "Open using ... Installer" from
+the contextual menu that appears.
 
 Python consists of the Python programming language interpreter, plus
 a set of programs to allow easy access to it for Mac users including
@@ -16,10 +23,11 @@ Python programs.
 
                     **** IMPORTANT ****
                     
-Before using IDLE or other programs using the tkinter graphical user
-interface toolkit, visit http://www.python.org/download/mac/tcltk/
-for current information about supported and recommended versions
-of Tcl/Tk for this version of Python and Mac OS X.
+To use IDLE or other programs that use the tkinter graphical user
+interface toolkit, you may need to install a third-party version of
+the Tcl/Tk frameworks.  Visit http://www.python.org/download/mac/tcltk/
+for current information about supported and recommended versions of
+Tcl/Tk for this version of Python and of Mac OS X.
 
                     *******************
 
@@ -32,5 +40,13 @@ optionally place links to the command-line tools in /usr/local/bin as
 well. Double-click on the "Update Shell Profile" command to add the
 "bin" directory inside the framework to your shell's search path.
 
+You must install onto your current boot disk, even though the
+installer does not enforce this, otherwise things will not work.
+
+You can verify the integrity of the disk image file containing the
+installer package and this ReadMe file by comparing its md5 checksum
+and size with the values published on the release page linked at
+http://www.python.org/download/
+
 More information on Python in general can be found at
 http://www.python.org.
diff --git a/Mac/BuildScript/resources/Welcome.rtf b/Mac/BuildScript/resources/Welcome.rtf
index d209b10..86fbf63 100644
--- a/Mac/BuildScript/resources/Welcome.rtf
+++ b/Mac/BuildScript/resources/Welcome.rtf
@@ -1,8 +1,8 @@
-{\rtf1\ansi\ansicpg1252\cocoartf1038\cocoasubrtf350
+{\rtf1\ansi\ansicpg1252\cocoartf1138\cocoasubrtf470
 {\fonttbl\f0\fswiss\fcharset0 Helvetica;}
 {\colortbl;\red255\green255\blue255;}
 \paperw11904\paperh16836\margl1440\margr1440\vieww9640\viewh10620\viewkind0
-\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural
+\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640
 
 \f0\fs24 \cf0 This package will install 
 \b Python $FULL_VERSION
@@ -20,9 +20,9 @@ See the ReadMe file and the Python documentation for more information.\
 \
 
 \b NOTE: 
-\b0 This package will by default not update your shell profile and will also not install files in /usr/local.  Double-click 
+\b0 This package will not update your shell profile by default.  Double-click 
 \b Update Shell Profile
-\b0  at any time to make $FULL_VERSION the default Python.\
+\b0  at any time to make $FULL_VERSION the default Python 3 version.  This version can co-exist with other installed versions of Python 3 and Python 2.\
 \
 
 \b IMPORTANT:
diff --git a/Mac/README b/Mac/README
index e8c6da8..f7bc6c3 100644
--- a/Mac/README
+++ b/Mac/README
@@ -129,8 +129,8 @@ The makefile for a framework build will also install ``python3.3-32``
 binaries when the universal architecture includes at least one 32-bit
 architecture (that is, for all flavors but ``64-bit``).
 
-Running a specific archicture
-.............................
+Running a specific architecture
+...............................
 
 You can run code using a specific architecture using the ``arch`` command::
 
@@ -145,6 +145,14 @@ Python 2.7 or 3.2, in earlier versions the python (and pythonw) commands are
 wrapper tools that execute the real interpreter without ensuring that the
 real interpreter runs with the same architecture.
 
+Using ``arch`` is not a perfect solution as the selected architecture will
+not automatically carry through to subprocesses launched by programs and tests
+under that Python.  If you want to ensure that Python interpreters launched in
+subprocesses also run in 32-bit-mode if the main interpreter does, use
+a ``python3.3-32`` binary and use the value of ``sys.executable`` as the
+``subprocess`` ``Popen`` executable value.
+
+
 Building and using a framework-based Python on Mac OS X.
 ========================================================
 
@@ -180,9 +188,16 @@ Versions/Current and you will see the familiar bin and lib directories.
 ----------------------------
 
 Yes, probably.  If you want Tkinter support you need to get the OSX AquaTk 
-distribution, this is installed by default on Mac OS X 10.4 or later. If
-you want wxPython you need to get that. If you want Cocoa you need to get
-PyObjC. 
+distribution, this is installed by default on Mac OS X 10.4 or later.  Be
+aware, though, that the Cocoa-based AquaTk's supplied starting with OS X
+10.6 have proven to be unstable.  If possible, you should consider
+installing a newer version before building on OS X 10.6 or later, such as
+the ActiveTcl 8.5.  See http://www.python.org/download/mac/tcltk/.  If you
+are building with an SDK, ensure that the newer Tcl and Tk frameworks are
+seen in the SDK's ``Library/Frameworks`` directory; you may need to
+manually create symlinks to their installed location, ``/Library/Frameworks``.
+If you want wxPython you need to get that.
+If you want Cocoa you need to get PyObjC.
 
 4. How do I build a framework Python?
 -------------------------------------
@@ -260,7 +275,13 @@ However, the Python build process itself has several build dependencies not
 available out of the box with OS X 10.4 so you may have to install
 additional software beyond what is provided with Xcode 2.  OS X 10.5
 provides a recent enough system Python (in ``/usr/bin``) to build
-the Python documentation set.
+the Python documentation set.  It should be possible to use SDKs and/or older
+versions of Xcode to build installers that are compatible with older systems
+on a newer system but this may not be completely foolproof so the resulting
+executables, shared libraries, and ``.so`` bundles should be carefully
+examined and tested on all supported systems for proper dynamic linking
+dependencies.  It is safest to build the distribution on a system running the
+minimum OS X version supported.
 
 All of this is normally done completely isolated in /tmp/_py, so it does not
 use your normal build directory nor does it install into /.
@@ -285,7 +306,7 @@ The configure script sometimes emits warnings like the one below::
    configure: WARNING:     ## -------------------------------------- ##
 
 This almost always means you are trying to build a universal binary for
-Python and have libaries in ``/usr/local`` that don't contain the required
+Python and have libraries in ``/usr/local`` that don't contain the required
 architectures. Temporarily move ``/usr/local`` aside to finish the build.