| Building and using a framework-based Python on Mac OS X. |
| -------------------------------------------------------- |
| |
| This document provides a quick introduction to framework-based Python. |
| It is rather terse and probably incomplete, please send me feedback. |
| |
| 1. Why would I want a framework Python in stead of a normal static Python? |
| -------------------------------------------------------------------------- |
| |
| The main reason is because you want to create GUI programs in Python. With the |
| exception of X11/XDarwin-based GUI toolkits it appears that all GUI programs |
| need to be run from a fullblown MacOSX application (a ".app" bundle). |
| |
| While it is technically possible to create a .app without using frameworks you |
| will have to do the work yourself if you really want this. |
| |
| A second reason for using frameworks is that they put Python-related items in |
| only two places: /Library/Framework/Python.framework and /Applications/Python. |
| This simplifies matters for users installing Python from a binary distribution |
| if they want to get rid of it again. Moreover, due to the way frameworks work |
| a user without admin privileges can install a binary distribution in his or |
| her home directory without recompilation. |
| |
| 2. How does a framework Python differ from a normal static Python? |
| ------------------------------------------------------------------ |
| |
| In everyday use there is no difference, except that things are stored in |
| a different place. If you look in /Library/Frameworks/Python.framework |
| you will see lots of relative symlinks, see the Apple documentation for |
| details. If you are used to a normal unix Python file layout go down to |
| Versions/Current and you will see the familiar bin and lib directories. |
| |
| 3. Do I need extra packages? |
| ---------------------------- |
| |
| Yes, probably. If you want to be able to use the PythonIDE you will need to |
| get Waste, an all-singing-all-dancing TextEdit replacement, from |
| www.merzwaren.com. It will unpack into a folder named something like "Waste |
| 2.1 Distribution". Make a symlink called "waste" to this folder, somewhere |
| beside your Python source distribution (it can be "../waste", "../../waste", |
| etc). |
| |
| If you want Tkinter support you need to get the OSX AquaTk distribution. If |
| you want wxPython you need to get that. If you want Cocoa you need to get |
| pyobjc. Because all these are currently in a state of flux please refer to |
| http://www.cwi.nl/~jack/macpython.html, which should contain pointers to more |
| information. |
| |
| 4. How do I build a framework Python? |
| ------------------------------------- |
| |
| This directory contains a Makefile that will create a couple of python-related |
| applications (fullblown OSX .app applications, that is) in |
| /Applications/Python, and a hidden helper application Python.app inside the |
| Python.framework, and unix tools "python" and "pythonw" into /usr/local/bin. |
| In addition it has a target "installmacsubtree" that installs the relevant |
| portions of the Mac subtree into the Python.framework. |
| |
| It is normally invoked indirectly through the main Makefile, as the last step |
| in the sequence |
| 1. ./configure --enable-framework |
| 2. make |
| 3. make frameworkinstall |
| |
| This sequence will put the framework in /Library/Framework/Python.framework, |
| the applications in /Applications/Python and the unix tools in /usr/local/bin. |
| |
| Building in another place, for instance $HOME/Library/Frameworks if you have |
| no admin privileges on your machine, has only been tested very lightly. This |
| can be done by configuring with --enable-framework=$HOME/Library/Frameworks. |
| The other two directories, /Applications/Python and /usr/local/bin, will then |
| also be deposited in $HOME. This is sub-optimal for the unix tools, which you |
| would want in $HOME/bin, but there is no easy way to fix this right now. |
| |
| Note that there are no references to the actual locations in the code or |
| resource files, so you are free to move things around afterwards. For example, |
| you could use --enable-framework=/tmp/newversion/Library/Frameworks and use |
| /tmp/newversion as the basis for an installer or something. |
| |
| If you want to install some part, but not all, read the main Makefile. The |
| frameworkinstall is composed of a couple of sub-targets that install the |
| framework itself, the Mac subtree, the applications and the unix tools. |
| |
| If you want to run the Makefile here directly, in stead of through the main |
| Makefile, you will have to pass various variable-assignments. Read the |
| beginning of the Makefile for details. |
| |
| |
| 5. What do all these programs do? |
| --------------------------------- |
| |
| PythonIDE.app is an integrated development environment for Python: editor, |
| debugger, etc. |
| |
| PythonLauncher.app is a helper application that will handle things when you |
| double-click a .py, .pyc or .pyw file. For the first two it creates a Terminal |
| window and runs the scripts with the normal command-line Python. For the |
| latter it runs the script in the Python.app interpreter so the script can do |
| GUI-things. Keep the "alt" key depressed while dragging or double-clicking a |
| script to set runtime options. These options can be set once and for all |
| through PythonLauncher's preferences dialog. |
| |
| BuildApplet.app creates an applet from a Python script. Drop the script on it |
| and out comes a full-featured MacOS application. There is much more to this, |
| to be supplied later. Some useful (but outdated) info can be found in |
| Mac/Demo. |
| |
| The commandline scripts /usr/local/bin/python and pythonw can be used to run |
| non-GUI and GUI python scripts from the command line, respectively. |
| |
| 6. How do I create a binary distribution? |
| ----------------------------------------- |
| |
| Note: this section is work-in-progress. |
| |
| First, to make sure there's no contamination, it is best to remove your |
| existing Python installation (clear out /Library/Frameworks/Python.framework |
| and /Applications/Python). Also, after build/install is finished check that |
| nothing has shown up in those two locations. |
| |
| Create a subdirectory of the main python directory, say build-pythondist. In |
| there, run |
| ../configure --enable-framework=/tmp/pythondist/Library/Frameworks \ |
| LDFLAGS=-Wl,-x |
| make |
| make frameworkinstall |
| This installs a complete distribution set in /tmp/pythondist: in a framework |
| build all other pathnames are computed from the framework pathname. |
| |
| Optionally you may want to include the full documentation in the binary installer. |
| To this end, execute the following commands: |
| python.exe ../Mac/OSX/setupDocs.py build |
| python.exe ../Mac/OSX/setupDocs.py install \ |
| --prefix=/tmp/python/Library/Frameworks/Python.framework/Versions/Current |
| |
| Note that the unix tools in /tmp/pythondist are wrong, these have to be |
| removed, and the installer post-install script should recreate them on the |
| target system. Also, the .pyc and .pyo files need to be removed: |
| rm -rf /tmp/pythondist/usr |
| python.exe ../Mac/script/zappycfiles.py /tmp/pythondist |
| |
| Finally, create the .pkg file with a commandline like |
| python ../Mac/scripts/buildpkg.py \ |
| --Title=MacPython-X \ |
| --Version=2.3a0 \ |
| --Description="Python for Mac OS X, framework based" \ |
| /tmp/pythondist |
| This creates a MacPython-X.pkg in the current directory. |
| |
| TBD: provide postinstall scripts to precompile .pyc/.pyo files, and to recreate |
| the unix programs. |
| |
| 7. Odds and ends. |
| ----------------- |
| |
| The PythonLauncher is actually an Objective C Cocoa app built with Project |
| Builder. It could be a Python program, except for the fact that pyobjc is not |
| a part of the core distribution, and is not completely finished yet as of this |
| writing. |
| |
| Something to take note of is that the ".rsrc" files in the distribution are |
| not actually resource files, they're AppleSingle encoded resource files. The |
| macresource module and the Mac/OSX/Makefile cater for this, and create |
| ".rsrc.df.rsrc" files on the fly that are normal datafork-based resource |
| files. |
| |
| Jack Jansen, jack@oratrix.com, 06-Sep-02 |