5 This document provides a quick overview of some Mac OS X specific features in
6 the Python distribution.
8 Mac-specific arguments to configure
9 ===================================
11 * ``--enable-framework``
13 If this argument is specified the build will create a Python.framework rather
14 than a traditional Unix install. See the section
15 _`Building and using a framework-based Python on Mac OS X` for more
16 information on frameworks.
18 * ``--with-framework-name=NAME``
20 Specify the name for the python framework, defaults to ``Python``. This option
21 is only valid when ``--enable-framework`` is specified.
23 * ``--enable-universalsdk[=PATH]``
25 Create a universal binary build of of Python. This can be used with both
26 regular and framework builds.
28 The optional argument specifies which OSX SDK should be used to perform the
29 build. This defaults to ``/Developer/SDKs/MacOSX.10.4u.sdk``, specify
30 ``/`` when building on a 10.5 system, especially when building 64-bit code.
32 See the section _`Building and using a universal binary of Python on Mac OS X`
35 * ``--with-univeral-archs=VALUE``
37 Specify the kind of universal binary that should be created. This option is
38 only valid when ``--enable-universalsdk`` is specified.
42 Building and using a universal binary of Python on Mac OS X
43 ===========================================================
45 1. What is a universal binary
46 -----------------------------
48 A universal binary build of Python contains object code for both PPC and i386
49 and can therefore run at native speed on both classic powerpc based macs and
50 the newer intel based macs.
52 2. How do I build a universal binary
53 ------------------------------------
55 You can enable universal binaries by specifying the "--enable-universalsdk"
58 $ ./configure --enable-universalsdk
62 This flag can be used a framework build of python, but also with a classic
63 unix build. Either way you will have to build python on Mac OS X 10.4 (or later)
64 with Xcode 2.1 (or later). You also have to install the 10.4u SDK when
67 The option ``--enable-universalsdk`` has an optional argument to specify an
68 SDK, which defaults to the 10.4u SDK. When you build on OSX 10.5 or later
69 you can use the system headers instead of an SDK::
71 $ ./configure --enable-universalsdk=/
73 2.1 Flavours of universal binaries
74 ..................................
76 It is possible to build a number of flavours of the universal binary build,
77 the default is a 32-bit only binary (i386 and ppc). The flavour can be
78 specified using the option ``--with-universal-archs=VALUE``. The following
81 * ``32-bit``: ``ppc``, ``i386``
83 * ``64-bit``: ``ppc64``, ``x86_64``
85 * ``all``: ``ppc``, ``ppc64``, ``i386``, ``x86_64``
87 * ``3-way``: ``ppc``, ``i386`` and ``x86_64``
89 * ``intel``: ``i386``, ``x86_64``
91 To build a universal binary that includes a 64-bit architecture, you must build
92 on a system running OSX 10.5 or later. The ``all`` flavour can only be built on
95 The makefile for a framework build will install ``python32`` and ``pythonw32``
96 binaries when the universal architecures includes at least one 32-bit architecture
97 (that is, for all flavours but ``64-bit``).
99 Running a specific archicture
100 .............................
102 You can run code using a specific architecture using the ``arch`` command::
106 Or to explicitly run in 32-bit mode, regardless of the machine hardware::
108 $ arch -i386 -ppc python
110 NOTE: When you're using a framework install of Python this requires at least
111 Python 2.7 or 3.2, in earlier versions the python (and pythonw) commands are
112 wrapper tools that execute the real interpreter without ensuring that the
113 real interpreter runs with the same architecture.
115 Building and using a framework-based Python on Mac OS X.
116 ========================================================
119 1. Why would I want a framework Python instead of a normal static Python?
120 --------------------------------------------------------------------------
122 The main reason is because you want to create GUI programs in Python. With the
123 exception of X11/XDarwin-based GUI toolkits all GUI programs need to be run
124 from a fullblown MacOSX application (a ".app" bundle).
126 While it is technically possible to create a .app without using frameworks you
127 will have to do the work yourself if you really want this.
129 A second reason for using frameworks is that they put Python-related items in
130 only two places: "/Library/Framework/Python.framework" and
131 "/Applications/MacPython 2.6". This simplifies matters for users installing
132 Python from a binary distribution if they want to get rid of it again. Moreover,
133 due to the way frameworks work a user without admin privileges can install a
134 binary distribution in his or her home directory without recompilation.
136 2. How does a framework Python differ from a normal static Python?
137 ------------------------------------------------------------------
139 In everyday use there is no difference, except that things are stored in
140 a different place. If you look in /Library/Frameworks/Python.framework
141 you will see lots of relative symlinks, see the Apple documentation for
142 details. If you are used to a normal unix Python file layout go down to
143 Versions/Current and you will see the familiar bin and lib directories.
145 3. Do I need extra packages?
146 ----------------------------
148 Yes, probably. If you want Tkinter support you need to get the OSX AquaTk
149 distribution, this is installed by default on Mac OS X 10.4 or later. If
150 you want wxPython you need to get that. If you want Cocoa you need to get
153 4. How do I build a framework Python?
154 -------------------------------------
156 This directory contains a Makefile that will create a couple of python-related
157 applications (fullblown OSX .app applications, that is) in
158 "/Applications/MacPython 2.6", and a hidden helper application Python.app
159 inside the Python.framework, and unix tools "python" and "pythonw" into
160 /usr/local/bin. In addition it has a target "installmacsubtree" that installs
161 the relevant portions of the Mac subtree into the Python.framework.
163 It is normally invoked indirectly through the main Makefile, as the last step
166 $ ./configure --enable-framework
170 This sequence will put the framework in /Library/Framework/Python.framework,
171 the applications in "/Applications/MacPython 2.6" and the unix tools in
174 It is possible to select a different name for the framework using the configure
175 option ``--with-framework-name=NAME``. This makes it possible to have several
176 parallel installs of a Python framework.
178 Installing in another place, for instance $HOME/Library/Frameworks if you have
179 no admin privileges on your machine, has only been tested very lightly. This
180 can be done by configuring with --enable-framework=$HOME/Library/Frameworks.
181 The other two directories, "/Applications/MacPython-2.6" and /usr/local/bin,
182 will then also be deposited in $HOME. This is sub-optimal for the unix tools,
183 which you would want in $HOME/bin, but there is no easy way to fix this right
186 What do all these programs do?
187 ===============================
189 "IDLE.app" is an integrated development environment for Python: editor,
192 "PythonLauncher.app" is a helper application that will handle things when you
193 double-click a .py, .pyc or .pyw file. For the first two it creates a Terminal
194 window and runs the scripts with the normal command-line Python. For the
195 latter it runs the script in the Python.app interpreter so the script can do
196 GUI-things. Keep the "alt" key depressed while dragging or double-clicking a
197 script to set runtime options. These options can be set once and for all
198 through PythonLauncher's preferences dialog.
200 "BuildApplet.app" creates an applet from a Python script. Drop the script on it
201 and out comes a full-featured MacOS application. There is much more to this,
202 to be supplied later. Some useful (but outdated) info can be found in
205 The commandline scripts /usr/local/bin/python and pythonw can be used to run
206 non-GUI and GUI python scripts from the command line, respectively.
208 How do I create a binary distribution?
209 ======================================
211 Go to the directory "Mac/OSX/BuildScript". There you'll find a script
212 "build-installer.py" that does all the work. This will download and build
213 a number of 3th-party libaries, configures and builds a framework Python,
214 installs it, creates the installer pacakge files and then packs this in a
217 The script will build a universal binary, you'll therefore have to run this
218 script on Mac OS X 10.4 or later and with Xcode 2.1 or later installed.
220 All of this is normally done completely isolated in /tmp/_py, so it does not
221 use your normal build directory nor does it install into /.
223 Because of the way the script locates the files it needs you have to run it
224 from within the BuildScript directory. The script accepts a number of
225 command-line arguments, run it with --help for more information.
230 Something to take note of is that the ".rsrc" files in the distribution are
231 not actually resource files, they're AppleSingle encoded resource files. The
232 macresource module and the Mac/OSX/Makefile cater for this, and create
233 ".rsrc.df.rsrc" files on the fly that are normal datafork-based resource
236 Jack Jansen, Jack.Jansen@cwi.nl, 15-Jul-2004.
237 Ronald Oussoren, RonaldOussoren@mac.com, 26-May-2006