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
   9 Building and using a universal binary of Python on Mac OS X
  10 ===========================================================
  11
  12 1. What is a universal binary
  13 -----------------------------
  14
  15 A universal binary build of Python contains object code for both PPC and i386
  16 and can therefore run at native speed on both classic powerpc based macs and
  17 the newer intel based macs.
  18
  19 2. How do I build a universal binary
  20 ------------------------------------
  21
  22 You can enable universal binaries by specifying the "--enable-universalsdk"
  23 flag to configure::
  24
  25   $ ./configure --enable-universalsdk
  26   $ make
  27   $ make install
  28
  29 This flag can be used a framework build of python, but also with a classic
  30 unix build. Either way you will have to build python on Mac OS X 10.4 (or later)
  31 with Xcode 2.1 (or later). You also have to install the 10.4u SDK when
  32 installing Xcode.
  33
  34
  35 Building and using a framework-based Python on Mac OS X.
  36 ========================================================
  37
  38
  39 1. Why would I want a framework Python instead of a normal static Python?
  40 --------------------------------------------------------------------------
  41
  42 The main reason is because you want to create GUI programs in Python. With the
  43 exception of X11/XDarwin-based GUI toolkits all GUI programs need to be run
  44 from a fullblown MacOSX application (a ".app" bundle).
  45
  46 While it is technically possible to create a .app without using frameworks you
  47 will have to do the work yourself if you really want this.
  48
  49 A second reason for using frameworks is that they put Python-related items in
  50 only two places: "/Library/Framework/Python.framework" and
  51 "/Applications/MacPython 2.5".  This simplifies matters for users installing
  52 Python from a binary distribution if they want to get rid of it again. Moreover,
  53 due to the way frameworks work a user without admin privileges can install a
  54 binary distribution in his or her home directory without recompilation.
  55
  56 2. How does a framework Python differ from a normal static Python?
  57 ------------------------------------------------------------------
  58
  59 In everyday use there is no difference, except that things are stored in
  60 a different place. If you look in /Library/Frameworks/Python.framework
  61 you will see lots of relative symlinks, see the Apple documentation for
  62 details. If you are used to a normal unix Python file layout go down to
  63 Versions/Current and you will see the familiar bin and lib directories.
  64
  65 3. Do I need extra packages?
  66 ----------------------------
  67
  68 Yes, probably.  If you want Tkinter support you need to get the OSX AquaTk
  69 distribution, this is installed by default on Mac OS X 10.4 or later. If
  70 you want wxPython you need to get that. If you want Cocoa you need to get
  71 PyObjC.
  72
  73 4. How do I build a framework Python?
  74 -------------------------------------
  75
  76 This directory contains a Makefile that will create a couple of python-related
  77 applications (fullblown OSX .app applications, that is) in
  78 "/Applications/MacPython 2.3", and a hidden helper application Python.app
  79 inside the Python.framework, and unix tools "python" and "pythonw" into
  80 /usr/local/bin.  In addition it has a target "installmacsubtree" that installs
  81 the relevant portions of the Mac subtree into the Python.framework.
  82
  83 It is normally invoked indirectly through the main Makefile, as the last step
  84 in the sequence
  85
  86  1. ./configure --enable-framework
  87
  88  2. make
  89
  90  3. make install
  91
  92 This sequence will put the framework in /Library/Framework/Python.framework,
  93 the applications in /Applications/MacPython 2.5 and the unix tools in
  94 /usr/local/bin.
  95
  96 Installing in another place, for instance $HOME/Library/Frameworks if you have
  97 no admin privileges on your machine, has only been tested very lightly. This
  98 can be done by configuring with --enable-framework=$HOME/Library/Frameworks.
  99 The other two directories, /Applications/MacPython-2.3 and /usr/local/bin, will
 100 then also be deposited in $HOME. This is sub-optimal for the unix tools, which
 101 you would want in $HOME/bin, but there is no easy way to fix this right now.
 102
 103 Note that there are no references to the actual locations in the code or
 104 resource files, so you are free to move things around afterwards. For example,
 105 you could use --enable-framework=/tmp/newversion/Library/Frameworks and use
 106 /tmp/newversion as the basis for an installer or something.
 107
 108 If you want to install some part, but not all, read the main Makefile. The
 109 frameworkinstall is composed of a couple of sub-targets that install the
 110 framework itself, the Mac subtree, the applications and the unix tools.
 111
 112 There is an extra target frameworkinstallextras that is not part of the
 113 normal frameworkinstall which installs the Demo and Tools directories
 114 into /Applications/MacPython-2.3, this is useful for binary distributions.
 115
 116 What do all these programs do?
 117 ===============================
 118
 119 "IDLE.app" is an integrated development environment for Python: editor,
 120 debugger, etc.
 121
 122 "PythonLauncher.app" is a helper application that will handle things when you
 123 double-click a .py, .pyc or .pyw file. For the first two it creates a Terminal
 124 window and runs the scripts with the normal command-line Python. For the
 125 latter it runs the script in the Python.app interpreter so the script can do
 126 GUI-things. Keep the "alt" key depressed while dragging or double-clicking a
 127 script to set runtime options. These options can be set once and for all
 128 through PythonLauncher's preferences dialog.
 129
 130 "BuildApplet.app" creates an applet from a Python script. Drop the script on it
 131 and out comes a full-featured MacOS application. There is much more to this,
 132 to be supplied later. Some useful (but outdated) info can be found in
 133 Mac/Demo.
 134
 135 The commandline scripts /usr/local/bin/python and pythonw can be used to run
 136 non-GUI and GUI python scripts from the command line, respectively.
 137
 138 How do I create a binary distribution?
 139 ======================================
 140
 141 Go to the directory "Mac/OSX/BuildScript". There you'll find a script
 142 "build-installer.py" that does all the work. This will download and build
 143 a number of 3th-party libaries, configures and builds a framework Python,
 144 installs it, creates the installer pacakge files and then packs this in a
 145 DMG image.
 146
 147 The script will build a universal binary, you'll therefore have to run this
 148 script on Mac OS X 10.4 or later and with Xcode 2.1 or later installed.
 149
 150 All of this is normally done completely isolated in /tmp/_py, so it does not
 151 use your normal build directory nor does it install into /.
 152
 153 Because of the way the script locates the files it needs you have to run it
 154 from within the BuildScript directory. The script accepts a number of
 155 command-line arguments, run it with --help for more information.
 156
 157 Odds and ends
 158 =============
 159
 160 Something to take note of is that the ".rsrc" files in the distribution are
 161 not actually resource files, they're AppleSingle encoded resource files. The
 162 macresource module and the Mac/OSX/Makefile cater for this, and create
 163 ".rsrc.df.rsrc" files on the fly that are normal datafork-based resource
 164 files.
 165
 166         Jack Jansen, Jack.Jansen@cwi.nl, 15-Jul-2004.
 167         Ronald Oussoren, RonaldOussoren@mac.com, 26-May-2006