an Installer package from the installation plus other files in ``resources``
and ``scripts`` and placed that on a ``.dmg`` disk image.
-For Python 2.7.x and 3.2.x, PSF practice is to build two installer variants
+For Python 2.7.x and 3.x, 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.3.9 through (at least) 10.8::
+Beginning with Python 2.7.8, we plan to drop binary installer support for
+Mac OS X 10.3.9 and 10.4.x systems. To ease the transition, for Python 2.7.7
+only there will be three installers provided:
+
+1. DEPRECATED - 32-bit-only, i386 and PPC universal, capable on running on all
+ machines supported by Mac OS X 10.3.9 through (at least) 10.9::
/usr/bin/python build-installer.py \
--sdk-path=/Developer/SDKs/MacOSX10.4u.sdk \
- 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. 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::
+
+ /usr/bin/python build-installer.py \
+ --sdk-path=/Developer/SDKs/MacOSX10.5.sdk \
+ --universal-archs=32-bit \
+ --dep-target=10.5
-2. 64-bit / 32-bit, x86_64 and i386 universal, for OS X 10.6 (and later)::
+ - builds the following third-party libraries
+
+ * NCurses 5.9
+ * SQLite 3.7.13
+ * Oracle Sleepycat DB 4.8 (Python 2.x only)
+
+ - 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``
+ * 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``
+ * Note Xcode 4.* does not support building for PPC so cannot be used for this build
+
+3. 64-bit / 32-bit, x86_64 and i386 universal, for OS X 10.6 (and later)::
/usr/bin/python build-installer.py \
--sdk-path=/Developer/SDKs/MacOSX10.6.sdk \
* NCurses 5.9 (http://bugs.python.org/issue15037)
* SQLite 3.7.13
+ * Oracle Sleepycat DB 4.8 (Python 2.x only)
- uses system-supplied versions of third-party libraries
* readline module links with Apple BSD editline (libedit)
- * builds Oracle Sleepycat DB 4.8 (Python 2.x only)
- - requires ActiveState Tcl/Tk 8.5.9 (or later) to be installed for building
+ - requires ActiveState Tcl/Tk 8.5.15 (or later) to be installed for building
- recommended build environment:
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 4 releases (Xcode 4.5.x
- as of this writing), there are still some open issues when
- building Python and there has not yet been the level of exposure in
- production environments that the Xcode 3 gcc-4.2 compiler has had.
+ 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.
General Prerequisites
-============
-MacOSX Notes
-============
+=========================
+Python on Mac OS X README
+=========================
+
+:Authors:
+ Jack Jansen (2004-07),
+ Ronald Oussoren (2010-04),
+ Ned Deily (2014-05)
+
+:Version: 2.7.7
This document provides a quick overview of some Mac OS X specific features in
the Python distribution.
-Mac-specific arguments to configure
-===================================
+OS X specific arguments to configure
+====================================
* ``--enable-framework[=DIR]``
_`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 it installed
+ 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
+ $ ./configure --enable-framework=/Users/ronald/Library/Frameworks
$ make && make install
This will install the framework itself in ``/Users/ronald/Library/Frameworks``,
Create a universal binary build of Python. This can be used with both
regular and framework builds.
- The optional argument specifies which OSX SDK should be used to perform the
- build. This defaults to ``/Developer/SDKs/MacOSX.10.4u.sdk``, specify
- ``/`` when building on a 10.5 system, especially when building 64-bit code.
+ The optional argument specifies which OS X SDK should be used to perform the
+ build. This defaults to ``/Developer/SDKs/MacOSX.10.4u.sdk``. When building
+ on OS X 10.5 or later, you can specify ``/`` to use the installed system
+ headers rather than an SDK.
See the section _`Building and using a universal binary of Python on Mac OS X`
for more information.
1. What is a universal binary
-----------------------------
-A universal binary build of Python contains object code for both PPC and i386
-and can therefore run at native speed on both classic powerpc based macs and
-the newer intel based macs.
+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
------------------------------------
$ make install
This flag can be used with a framework build of python, but also with a classic
-unix build. Either way you will have to build python on Mac OS X 10.4 (or later)
-with Xcode 2.1 (or later). You also have to install the 10.4u SDK when
-installing Xcode.
+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.
The option ``--enable-universalsdk`` has an optional argument to specify an
-SDK, which defaults to the 10.4u SDK. When you build on OSX 10.5 or later
+SDK, which defaults to the 10.4u SDK. When you build on OS X 10.5 or later
you can use the system headers instead of an SDK::
$ ./configure --enable-universalsdk=/
Python Developer's Guide (http://docs.python.org/devguide/setup.html)
for more information.
-2.1 Flavours of universal binaries
-..................................
+2.1 Flavors of universal binaries
+.................................
-It is possible to build a number of flavours of the universal binary build,
-the default is a 32-bit only binary (i386 and ppc). The flavour can be
+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). Note that starting with
+Xcode 4, the build tools no longer support ppc. The flavor can be
specified using the option ``--with-universal-archs=VALUE``. The following
values are available:
+ * ``intel``: ``i386``, ``x86_64``
+
* ``32-bit``: ``ppc``, ``i386``
+ * ``3-way``: ``i386``, ``x86_64``, ``ppc``
+
* ``64-bit``: ``ppc64``, ``x86_64``
* ``all``: ``ppc``, ``ppc64``, ``i386``, ``x86_64``
- * ``3-way``: ``ppc``, ``i386`` and ``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 an 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:
- * ``intel``: ``i386``, ``x86_64``
+ * 10.4u SDK with Xcode 2 supports ``32-bit`` only
-To build a universal binary that includes a 64-bit architecture, you must build
-on a system running OSX 10.5 or later. The ``all`` flavour can only be built on
-OSX 10.5.
+ * 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``
-The makefile for a framework build will install ``python32`` and ``pythonw32``
-binaries when the universal architecures includes at least one 32-bit architecture
-(that is, for all flavours but ``64-bit``).
+ * 10.6 SDK with Xcode 4 supports ``intel`` only
-Running a specific archicture
-.............................
+ * 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 ``python2.7-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::
wrapper tools that execute the real interpreter without ensuring that the
real interpreter runs with the same architecture.
+Using ``arch`` is not a perfect solution as the selected architecture will
+not automatically carry through to subprocesses launched by programs and tests
+under that Python. If you want to ensure that Python interpreters launched in
+subprocesses also run in 32-bit-mode if the main interpreter does, use
+a ``python2.7-32`` binary and use the value of ``sys.executable`` as the
+``subprocess`` ``Popen`` executable value.
+
Building and using a framework-based Python on Mac OS X.
========================================================
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 fullblown MacOSX application (a ".app" bundle).
+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/MacPython 2.6". This simplifies matters for users installing
+"/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
+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?
3. Do I need extra packages?
----------------------------
-Yes, probably. If you want Tkinter support you need to get the OSX AquaTk
-distribution, this is installed by default on Mac OS X 10.4 or later. If
-you want wxPython you need to get that. If you want Cocoa you need to get
-PyObjC.
+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 (fullblown OSX .app applications, that is) in
-"/Applications/MacPython 2.6", and a hidden helper application Python.app
-inside the Python.framework, and unix tools "python" and "pythonw" into
-/usr/local/bin. In addition it has a target "installmacsubtree" that installs
+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 "python" and "pythonw" 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::
+in the sequence
- $ ./configure --enable-framework
- $ make
- $ make install
+ 1. ./configure --enable-framework
-This sequence will put the framework in /Library/Framework/Python.framework,
-the applications in "/Applications/MacPython 2.6" and the unix tools in
-/usr/local/bin.
+ 2. make
+
+ 3. make install
-It is possible to select a different name for the framework using the configure
-option ``--with-framework-name=NAME``. This makes it possible to have several
-parallel installs of a Python framework.
+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, has only been tested very lightly. This
-can be done by configuring with --enable-framework=$HOME/Library/Frameworks.
-The other two directories, "/Applications/MacPython-2.6" and /usr/local/bin,
-will then also be deposited in $HOME. This is sub-optimal for the unix tools,
-which you would want in $HOME/bin, but there is no easy way to fix this right
-now.
+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.
-"PythonLauncher.app" is a helper application that will handle things when you
+"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 "alt" key depressed while dragging or double-clicking a
-script to set runtime options. These options can be set once and for all
-through PythonLauncher's preferences dialog.
+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.
-"BuildApplet.app" creates an applet from a Python script. Drop the script on it
-and out comes a full-featured MacOS application. BuildApplet.app is now
+"Build Applet.app" creates an applet from a Python script. Drop the script on it
+and out comes a full-featured Mac OS X application. "Build Applet.app" is now
deprecated and has been removed in Python 3. As of OS X 10.8, Xcode 4 no
longer supplies the headers for the deprecated QuickDraw APIs used by
the EasyDialogs module making BuildApplet unusable as an app. It will
not be built by the Mac/Makefile in this case.
-The commandline scripts /usr/local/bin/python and pythonw can be used to run
-non-GUI and GUI python scripts from the command line, respectively.
+The program ``pythonx.x`` runs python scripts from the command line. Various
+compatibility aliases are also installed, including ``pythonwx.x`` which
+in early releases of Python on OS X was required to run GUI programs. In
+current releases, the ``pythonx.x`` and ``pythonwx.x`` commands are identical
+and the use of ``pythonwx.x`` should be avoided as it has been removed in
+current versions of Python 3.
How do I create a binary distribution?
======================================
-Go to the directory "Mac/OSX/BuildScript". There you'll find a script
-"build-installer.py" that does all the work. This will download and build
+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.
+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, 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.
+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 /.
configure: WARNING: ## -------------------------------------- ##
This almost always means you are trying to build a universal binary for
-Python and have libaries in ``/usr/local`` that don't contain the required
+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 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.
-Sadly enough OSX does not have a central uninstaller.
+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
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``.
-Odds and ends
-=============
-Something to take note of is that the ".rsrc" files in the distribution are
-not actually resource files, they're AppleSingle encoded resource files. The
-macresource module and the Mac/OSX/Makefile cater for this, and create
-".rsrc.df.rsrc" files on the fly that are normal datafork-based resource
-files.
+Resources
+=========
+
+ * http://www.python.org/download/mac/
+
+ * http://www.python.org/community/sigs/current/pythonmac-sig/
- Jack Jansen, Jack.Jansen@cwi.nl, 15-Jul-2004.
- Ronald Oussoren, RonaldOussoren@mac.com, 30-April-2010
+ * http://docs.python.org/devguide/
projects / python / commitdiff