============ MacOSX Notes ============ This document provides a quick overview of some Mac OS X specific features in the Python distribution. Mac-specific arguments to configure =================================== * ``--enable-framework[=DIR]`` If this argument is specified the build will create a Python.framework rather than a traditional Unix install. See the section _`Building and using a framework-based Python on Mac OS X` for more information on frameworks. If the optional directory argument is specified the framework it installed into that directory. This can be used to install a python framework into your home directory:: $ configure --enable-framework=/Users/ronald/Library/Frameworks $ make && make install This will install the framework itself in ``/Users/ronald/Library/Frameworks``, the applications in a subdirectory of ``/Users/ronald/Applications`` and the command-line tools in ``/Users/ronald/bin``. * ``--with-framework-name=NAME`` Specify the name for the python framework, defaults to ``Python``. This option is only valid when ``--enable-framework`` is specified. * ``--enable-universalsdk[=PATH]`` Create a universal binary build of of Python. This can be used with both regular and framework builds. The optional argument specifies which OSX SDK should be used to perform the build. This defaults to ``/Developer/SDKs/MacOSX.10.4u.sdk``, specify ``/`` when building on a 10.5 system, especially when building 64-bit code. See the section _`Building and using a universal binary of Python on Mac OS X` for more information. * ``--with-univeral-archs=VALUE`` Specify the kind of universal binary that should be created. This option is only valid when ``--enable-universalsdk`` is specified. Building and using a universal binary of Python on Mac OS X =========================================================== 1. What is a universal binary ----------------------------- A universal binary build of Python contains object code for both PPC and i386 and can therefore run at native speed on both classic powerpc based macs and the newer intel based macs. 2. How do I build a universal binary ------------------------------------ You can enable universal binaries by specifying the "--enable-universalsdk" flag to configure:: $ ./configure --enable-universalsdk $ make $ make install This flag can be used a framework build of python, but also with a classic unix build. Either way you will have to build python on Mac OS X 10.4 (or later) with Xcode 2.1 (or later). You also have to install the 10.4u SDK when installing Xcode. The option ``--enable-universalsdk`` has an optional argument to specify an SDK, which defaults to the 10.4u SDK. When you build on OSX 10.5 or later you can use the system headers instead of an SDK:: $ ./configure --enable-universalsdk=/ 2.1 Flavours of universal binaries .................................. It is possible to build a number of flavours of the universal binary build, the default is a 32-bit only binary (i386 and ppc). The flavour can be specified using the option ``--with-universal-archs=VALUE``. The following values are available: * ``32-bit``: ``ppc``, ``i386`` * ``64-bit``: ``ppc64``, ``x86_64`` * ``all``: ``ppc``, ``ppc64``, ``i386``, ``x86_64`` * ``3-way``: ``ppc``, ``i386`` and ``x86_64`` * ``intel``: ``i386``, ``x86_64`` To build a universal binary that includes a 64-bit architecture, you must build on a system running OSX 10.5 or later. The ``all`` flavour can only be built on OSX 10.5. The makefile for a framework build will install ``python32`` and ``pythonw32`` binaries when the universal architecures includes at least one 32-bit architecture (that is, for all flavours but ``64-bit``). Running a specific archicture ............................. You can run code using a specific architecture using the ``arch`` command:: $ arch -i386 python Or to explicitly run in 32-bit mode, regardless of the machine hardware:: $ arch -i386 -ppc python NOTE: When you're using a framework install of Python this requires at least Python 2.7 or 3.2, in earlier versions the python (and pythonw) commands are wrapper tools that execute the real interpreter without ensuring that the real interpreter runs with the same architecture. Building and using a framework-based Python on Mac OS X. ======================================================== 1. Why would I want a framework Python instead 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 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/MacPython 2.6". 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 Tkinter support you need to get the OSX AquaTk distribution, this is installed by default on Mac OS X 10.4 or later. If you want wxPython you need to get that. If you want Cocoa you need to get PyObjC. 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/MacPython 2.6", 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:: $ ./configure --enable-framework $ make $ make install This sequence will put the framework in /Library/Framework/Python.framework, the applications in "/Applications/MacPython 2.6" and the unix tools in /usr/local/bin. It is possible to select a different name for the framework using the configure option ``--with-framework-name=NAME``. This makes it possible to have several parallel installs of a Python framework. Installing 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/MacPython-2.6" 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. What do all these programs do? =============================== "IDLE.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. How do I create a binary distribution? ====================================== Go to the directory "Mac/OSX/BuildScript". There you'll find a script "build-installer.py" that does all the work. This will download and build a number of 3th-party libaries, configures and builds a framework Python, installs it, creates the installer pacakge files and then packs this in a DMG image. The script will build a universal binary, you'll therefore have to run this script on Mac OS X 10.4 or later and with Xcode 2.1 or later installed. All of this is normally done completely isolated in /tmp/_py, so it does not use your normal build directory nor does it install into /. Because of the way the script locates the files it needs you have to run it from within the BuildScript directory. The script accepts a number of command-line arguments, run it with --help for more information. Configure warnings ================== The configure script sometimes emits warnings like the one below:: configure: WARNING: libintl.h: present but cannot be compiled configure: WARNING: libintl.h: check for missing prerequisite headers? configure: WARNING: libintl.h: see the Autoconf documentation configure: WARNING: libintl.h: section "Present But Cannot Be Compiled" configure: WARNING: libintl.h: proceeding with the preprocessor's result configure: WARNING: libintl.h: in the future, the compiler will take precedence configure: WARNING: ## -------------------------------------- ## configure: WARNING: ## Report this to http://bugs.python.org/ ## configure: WARNING: ## -------------------------------------- ## This almost always means you are trying to build a universal binary for Python and have libaries in ``/usr/local`` that don't contain the required architectures. Temporarily move ``/usr/local`` aside to finish the build. Uninstalling a framework install, including the binary installer ================================================================ Uninstalling a framework can be done by manually removing all bits that got installed, that's true for both installations from source and installations using the binary installer. Sadly enough OSX does not have a central uninstaller. The main bit of a framework install is the framework itself, installed in ``/Library/Frameworks/Python.framework``. This can contain multiple versions of Python, if you want to remove just one version you have to remove the version-specific subdirectory: ``/Library/Frameworks/Python.framework/Versions/X.Y``. If you do that, ensure that ``/Library/Frameworks/Python.framework/Versions/Current`` is a symlink that points to an installed version of Python. A framework install also installs some applications in ``/Applications/Python X.Y``, And lastly a framework installation installs files in ``/usr/local/bin``, all of them symbolic links to files in ``/Library/Frameworks/Python.framework/Versions/X.Y/bin``. Odds and ends ============= 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.Jansen@cwi.nl, 15-Jul-2004. Ronald Oussoren, RonaldOussoren@mac.com, 30-April-2010