Issue #7455: Fix possible crash in cPickle on invalid input. Patch by
[python.git] / Mac / README
blob988e624c4bd360db9a0ec1bc1ec4bbc0fa8b4f6f
1 ============
2 MacOSX Notes
3 ============
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`
33   for more information.
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.
40   
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"
56 flag to configure::
58   $ ./configure --enable-universalsdk
59   $ make
60   $ make install
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 
65 installing Xcode.
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
79 values are available:
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
93 OSX 10.5.
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::
104    $ arch -i386 python
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
151 PyObjC. 
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
164 in the sequence::
166  $ ./configure --enable-framework
167  $ make
168  $ make install
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 
172 /usr/local/bin.
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 
184 now.
186 What do all these programs do?
187 ===============================
189 "IDLE.app" is an integrated development environment for Python: editor,
190 debugger, etc.
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
203 Mac/Demo.
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 
215 DMG image.
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.
227 Odds and ends
228 =============
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
234 files.
236         Jack Jansen, Jack.Jansen@cwi.nl, 15-Jul-2004.
237         Ronald Oussoren, RonaldOussoren@mac.com, 26-May-2006