1=========================
2Python on Mac OS X README
3=========================
4
5:Authors:
6    Jack Jansen (2004-07),
7    Ronald Oussoren (2010-04),
8    Ned Deily (2014-05)
9
10:Version: 2.7.15
11
12This document provides a quick overview of some Mac OS X specific features in
13the Python distribution.
14
15OS X specific arguments to configure
16====================================
17
18* ``--enable-framework[=DIR]``
19
20  If this argument is specified the build will create a Python.framework rather
21  than a traditional Unix install. See the section
22  _`Building and using a framework-based Python on Mac OS X` for more
23  information on frameworks.
24
25  If the optional directory argument is specified the framework is installed
26  into that directory. This can be used to install a python framework into
27  your home directory::
28
29     $ ./configure --enable-framework=/Users/ronald/Library/Frameworks
30     $ make && make install
31
32  This will install the framework itself in ``/Users/ronald/Library/Frameworks``,
33  the applications in a subdirectory of ``/Users/ronald/Applications`` and the
34  command-line tools in ``/Users/ronald/bin``.
35
36* ``--with-framework-name=NAME``
37
38  Specify the name for the python framework, defaults to ``Python``. This option
39  is only valid when ``--enable-framework`` is specified.
40
41* ``--enable-universalsdk[=PATH]``
42
43  Create a universal binary build of Python. This can be used with both
44  regular and framework builds.
45
46  The optional argument specifies which OS X SDK should be used to perform the
47  build.  If xcodebuild is available and configured, this defaults to
48  the Xcode default MacOS X SDK, otherwise ``/Developer/SDKs/MacOSX.10.4u.sdk``
49  if available or ``/`` if not.  When building on OS X 10.5 or later, you can
50  specify ``/`` to use the installed system headers rather than an SDK.  As of
51  OS X 10.9, you should install the optional system headers from the Command
52  Line Tools component using ``xcode-select``::
53
54     $ sudo xcode-select --install
55
56  See the section _`Building and using a universal binary of Python on Mac OS X`
57  for more information.
58
59* ``--with-universal-archs=VALUE``
60
61  Specify the kind of universal binary that should be created. This option is
62  only valid when ``--enable-universalsdk`` is specified.  The default is
63  ``32-bit`` if a building with a SDK that supports PPC, otherwise defaults
64  to ``intel``.
65
66
67Building and using a universal binary of Python on Mac OS X
68===========================================================
69
701. What is a universal binary
71-----------------------------
72
73A universal binary build of Python contains object code for more than one
74CPU architecture.  A universal OS X executable file or library combines the
75architecture-specific code into one file and can therefore run at native
76speed on all supported architectures.  Universal files were introduced in
77OS X 10.4 to add support for Intel-based Macs to the existing PowerPC (PPC)
78machines.  In OS X 10.5 support was extended to 64-bit Intel and 64-bit PPC
79architectures.  It is possible to build Python with various combinations
80of architectures depending on the build tools and OS X version in use.
81
822. How do I build a universal binary
83------------------------------------
84
85You can enable universal binaries by specifying the "--enable-universalsdk"
86flag to configure::
87
88  $ ./configure --enable-universalsdk
89  $ make
90  $ make install
91
92This flag can be used with a framework build of python, but also with a classic
93unix build. Universal builds were first supported with OS X 10.4 with Xcode 2.1
94and the 10.4u SDK.  Starting with Xcode 3 and OS X 10.5, more configurations are
95available.
96
97In general, universal builds depend on specific features provided by the
98Apple-supplied compilers and other build tools included in Apple's Xcode
99development tools.  You should install Xcode and the command line tools
100component appropriate for the OS X release you are running on.  See the
101Python Developer's Guide (https://devguide.python.org/setup/)
102for more information.
103
1042.1 Flavors of universal binaries
105.................................
106
107It is possible to build a number of flavors of the universal binary build,
108the default is a 32-bit only binary (i386 and ppc) in build environments that
109support ppc (10.4 with Xcode 2, 10.5 and 10.6 with Xcode 3) or an
110Intel-32/-64-bit binary (i386 and X86_64) in build environments that do not
111support ppc (Xcode 4 on 10.6 and later systems).  The flavor can be specified
112using the configure option ``--with-universal-archs=VALUE``. The following
113values are available:
114
115  * ``intel``:	  ``i386``, ``x86_64``
116
117  * ``intel-32``: ``i386``
118
119  * ``intel-64``: ``x86_64``
120
121  * ``32-bit``:   ``ppc``, ``i386``
122
123  * ``3-way``:	  ``i386``, ``x86_64``, ``ppc``
124
125  * ``64-bit``:   ``ppc64``, ``x86_64``
126
127  * ``all``:      ``ppc``, ``ppc64``, ``i386``, ``x86_64``
128
129To build a universal binary that includes a 64-bit architecture, you must build
130on a system running OS X 10.5 or later.  The ``all`` and ``64-bit`` flavors can
131only be built with a 10.5 SDK because ``ppc64`` support was only included with
132OS X 10.5.  Although legacy ``ppc`` support was included with Xcode 3 on OS X
13310.6, it was removed in Xcode 4, versions of which were released on OS X 10.6
134and which is the standard for OS X 10.7.  To summarize, the
135following combinations of SDKs and universal-archs flavors are available:
136
137  * 10.4u SDK with Xcode 2 supports ``32-bit`` only
138
139  * 10.5 SDK with Xcode 3.1.x supports all flavors
140
141  * 10.6 SDK with Xcode 3.2.x supports ``intel``, ``3-way``, and ``32-bit``
142
143  * 10.6 SDK with Xcode 4 supports ``intel`` only
144
145  * 10.7 and 10.8 SDKs with Xcode 4 support ``intel`` only
146
147  * 10.8 and 10.9 SDKs with Xcode 5 support ``intel`` only
148
149The makefile for a framework build will also install ``python2.7-32``
150binaries when the universal architecture includes at least one 32-bit
151architecture (that is, for all flavors but ``64-bit``).
152
153Running a specific architecture
154...............................
155
156You can run code using a specific architecture using the ``arch`` command::
157
158   $ arch -i386 python
159
160Or to explicitly run in 32-bit mode, regardless of the machine hardware::
161
162   $ arch -i386 -ppc python
163
164NOTE: When you're using a framework install of Python this requires at least
165Python 2.7 or 3.2, in earlier versions the python (and pythonw) commands are
166wrapper tools that execute the real interpreter without ensuring that the
167real interpreter runs with the same architecture.
168
169Using ``arch`` is not a perfect solution as the selected architecture will
170not automatically carry through to subprocesses launched by programs and tests
171under that Python.  If you want to ensure that Python interpreters launched in
172subprocesses also run in 32-bit-mode if the main interpreter does, use
173a ``python2.7-32`` binary and use the value of ``sys.executable`` as the
174``subprocess`` ``Popen`` executable value.
175
176Building and using a framework-based Python on Mac OS X.
177========================================================
178
179
1801. Why would I want a framework Python instead of a normal static Python?
181--------------------------------------------------------------------------
182
183The main reason is because you want to create GUI programs in Python. With the
184exception of X11/XDarwin-based GUI toolkits all GUI programs need to be run
185from a Mac OS X application bundle (".app").
186
187While it is technically possible to create a .app without using frameworks you
188will have to do the work yourself if you really want this.
189
190A second reason for using frameworks is that they put Python-related items in
191only two places: "/Library/Framework/Python.framework" and
192"/Applications/Python <VERSION>" where ``<VERSION>`` can be e.g. "3.4",
193"2.7", etc.  This simplifies matters for users installing
194Python from a binary distribution if they want to get rid of it again. Moreover,
195due to the way frameworks work, a user without admin privileges can install a
196binary distribution in his or her home directory without recompilation.
197
1982. How does a framework Python differ from a normal static Python?
199------------------------------------------------------------------
200
201In everyday use there is no difference, except that things are stored in
202a different place. If you look in /Library/Frameworks/Python.framework
203you will see lots of relative symlinks, see the Apple documentation for
204details. If you are used to a normal unix Python file layout go down to
205Versions/Current and you will see the familiar bin and lib directories.
206
2073. Do I need extra packages?
208----------------------------
209
210Yes, probably.  If you want Tkinter support you need to get the OS X AquaTk
211distribution, this is installed by default on Mac OS X 10.4 or later.  Be
212aware, though, that the Cocoa-based AquaTk's supplied starting with OS X
21310.6 have proven to be unstable.  If possible, you should consider
214installing a newer version before building on OS X 10.6 or later, such as
215the ActiveTcl 8.5.  See http://www.python.org/download/mac/tcltk/.  If you
216are building with an SDK, ensure that the newer Tcl and Tk frameworks are
217seen in the SDK's ``Library/Frameworks`` directory; you may need to
218manually create symlinks to their installed location, ``/Library/Frameworks``.
219If you want wxPython you need to get that.
220If you want Cocoa you need to get PyObjC.
221
2224. How do I build a framework Python?
223-------------------------------------
224
225This directory contains a Makefile that will create a couple of python-related
226applications (full-blown OS X .app applications, that is) in
227"/Applications/Python <VERSION>", and a hidden helper application Python.app
228inside the Python.framework, and unix tools including "python" into
229/usr/local/bin.  In addition it has a target "installmacsubtree" that installs
230the relevant portions of the Mac subtree into the Python.framework.
231
232It is normally invoked indirectly through the main Makefile, as the last step
233in the sequence
234
235 1. ./configure --enable-framework
236
237 2. make
238
239 3. make install
240
241This sequence will put the framework in ``/Library/Framework/Python.framework``,
242the applications in ``/Applications/Python <VERSION>`` and the unix tools in
243``/usr/local/bin``.
244
245Installing in another place, for instance ``$HOME/Library/Frameworks`` if you
246have no admin privileges on your machine, is possible. This can be accomplished
247by configuring with ``--enable-framework=$HOME/Library/Frameworks``.
248The other two directories will then also be installed in your home directory,
249at ``$HOME/Applications/Python-<VERSION>`` and ``$HOME/bin``.
250
251If you want to install some part, but not all, read the main Makefile. The
252frameworkinstall is composed of a couple of sub-targets that install the
253framework itself, the Mac subtree, the applications and the unix tools.
254
255There is an extra target frameworkinstallextras that is not part of the
256normal frameworkinstall which installs the Tools directory into
257"/Applications/Python <VERSION>", this is useful for binary
258distributions.
259
260What do all these programs do?
261===============================
262
263"IDLE.app" is an integrated development environment for Python: editor,
264debugger, etc.
265
266"Python Launcher.app" is a helper application that will handle things when you
267double-click a .py, .pyc or .pyw file. For the first two it creates a Terminal
268window and runs the scripts with the normal command-line Python. For the
269latter it runs the script in the Python.app interpreter so the script can do
270GUI-things. Keep the ``Option`` key depressed while dragging or double-clicking
271a script to set runtime options. These options can be set persistently
272through Python Launcher's preferences dialog.
273
274"Build Applet.app" creates an applet from a Python script. Drop the script on it
275and out comes a full-featured Mac OS X application.  "Build Applet.app" is now
276deprecated and has been removed in Python 3.  As of OS X 10.8, Xcode 4 no
277longer supplies the headers for the deprecated QuickDraw APIs used by
278the EasyDialogs module making BuildApplet unusable as an app.  It will
279not be built by the Mac/Makefile in this case.
280
281The program ``pythonx.x`` runs python scripts from the command line.  Various
282compatibility aliases are also installed, including ``pythonwx.x`` which
283in early releases of Python on OS X was required to run GUI programs.  In
284current releases, the ``pythonx.x`` and ``pythonwx.x`` commands are identical
285and the use of ``pythonwx.x`` should be avoided as it has been removed in
286current versions of Python 3.
287
288How do I create a binary distribution?
289======================================
290
291Download and unpack the source release from http://www.python.org/download/.
292Go to the directory ``Mac/BuildScript``. There you will find a script
293``build-installer.py`` that does all the work. This will download and build
294a number of 3rd-party libaries, configures and builds a framework Python,
295installs it, creates the installer package files and then packs this in a
296DMG image.  The script also builds an HTML copy of the current Python
297documentation set for this release for inclusion in the framework.  The
298installer package will create links to the documentation for use by IDLE,
299pydoc, shell users, and Finder user.
300
301The script will build a universal binary so you'll therefore have to run this
302script on Mac OS X 10.4 or later and with Xcode 2.1 or later installed.
303However, the Python build process itself has several build dependencies not
304available out of the box with OS X 10.4 so you may have to install
305additional software beyond what is provided with Xcode 2.  OS X 10.5
306provides a recent enough system Python (in ``/usr/bin``) to build
307the Python documentation set.  It should be possible to use SDKs and/or older
308versions of Xcode to build installers that are compatible with older systems
309on a newer system but this may not be completely foolproof so the resulting
310executables, shared libraries, and ``.so`` bundles should be carefully
311examined and tested on all supported systems for proper dynamic linking
312dependencies.  It is safest to build the distribution on a system running the
313minimum OS X version supported.
314
315All of this is normally done completely isolated in /tmp/_py, so it does not
316use your normal build directory nor does it install into /.
317
318Because of the way the script locates the files it needs you have to run it
319from within the BuildScript directory. The script accepts a number of
320command-line arguments, run it with --help for more information.
321
322Configure warnings
323==================
324
325The configure script sometimes emits warnings like the one below::
326
327   configure: WARNING: libintl.h: present but cannot be compiled
328   configure: WARNING: libintl.h:     check for missing prerequisite headers?
329   configure: WARNING: libintl.h: see the Autoconf documentation
330   configure: WARNING: libintl.h:     section "Present But Cannot Be Compiled"
331   configure: WARNING: libintl.h: proceeding with the preprocessor's result
332   configure: WARNING: libintl.h: in the future, the compiler will take precedence
333   configure: WARNING:     ## -------------------------------------- ##
334   configure: WARNING:     ## Report this to http://bugs.python.org/ ##
335   configure: WARNING:     ## -------------------------------------- ##
336
337This almost always means you are trying to build a universal binary for
338Python and have libraries in ``/usr/local`` that don't contain the required
339architectures. Temporarily move ``/usr/local`` aside to finish the build.
340
341
342Uninstalling a framework install, including the binary installer
343================================================================
344
345Uninstalling a framework can be done by manually removing all bits that got installed.
346That's true for both installations from source and installations using the binary installer.
347OS X does not provide a central uninstaller.
348
349The main bit of a framework install is the framework itself, installed in
350``/Library/Frameworks/Python.framework``. This can contain multiple versions
351of Python, if you want to remove just one version you have to remove the
352version-specific subdirectory: ``/Library/Frameworks/Python.framework/Versions/X.Y``.
353If you do that, ensure that ``/Library/Frameworks/Python.framework/Versions/Current``
354is a symlink that points to an installed version of Python.
355
356A framework install also installs some applications in ``/Applications/Python X.Y``,
357
358And lastly a framework installation installs files in ``/usr/local/bin``, all of
359them symbolic links to files in ``/Library/Frameworks/Python.framework/Versions/X.Y/bin``.
360
361
362Resources
363=========
364
365  *  http://www.python.org/download/mac/
366
367  *  http://www.python.org/community/sigs/current/pythonmac-sig/
368
369  *  https://devguide.python.org/
370