/Mac/README

  1============
  2MacOSX Notes
  3============
  4
  5This document provides a quick overview of some Mac OS X specific features in
  6the Python distribution.
  7
  8Mac-specific arguments to configure
  9===================================
 10
 11* ``--enable-framework``
 12
 13  If this argument is specified the build will create a Python.framework rather
 14  than a traditional Unix install. See the section
 15  _`Building and using a framework-based Python on Mac OS X` for more 
 16  information on frameworks.
 17
 18* ``--with-framework-name=NAME``
 19
 20  Specify the name for the python framework, defaults to ``Python``. This option
 21  is only valid when ``--enable-framework`` is specified.
 22
 23* ``--enable-universalsdk[=PATH]``
 24
 25  Create a universal binary build of of Python. This can be used with both
 26  regular and framework builds.
 27
 28  The optional argument specifies with OSX SDK should be used to perform the
 29  build. This defaults to ``/Developer/SDKs/MacOSX.10.4u.sdk``, specify 
 30  ``/`` when building on a 10.5 system, especially when building 64-bit code.
 31
 32  See the section _`Building and using a universal binary of Python on Mac OS X`
 33  for more information.
 34
 35* ``--with-univeral-archs=VALUE``
 36
 37  Specify the kind of universal binary that should be created. This option is 
 38  only valid when ``--enable-universalsdk`` is specified.
 39
 40  
 41
 42Building and using a universal binary of Python on Mac OS X
 43===========================================================
 44
 451. What is a universal binary
 46-----------------------------
 47
 48A universal binary build of Python contains object code for both PPC and i386
 49and can therefore run at native speed on both classic powerpc based macs and
 50the newer intel based macs.
 51
 522. How do I build a universal binary
 53------------------------------------
 54
 55You can enable universal binaries by specifying the "--enable-universalsdk"
 56flag to configure::
 57
 58  $ ./configure --enable-universalsdk
 59  $ make
 60  $ make install
 61
 62This flag can be used a framework build of python, but also with a classic
 63unix build. Either way you will have to build python on Mac OS X 10.4 (or later)
 64with Xcode 2.1 (or later). You also have to install the 10.4u SDK when 
 65installing Xcode.
 66
 67The option ``--enable-universalsdk`` has an optional argument to specify an
 68SDK, which defaults to the 10.4u SDK. When you build on OSX 10.5 or later 
 69you can use the system headers instead of an SDK::
 70
 71  $ ./configure --enable-universalsdk=/
 72
 732.1 Flavours of universal binaries
 74..................................
 75
 76It is possible to build a number of flavours of the universal binary build,
 77the default is a 32-bit only binary (i386 and ppc). The flavour can be
 78specified using the option ``--with-universal-archs=VALUE``. The following
 79values are available:
 80
 81  * ``32-bit``:   ``ppc``, ``i386``
 82
 83  * ``64-bit``:   ``ppc64``, ``x86_64``
 84
 85  * ``all``:      ``ppc``, ``ppc64``, ``i386``, ``x86_64``
 86
 87  * ``3-way``:	  ``ppc``, ``i386`` and ``x86_64``
 88
 89  * ``intel``:	  ``i386``, ``x86_64``
 90
 91To build a universal binary that includes a 64-bit architecture you must build
 92on a system running OSX 10.5 or later. The ``all`` flavour can only be build on
 93OSX 10.5.
 94
 95
 96Building and using a framework-based Python on Mac OS X.
 97========================================================
 98
 99
1001. Why would I want a framework Python instead of a normal static Python?
101--------------------------------------------------------------------------
102
103The main reason is because you want to create GUI programs in Python. With the
104exception of X11/XDarwin-based GUI toolkits all GUI programs need to be run 
105from a fullblown MacOSX application (a ".app" bundle).
106
107While it is technically possible to create a .app without using frameworks you
108will have to do the work yourself if you really want this.
109
110A second reason for using frameworks is that they put Python-related items in
111only two places: "/Library/Framework/Python.framework" and 
112"/Applications/MacPython 2.6".  This simplifies matters for users installing 
113Python from a binary distribution if they want to get rid of it again. Moreover,
114due to the way frameworks work a user without admin privileges can install a 
115binary distribution in his or her home directory without recompilation.
116
1172. How does a framework Python differ from a normal static Python?
118------------------------------------------------------------------
119
120In everyday use there is no difference, except that things are stored in
121a different place. If you look in /Library/Frameworks/Python.framework
122you will see lots of relative symlinks, see the Apple documentation for
123details. If you are used to a normal unix Python file layout go down to
124Versions/Current and you will see the familiar bin and lib directories.
125
1263. Do I need extra packages?
127----------------------------
128
129Yes, probably.  If you want Tkinter support you need to get the OSX AquaTk 
130distribution, this is installed by default on Mac OS X 10.4 or later. If
131you want wxPython you need to get that. If you want Cocoa you need to get
132PyObjC. 
133
1344. How do I build a framework Python?
135-------------------------------------
136
137This directory contains a Makefile that will create a couple of python-related
138applications (fullblown OSX .app applications, that is) in
139"/Applications/MacPython 2.6", and a hidden helper application Python.app 
140inside the Python.framework, and unix tools "python" and "pythonw" into 
141/usr/local/bin.  In addition it has a target "installmacsubtree" that installs 
142the relevant portions of the Mac subtree into the Python.framework.
143
144It is normally invoked indirectly through the main Makefile, as the last step
145in the sequence::
146
147 $ ./configure --enable-framework
148 $ make
149 $ make install
150
151This sequence will put the framework in /Library/Framework/Python.framework,
152the applications in "/Applications/MacPython 2.6" and the unix tools in 
153/usr/local/bin.
154
155It is possible to select a different name for the framework using the configure 
156option ``--with-framework-name=NAME``. This makes it possible to have several
157parallel installs of a Python framework.
158
159Installing in another place, for instance $HOME/Library/Frameworks if you have
160no admin privileges on your machine, has only been tested very lightly. This
161can be done by configuring with --enable-framework=$HOME/Library/Frameworks.
162The other two directories, "/Applications/MacPython-2.6" and /usr/local/bin, 
163will then also be deposited in $HOME. This is sub-optimal for the unix tools, 
164which you would want in $HOME/bin, but there is no easy way to fix this right 
165now.
166
167What do all these programs do?
168===============================
169
170"IDLE.app" is an integrated development environment for Python: editor,
171debugger, etc.
172
173"PythonLauncher.app" is a helper application that will handle things when you
174double-click a .py, .pyc or .pyw file. For the first two it creates a Terminal
175window and runs the scripts with the normal command-line Python. For the
176latter it runs the script in the Python.app interpreter so the script can do
177GUI-things. Keep the "alt" key depressed while dragging or double-clicking a
178script to set runtime options. These options can be set once and for all
179through PythonLauncher's preferences dialog.
180
181"BuildApplet.app" creates an applet from a Python script. Drop the script on it
182and out comes a full-featured MacOS application. There is much more to this,
183to be supplied later. Some useful (but outdated) info can be found in
184Mac/Demo.
185
186The commandline scripts /usr/local/bin/python and pythonw can be used to run
187non-GUI and GUI python scripts from the command line, respectively.
188
189How do I create a binary distribution?
190======================================
191
192Go to the directory "Mac/OSX/BuildScript". There you'll find a script 
193"build-installer.py" that does all the work. This will download and build
194a number of 3th-party libaries, configures and builds a framework Python,
195installs it, creates the installer pacakge files and then packs this in a 
196DMG image.
197
198The script will build a universal binary, you'll therefore have to run this
199script on Mac OS X 10.4 or later and with Xcode 2.1 or later installed.
200
201All of this is normally done completely isolated in /tmp/_py, so it does not
202use your normal build directory nor does it install into /.
203
204Because of the way the script locates the files it needs you have to run it
205from within the BuildScript directory. The script accepts a number of 
206command-line arguments, run it with --help for more information.
207
208Odds and ends
209=============
210
211Something to take note of is that the ".rsrc" files in the distribution are
212not actually resource files, they're AppleSingle encoded resource files. The
213macresource module and the Mac/OSX/Makefile cater for this, and create
214".rsrc.df.rsrc" files on the fly that are normal datafork-based resource
215files.
216
217	Jack Jansen, Jack.Jansen@cwi.nl, 15-Jul-2004.
218	Ronald Oussoren, RonaldOussoren@mac.com, 26-May-2006