Jack Jansen | 0fdaee7 | 2002-08-02 21:45:27 +0000 | [diff] [blame] | 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 |
| 11 | the 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 |
| 15 | you 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 |
| 18 | in 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 |
| 21 | work a user without admin privileges can install a binary distribution in |
| 22 | his or 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 www.merzwaren.com. |
| 38 | It will unpack into a folder named something like "Waste 2.1 Distribution". Make |
| 39 | a symlink called "waste" to this folder, somewhere beside your Python source |
| 40 | distribution (it can be "../waste", "../../waste", etc). |
| 41 | |
| 42 | If you want Tkinter support you need to get the OSX AquaTk distribution. If you |
| 43 | want wxPython you need to get that. If you want Cocoa you need to get pyobjc. |
| 44 | Because all these are currently in a state of flux please refer to |
| 45 | http://www.cwi.nl/~jack/macpython.html, which should contain pointers to more |
| 46 | information. |
| 47 | |
| 48 | 4. How do I build a framework Python? |
| 49 | ------------------------------------- |
| 50 | |
Jack Jansen | 21ed16a | 2002-08-02 14:11:24 +0000 | [diff] [blame] | 51 | This directory contains a Makefile that will create a couple of python-related |
| 52 | applications (fullblown OSX .app applications, that is) in /Applications/Python, |
Jack Jansen | 7a1703d | 2002-08-12 20:46:18 +0000 | [diff] [blame] | 53 | and a hidden helper application Python.app inside the Python.framework, and |
| 54 | unix tools "python" and "pythonw" into /usr/local/bin. In addition |
Jack Jansen | 21ed16a | 2002-08-02 14:11:24 +0000 | [diff] [blame] | 55 | it has a target "installmacsubtree" that installs the relevant portions of the |
| 56 | Mac subtree into the Python.framework. |
Jack Jansen | 0511b76 | 2001-09-06 16:36:42 +0000 | [diff] [blame] | 57 | |
Jack Jansen | 21ed16a | 2002-08-02 14:11:24 +0000 | [diff] [blame] | 58 | It is normally invoked indirectly through the main Makefile, as the last step |
| 59 | in the sequence |
| 60 | 1. configure --enable-framework |
| 61 | 2. make |
| 62 | 3. make frameworkinstall |
Jack Jansen | 0fdaee7 | 2002-08-02 21:45:27 +0000 | [diff] [blame] | 63 | |
Jack Jansen | 7a1703d | 2002-08-12 20:46:18 +0000 | [diff] [blame] | 64 | This sequence will put the framework in /Library/Framework/Python.framework, |
| 65 | the applications in /Applications/Python and the unix tools in /usr/local/bin. |
| 66 | |
| 67 | Building in another place, for instance $HOME/Library/Frameworks if you have no |
| 68 | admin privileges on your machine, has only been tested very lightly. This can be done |
| 69 | by configuring with --enable-framework=$HOME/Library/Frameworks. The other two |
| 70 | directories, /Applications/Python and /usr/local/bin, will then also be deposited |
| 71 | in $HOME. This is sub-optimal for the unix tools, which you would want in $HOME/bin, |
| 72 | but there is no easy way to fix this right now. |
| 73 | |
| 74 | Note that there are no references to the actual locations in the code or resource |
| 75 | files, so you are free to move things around afterwards. For example, you could |
| 76 | use --enable-framework=/tmp/newversion/Library/Frameworks and use /tmp/newversion |
| 77 | as the basis for an installer or something. |
| 78 | |
| 79 | If you want to install some part, but not all, read the main Makefile. The |
| 80 | frameworkinstall is composed of a couple of sub-targets that install the framework |
| 81 | itself, the Mac subtree, the applications and the unix tools. |
| 82 | |
| 83 | If you want to run the Makefile here directly, in stead of through the main Makefile, |
| 84 | you will have to pass various variable-assignments. Read the beginning of the Makefile |
| 85 | for details. |
| 86 | |
Jack Jansen | 0fdaee7 | 2002-08-02 21:45:27 +0000 | [diff] [blame] | 87 | |
| 88 | 5. What do all these programs do? |
| 89 | --------------------------------- |
| 90 | |
| 91 | PythonIDE.app is an integrated development environment for Python: editor, |
| 92 | debugger, etc. |
| 93 | |
| 94 | PythonLauncher.app is a helper application that will handle things when you |
| 95 | double-click a .py, .pyc or .pyw file. For the first two it creates a Terminal |
| 96 | window and runs the scripts with the normal command-line Python. For the latter |
| 97 | it runs the script in the Python.app interpreter so the script can do GUI-things. |
| 98 | Keep the "alt" key depressed while dragging or double-clicking a script to set |
| 99 | runtime options. These options can be set once and for all through PythonLauncher's |
| 100 | preferences dialog. |
| 101 | |
| 102 | BuildApplet.app creates an applet from a Python script. Drop the script on it |
| 103 | and out comes a full-featured MacOS application. There is much more to this, to |
| 104 | be supplied later. Some useful (but outdated) info can be found in Mac/Demo. |
| 105 | |
Jack Jansen | 7a1703d | 2002-08-12 20:46:18 +0000 | [diff] [blame] | 106 | The commandline scripts /usr/local/bin/python and pythonw |
Jack Jansen | 0fdaee7 | 2002-08-02 21:45:27 +0000 | [diff] [blame] | 107 | can be used to run non-GUI and GUI python scripts from the command line, respectively. |
| 108 | |
Jack Jansen | 8ba4220 | 2002-09-06 20:24:51 +0000 | [diff] [blame^] | 109 | 6. How do I create a binary distribution? |
| 110 | ----------------------------------------- |
| 111 | |
| 112 | Note: this section is work-in-progress. |
| 113 | |
| 114 | First, to make sure there's no contamination, it is best to remove your existing Python |
| 115 | installation (clear out /Library/Frameworks/Python.framework and /Applications/Python). |
| 116 | Also, after build/install is finished check that nothing has shown up in those two locations. |
| 117 | |
| 118 | Create a subdirectory of the main python directory, say build-pythondist. In there, run |
| 119 | ../configure --enable-framework=/tmp/pythondist/Library/Frameworks/Python.framework \ |
| 120 | LDFLAGS=-Wl,-x |
| 121 | make |
| 122 | make frameworkinstall |
| 123 | This installs a complete distribution set in /tmp/pythondist: in a framework build all other |
| 124 | pathnames are computed from the framework pathname. |
| 125 | |
| 126 | Note that the unix tools in /tmp/pythondist are wrong, these have to be removed, and the |
| 127 | installer post-install script should recreate them on the target system. Also, the .pyc and |
| 128 | .pyo files need to be removed: |
| 129 | rm -rf /tmp/pythondist/usr |
| 130 | python.exe ../Mac/script/zappycfiles.py /tmp/pythondist |
| 131 | |
| 132 | TBD: find out how to make a .pkg from here. |
| 133 | |
| 134 | TBD: documentation. |
| 135 | |
| 136 | 7. Odds and ends. |
Jack Jansen | 0fdaee7 | 2002-08-02 21:45:27 +0000 | [diff] [blame] | 137 | ----------------- |
Jack Jansen | 0511b76 | 2001-09-06 16:36:42 +0000 | [diff] [blame] | 138 | |
Jack Jansen | 0fdaee7 | 2002-08-02 21:45:27 +0000 | [diff] [blame] | 139 | The PythonLauncher is actually an Objective C Cocoa app built with Project Builder. |
| 140 | It could be a Python program, except for the fact that pyobjc is not a part of |
| 141 | the core distribution, and is not completely finished yet as of this writing. |
Jack Jansen | 408c16f | 2001-09-11 11:30:02 +0000 | [diff] [blame] | 142 | |
Jack Jansen | 0511b76 | 2001-09-06 16:36:42 +0000 | [diff] [blame] | 143 | Something to take note of is that the ".rsrc" files in the distribution are not |
Jack Jansen | 0fdaee7 | 2002-08-02 21:45:27 +0000 | [diff] [blame] | 144 | actually resource files, they're AppleSingle encoded resource files. The macresource |
| 145 | module and the Mac/OSX/Makefile cater for this, and create ".rsrc.df.rsrc" files |
| 146 | on the fly that are normal datafork-based resource files. |
Jack Jansen | 0511b76 | 2001-09-06 16:36:42 +0000 | [diff] [blame] | 147 | |
Jack Jansen | 7a1703d | 2002-08-12 20:46:18 +0000 | [diff] [blame] | 148 | Jack Jansen, jack@oratrix.com, 12-Aug-02 |