Update build docs for macOS (GH-16844)

Author: ned-deily

Mac/BuildScript/README.txt renamed to Mac/BuildScript/README.rst

@@ -1,25 +1,23 @@
-=========================
-Python on Mac OS X README
-=========================
+======================
+Python on macOS README
+======================
 
 :Authors:
     Jack Jansen (2004-07),
     Ronald Oussoren (2010-04),
-    Ned Deily (2014-05)
+    Ned Deily (2012-06)
 
-:Version: 2.7.15
-
-This document provides a quick overview of some Mac OS X specific features in
+This document provides a quick overview of some macOS specific features in
 the Python distribution.
 
-OS X specific arguments to configure
-====================================
+macOS specific arguments to configure
+=====================================
 
 * ``--enable-framework[=DIR]``
 
   If this argument is specified the build will create a Python.framework rather
   than a traditional Unix install. See the section
-  _`Building and using a framework-based Python on Mac OS X` for more
+  _`Building and using a framework-based Python on macOS` for more
   information on frameworks.
 
   If the optional directory argument is specified the framework is installed
@@ -43,41 +41,51 @@ OS X specific arguments to configure
   Create a universal binary build of Python. This can be used with both
   regular and framework builds.
 
-  The optional argument specifies which OS X SDK should be used to perform the
-  build.  If xcodebuild is available and configured, this defaults to
-  the Xcode default MacOS X SDK, otherwise ``/Developer/SDKs/MacOSX.10.4u.sdk``
-  if available or ``/`` if not.  When building on OS X 10.5 or later, you can
-  specify ``/`` to use the installed system headers rather than an SDK.  As of
-  OS X 10.9, you should install the optional system headers from the Command
-  Line Tools component using ``xcode-select``::
-
-     $ sudo xcode-select --install
-
-  See the section _`Building and using a universal binary of Python on Mac OS X`
-  for more information.
+  The optional argument specifies which macOS SDK should be used to perform the
+  build.  In most cases on current systems, you do not need to specify PATH or
+  you can just use ``/``; the default MacOSX SDK for the active Xcode or Command
+  Line Tools developer directory will be used.  See the macOS ``xcrun`` man page
+  for more information.  Current versions of macOS and Xcode no longer install
+  system header files in their traditional locations, like ``/usr/include`` and
+  ``/System/Library/Frameworks``; instead they are found within a MacOSX SDK.
+  The Apple-supplied build tools handle this transparently and current
+  versiona of Python now handle this as well.  So it is no longer necessary,
+  and since macOS 10.14, no longer possible to force the installation of system
+  headers with ``xcode-select``.
 
 * ``--with-universal-archs=VALUE``
 
   Specify the kind of universal binary that should be created. This option is
   only valid when ``--enable-universalsdk`` is specified.  The default is
-  ``32-bit`` if a building with a SDK that supports PPC, otherwise defaults
-  to ``intel``.
+  ``32-bit`` if building with a SDK that supports PPC, otherwise defaults
+  to ``intel``.  Note that ``intel`` means a universal build of both 32-bit
+  and 64-bit binaries and that may not be what you want; for example,
+  as of macOS 10.15 Catalina, 32-bit execution is no longer supported by
+  the operating system.  Thus it is best to either explicitly specify
+  values for ``--with-universal-archs``:
+
+      ``--enable-universalsdk --with-universal-archs=intel-64``
 
+  or avoid using either.
 
-Building and using a universal binary of Python on Mac OS X
-===========================================================
+
+Building and using a universal binary of Python on macOS
+========================================================
 
 1. What is a universal binary
 -----------------------------
 
 A universal binary build of Python contains object code for more than one
-CPU architecture.  A universal OS X executable file or library combines the
+CPU architecture.  A universal macOS executable file or library combines the
 architecture-specific code into one file and can therefore run at native
 speed on all supported architectures.  Universal files were introduced in
-OS X 10.4 to add support for Intel-based Macs to the existing PowerPC (PPC)
-machines.  In OS X 10.5 support was extended to 64-bit Intel and 64-bit PPC
+macOS 10.4 to add support for Intel-based Macs to the existing PowerPC (PPC)
+machines.  In macOS 10.5 support was extended to 64-bit Intel and 64-bit PPC
 architectures.  It is possible to build Python with various combinations
-of architectures depending on the build tools and OS X version in use.
+of architectures depending on the build tools and macOS version in use.
+Note that PPC support was removed in macOS 10.7 and 32-bit Intel support
+was removed in macOS 10.15.  So currently as of macOS 10.15, macOS only
+supports one execution architecture, 64-bit Intel (``x86_64``).
 
 2. How do I build a universal binary
 ------------------------------------
@@ -90,14 +98,14 @@ flag to configure::
   $ make install
 
 This flag can be used with a framework build of python, but also with a classic
-unix build. Universal builds were first supported with OS X 10.4 with Xcode 2.1
-and the 10.4u SDK.  Starting with Xcode 3 and OS X 10.5, more configurations are
+unix build. Universal builds were first supported with macOS 10.4 with Xcode 2.1
+and the 10.4u SDK.  Starting with Xcode 3 and macOS 10.5, more configurations are
 available.
 
 In general, universal builds depend on specific features provided by the
 Apple-supplied compilers and other build tools included in Apple's Xcode
-development tools.  You should install Xcode and the command line tools
-component appropriate for the OS X release you are running on.  See the
+development tools.  You should install Xcode or the command line tools
+component appropriate for the macOS release you are running on.  See the
 Python Developer's Guide (https://devguide.python.org/setup/)
 for more information.
 
@@ -127,28 +135,29 @@ values are available:
   * ``all``:      ``ppc``, ``ppc64``, ``i386``, ``x86_64``
 
 To build a universal binary that includes a 64-bit architecture, you must build
-on a system running OS X 10.5 or later.  The ``all`` and ``64-bit`` flavors can
+on a system running macOS 10.5 or later.  The ``all`` and ``64-bit`` flavors can
 only be built with a 10.5 SDK because ``ppc64`` support was only included with
-OS X 10.5.  Although legacy ``ppc`` support was included with Xcode 3 on OS X
-10.6, it was removed in Xcode 4, versions of which were released on OS X 10.6
-and which is the standard for OS X 10.7.  To summarize, the
+macOS 10.5.  Although legacy ``ppc`` support was included with Xcode 3 on macOS
+10.6, it was removed in Xcode 4, versions of which were released on macOS 10.6
+and which is the standard for macOS 10.7.  To summarize, the
 following combinations of SDKs and universal-archs flavors are available:
 
   * 10.4u SDK with Xcode 2 supports ``32-bit`` only
 
   * 10.5 SDK with Xcode 3.1.x supports all flavors
 
-  * 10.6 SDK with Xcode 3.2.x supports ``intel``, ``3-way``, and ``32-bit``
+  * 10.6 SDK with Xcode 3.2.x supports ``intel``, ``intel-32``,
+    ``intel-64``, ``3-way``, and ``32-bit``
 
-  * 10.6 SDK with Xcode 4 supports ``intel`` only
+  * 10.6 SDK with Xcode 4 supports ``intel``, ``intel-32``, and ``intel-64``
 
-  * 10.7 and 10.8 SDKs with Xcode 4 support ``intel`` only
+  * 10.7 through 10.14 SDKs support ``intel``, ``intel-32``, and ``intel-64``
 
-  * 10.8 and 10.9 SDKs with Xcode 5 support ``intel`` only
+  * 10.15 and later SDKs support ``intel-64`` only
 
 The makefile for a framework build will also install ``python2.7-32``
 binaries when the universal architecture includes at least one 32-bit
-architecture (that is, for all flavors but ``64-bit``).
+architecture (that is, for all flavors but ``64-bit`` and ``intel-64``).
 
 Running a specific architecture
 ...............................
@@ -161,39 +170,34 @@ Or to explicitly run in 32-bit mode, regardless of the machine hardware::
 
    $ arch -i386 -ppc python
 
-NOTE: When you're using a framework install of Python this requires at least
-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 ``python2.7-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.
-========================================================
+Building and using a framework-based Python on macOS
+====================================================
 
 
 1. Why would I want a framework Python instead of a normal static Python?
 --------------------------------------------------------------------------
 
 The main reason is because you want to create GUI programs in Python. With the
 exception of X11/XDarwin-based GUI toolkits all GUI programs need to be run
-from a Mac OS X application bundle (".app").
+from a macOS application bundle (".app").
 
 While it is technically possible to create a .app without using frameworks you
 will have to do the work yourself if you really want this.
 
 A second reason for using frameworks is that they put Python-related items in
 only two places: "/Library/Framework/Python.framework" and
-"/Applications/Python <VERSION>" where ``<VERSION>`` can be e.g. "3.4",
+"/Applications/Python <VERSION>" where ``<VERSION>`` can be e.g. "3.8",
 "2.7", etc.  This simplifies matters for users installing
 Python from a binary distribution if they want to get rid of it again. Moreover,
-due to the way frameworks work, a user without admin privileges can install a
-binary distribution in his or her home directory without recompilation.
+due to the way frameworks work, usera without admin privileges can install a
+binary distribution in their home directory without recompilation.
 
 2. How does a framework Python differ from a normal static Python?
 ------------------------------------------------------------------
@@ -207,12 +211,12 @@ Versions/Current and you will see the familiar bin and lib directories.
 3. Do I need extra packages?
 ----------------------------
 
-Yes, probably.  If you want Tkinter support you need to get the OS X AquaTk
-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
+Yes, probably.  If you want Tkinter support you need to get the macOS AquaTk
+distribution, this is installed by default on macOS 10.4 or later.  Be
+aware, though, that the Cocoa-based AquaTk's supplied starting with macOS
 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
+installing a newer version before building on macOS 10.6 or later, such as
+the ActiveTcl 8.6.  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``.
@@ -223,7 +227,7 @@ If you want Cocoa you need to get PyObjC.
 -------------------------------------
 
 This directory contains a Makefile that will create a couple of python-related
-applications (full-blown OS X .app applications, that is) in
+applications (full-blown macOS .app applications, that is) in
 "/Applications/Python <VERSION>", and a hidden helper application Python.app
 inside the Python.framework, and unix tools including "python" into
 /usr/local/bin.  In addition it has a target "installmacsubtree" that installs
@@ -291,26 +295,25 @@ How do I create a binary distribution?
 Download and unpack the source release from http://www.python.org/download/.
 Go to the directory ``Mac/BuildScript``. There you will find a script
 ``build-installer.py`` that does all the work. This will download and build
-a number of 3rd-party libaries, configures and builds a framework Python,
+a number of 3rd-party libraries, configures and builds a framework Python,
 installs it, creates the installer package files and then packs this in a
 DMG image.  The script also builds an HTML copy of the current Python
 documentation set for this release for inclusion in the framework.  The
 installer package will create links to the documentation for use by IDLE,
 pydoc, shell users, and Finder user.
 
 The script will build a universal binary so you'll therefore have to run this
-script on Mac OS X 10.4 or later and with Xcode 2.1 or later installed.
+script on macOS 10.4 or later and with Xcode 2.1 or later installed.
 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.  It should be possible to use SDKs and/or older
+available out of the box with macOS 10.4 so you may have to install
+additional software beyond what is provided with Xcode 2.
+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.
+minimum macOS 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 /.
@@ -344,7 +347,7 @@ Uninstalling a framework install, including the binary installer
 
 Uninstalling a framework can be done by manually removing all bits that got installed.
 That's true for both installations from source and installations using the binary installer.
-OS X does not provide a central uninstaller.
+macOS does not provide a central uninstaller.
 
 The main bit of a framework install is the framework itself, installed in
 ``/Library/Frameworks/Python.framework``. This can contain multiple versions

Mac/README renamed to Mac/README.rst

@@ -582,19 +582,30 @@ Reliant UNIX: The thread support does not compile on Reliant UNIX, and
         platform as well.  This should be resolved in time for a
         future release.
 
-MacOSX: The tests will crash on both 10.1 and 10.2 with SEGV in
+macOS:  Building a complete Python installation requires the use of various
+        additional third-party libraries, depending on your build platform and
+        configure options.  Not all standard library modules are buildable or
+        useable on all platforms.  Refer to the "Install Dependencies" section
+        section of the "Developer Guide" for current detailed information on
+        dependencies for macOS:
+            https://devguide.python.org/setup/#install-dependencies
+
+        On macOS, there are additional configure and build options related
+        to macOS framework and universal builds.  Refer to Mac/README.rst.
+
+        The tests will crash on both 10.1 and 10.2 with SEGV in
         test_re and test_sre due to the small default stack size.  If
         you set the stack size to 2048 before doing a "make test" the
         failure can be avoided.  If you're using the tcsh or csh shells,
         use "limit stacksize 2048" and for the bash shell (the default
-        as of OSX 10.3), use "ulimit -s 2048".
+        as of macOS 10.3), use "ulimit -s 2048".
 
         On naked Darwin you may want to add the configure option
         "--disable-toolbox-glue" to disable the glue code for the Carbon
         interface modules. The modules themselves are currently only built
         if you add the --enable-framework option, see below.
 
-        On a clean OSX /usr/local does not exist. Do a
+        On a clean macOS /usr/local does not exist. Do a
         "sudo mkdir -m 775 /usr/local"
         before you do a make install. It is probably not a good idea to
         do "sudo make install" which installs everything as superuser,
@@ -605,20 +616,6 @@ MacOSX: The tests will crash on both 10.1 and 10.2 with SEGV in
         to install additional unix software. Disabling fink (remove all 
         references to /sw from your .profile or .login) should solve this.
 
-        You may want to try the configure option "--enable-framework"
-        which installs Python as a framework. The location can be set
-        as argument to the --enable-framework option (default
-        /Library/Frameworks). A framework install is probably needed if you
-        want to use any Aqua-based GUI toolkit (whether Tkinter, wxPython,
-        Carbon, Cocoa or anything else).
-
-        You may also want to try the configure option "--enable-universalsdk"
-        which builds Python as a universal binary with support for the 
-        i386 and PPC architetures. This requires Xcode 2.1 or later to build.
-
-        See Mac/README for more information on framework and 
-        universal builds.
-
 Cygwin: With recent (relative to the time of writing, 2001-12-19)
         Cygwin installations, there are problems with the interaction
         of dynamic linking and fork().  This manifests itself in build
@@ -949,11 +946,6 @@ Emacs found in Misc/python-mode.el.  (But then again, more recent
 versions of Emacs may already have it.)  Follow the instructions that
 came with Emacs for installation of site-specific files.
 
-On Mac OS X, if you have configured Python with --enable-framework, you
-should use "make frameworkinstall" to do the installation. Note that this
-installs the Python executable in a place that is not normally on your
-PATH, you may want to set up a symlink in /usr/local/bin.
-
 
 Installing multiple versions
 ----------------------------