Mac/OSX/README

   1 Building and using a framework-based Python on Mac OS X.
   2 --------------------------------------------------------
   3
   4 This document provides a quick introduction to framework-based Python.
   5 It is rather terse and probably incomplete, please send me feedback.
   6
   7 1. Why would I want a framework Python in stead of a normal static Python?
   8 --------------------------------------------------------------------------
   9
  10 The main reason is because you want to create GUI programs in Python. With the
  11 exception of X11/XDarwin-based GUI toolkits it appears that all GUI programs
  12 need to be run from a fullblown MacOSX application (a ".app" bundle).
  13
  14 While it is technically possible to create a .app without using frameworks you
  15 will have to do the work yourself if you really want this.
  16
  17 A second reason for using frameworks is that they put Python-related items in
  18 only two places: /Library/Framework/Python.framework and /Applications/Python.
  19 This simplifies matters for users installing Python from a binary distribution
  20 if they want to get rid of it again. Moreover, due to the way frameworks work
  21 a user without admin privileges can install a binary distribution in his or
  22 her home directory without recompilation.
  23
  24 2. How does a framework Python differ from a normal static Python?
  25 ------------------------------------------------------------------
  26
  27 In everyday use there is no difference, except that things are stored in
  28 a different place. If you look in /Library/Frameworks/Python.framework
  29 you will see lots of relative symlinks, see the Apple documentation for
  30 details. If you are used to a normal unix Python file layout go down to
  31 Versions/Current and you will see the familiar bin and lib directories.
  32
  33 3. Do I need extra packages?
  34 ----------------------------
  35
  36 Yes, probably. If you want to be able to use the PythonIDE you will need to
  37 get Waste, an all-singing-all-dancing TextEdit replacement, from
  38 www.merzwaren.com. It will unpack into a folder named something like "Waste
  39 2.1 Distribution". Make a symlink called "waste" to this folder, somewhere
  40 beside your Python source distribution (it can be "../waste", "../../waste",
  41 etc).
  42
  43 If you want Tkinter support you need to get the OSX AquaTk distribution. If
  44 you want wxPython you need to get that. If you want Cocoa you need to get
  45 pyobjc. Because all these are currently in a state of flux please refer to
  46 http://www.cwi.nl/~jack/macpython.html, which should contain pointers to more
  47 information.
  48
  49 4. How do I build a framework Python?
  50 -------------------------------------
  51
  52 This directory contains a Makefile that will create a couple of python-related
  53 applications (fullblown OSX .app applications, that is) in
  54 /Applications/Python, and a hidden helper application Python.app inside the
  55 Python.framework, and unix tools "python" and "pythonw" into /usr/local/bin.
  56 In addition it has a target "installmacsubtree" that installs the relevant
  57 portions of the Mac subtree into the Python.framework.
  58
  59 It is normally invoked indirectly through the main Makefile, as the last step
  60 in the sequence
  61 1. ./configure --enable-framework
  62 2. make
  63 3. make frameworkinstall
  64
  65 This sequence will put the framework in /Library/Framework/Python.framework,
  66 the applications in /Applications/Python and the unix tools in /usr/local/bin.
  67
  68 Building in another place, for instance $HOME/Library/Frameworks if you have
  69 no admin privileges on your machine, has only been tested very lightly. This
  70 can be done by configuring with --enable-framework=$HOME/Library/Frameworks.
  71 The other two directories, /Applications/Python and /usr/local/bin, will then
  72 also be deposited in $HOME. This is sub-optimal for the unix tools, which you
  73 would want in $HOME/bin, but there is no easy way to fix this right now.
  74
  75 Note that there are no references to the actual locations in the code or
  76 resource files, so you are free to move things around afterwards. For example,
  77 you could use --enable-framework=/tmp/newversion/Library/Frameworks and use
  78 /tmp/newversion as the basis for an installer or something.
  79
  80 If you want to install some part, but not all, read the main Makefile. The
  81 frameworkinstall is composed of a couple of sub-targets that install the
  82 framework itself, the Mac subtree, the applications and the unix tools.
  83
  84 If you want to run the Makefile here directly, in stead of through the main
  85 Makefile, you will have to pass various variable-assignments. Read the
  86 beginning of the Makefile for details.
  87
  88
  89 5. What do all these programs do?
  90 ---------------------------------
  91
  92 PythonIDE.app is an integrated development environment for Python: editor,
  93 debugger, etc.
  94
  95 PythonLauncher.app is a helper application that will handle things when you
  96 double-click a .py, .pyc or .pyw file. For the first two it creates a Terminal
  97 window and runs the scripts with the normal command-line Python. For the
  98 latter it runs the script in the Python.app interpreter so the script can do
  99 GUI-things. Keep the "alt" key depressed while dragging or double-clicking a
 100 script to set runtime options. These options can be set once and for all
 101 through PythonLauncher's preferences dialog.
 102
 103 BuildApplet.app creates an applet from a Python script. Drop the script on it
 104 and out comes a full-featured MacOS application. There is much more to this,
 105 to be supplied later. Some useful (but outdated) info can be found in
 106 Mac/Demo.
 107
 108 The commandline scripts /usr/local/bin/python and pythonw can be used to run
 109 non-GUI and GUI python scripts from the command line, respectively.
 110
 111 6. How do I create a binary distribution?
 112 -----------------------------------------
 113
 114 Note: this section is work-in-progress.
 115
 116 First, to make sure there's no contamination, it is best to remove your
 117 existing Python installation (clear out /Library/Frameworks/Python.framework
 118 and /Applications/Python). Also, after build/install is finished check that
 119 nothing has shown up in those two locations.
 120
 121 Create a subdirectory of the main python directory, say build-pythondist. In
 122 there, run
 123         ../configure --enable-framework=/tmp/pythondist/Library/Frameworks \
 124                 LDFLAGS=-Wl,-x
 125         make
 126         make frameworkinstall
 127 This installs a complete distribution set in /tmp/pythondist: in a framework
 128 build all other pathnames are computed from the framework pathname.
 129
 130 Optionally you may want to include the full documentation in the binary installer.
 131 To this end, execute the following commands:
 132         python.exe ../Mac/OSX/setupDocs.py build
 133         python.exe ../Mac/OSX/setupDocs.py install \
 134                 --prefix=/tmp/python/Library/Frameworks/Python.framework/Versions/Current
 135
 136 Note that the unix tools in /tmp/pythondist are wrong, these have to be
 137 removed, and the installer post-install script should recreate them on the
 138 target system. Also, the .pyc and .pyo files need to be removed:
 139         rm -rf /tmp/pythondist/usr
 140         python.exe ../Mac/script/zappycfiles.py /tmp/pythondist
 141
 142 Finally, create the .pkg file with a commandline like
 143         python ../Mac/scripts/buildpkg.py \
 144                 --Title=MacPython-X \
 145                 --Version=2.3a0 \
 146                 --Description="Python for Mac OS X, framework based" \
 147                 /tmp/pythondist
 148 This creates a MacPython-X.pkg in the current directory.
 149
 150 TBD: provide postinstall scripts to precompile .pyc/.pyo files, and to recreate
 151 the unix programs.
 152
 153 7. Odds and ends.
 154 -----------------
 155
 156 The PythonLauncher is actually an Objective C Cocoa app built with Project
 157 Builder. It could be a Python program, except for the fact that pyobjc is not
 158 a part of the core distribution, and is not completely finished yet as of this
 159 writing.
 160
 161 Something to take note of is that the ".rsrc" files in the distribution are
 162 not actually resource files, they're AppleSingle encoded resource files. The
 163 macresource module and the Mac/OSX/Makefile cater for this, and create
 164 ".rsrc.df.rsrc" files on the fly that are normal datafork-based resource
 165 files.
 166
 167         Jack Jansen, jack@oratrix.com, 06-Sep-02