From 19d6842c15c145f65178f806048ac1a8ae7d05f6 Mon Sep 17 00:00:00 2001 From: Ned Deily Date: Mon, 14 Oct 2019 08:16:10 -0400 Subject: Update build docs for macOS (GH-16771) --- Mac/BuildScript/README.rst | 222 +++++++++++++++++++++++++++ Mac/BuildScript/README.txt | 222 --------------------------- Mac/README | 358 -------------------------------------------- Mac/README.rst | 363 +++++++++++++++++++++++++++++++++++++++++++++ README.rst | 23 +-- 5 files changed, 597 insertions(+), 591 deletions(-) create mode 100644 Mac/BuildScript/README.rst delete mode 100644 Mac/BuildScript/README.txt delete mode 100644 Mac/README create mode 100644 Mac/README.rst diff --git a/Mac/BuildScript/README.rst b/Mac/BuildScript/README.rst new file mode 100644 index 0000000000..f8b25fa5af --- /dev/null +++ b/Mac/BuildScript/README.rst @@ -0,0 +1,222 @@ +Building a Python Mac OS X distribution +======================================= + +The ``build-install.py`` script creates Python distributions, including +certain third-party libraries as necessary. It builds a complete +framework-based Python out-of-tree, installs it in a funny place with +$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. + +For Python 3.4.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.5 through (at least) 10.9:: + + /path/to/bootstrap/python2.7 build-installer.py \ + --sdk-path=/Developer/SDKs/MacOSX10.5.sdk \ + --universal-archs=32-bit \ + --dep-target=10.5 + + - builds the following third-party libraries + + * NCurses 5.9 (http://bugs.python.org/issue15037) + * SQLite 3.8.11 + * XZ 5.0.5 + + - 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.20) to be installed for building + + - 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`` + * bootstrap non-framework Python 2.7 for documentation build with + Sphinx (as of 3.4.1) + + - 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`` + * 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):: + + /path/to/bootstrap/python2.7 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.8.11 + * XZ 5.0.5 + + - uses system-supplied versions of third-party libraries + + * readline module links with Apple BSD editline (libedit) + + - requires ActiveState Tcl/Tk 8.5.15.1 (or later) to be installed for building + + - 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`` + * bootstrap non-framework Python 2.7 for documentation build with + Sphinx (as of 3.4.1) + + - alternate build environments: + + * 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 5 releases, the versions + available on the deprecated Xcode 4.x for 10.6 were early releases + and did not receive 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.20) 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 +--------------------- + +* No Fink (in ``/sw``) or MacPorts (in ``/opt/local``) or other local + libraries or utilities (in ``/usr/local``) as they could + interfere with the build. + +* The documentation for the release is built using Sphinx + because it is included in the installer. For 2.7.x and 3.x.x up to and + including 3.4.0, the ``Doc/Makefile`` uses ``svn`` to download repos of + ``Sphinx`` and its dependencies. Beginning with 3.4.1, the ``Doc/Makefile`` + assumes there is an externally-provided ``sphinx-build`` and requires at + least Python 2.6 to run. Because of this, it is no longer possible to + build a 3.4.1 or later installer on OS X 10.5 using the Apple-supplied + Python 2.5. + +* 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 +---------- + +Here are the steps you need to follow to build a Python installer: + +* Run ``build-installer.py``. Optionally you can pass a number of arguments + to specify locations of various files. Please see the top of + ``build-installer.py`` for its usage. + + Running this script takes some time, it will not only build Python itself + but also some 3th-party libraries that are needed for extensions. + +* When done the script will tell you where the DMG image is (by default + somewhere in ``/tmp/_py``). + +Building other universal installers +................................... + +It is also possible to build a 4-way universal installer that runs on +OS X 10.5 Leopard or later:: + + /usr/bin/python /build-installer.py \ + --dep-target=10.5 + --universal-archs=all + --sdk-path=/Developer/SDKs/MacOSX10.5.sdk + +This requires that the deployment target is 10.5, and hence +also that you are building on at least OS X 10.5. 4-way includes +``i386``, ``x86_64``, ``ppc``, and ``ppc64`` (G5). ``ppc64`` executable +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. 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 +are regularly exercised; use at your own risk. + + +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 +a PPC G4 system with OS X 10.5 and at least one Intel system running OS X +10.9, 10.8, 10.7, 10.6, or 10.5. Variant 2 should be run on 10.9, 10.8, +10.7, and 10.6 systems in both 32-bit and 64-bit modes.:: + + /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 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/Python n.n``. +It should also be tested from the command line:: + + /usr/local/bin/idlen.n + diff --git a/Mac/BuildScript/README.txt b/Mac/BuildScript/README.txt deleted file mode 100644 index f8b25fa5af..0000000000 --- a/Mac/BuildScript/README.txt +++ /dev/null @@ -1,222 +0,0 @@ -Building a Python Mac OS X distribution -======================================= - -The ``build-install.py`` script creates Python distributions, including -certain third-party libraries as necessary. It builds a complete -framework-based Python out-of-tree, installs it in a funny place with -$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. - -For Python 3.4.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.5 through (at least) 10.9:: - - /path/to/bootstrap/python2.7 build-installer.py \ - --sdk-path=/Developer/SDKs/MacOSX10.5.sdk \ - --universal-archs=32-bit \ - --dep-target=10.5 - - - builds the following third-party libraries - - * NCurses 5.9 (http://bugs.python.org/issue15037) - * SQLite 3.8.11 - * XZ 5.0.5 - - - 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.20) to be installed for building - - - 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`` - * bootstrap non-framework Python 2.7 for documentation build with - Sphinx (as of 3.4.1) - - - 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`` - * 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):: - - /path/to/bootstrap/python2.7 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.8.11 - * XZ 5.0.5 - - - uses system-supplied versions of third-party libraries - - * readline module links with Apple BSD editline (libedit) - - - requires ActiveState Tcl/Tk 8.5.15.1 (or later) to be installed for building - - - 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`` - * bootstrap non-framework Python 2.7 for documentation build with - Sphinx (as of 3.4.1) - - - alternate build environments: - - * 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 5 releases, the versions - available on the deprecated Xcode 4.x for 10.6 were early releases - and did not receive 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.20) 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 ---------------------- - -* No Fink (in ``/sw``) or MacPorts (in ``/opt/local``) or other local - libraries or utilities (in ``/usr/local``) as they could - interfere with the build. - -* The documentation for the release is built using Sphinx - because it is included in the installer. For 2.7.x and 3.x.x up to and - including 3.4.0, the ``Doc/Makefile`` uses ``svn`` to download repos of - ``Sphinx`` and its dependencies. Beginning with 3.4.1, the ``Doc/Makefile`` - assumes there is an externally-provided ``sphinx-build`` and requires at - least Python 2.6 to run. Because of this, it is no longer possible to - build a 3.4.1 or later installer on OS X 10.5 using the Apple-supplied - Python 2.5. - -* 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 ----------- - -Here are the steps you need to follow to build a Python installer: - -* Run ``build-installer.py``. Optionally you can pass a number of arguments - to specify locations of various files. Please see the top of - ``build-installer.py`` for its usage. - - Running this script takes some time, it will not only build Python itself - but also some 3th-party libraries that are needed for extensions. - -* When done the script will tell you where the DMG image is (by default - somewhere in ``/tmp/_py``). - -Building other universal installers -................................... - -It is also possible to build a 4-way universal installer that runs on -OS X 10.5 Leopard or later:: - - /usr/bin/python /build-installer.py \ - --dep-target=10.5 - --universal-archs=all - --sdk-path=/Developer/SDKs/MacOSX10.5.sdk - -This requires that the deployment target is 10.5, and hence -also that you are building on at least OS X 10.5. 4-way includes -``i386``, ``x86_64``, ``ppc``, and ``ppc64`` (G5). ``ppc64`` executable -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. 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 -are regularly exercised; use at your own risk. - - -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 -a PPC G4 system with OS X 10.5 and at least one Intel system running OS X -10.9, 10.8, 10.7, 10.6, or 10.5. Variant 2 should be run on 10.9, 10.8, -10.7, and 10.6 systems in both 32-bit and 64-bit modes.:: - - /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 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/Python n.n``. -It should also be tested from the command line:: - - /usr/local/bin/idlen.n - diff --git a/Mac/README b/Mac/README deleted file mode 100644 index d4194747eb..0000000000 --- a/Mac/README +++ /dev/null @@ -1,358 +0,0 @@ -========================= -Python on Mac OS X README -========================= - -:Authors: - Jack Jansen (2004-07), - Ronald Oussoren (2010-04), - Ned Deily (2012-06) - -:Version: 3.4.0 - -This document provides a quick overview of some Mac OS X specific features in -the Python distribution. - -OS X 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 - information on frameworks. - - If the optional directory argument is specified the framework is installed - into that directory. This can be used to install a python framework into - your home directory:: - - $ ./configure --enable-framework=/Users/ronald/Library/Frameworks - $ make && make install - - This will install the framework itself in ``/Users/ronald/Library/Frameworks``, - the applications in a subdirectory of ``/Users/ronald/Applications`` and the - command-line tools in ``/Users/ronald/bin``. - -* ``--with-framework-name=NAME`` - - Specify the name for the python framework, defaults to ``Python``. This option - is only valid when ``--enable-framework`` is specified. - -* ``--enable-universalsdk[=PATH]`` - - 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. - -* ``--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``. - - -Building and using a universal binary of Python on Mac OS X -=========================================================== - -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 -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 -architectures. It is possible to build Python with various combinations -of architectures depending on the build tools and OS X version in use. - -2. How do I build a universal binary ------------------------------------- - -You can enable universal binaries by specifying the "--enable-universalsdk" -flag to configure:: - - $ ./configure --enable-universalsdk - $ make - $ 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 -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 -Python Developer's Guide (https://devguide.python.org/setup/) -for more information. - -2.1 Flavors of universal binaries -................................. - -It is possible to build a number of flavors of the universal binary build, -the default is a 32-bit only binary (i386 and ppc) in build environments that -support ppc (10.4 with Xcode 2, 10.5 and 10.6 with Xcode 3) or an -Intel-32/-64-bit binary (i386 and X86_64) in build environments that do not -support ppc (Xcode 4 on 10.6 and later systems). The flavor can be specified -using the configure option ``--with-universal-archs=VALUE``. The following -values are available: - - * ``intel``: ``i386``, ``x86_64`` - - * ``intel-32``: ``i386`` - - * ``32-bit``: ``ppc``, ``i386`` - - * ``3-way``: ``i386``, ``x86_64``, ``ppc`` - - * ``64-bit``: ``ppc64``, ``x86_64`` - - * ``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 -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 -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 4 supports ``intel`` only - - * 10.7 and 10.8 SDKs with Xcode 4 support ``intel`` only - - * 10.8 and 10.9 SDKs with Xcode 5 support ``intel`` only - -The makefile for a framework build will also install ``python3.4-32`` -binaries when the universal architecture includes at least one 32-bit -architecture (that is, for all flavors but ``64-bit``). - -Running a specific architecture -............................... - -You can run code using a specific architecture using the ``arch`` command:: - - $ arch -i386 python - -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 ``python3.4-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. -======================================================== - - -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"). - -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 " where ```` can be e.g. "3.4", -"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. - -2. How does a framework Python differ from a normal static Python? ------------------------------------------------------------------- - -In everyday use there is no difference, except that things are stored in -a different place. If you look in /Library/Frameworks/Python.framework -you will see lots of relative symlinks, see the Apple documentation for -details. If you are used to a normal unix Python file layout go down to -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 -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? -------------------------------------- - -This directory contains a Makefile that will create a couple of python-related -applications (full-blown OS X .app applications, that is) in -"/Applications/Python ", 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 -the relevant portions of the Mac subtree into the Python.framework. - -It is normally invoked indirectly through the main Makefile, as the last step -in the sequence - - 1. ./configure --enable-framework - - 2. make - - 3. make install - -This sequence will put the framework in ``/Library/Framework/Python.framework``, -the applications in ``/Applications/Python `` and the unix tools in -``/usr/local/bin``. - -Installing in another place, for instance ``$HOME/Library/Frameworks`` if you -have no admin privileges on your machine, is possible. This can be accomplished -by configuring with ``--enable-framework=$HOME/Library/Frameworks``. -The other two directories will then also be installed in your home directory, -at ``$HOME/Applications/Python-`` and ``$HOME/bin``. - -If you want to install some part, but not all, read the main Makefile. The -frameworkinstall is composed of a couple of sub-targets that install the -framework itself, the Mac subtree, the applications and the unix tools. - -There is an extra target frameworkinstallextras that is not part of the -normal frameworkinstall which installs the Tools directory into -"/Applications/Python ", this is useful for binary -distributions. - -What do all these programs do? -=============================== - -"IDLE.app" is an integrated development environment for Python: editor, -debugger, etc. - -"Python Launcher.app" is a helper application that will handle things when you -double-click a .py, .pyc or .pyw file. For the first two it creates a Terminal -window and runs the scripts with the normal command-line Python. For the -latter it runs the script in the Python.app interpreter so the script can do -GUI-things. Keep the ``Option`` key depressed while dragging or double-clicking -a script to set runtime options. These options can be set persistently -through Python Launcher's preferences dialog. - -The program ``pythonx.x`` runs python scripts from the command line. -Previously, various compatibility aliases were also installed, including -``pythonwx.x`` which in early releases of Python on OS X was required to run -GUI programs. As of 3.4.0, the ``pythonwx.x`` aliases are no longer installed. - -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, -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. -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 -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 /. - -Because of the way the script locates the files it needs you have to run it -from within the BuildScript directory. The script accepts a number of -command-line arguments, run it with --help for more information. - -Configure warnings -================== - -The configure script sometimes emits warnings like the one below:: - - configure: WARNING: libintl.h: present but cannot be compiled - configure: WARNING: libintl.h: check for missing prerequisite headers? - configure: WARNING: libintl.h: see the Autoconf documentation - configure: WARNING: libintl.h: section "Present But Cannot Be Compiled" - configure: WARNING: libintl.h: proceeding with the preprocessor's result - configure: WARNING: libintl.h: in the future, the compiler will take precedence - configure: WARNING: ## -------------------------------------- ## - configure: WARNING: ## Report this to http://bugs.python.org/ ## - configure: WARNING: ## -------------------------------------- ## - -This almost always means you are trying to build a universal binary for -Python and have libraries in ``/usr/local`` that don't contain the required -architectures. Temporarily move ``/usr/local`` aside to finish the build. - - -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. - -The main bit of a framework install is the framework itself, installed in -``/Library/Frameworks/Python.framework``. This can contain multiple versions -of Python, if you want to remove just one version you have to remove the -version-specific subdirectory: ``/Library/Frameworks/Python.framework/Versions/X.Y``. -If you do that, ensure that ``/Library/Frameworks/Python.framework/Versions/Current`` -is a symlink that points to an installed version of Python. - -A framework install also installs some applications in ``/Applications/Python X.Y``, - -And lastly a framework installation installs files in ``/usr/local/bin``, all of -them symbolic links to files in ``/Library/Frameworks/Python.framework/Versions/X.Y/bin``. - - -Resources -========= - - * http://www.python.org/download/mac/ - - * http://www.python.org/community/sigs/current/pythonmac-sig/ - - * https://devguide.python.org/ diff --git a/Mac/README.rst b/Mac/README.rst new file mode 100644 index 0000000000..4f2e2ce662 --- /dev/null +++ b/Mac/README.rst @@ -0,0 +1,363 @@ +====================== +Python on macOS README +====================== + +:Authors: + Jack Jansen (2004-07), + Ronald Oussoren (2010-04), + Ned Deily (2012-06) + +This document provides a quick overview of some macOS specific features in +the Python distribution. + +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 macOS` for more + information on frameworks. + + If the optional directory argument is specified the framework is installed + into that directory. This can be used to install a python framework into + your home directory:: + + $ ./configure --enable-framework=/Users/ronald/Library/Frameworks + $ make && make install + + This will install the framework itself in ``/Users/ronald/Library/Frameworks``, + the applications in a subdirectory of ``/Users/ronald/Applications`` and the + command-line tools in ``/Users/ronald/bin``. + +* ``--with-framework-name=NAME`` + + Specify the name for the python framework, defaults to ``Python``. This option + is only valid when ``--enable-framework`` is specified. + +* ``--enable-universalsdk[=PATH]`` + + Create a universal binary build of Python. This can be used with both + regular and framework builds. + + 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 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 macOS +======================================================== + +1. What is a universal binary +----------------------------- + +A universal binary build of Python contains object code for more than one +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 +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 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 +------------------------------------ + +You can enable universal binaries by specifying the "--enable-universalsdk" +flag to configure:: + + $ ./configure --enable-universalsdk + $ make + $ 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 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 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. + +2.1 Flavors of universal binaries +................................. + +It is possible to build a number of flavors of the universal binary build, +the default is a 32-bit only binary (i386 and ppc) in build environments that +support ppc (10.4 with Xcode 2, 10.5 and 10.6 with Xcode 3) or an +Intel-32/-64-bit binary (i386 and X86_64) in build environments that do not +support ppc (Xcode 4 on 10.6 and later systems). The flavor can be specified +using the configure option ``--with-universal-archs=VALUE``. The following +values are available: + + * ``intel``: ``i386``, ``x86_64`` + + * ``intel-32``: ``i386`` + + * ``intel-64``: ``x86_64`` + + * ``32-bit``: ``ppc``, ``i386`` + + * ``3-way``: ``i386``, ``x86_64``, ``ppc`` + + * ``64-bit``: ``ppc64``, ``x86_64`` + + * ``all``: ``ppc``, ``ppc64``, ``i386``, ``x86_64`` + +To build a universal binary that includes a 64-bit architecture, you must build +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 +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``, ``intel-32``, + ``intel-64``, ``3-way``, and ``32-bit`` + + * 10.6 SDK with Xcode 4 supports ``intel``, ``intel-32``, and ``intel-64`` + + * 10.7 through 10.14 SDKs support ``intel``, ``intel-32``, and ``intel-64`` + + * 10.15 and later SDKs support ``intel-64`` only + +The makefile for a framework build will also install ``python3.x-32`` +binaries when the universal architecture includes at least one 32-bit +architecture (that is, for all flavors but ``64-bit`` and ``intel-64``). + +Running a specific architecture +............................... + +You can run code using a specific architecture using the ``arch`` command:: + + $ arch -i386 python + +Or to explicitly run in 32-bit mode, regardless of the machine hardware:: + + $ arch -i386 -ppc python + +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.x-32`` binary and use the value of ``sys.executable`` as the +``subprocess`` ``Popen`` executable value. + +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 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 " where ```` 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, 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? +------------------------------------------------------------------ + +In everyday use there is no difference, except that things are stored in +a different place. If you look in /Library/Frameworks/Python.framework +you will see lots of relative symlinks, see the Apple documentation for +details. If you are used to a normal unix Python file layout go down to +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 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 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``. +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? +------------------------------------- + +This directory contains a Makefile that will create a couple of python-related +applications (full-blown macOS .app applications, that is) in +"/Applications/Python ", 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 +the relevant portions of the Mac subtree into the Python.framework. + +It is normally invoked indirectly through the main Makefile, as the last step +in the sequence + + 1. ./configure --enable-framework + + 2. make + + 3. make install + +This sequence will put the framework in ``/Library/Framework/Python.framework``, +the applications in ``/Applications/Python `` and the unix tools in +``/usr/local/bin``. + +Installing in another place, for instance ``$HOME/Library/Frameworks`` if you +have no admin privileges on your machine, is possible. This can be accomplished +by configuring with ``--enable-framework=$HOME/Library/Frameworks``. +The other two directories will then also be installed in your home directory, +at ``$HOME/Applications/Python-`` and ``$HOME/bin``. + +If you want to install some part, but not all, read the main Makefile. The +frameworkinstall is composed of a couple of sub-targets that install the +framework itself, the Mac subtree, the applications and the unix tools. + +There is an extra target frameworkinstallextras that is not part of the +normal frameworkinstall which installs the Tools directory into +"/Applications/Python ", this is useful for binary +distributions. + +What do all these programs do? +=============================== + +"IDLE.app" is an integrated development environment for Python: editor, +debugger, etc. + +"Python Launcher.app" is a helper application that will handle things when you +double-click a .py, .pyc or .pyw file. For the first two it creates a Terminal +window and runs the scripts with the normal command-line Python. For the +latter it runs the script in the Python.app interpreter so the script can do +GUI-things. Keep the ``Option`` key depressed while dragging or double-clicking +a script to set runtime options. These options can be set persistently +through Python Launcher's preferences dialog. + +The program ``pythonx.x`` runs python scripts from the command line. +Previously, various compatibility aliases were also installed, including +``pythonwx.x`` which in early releases of Python on macOS was required to run +GUI programs. As of 3.4.0, the ``pythonwx.x`` aliases are no longer installed. + +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, +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 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 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 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 /. + +Because of the way the script locates the files it needs you have to run it +from within the BuildScript directory. The script accepts a number of +command-line arguments, run it with --help for more information. + +Configure warnings +================== + +The configure script sometimes emits warnings like the one below:: + + configure: WARNING: libintl.h: present but cannot be compiled + configure: WARNING: libintl.h: check for missing prerequisite headers? + configure: WARNING: libintl.h: see the Autoconf documentation + configure: WARNING: libintl.h: section "Present But Cannot Be Compiled" + configure: WARNING: libintl.h: proceeding with the preprocessor's result + configure: WARNING: libintl.h: in the future, the compiler will take precedence + configure: WARNING: ## -------------------------------------- ## + configure: WARNING: ## Report this to http://bugs.python.org/ ## + configure: WARNING: ## -------------------------------------- ## + +This almost always means you are trying to build a universal binary for +Python and have libraries in ``/usr/local`` that don't contain the required +architectures. Temporarily move ``/usr/local`` aside to finish the build. + + +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. +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 +of Python, if you want to remove just one version you have to remove the +version-specific subdirectory: ``/Library/Frameworks/Python.framework/Versions/X.Y``. +If you do that, ensure that ``/Library/Frameworks/Python.framework/Versions/Current`` +is a symlink that points to an installed version of Python. + +A framework install also installs some applications in ``/Applications/Python X.Y``, + +And lastly a framework installation installs files in ``/usr/local/bin``, all of +them symbolic links to files in ``/Library/Frameworks/Python.framework/Versions/X.Y/bin``. + + +Resources +========= + + * http://www.python.org/download/mac/ + + * http://www.python.org/community/sigs/current/pythonmac-sig/ + + * https://devguide.python.org/ diff --git a/README.rst b/README.rst index ca397b896e..dfc8566d5e 100644 --- a/README.rst +++ b/README.rst @@ -62,18 +62,20 @@ On Unix, Linux, BSD, macOS, and Cygwin:: This will install Python as ``python3``. You can pass many options to the configure script; run ``./configure --help`` -to find out more. On macOS and Cygwin, the executable is called ``python.exe``; -elsewhere it's just ``python``. +to find out more. On macOS case-insensitive file systems and on Cygwin, +the executable is called ``python.exe``; elsewhere it's just ``python``. -If you are running on macOS with the latest updates installed, make sure to install -OpenSSL or some other SSL software along with Homebrew or another package manager. -If issues persist, see https://devguide.python.org/setup/#macos-and-os-x for more -information. +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 of the `Developer Guide`_ for current detailed information on +dependencies for various Linux distributions and macOS. -On macOS, 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``. +On macOS, there are additional configure and build options related +to macOS framework and universal builds. Refer to `Mac/README.rst +`_. On Windows, see `PCbuild/readme.txt `_. @@ -96,7 +98,6 @@ Profile Guided Optimization (PGO) and may be used to auto-enable Link Time Optimization (LTO) on some platforms. For more details, see the sections below. - Profile Guided Optimization ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -- cgit v1.2.1