blob: 6853db44c682bd6890186220524486f8c1c4ce27 [file] [log] [blame]
Thomas Wouters477c8d52006-05-27 19:21:47 +00001============
2MacOSX Notes
3============
Jack Jansen0fdaee72002-08-02 21:45:27 +00004
Thomas Wouters477c8d52006-05-27 19:21:47 +00005This document provides a quick overview of some Mac OS X specific features in
6the Python distribution.
7
Ronald Oussoren86b33c82010-04-30 11:41:56 +00008* ``--enable-framework[=DIR]``
Ronald Oussoren6f6c5622009-12-24 14:03:19 +00009
10 If this argument is specified the build will create a Python.framework rather
11 than a traditional Unix install. See the section
12 _`Building and using a framework-based Python on Mac OS X` for more
13 information on frameworks.
14
Ronald Oussoren86b33c82010-04-30 11:41:56 +000015 If the optional directory argument is specified the framework it installed
16 into that directory. This can be used to install a python framework into
17 your home directory::
18
19 $ configure --enable-framework=/Users/ronald/Library/Frameworks
20 $ make && make install
21
22 This will install the framework itself in ``/Users/ronald/Library/Frameworks``,
23 the applications in a subdirectory of ``/Users/ronald/Applications`` and the
24 command-line tools in ``/Users/ronald/bin``.
25
Ronald Oussoren6f6c5622009-12-24 14:03:19 +000026* ``--with-framework-name=NAME``
27
28 Specify the name for the python framework, defaults to ``Python``. This option
29 is only valid when ``--enable-framework`` is specified.
30
31* ``--enable-universalsdk[=PATH]``
32
33 Create a universal binary build of of Python. This can be used with both
34 regular and framework builds.
35
36 The optional argument specifies which OSX SDK should be used to perform the
37 build. This defaults to ``/Developer/SDKs/MacOSX.10.4u.sdk``, specify
38 ``/`` when building on a 10.5 system, especially when building 64-bit code.
39
40 See the section _`Building and using a universal binary of Python on Mac OS X`
41 for more information.
42
43* ``--with-univeral-archs=VALUE``
44
45 Specify the kind of universal binary that should be created. This option is
46 only valid when ``--enable-universalsdk`` is specified.
47
Thomas Wouters477c8d52006-05-27 19:21:47 +000048
49Building and using a universal binary of Python on Mac OS X
50===========================================================
51
521. What is a universal binary
53-----------------------------
54
55A universal binary build of Python contains object code for both PPC and i386
56and can therefore run at native speed on both classic powerpc based macs and
57the newer intel based macs.
58
592. How do I build a universal binary
60------------------------------------
61
62You can enable universal binaries by specifying the "--enable-universalsdk"
63flag to configure::
64
65 $ ./configure --enable-universalsdk
66 $ make
67 $ make install
68
Ned Deilye742ade2012-03-17 10:29:41 -070069This flag can be used with a framework build of python, but also with a classic
Thomas Wouters477c8d52006-05-27 19:21:47 +000070unix build. Either way you will have to build python on Mac OS X 10.4 (or later)
71with Xcode 2.1 (or later). You also have to install the 10.4u SDK when
72installing Xcode.
73
Ronald Oussoren6f6c5622009-12-24 14:03:19 +0000742.1 Flavours of universal binaries
75..................................
76
77It is possible to build a number of flavours of the universal binary build,
78the default is a 32-bit only binary (i386 and ppc). The flavour can be
79specified using the option ``--with-universal-archs=VALUE``. The following
80values are available:
81
82 * ``32-bit``: ``ppc``, ``i386``
83
84 * ``64-bit``: ``ppc64``, ``x86_64``
85
86 * ``all``: ``ppc``, ``ppc64``, ``i386``, ``x86_64``
87
88 * ``3-way``: ``ppc``, ``i386`` and ``x86_64``
89
90 * ``intel``: ``i386``, ``x86_64``
91
92To build a universal binary that includes a 64-bit architecture, you must build
93on a system running OSX 10.5 or later. The ``all`` flavour can only be built on
94OSX 10.5.
95
96The makefile for a framework build will install ``python32`` and ``pythonw32``
97binaries when the universal architecures includes at least one 32-bit architecture
98(that is, for all flavours but ``64-bit``).
99
100Running a specific archicture
101.............................
102
103You can run code using a specific architecture using the ``arch`` command::
104
105 $ arch -i386 python
106
107Or to explicitly run in 32-bit mode, regardless of the machine hardware::
108
109 $ arch -i386 -ppc python
110
111NOTE: When you're using a framework install of Python this requires at least
112Python 2.7 or 3.2, in earlier versions the python (and pythonw) commands are
113wrapper tools that execute the real interpreter without ensuring that the
114real interpreter runs with the same architecture.
Thomas Wouters477c8d52006-05-27 19:21:47 +0000115
116Building and using a framework-based Python on Mac OS X.
117========================================================
118
Jack Jansen0fdaee72002-08-02 21:45:27 +0000119
Brett Cannon98809b72004-12-06 06:01:13 +00001201. Why would I want a framework Python instead of a normal static Python?
Jack Jansen0fdaee72002-08-02 21:45:27 +0000121--------------------------------------------------------------------------
122
Jack Jansen1f74ed82002-09-06 21:00:55 +0000123The main reason is because you want to create GUI programs in Python. With the
Thomas Wouters477c8d52006-05-27 19:21:47 +0000124exception of X11/XDarwin-based GUI toolkits all GUI programs need to be run
125from a fullblown MacOSX application (a ".app" bundle).
Jack Jansen0fdaee72002-08-02 21:45:27 +0000126
Jack Jansen1f74ed82002-09-06 21:00:55 +0000127While it is technically possible to create a .app without using frameworks you
128will have to do the work yourself if you really want this.
Jack Jansen0fdaee72002-08-02 21:45:27 +0000129
Jack Jansen1f74ed82002-09-06 21:00:55 +0000130A second reason for using frameworks is that they put Python-related items in
Thomas Wouters477c8d52006-05-27 19:21:47 +0000131only two places: "/Library/Framework/Python.framework" and
Brett Cannon85266da2009-12-13 21:15:41 +0000132"/Applications/MacPython <VERSION>" where ``<VERSION>`` can be e.g. "2.6",
133"3.1", etc.. This simplifies matters for users installing
Thomas Wouters477c8d52006-05-27 19:21:47 +0000134Python from a binary distribution if they want to get rid of it again. Moreover,
135due to the way frameworks work a user without admin privileges can install a
136binary distribution in his or her home directory without recompilation.
Jack Jansen7c0d7ba2003-06-20 15:14:08 +0000137
Jack Jansen0fdaee72002-08-02 21:45:27 +00001382. How does a framework Python differ from a normal static Python?
139------------------------------------------------------------------
140
141In everyday use there is no difference, except that things are stored in
142a different place. If you look in /Library/Frameworks/Python.framework
143you will see lots of relative symlinks, see the Apple documentation for
144details. If you are used to a normal unix Python file layout go down to
145Versions/Current and you will see the familiar bin and lib directories.
146
1473. Do I need extra packages?
148----------------------------
149
Thomas Wouters477c8d52006-05-27 19:21:47 +0000150Yes, probably. If you want Tkinter support you need to get the OSX AquaTk
151distribution, this is installed by default on Mac OS X 10.4 or later. If
Jack Jansen1f74ed82002-09-06 21:00:55 +0000152you want wxPython you need to get that. If you want Cocoa you need to get
Thomas Wouters477c8d52006-05-27 19:21:47 +0000153PyObjC.
Jack Jansen0fdaee72002-08-02 21:45:27 +0000154
1554. How do I build a framework Python?
156-------------------------------------
157
Jack Jansen21ed16a2002-08-02 14:11:24 +0000158This directory contains a Makefile that will create a couple of python-related
Jack Jansen1f74ed82002-09-06 21:00:55 +0000159applications (fullblown OSX .app applications, that is) in
Brett Cannon85266da2009-12-13 21:15:41 +0000160"/Applications/MacPython <VERSION>", and a hidden helper application Python.app
Thomas Wouters477c8d52006-05-27 19:21:47 +0000161inside the Python.framework, and unix tools "python" and "pythonw" into
162/usr/local/bin. In addition it has a target "installmacsubtree" that installs
163the relevant portions of the Mac subtree into the Python.framework.
Jack Jansen0511b762001-09-06 16:36:42 +0000164
Jack Jansen21ed16a2002-08-02 14:11:24 +0000165It is normally invoked indirectly through the main Makefile, as the last step
166in the sequence
Thomas Wouters477c8d52006-05-27 19:21:47 +0000167
168 1. ./configure --enable-framework
169
170 2. make
171
172 3. make install
Jack Jansen0fdaee72002-08-02 21:45:27 +0000173
Jack Jansen1f74ed82002-09-06 21:00:55 +0000174This sequence will put the framework in /Library/Framework/Python.framework,
Brett Cannon85266da2009-12-13 21:15:41 +0000175the applications in "/Applications/MacPython <VERSION>" and the unix tools in
Thomas Wouters477c8d52006-05-27 19:21:47 +0000176/usr/local/bin.
Jack Jansen7a1703d2002-08-12 20:46:18 +0000177
Jack Jansen7c0d7ba2003-06-20 15:14:08 +0000178Installing in another place, for instance $HOME/Library/Frameworks if you have
Jack Jansen1f74ed82002-09-06 21:00:55 +0000179no admin privileges on your machine, has only been tested very lightly. This
180can be done by configuring with --enable-framework=$HOME/Library/Frameworks.
Brett Cannon85266da2009-12-13 21:15:41 +0000181The other two directories, "/Applications/MacPython-<VERSION>" and
182/usr/local/bin, will then also be deposited in $HOME. This is sub-optimal for
183the unix tools, which you would want in $HOME/bin, but there is no easy way to
184fix this right now.
Jack Jansen7a1703d2002-08-12 20:46:18 +0000185
186If you want to install some part, but not all, read the main Makefile. The
Jack Jansen1f74ed82002-09-06 21:00:55 +0000187frameworkinstall is composed of a couple of sub-targets that install the
188framework itself, the Mac subtree, the applications and the unix tools.
Jack Jansen7a1703d2002-08-12 20:46:18 +0000189
Jack Jansen7c0d7ba2003-06-20 15:14:08 +0000190There is an extra target frameworkinstallextras that is not part of the
Georg Brandl59b44722010-12-30 22:12:40 +0000191normal frameworkinstall which installs the Tools directory into
192"/Applications/MacPython <VERSION>", this is useful for binary
Brett Cannon85266da2009-12-13 21:15:41 +0000193distributions.
Jack Jansen7c0d7ba2003-06-20 15:14:08 +0000194
Thomas Wouters477c8d52006-05-27 19:21:47 +0000195What do all these programs do?
196===============================
Jack Jansen7a1703d2002-08-12 20:46:18 +0000197
Thomas Wouters477c8d52006-05-27 19:21:47 +0000198"IDLE.app" is an integrated development environment for Python: editor,
Jack Jansen0fdaee72002-08-02 21:45:27 +0000199debugger, etc.
200
Thomas Wouters477c8d52006-05-27 19:21:47 +0000201"PythonLauncher.app" is a helper application that will handle things when you
Jack Jansen0fdaee72002-08-02 21:45:27 +0000202double-click a .py, .pyc or .pyw file. For the first two it creates a Terminal
Jack Jansen1f74ed82002-09-06 21:00:55 +0000203window and runs the scripts with the normal command-line Python. For the
204latter it runs the script in the Python.app interpreter so the script can do
205GUI-things. Keep the "alt" key depressed while dragging or double-clicking a
206script to set runtime options. These options can be set once and for all
207through PythonLauncher's preferences dialog.
Jack Jansen0fdaee72002-08-02 21:45:27 +0000208
Jack Jansen1f74ed82002-09-06 21:00:55 +0000209The commandline scripts /usr/local/bin/python and pythonw can be used to run
210non-GUI and GUI python scripts from the command line, respectively.
Jack Jansen0fdaee72002-08-02 21:45:27 +0000211
Thomas Wouters477c8d52006-05-27 19:21:47 +0000212How do I create a binary distribution?
213======================================
Jack Jansen8ba42202002-09-06 20:24:51 +0000214
Thomas Wouters477c8d52006-05-27 19:21:47 +0000215Go to the directory "Mac/OSX/BuildScript". There you'll find a script
216"build-installer.py" that does all the work. This will download and build
Ned Deilye742ade2012-03-17 10:29:41 -0700217a number of 3rd-party libaries, configures and builds a framework Python,
218installs it, creates the installer package files and then packs this in a
Thomas Wouters477c8d52006-05-27 19:21:47 +0000219DMG image.
Jack Jansen4f901372004-07-15 21:30:41 +0000220
Thomas Wouters477c8d52006-05-27 19:21:47 +0000221The script will build a universal binary, you'll therefore have to run this
222script on Mac OS X 10.4 or later and with Xcode 2.1 or later installed.
Jack Jansen8ba42202002-09-06 20:24:51 +0000223
Jack Jansen7c0d7ba2003-06-20 15:14:08 +0000224All of this is normally done completely isolated in /tmp/_py, so it does not
225use your normal build directory nor does it install into /.
Jack Jansen8ba42202002-09-06 20:24:51 +0000226
Thomas Wouters477c8d52006-05-27 19:21:47 +0000227Because of the way the script locates the files it needs you have to run it
228from within the BuildScript directory. The script accepts a number of
229command-line arguments, run it with --help for more information.
Jack Jansen8ba42202002-09-06 20:24:51 +0000230
Ronald Oussorenf9adc372010-02-07 11:46:38 +0000231Configure warnings
232==================
233
234The configure script sometimes emits warnings like the one below::
235
236 configure: WARNING: libintl.h: present but cannot be compiled
237 configure: WARNING: libintl.h: check for missing prerequisite headers?
238 configure: WARNING: libintl.h: see the Autoconf documentation
239 configure: WARNING: libintl.h: section "Present But Cannot Be Compiled"
240 configure: WARNING: libintl.h: proceeding with the preprocessor's result
241 configure: WARNING: libintl.h: in the future, the compiler will take precedence
242 configure: WARNING: ## -------------------------------------- ##
243 configure: WARNING: ## Report this to http://bugs.python.org/ ##
244 configure: WARNING: ## -------------------------------------- ##
245
246This almost always means you are trying to build a universal binary for
247Python and have libaries in ``/usr/local`` that don't contain the required
248architectures. Temporarily move ``/usr/local`` aside to finish the build.
249
Ronald Oussoren56d64102010-04-30 15:13:13 +0000250
251Uninstalling a framework install, including the binary installer
252================================================================
253
Ned Deilye742ade2012-03-17 10:29:41 -0700254Uninstalling a framework can be done by manually removing all bits that got installed.
255That's true for both installations from source and installations using the binary installer.
Ronald Oussoren56d64102010-04-30 15:13:13 +0000256Sadly enough OSX does not have a central uninstaller.
257
258The main bit of a framework install is the framework itself, installed in
259``/Library/Frameworks/Python.framework``. This can contain multiple versions
260of Python, if you want to remove just one version you have to remove the
261version-specific subdirectory: ``/Library/Frameworks/Python.framework/Versions/X.Y``.
262If you do that, ensure that ``/Library/Frameworks/Python.framework/Versions/Current``
263is a symlink that points to an installed version of Python.
264
265A framework install also installs some applications in ``/Applications/Python X.Y``,
266
267And lastly a framework installation installs files in ``/usr/local/bin``, all of
268them symbolic links to files in ``/Library/Frameworks/Python.framework/Versions/X.Y/bin``.
269
Thomas Wouters477c8d52006-05-27 19:21:47 +0000270Odds and ends
271=============
Jack Jansen408c16f2001-09-11 11:30:02 +0000272
Jack Jansen1f74ed82002-09-06 21:00:55 +0000273Something to take note of is that the ".rsrc" files in the distribution are
274not actually resource files, they're AppleSingle encoded resource files. The
275macresource module and the Mac/OSX/Makefile cater for this, and create
276".rsrc.df.rsrc" files on the fly that are normal datafork-based resource
277files.
Jack Jansen0511b762001-09-06 16:36:42 +0000278
Brett Cannon98809b72004-12-06 06:01:13 +0000279 Jack Jansen, Jack.Jansen@cwi.nl, 15-Jul-2004.
Ronald Oussoren56d64102010-04-30 15:13:13 +0000280 Ronald Oussoren, RonaldOussoren@mac.com, 30-April-2010