README 7.62 KB
Newer Older
1 2 3 4 5 6 7 8 9
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?
--------------------------------------------------------------------------

10 11
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
12 13
need to be run from a fullblown MacOSX application (a ".app" bundle).

14 15
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.
16

17 18
A second reason for using frameworks is that they put Python-related items in
only two places: /Library/Framework/Python.framework and /Applications/Python.
19
This simplifies matters for users installing Python from a binary distribution
20 21 22
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.
23 24 25 26 27 28 29 30 31 32 33 34 35 36

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
37 38 39 40 41 42 43 44 45
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
46 47 48 49 50 51
http://www.cwi.nl/~jack/macpython.html, which should contain pointers to more
information.

4. How do I build a framework Python?
-------------------------------------

52
This directory contains a Makefile that will create a couple of python-related
53 54 55 56 57
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.
58

59 60
It is normally invoked indirectly through the main Makefile, as the last step
in the sequence
61
1. ./configure --enable-framework
62 63
2. make
3. make frameworkinstall
64

65 66
This sequence will put the framework in /Library/Framework/Python.framework,
the applications in /Applications/Python and the unix tools in /usr/local/bin.
67

68 69 70 71 72 73
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.
74

75 76 77 78
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.
79 80

If you want to install some part, but not all, read the main Makefile. The
81 82
frameworkinstall is composed of a couple of sub-targets that install the
framework itself, the Mac subtree, the applications and the unix tools.
83

84 85 86
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.
87

88 89 90 91 92 93 94 95 96

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
97 98 99 100 101
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.
102 103

BuildApplet.app creates an applet from a Python script. Drop the script on it
104 105 106
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.
107

108 109
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.
110

111 112 113 114 115
6. How do I create a binary distribution?
-----------------------------------------

Note: this section is work-in-progress.

116 117 118 119
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.
120

121 122 123
Create a subdirectory of the main python directory, say build-pythondist. In
there, run
	../configure --enable-framework=/tmp/pythondist/Library/Frameworks \
124 125 126
		LDFLAGS=-Wl,-x
	make
	make frameworkinstall
127 128
This installs a complete distribution set in /tmp/pythondist: in a framework
build all other pathnames are computed from the framework pathname.
129

130 131 132 133 134 135
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
		
136 137 138
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:
139 140 141
	rm -rf /tmp/pythondist/usr
	python.exe ../Mac/script/zappycfiles.py /tmp/pythondist

142 143 144 145 146 147 148
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.
149

150 151
TBD: provide postinstall scripts to precompile .pyc/.pyo files, and to recreate
the unix programs.
152 153

7. Odds and ends.
154
-----------------
155

156 157 158 159
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.
160

161 162 163 164 165
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.
166

167
	Jack Jansen, jack@oratrix.com, 06-Sep-02