1
=========================
2
Python on Mac OS X README
3
=========================
7
Ronald Oussoren (2010-04),
12
This document provides a quick overview of some Mac OS X specific features in
13
the Python distribution.
15
* ``--enable-framework[=DIR]``
17
If this argument is specified the build will create a Python.framework rather
18
than a traditional Unix install. See the section
19
_`Building and using a framework-based Python on Mac OS X` for more
20
information on frameworks.
22
If the optional directory argument is specified the framework is installed
23
into that directory. This can be used to install a python framework into
26
$ ./configure --enable-framework=/Users/ronald/Library/Frameworks
27
$ make && make install
29
This will install the framework itself in ``/Users/ronald/Library/Frameworks``,
30
the applications in a subdirectory of ``/Users/ronald/Applications`` and the
31
command-line tools in ``/Users/ronald/bin``.
33
* ``--with-framework-name=NAME``
35
Specify the name for the python framework, defaults to ``Python``. This option
36
is only valid when ``--enable-framework`` is specified.
38
* ``--enable-universalsdk[=PATH]``
40
Create a universal binary build of Python. This can be used with both
41
regular and framework builds.
43
The optional argument specifies which OS X SDK should be used to perform the
44
build. If xcodebuild is available and configured, this defaults to
45
the Xcode default MacOS X SDK, otherwise ``/Developer/SDKs/MacOSX.10.4u.sdk``
46
if available or ``/`` if not.
48
See the section _`Building and using a universal binary of Python on Mac OS X`
51
* ``--with-univeral-archs=VALUE``
53
Specify the kind of universal binary that should be created. This option is
54
only valid when ``--enable-universalsdk`` is specified. The default is
55
``32-bit`` if a building with a SDK that supports PPC, otherwise defaults
59
Building and using a universal binary of Python on Mac OS X
60
===========================================================
62
1. What is a universal binary
63
-----------------------------
65
A universal binary build of Python contains object code for more than one
66
CPU architecture. A universal OS X executable file or library combines the
67
architecture-specific code into one file and can therefore run at native
68
speed on all supported architectures. Universal files were introduced in
69
OS X 10.4 to add support for Intel-based Macs to the existing PowerPC (PPC)
70
machines. In OS X 10.5 support was extended to 64-bit Intel and 64-bit PPC
71
architectures. It is possible to build Python with various combinations
72
of architectures depending on the build tools and OS X version in use.
74
2. How do I build a universal binary
75
------------------------------------
77
You can enable universal binaries by specifying the "--enable-universalsdk"
80
$ ./configure --enable-universalsdk
84
This flag can be used with a framework build of python, but also with a classic
85
unix build. Universal builds were first supported with OS X 10.4 with Xcode 2.1
86
and the 10.4u SDK. Starting with Xcode 3 and OS X 10.5, more configurations are
89
2.1 Flavors of universal binaries
90
.................................
92
It is possible to build a number of flavors of the universal binary build,
93
the default is a 32-bit only binary (i386 and ppc) in build environments that
94
support ppc (10.4 with Xcode 2, 10.5 and 10.6 with Xcode 3) or an
95
Intel-32/-64-bit binary (i386 and X86_64) in build environments that do not
96
support ppc (Xcode 4 on 10.6 and later systems). The flavor can be specified
97
using the configure option ``--with-universal-archs=VALUE``. The following
100
* ``intel``: ``i386``, ``x86_64``
102
* ``intel-32``: ``i386``
104
* ``32-bit``: ``ppc``, ``i386``
106
* ``3-way``: ``i386``, ``x86_64``, ``ppc``
108
* ``64-bit``: ``ppc64``, ``x86_64``
110
* ``all``: ``ppc``, ``ppc64``, ``i386``, ``x86_64``
112
To build a universal binary that includes a 64-bit architecture, you must build
113
on a system running OS X 10.5 or later. The ``all`` and ``64-bit`` flavors can
114
only be built with an 10.5 SDK because ``ppc64`` support was only included with
115
OS X 10.5. Although legacy ``ppc`` support was included with Xcode 3 on OS X
116
10.6, it was removed in Xcode 4, versions of which were released on OS X 10.6
117
and which is the current standard for OS X 10.7 and 10.8. To summarize, the
118
following combinations of SDKs and universal-archs flavors are available:
120
* 10.4u SDK with Xcode 2 supports ``32-bit`` only
122
* 10.5 SDK with Xcode 3.1.x supports all flavors
124
* 10.6 SDK with Xcode 3.2.x supports ``intel``, ``3-way``, and ``32-bit``
126
* 10.6 SDK with Xcode 4 supports ``intel`` only
128
* 10.7 and 10.8 SDKs with Xcode 4 support ``intel`` only
130
The makefile for a framework build will also install ``python3.4-32``
131
binaries when the universal architecture includes at least one 32-bit
132
architecture (that is, for all flavors but ``64-bit``).
134
Running a specific architecture
135
...............................
137
You can run code using a specific architecture using the ``arch`` command::
141
Or to explicitly run in 32-bit mode, regardless of the machine hardware::
143
$ arch -i386 -ppc python
145
NOTE: When you're using a framework install of Python this requires at least
146
Python 2.7 or 3.2, in earlier versions the python (and pythonw) commands are
147
wrapper tools that execute the real interpreter without ensuring that the
148
real interpreter runs with the same architecture.
150
Using ``arch`` is not a perfect solution as the selected architecture will
151
not automatically carry through to subprocesses launched by programs and tests
152
under that Python. If you want to ensure that Python interpreters launched in
153
subprocesses also run in 32-bit-mode if the main interpreter does, use
154
a ``python3.4-32`` binary and use the value of ``sys.executable`` as the
155
``subprocess`` ``Popen`` executable value.
158
Building and using a framework-based Python on Mac OS X.
159
========================================================
162
1. Why would I want a framework Python instead of a normal static Python?
163
--------------------------------------------------------------------------
165
The main reason is because you want to create GUI programs in Python. With the
166
exception of X11/XDarwin-based GUI toolkits all GUI programs need to be run
167
from a Mac OSX application bundle (".app").
169
While it is technically possible to create a .app without using frameworks you
170
will have to do the work yourself if you really want this.
172
A second reason for using frameworks is that they put Python-related items in
173
only two places: "/Library/Framework/Python.framework" and
174
"/Applications/Python <VERSION>" where ``<VERSION>`` can be e.g. "3.4",
175
"2.7", etc. This simplifies matters for users installing
176
Python from a binary distribution if they want to get rid of it again. Moreover,
177
due to the way frameworks work, a user without admin privileges can install a
178
binary distribution in his or her home directory without recompilation.
180
2. How does a framework Python differ from a normal static Python?
181
------------------------------------------------------------------
183
In everyday use there is no difference, except that things are stored in
184
a different place. If you look in /Library/Frameworks/Python.framework
185
you will see lots of relative symlinks, see the Apple documentation for
186
details. If you are used to a normal unix Python file layout go down to
187
Versions/Current and you will see the familiar bin and lib directories.
189
3. Do I need extra packages?
190
----------------------------
192
Yes, probably. If you want Tkinter support you need to get the OSX AquaTk
193
distribution, this is installed by default on Mac OS X 10.4 or later. Be
194
aware, though, that the Cocoa-based AquaTk's supplied starting with OS X
195
10.6 have proven to be unstable. If possible, you should consider
196
installing a newer version before building on OS X 10.6 or later, such as
197
the ActiveTcl 8.5. See http://www.python.org/download/mac/tcltk/. If you
198
are building with an SDK, ensure that the newer Tcl and Tk frameworks are
199
seen in the SDK's ``Library/Frameworks`` directory; you may need to
200
manually create symlinks to their installed location, ``/Library/Frameworks``.
201
If you want wxPython you need to get that.
202
If you want Cocoa you need to get PyObjC.
204
4. How do I build a framework Python?
205
-------------------------------------
207
This directory contains a Makefile that will create a couple of python-related
208
applications (full-blown OSX .app applications, that is) in
209
"/Applications/Python <VERSION>", and a hidden helper application Python.app
210
inside the Python.framework, and unix tools "python" and "pythonw" into
211
/usr/local/bin. In addition it has a target "installmacsubtree" that installs
212
the relevant portions of the Mac subtree into the Python.framework.
214
It is normally invoked indirectly through the main Makefile, as the last step
217
1. ./configure --enable-framework
223
This sequence will put the framework in ``/Library/Framework/Python.framework``,
224
the applications in ``/Applications/Python <VERSION>`` and the unix tools in
227
Installing in another place, for instance ``$HOME/Library/Frameworks`` if you
228
have no admin privileges on your machine, is possible. This can be accomplished
229
by configuring with ``--enable-framework=$HOME/Library/Frameworks``.
230
The other two directories will then also be installed in your home directory,
231
at ``$HOME/Applications/Python-<VERSION>`` and ``$HOME/bin``.
233
If you want to install some part, but not all, read the main Makefile. The
234
frameworkinstall is composed of a couple of sub-targets that install the
235
framework itself, the Mac subtree, the applications and the unix tools.
237
There is an extra target frameworkinstallextras that is not part of the
238
normal frameworkinstall which installs the Tools directory into
239
"/Applications/Python <VERSION>", this is useful for binary
242
What do all these programs do?
243
===============================
245
"IDLE.app" is an integrated development environment for Python: editor,
248
"PythonLauncher.app" is a helper application that will handle things when you
249
double-click a .py, .pyc or .pyw file. For the first two it creates a Terminal
250
window and runs the scripts with the normal command-line Python. For the
251
latter it runs the script in the Python.app interpreter so the script can do
252
GUI-things. Keep the ``Option`` key depressed while dragging or double-clicking
253
a script to set runtime options. These options can be set persistently
254
through PythonLauncher's preferences dialog.
256
The program ``pythonx.x`` runs python scripts from the command line. Various
257
compatibility aliases are also installed, including ``pythonwx.x`` which
258
in early releases of Python on OS X was required to run GUI programs. In
259
current releases, the ``pythonx.x`` and ``pythonwx.x`` commands are identical.
261
How do I create a binary distribution?
262
======================================
264
Download and unpack the source release from http://www.python.org/download/.
265
Go to the directory ``Mac/BuildScript``. There you will find a script
266
``build-installer.py`` that does all the work. This will download and build
267
a number of 3rd-party libaries, configures and builds a framework Python,
268
installs it, creates the installer package files and then packs this in a
269
DMG image. The script also builds an HTML copy of the current Python
270
documentation set for this release for inclusion in the framework. The
271
installer package will create links to the documentation for use by IDLE,
272
pydoc, shell users, and Finder user.
274
The script will build a universal binary so you'll therefore have to run this
275
script on Mac OS X 10.4 or later and with Xcode 2.1 or later installed.
276
However, the Python build process itself has several build dependencies not
277
available out of the box with OS X 10.4 so you may have to install
278
additional software beyond what is provided with Xcode 2. OS X 10.5
279
provides a recent enough system Python (in ``/usr/bin``) to build
280
the Python documentation set. It should be possible to use SDKs and/or older
281
versions of Xcode to build installers that are compatible with older systems
282
on a newer system but this may not be completely foolproof so the resulting
283
executables, shared libraries, and ``.so`` bundles should be carefully
284
examined and tested on all supported systems for proper dynamic linking
285
dependencies. It is safest to build the distribution on a system running the
286
minimum OS X version supported.
288
All of this is normally done completely isolated in /tmp/_py, so it does not
289
use your normal build directory nor does it install into /.
291
Because of the way the script locates the files it needs you have to run it
292
from within the BuildScript directory. The script accepts a number of
293
command-line arguments, run it with --help for more information.
298
The configure script sometimes emits warnings like the one below::
300
configure: WARNING: libintl.h: present but cannot be compiled
301
configure: WARNING: libintl.h: check for missing prerequisite headers?
302
configure: WARNING: libintl.h: see the Autoconf documentation
303
configure: WARNING: libintl.h: section "Present But Cannot Be Compiled"
304
configure: WARNING: libintl.h: proceeding with the preprocessor's result
305
configure: WARNING: libintl.h: in the future, the compiler will take precedence
306
configure: WARNING: ## -------------------------------------- ##
307
configure: WARNING: ## Report this to http://bugs.python.org/ ##
308
configure: WARNING: ## -------------------------------------- ##
310
This almost always means you are trying to build a universal binary for
311
Python and have libraries in ``/usr/local`` that don't contain the required
312
architectures. Temporarily move ``/usr/local`` aside to finish the build.
315
Uninstalling a framework install, including the binary installer
316
================================================================
318
Uninstalling a framework can be done by manually removing all bits that got installed.
319
That's true for both installations from source and installations using the binary installer.
320
OS X does not provide a central uninstaller.
322
The main bit of a framework install is the framework itself, installed in
323
``/Library/Frameworks/Python.framework``. This can contain multiple versions
324
of Python, if you want to remove just one version you have to remove the
325
version-specific subdirectory: ``/Library/Frameworks/Python.framework/Versions/X.Y``.
326
If you do that, ensure that ``/Library/Frameworks/Python.framework/Versions/Current``
327
is a symlink that points to an installed version of Python.
329
A framework install also installs some applications in ``/Applications/Python X.Y``,
331
And lastly a framework installation installs files in ``/usr/local/bin``, all of
332
them symbolic links to files in ``/Library/Frameworks/Python.framework/Versions/X.Y/bin``.
338
* http://www.python.org/download/mac/
340
* http://www.python.org/community/sigs/current/pythonmac-sig/
342
* http://docs.python.org/devguide/
b'\\ No newline at end of file'
added
removed
Mac/README
