Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

Update build docs for macOS (GH-16771)

This commit is contained in:
Ned Deily 2019-10-14 08:16:10 -04:00 committed by GitHub
parent aad2ee0156
commit 19d6842c15
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 86 additions and 80 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

0
Mac/BuildScript/README.txt → Mac/BuildScript/README.rst
View File

143
Mac/README → Mac/README.rst
View File

@ -1,25 +1,23 @@
========================= ======================
Python on Mac OS X README Python on macOS README
========================= ======================
:Authors: :Authors:
Jack Jansen (2004-07), Jack Jansen (2004-07),
Ronald Oussoren (2010-04), Ronald Oussoren (2010-04),
Ned Deily (2012-06) Ned Deily (2012-06)
:Version: 3.4.0 This document provides a quick overview of some macOS specific features in
This document provides a quick overview of some Mac OS X specific features in
the Python distribution. the Python distribution.
OS X specific arguments to configure macOS specific arguments to configure
==================================== =====================================
* ``--enable-framework[=DIR]`` * ``--enable-framework[=DIR]``
If this argument is specified the build will create a Python.framework rather If this argument is specified the build will create a Python.framework rather
than a traditional Unix install. See the section 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. information on frameworks.
If the optional directory argument is specified the framework is installed 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 Create a universal binary build of Python. This can be used with both
regular and framework builds. regular and framework builds.
The optional argument specifies which OS X SDK should be used to perform the The optional argument specifies which macOS SDK should be used to perform the
build. If xcodebuild is available and configured, this defaults to build. In most cases on current systems, you do not need to specify PATH or
the Xcode default MacOS X SDK, otherwise ``/Developer/SDKs/MacOSX.10.4u.sdk`` you can just use ``/``; the default MacOSX SDK for the active Xcode or Command
if available or ``/`` if not. When building on OS X 10.5 or later, you can Line Tools developer directory will be used. See the macOS ``xcrun`` man page
specify ``/`` to use the installed system headers rather than an SDK. As of for more information. Current versions of macOS and Xcode no longer install
OS X 10.9, you should install the optional system headers from the Command system header files in their traditional locations, like ``/usr/include`` and
Line Tools component using ``xcode-select``:: ``/System/Library/Frameworks``; instead they are found within a MacOSX SDK.
The Apple-supplied build tools handle this transparently and current
$ sudo xcode-select --install 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
See the section _`Building and using a universal binary of Python on Mac OS X` headers with ``xcode-select``.
for more information.
* ``--with-universal-archs=VALUE`` * ``--with-universal-archs=VALUE``
Specify the kind of universal binary that should be created. This option is Specify the kind of universal binary that should be created. This option is
only valid when ``--enable-universalsdk`` is specified. The default is only valid when ``--enable-universalsdk`` is specified. The default is
``32-bit`` if a building with a SDK that supports PPC, otherwise defaults ``32-bit`` if building with a SDK that supports PPC, otherwise defaults
to ``intel``. 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 1. What is a universal binary
----------------------------- -----------------------------
A universal binary build of Python contains object code for more than one 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 architecture-specific code into one file and can therefore run at native
speed on all supported architectures. Universal files were introduced in 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) macOS 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 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 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 2. How do I build a universal binary
------------------------------------ ------------------------------------
@ -90,14 +98,14 @@ flag to configure::
$ make install $ make install
This flag can be used with a framework build of python, but also with a classic 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 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 OS X 10.5, more configurations are and the 10.4u SDK. Starting with Xcode 3 and macOS 10.5, more configurations are
available. available.
In general, universal builds depend on specific features provided by the In general, universal builds depend on specific features provided by the
Apple-supplied compilers and other build tools included in Apple's Xcode Apple-supplied compilers and other build tools included in Apple's Xcode
development tools. You should install Xcode and the command line tools development tools. You should install Xcode or the command line tools
component appropriate for the OS X release you are running on. See the component appropriate for the macOS release you are running on. See the
Python Developer's Guide (https://devguide.python.org/setup/) Python Developer's Guide (https://devguide.python.org/setup/)
for more information. for more information.
@ -116,6 +124,8 @@ values are available:
* ``intel-32``: ``i386`` * ``intel-32``: ``i386``
* ``intel-64``: ``x86_64``
* ``32-bit``: ``ppc``, ``i386`` * ``32-bit``: ``ppc``, ``i386``
* ``3-way``: ``i386``, ``x86_64``, ``ppc`` * ``3-way``: ``i386``, ``x86_64``, ``ppc``
@ -125,28 +135,29 @@ values are available:
* ``all``: ``ppc``, ``ppc64``, ``i386``, ``x86_64`` * ``all``: ``ppc``, ``ppc64``, ``i386``, ``x86_64``
To build a universal binary that includes a 64-bit architecture, you must build 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 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 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 OS X 10.6 10.6, it was removed in Xcode 4, versions of which were released on macOS 10.6
and which is the standard for OS X 10.7. To summarize, the and which is the standard for macOS 10.7. To summarize, the
following combinations of SDKs and universal-archs flavors are available: following combinations of SDKs and universal-archs flavors are available:
* 10.4u SDK with Xcode 2 supports ``32-bit`` only * 10.4u SDK with Xcode 2 supports ``32-bit`` only
* 10.5 SDK with Xcode 3.1.x supports all flavors * 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 ``python3.4-32`` The makefile for a framework build will also install ``python3.x-32``
binaries when the universal architecture includes at least one 32-bit 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 Running a specific architecture
............................... ...............................
@ -159,20 +170,15 @@ Or to explicitly run in 32-bit mode, regardless of the machine hardware::
$ arch -i386 -ppc python $ 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 Using ``arch`` is not a perfect solution as the selected architecture will
not automatically carry through to subprocesses launched by programs and tests not automatically carry through to subprocesses launched by programs and tests
under that Python. If you want to ensure that Python interpreters launched in 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 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 a ``python3.x-32`` binary and use the value of ``sys.executable`` as the
``subprocess`` ``Popen`` executable value. ``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? 1. Why would I want a framework Python instead of a normal static Python?
@ -180,18 +186,18 @@ Building and using a framework-based Python on Mac OS X.
The main reason is because you want to create GUI programs in Python. With the 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 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 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. 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 A second reason for using frameworks is that they put Python-related items in
only two places: "/Library/Framework/Python.framework" and 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 "2.7", etc. This simplifies matters for users installing
Python from a binary distribution if they want to get rid of it again. Moreover, 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 due to the way frameworks work, usera without admin privileges can install a
binary distribution in his or her home directory without recompilation. binary distribution in their home directory without recompilation.
2. How does a framework Python differ from a normal static Python? 2. How does a framework Python differ from a normal static Python?
------------------------------------------------------------------ ------------------------------------------------------------------
@ -205,12 +211,12 @@ Versions/Current and you will see the familiar bin and lib directories.
3. Do I need extra packages? 3. Do I need extra packages?
---------------------------- ----------------------------
Yes, probably. If you want Tkinter support you need to get the OS X AquaTk Yes, probably. If you want Tkinter support you need to get the macOS AquaTk
distribution, this is installed by default on Mac OS X 10.4 or later. Be distribution, this is installed by default on macOS 10.4 or later. Be
aware, though, that the Cocoa-based AquaTk's supplied starting with OS X aware, though, that the Cocoa-based AquaTk's supplied starting with macOS
10.6 have proven to be unstable. If possible, you should consider 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 installing a newer version before building on macOS 10.6 or later, such as
the ActiveTcl 8.5. See http://www.python.org/download/mac/tcltk/. If you 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 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 seen in the SDK's ``Library/Frameworks`` directory; you may need to
manually create symlinks to their installed location, ``/Library/Frameworks``. manually create symlinks to their installed location, ``/Library/Frameworks``.
@ -221,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 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 "/Applications/Python <VERSION>", and a hidden helper application Python.app
inside the Python.framework, and unix tools including "python" into inside the Python.framework, and unix tools including "python" into
/usr/local/bin. In addition it has a target "installmacsubtree" that installs /usr/local/bin. In addition it has a target "installmacsubtree" that installs
@ -271,7 +277,7 @@ through Python Launcher's preferences dialog.
The program ``pythonx.x`` runs python scripts from the command line. The program ``pythonx.x`` runs python scripts from the command line.
Previously, various compatibility aliases were also installed, including Previously, various compatibility aliases were also installed, including
``pythonwx.x`` which in early releases of Python on OS X was required to run ``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. GUI programs. As of 3.4.0, the ``pythonwx.x`` aliases are no longer installed.
How do I create a binary distribution? How do I create a binary distribution?
@ -288,18 +294,17 @@ installer package will create links to the documentation for use by IDLE,
pydoc, shell users, and Finder user. pydoc, shell users, and Finder user.
The script will build a universal binary so you'll therefore have to run this 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 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 available out of the box with macOS 10.4 so you may have to install
additional software beyond what is provided with Xcode 2. OS X 10.5 additional software beyond what is provided with Xcode 2.
provides a recent enough system Python (in ``/usr/bin``) to build It should be possible to use SDKs and/or older
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 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 on a newer system but this may not be completely foolproof so the resulting
executables, shared libraries, and ``.so`` bundles should be carefully executables, shared libraries, and ``.so`` bundles should be carefully
examined and tested on all supported systems for proper dynamic linking examined and tested on all supported systems for proper dynamic linking
dependencies. It is safest to build the distribution on a system running the 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 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 /. use your normal build directory nor does it install into /.
@ -333,7 +338,7 @@ Uninstalling a framework install, including the binary installer
Uninstalling a framework can be done by manually removing all bits that got installed. 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. 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 The main bit of a framework install is the framework itself, installed in
``/Library/Frameworks/Python.framework``. This can contain multiple versions ``/Library/Frameworks/Python.framework``. This can contain multiple versions

23
README.rst
View File

@ -62,18 +62,20 @@ On Unix, Linux, BSD, macOS, and Cygwin::
This will install Python as ``python3``. This will install Python as ``python3``.
You can pass many options to the configure script; run ``./configure --help`` 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``; to find out more. On macOS case-insensitive file systems and on Cygwin,
elsewhere it's just ``python``. 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 Building a complete Python installation requires the use of various
OpenSSL or some other SSL software along with Homebrew or another package manager. additional third-party libraries, depending on your build platform and
If issues persist, see https://devguide.python.org/setup/#macos-and-os-x for more configure options. Not all standard library modules are buildable or
information. useable on all platforms. Refer to the
`Install dependencies <https://devguide.python.org/setup/#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 On macOS, there are additional configure and build options related
should use ``make frameworkinstall`` to do the installation. Note that this to macOS framework and universal builds. Refer to `Mac/README.rst
installs the Python executable in a place that is not normally on your PATH, <https://github.com/python/cpython/blob/master/Mac/README.rst>`_.
you may want to set up a symlink in ``/usr/local/bin``.
On Windows, see `PCbuild/readme.txt On Windows, see `PCbuild/readme.txt
<https://github.com/python/cpython/blob/master/PCbuild/readme.txt>`_. <https://github.com/python/cpython/blob/master/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 Optimization (LTO) on some platforms. For more details, see the sections
below. below.
Profile Guided Optimization Profile Guided Optimization
^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^