Mac/README

   1 ============
   2 MacOSX Notes
   3 ============
   4
   5 This document provides a quick overview of some Mac OS X specific features in
   6 the Python distribution.
   7
   8 Mac-specific arguments to configure
   9 ===================================
  10
  11 * ``--enable-framework``
  12
  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.
  17
  18 * ``--with-framework-name=NAME``
  19
  20   Specify the name for the python framework, defaults to ``Python``. This option
  21   is only valid when ``--enable-framework`` is specified.
  22
  23 * ``--enable-universalsdk[=PATH]``
  24
  25   Create a universal binary build of of Python. This can be used with both
  26   regular and framework builds.
  27
  28   The optional argument specifies with 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.
  31
  32   See the section _`Building and using a universal binary of Python on Mac OS X`
  33   for more information.
  34
  35 * ``--with-univeral-archs=VALUE``
  36
  37   Specify the kind of universal binary that should be created. This option is
  38   only valid when ``--enable-universalsdk`` is specified.
  39
  40
  41
  42 Building and using a universal binary of Python on Mac OS X
  43 ===========================================================
  44
  45 1. What is a universal binary
  46 -----------------------------
  47
  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.
  51
  52 2. How do I build a universal binary
  53 ------------------------------------
  54
  55 You can enable universal binaries by specifying the "--enable-universalsdk"
  56 flag to configure::
  57
  58   $ ./configure --enable-universalsdk
  59   $ make
  60   $ make install
  61
  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.
  66
  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::
  70
  71   $ ./configure --enable-universalsdk=/
  72
  73 2.1 Flavours of universal binaries
  74 ..................................
  75
  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:
  80
  81   * ``32-bit``:   ``ppc``, ``i386``
  82
  83   * ``64-bit``:   ``ppc64``, ``x86_64``
  84
  85   * ``all``:      ``ppc``, ``ppc64``, ``i386``, ``x86_64``
  86
  87   * ``3-way``:    ``ppc``, ``i386`` and ``x86_64``
  88
  89   * ``intel``:    ``i386``, ``x86_64``
  90
  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 build on
  93 OSX 10.5.
  94
  95
  96 Building and using a framework-based Python on Mac OS X.
  97 ========================================================
  98
  99
 100 1. Why would I want a framework Python instead of a normal static Python?
 101 --------------------------------------------------------------------------
 102
 103 The main reason is because you want to create GUI programs in Python. With the
 104 exception of X11/XDarwin-based GUI toolkits all GUI programs need to be run
 105 from a fullblown MacOSX application (a ".app" bundle).
 106
 107 While it is technically possible to create a .app without using frameworks you
 108 will have to do the work yourself if you really want this.
 109
 110 A second reason for using frameworks is that they put Python-related items in
 111 only two places: "/Library/Framework/Python.framework" and
 112 "/Applications/MacPython 2.6".  This simplifies matters for users installing
 113 Python from a binary distribution if they want to get rid of it again. Moreover,
 114 due to the way frameworks work a user without admin privileges can install a
 115 binary distribution in his or her home directory without recompilation.
 116
 117 2. How does a framework Python differ from a normal static Python?
 118 ------------------------------------------------------------------
 119
 120 In everyday use there is no difference, except that things are stored in
 121 a different place. If you look in /Library/Frameworks/Python.framework
 122 you will see lots of relative symlinks, see the Apple documentation for
 123 details. If you are used to a normal unix Python file layout go down to
 124 Versions/Current and you will see the familiar bin and lib directories.
 125
 126 3. Do I need extra packages?
 127 ----------------------------
 128
 129 Yes, probably.  If you want Tkinter support you need to get the OSX AquaTk
 130 distribution, this is installed by default on Mac OS X 10.4 or later. If
 131 you want wxPython you need to get that. If you want Cocoa you need to get
 132 PyObjC.
 133
 134 4. How do I build a framework Python?
 135 -------------------------------------
 136
 137 This directory contains a Makefile that will create a couple of python-related
 138 applications (fullblown OSX .app applications, that is) in
 139 "/Applications/MacPython 2.6", and a hidden helper application Python.app
 140 inside the Python.framework, and unix tools "python" and "pythonw" into
 141 /usr/local/bin.  In addition it has a target "installmacsubtree" that installs
 142 the relevant portions of the Mac subtree into the Python.framework.
 143
 144 It is normally invoked indirectly through the main Makefile, as the last step
 145 in the sequence::
 146
 147  $ ./configure --enable-framework
 148  $ make
 149  $ make install
 150
 151 This sequence will put the framework in /Library/Framework/Python.framework,
 152 the applications in "/Applications/MacPython 2.6" and the unix tools in
 153 /usr/local/bin.
 154
 155 It is possible to select a different name for the framework using the configure
 156 option ``--with-framework-name=NAME``. This makes it possible to have several
 157 parallel installs of a Python framework.
 158
 159 Installing in another place, for instance $HOME/Library/Frameworks if you have
 160 no admin privileges on your machine, has only been tested very lightly. This
 161 can be done by configuring with --enable-framework=$HOME/Library/Frameworks.
 162 The other two directories, "/Applications/MacPython-2.6" and /usr/local/bin,
 163 will then also be deposited in $HOME. This is sub-optimal for the unix tools,
 164 which you would want in $HOME/bin, but there is no easy way to fix this right
 165 now.
 166
 167 What do all these programs do?
 168 ===============================
 169
 170 "IDLE.app" is an integrated development environment for Python: editor,
 171 debugger, etc.
 172
 173 "PythonLauncher.app" is a helper application that will handle things when you
 174 double-click a .py, .pyc or .pyw file. For the first two it creates a Terminal
 175 window and runs the scripts with the normal command-line Python. For the
 176 latter it runs the script in the Python.app interpreter so the script can do
 177 GUI-things. Keep the "alt" key depressed while dragging or double-clicking a
 178 script to set runtime options. These options can be set once and for all
 179 through PythonLauncher's preferences dialog.
 180
 181 "BuildApplet.app" creates an applet from a Python script. Drop the script on it
 182 and out comes a full-featured MacOS application. There is much more to this,
 183 to be supplied later. Some useful (but outdated) info can be found in
 184 Mac/Demo.
 185
 186 The commandline scripts /usr/local/bin/python and pythonw can be used to run
 187 non-GUI and GUI python scripts from the command line, respectively.
 188
 189 How do I create a binary distribution?
 190 ======================================
 191
 192 Go to the directory "Mac/OSX/BuildScript". There you'll find a script
 193 "build-installer.py" that does all the work. This will download and build
 194 a number of 3th-party libaries, configures and builds a framework Python,
 195 installs it, creates the installer pacakge files and then packs this in a
 196 DMG image.
 197
 198 The script will build a universal binary, you'll therefore have to run this
 199 script on Mac OS X 10.4 or later and with Xcode 2.1 or later installed.
 200
 201 All of this is normally done completely isolated in /tmp/_py, so it does not
 202 use your normal build directory nor does it install into /.
 203
 204 Because of the way the script locates the files it needs you have to run it
 205 from within the BuildScript directory. The script accepts a number of
 206 command-line arguments, run it with --help for more information.
 207
 208 Odds and ends
 209 =============
 210
 211 Something to take note of is that the ".rsrc" files in the distribution are
 212 not actually resource files, they're AppleSingle encoded resource files. The
 213 macresource module and the Mac/OSX/Makefile cater for this, and create
 214 ".rsrc.df.rsrc" files on the fly that are normal datafork-based resource
 215 files.
 216
 217         Jack Jansen, Jack.Jansen@cwi.nl, 15-Jul-2004.
 218         Ronald Oussoren, RonaldOussoren@mac.com, 26-May-2006