mirror of
https://github.com/python/cpython
synced 2024-09-05 00:05:39 +00:00
358 lines
16 KiB
Plaintext
358 lines
16 KiB
Plaintext
=========================
|
|
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 (http://docs.python.org/devguide/setup.html)
|
|
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 <VERSION>" where ``<VERSION>`` 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 <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
|
|
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 <VERSION>`` 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-<VERSION>`` 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 <VERSION>", 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/
|
|
|
|
* http://docs.python.org/devguide/ |