Added a lot more information on framework builds, the various .app's,

etc. Still not enough, probably, but better than what we had.

1 files changed, 87 insertions, 2 deletions

diff --git a/Mac/OSX/README b/Mac/OSX/README
index 822a9d9..bfb9dde 100644
--- a/Mac/OSX/README
+++ b/Mac/OSX/README
@@ -1,3 +1,53 @@
+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
@@ -10,6 +60,36 @@ in the sequence
 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,
@@ -21,9 +101,14 @@ 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.
+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
\ No newline at end of file