Update build docs for macOS (GH-16844)
This commit is contained in:
Ned Deily
GitHub
parent
dedb99acdb
commit
4ae38ba52a
|
|
@ -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,11 +170,6 @@ 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
|
||||
|
|
@ -173,8 +177,8 @@ 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?
|
||||
|
|
@ -182,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
|
||||
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,7 +295,7 @@ 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
|
||||
|
|
@ -299,18 +303,17 @@ 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
|
||||
36
README
36
README
|
|
@ -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
|
||||
----------------------------
|
||||
|
|
|
|||
Loading…
Reference in New Issue