cpython/Mac/OSX/README

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. 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
4. make osxapps
5. [optional] in Mac/OSX do "make installunixprograms", see below.

This sequence will put the framework in /Library/Framework/Python.framework and
the applications in /Applications/Python. Building in another place, for instance
$HOME/Library/Frameworks if you have no admin privileges on your machine, has only
been tested very lightly.

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.

If you install the commandline scripts /usr/local/bin/python and pythonw these
can be used to run non-GUI and GUI python scripts from the command line, respectively.

6. Odds and ends.
-----------------

The interesting targets in the makefile are:
installmacsubtree - explained above,
dontinstallmacsubtree - Put only a .pth file into the framework (pointing to this
	sourcetree), which may be easier for development,
install_all - install all three .app applications,
install_Python - install the hidden interpreter .app into the framework,
install_PythonLauncher - install the user-visible script launch helper
install_IDE - install the IDE
installunixprograms - install symlinks/scripts mimicking normal unix Python into
	/usr/local.
	
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, 02-Aug-02