1========================= 2Python on Mac OS X README 3========================= 4 5:Authors: 6 Jack Jansen (2004-07), 7 Ronald Oussoren (2010-04), 8 Ned Deily (2012-06) 9 10:Version: 3.4.0 11 12This document provides a quick overview of some Mac OS X specific features in 13the Python distribution. 14 15OS X specific arguments to configure 16==================================== 17 18* ``--enable-framework[=DIR]`` 19 20 If this argument is specified the build will create a Python.framework rather 21 than a traditional Unix install. See the section 22 _`Building and using a framework-based Python on Mac OS X` for more 23 information on frameworks. 24 25 If the optional directory argument is specified the framework is installed 26 into that directory. This can be used to install a python framework into 27 your home directory:: 28 29 $ ./configure --enable-framework=/Users/ronald/Library/Frameworks 30 $ make && make install 31 32 This will install the framework itself in ``/Users/ronald/Library/Frameworks``, 33 the applications in a subdirectory of ``/Users/ronald/Applications`` and the 34 command-line tools in ``/Users/ronald/bin``. 35 36* ``--with-framework-name=NAME`` 37 38 Specify the name for the python framework, defaults to ``Python``. This option 39 is only valid when ``--enable-framework`` is specified. 40 41* ``--enable-universalsdk[=PATH]`` 42 43 Create a universal binary build of Python. This can be used with both 44 regular and framework builds. 45 46 The optional argument specifies which OS X SDK should be used to perform the 47 build. If xcodebuild is available and configured, this defaults to 48 the Xcode default MacOS X SDK, otherwise ``/Developer/SDKs/MacOSX.10.4u.sdk`` 49 if available or ``/`` if not. When building on OS X 10.5 or later, you can 50 specify ``/`` to use the installed system headers rather than an SDK. As of 51 OS X 10.9, you should install the optional system headers from the Command 52 Line Tools component using ``xcode-select``:: 53 54 $ sudo xcode-select --install 55 56 See the section _`Building and using a universal binary of Python on Mac OS X` 57 for more information. 58 59* ``--with-universal-archs=VALUE`` 60 61 Specify the kind of universal binary that should be created. This option is 62 only valid when ``--enable-universalsdk`` is specified. The default is 63 ``32-bit`` if a building with a SDK that supports PPC, otherwise defaults 64 to ``intel``. 65 66 67Building and using a universal binary of Python on Mac OS X 68=========================================================== 69 701. What is a universal binary 71----------------------------- 72 73A universal binary build of Python contains object code for more than one 74CPU architecture. A universal OS X executable file or library combines the 75architecture-specific code into one file and can therefore run at native 76speed on all supported architectures. Universal files were introduced in 77OS X 10.4 to add support for Intel-based Macs to the existing PowerPC (PPC) 78machines. In OS X 10.5 support was extended to 64-bit Intel and 64-bit PPC 79architectures. It is possible to build Python with various combinations 80of architectures depending on the build tools and OS X version in use. 81 822. How do I build a universal binary 83------------------------------------ 84 85You can enable universal binaries by specifying the "--enable-universalsdk" 86flag to configure:: 87 88 $ ./configure --enable-universalsdk 89 $ make 90 $ make install 91 92This flag can be used with a framework build of python, but also with a classic 93unix build. Universal builds were first supported with OS X 10.4 with Xcode 2.1 94and the 10.4u SDK. Starting with Xcode 3 and OS X 10.5, more configurations are 95available. 96 97In general, universal builds depend on specific features provided by the 98Apple-supplied compilers and other build tools included in Apple's Xcode 99development tools. You should install Xcode and the command line tools 100component appropriate for the OS X release you are running on. See the 101Python Developer's Guide (http://docs.python.org/devguide/setup.html) 102for more information. 103 1042.1 Flavors of universal binaries 105................................. 106 107It is possible to build a number of flavors of the universal binary build, 108the default is a 32-bit only binary (i386 and ppc) in build environments that 109support ppc (10.4 with Xcode 2, 10.5 and 10.6 with Xcode 3) or an 110Intel-32/-64-bit binary (i386 and X86_64) in build environments that do not 111support ppc (Xcode 4 on 10.6 and later systems). The flavor can be specified 112using the configure option ``--with-universal-archs=VALUE``. The following 113values are available: 114 115 * ``intel``: ``i386``, ``x86_64`` 116 117 * ``intel-32``: ``i386`` 118 119 * ``32-bit``: ``ppc``, ``i386`` 120 121 * ``3-way``: ``i386``, ``x86_64``, ``ppc`` 122 123 * ``64-bit``: ``ppc64``, ``x86_64`` 124 125 * ``all``: ``ppc``, ``ppc64``, ``i386``, ``x86_64`` 126 127To build a universal binary that includes a 64-bit architecture, you must build 128on a system running OS X 10.5 or later. The ``all`` and ``64-bit`` flavors can 129only be built with a 10.5 SDK because ``ppc64`` support was only included with 130OS X 10.5. Although legacy ``ppc`` support was included with Xcode 3 on OS X 13110.6, it was removed in Xcode 4, versions of which were released on OS X 10.6 132and which is the standard for OS X 10.7. To summarize, the 133following combinations of SDKs and universal-archs flavors are available: 134 135 * 10.4u SDK with Xcode 2 supports ``32-bit`` only 136 137 * 10.5 SDK with Xcode 3.1.x supports all flavors 138 139 * 10.6 SDK with Xcode 3.2.x supports ``intel``, ``3-way``, and ``32-bit`` 140 141 * 10.6 SDK with Xcode 4 supports ``intel`` only 142 143 * 10.7 and 10.8 SDKs with Xcode 4 support ``intel`` only 144 145 * 10.8 and 10.9 SDKs with Xcode 5 support ``intel`` only 146 147The makefile for a framework build will also install ``python3.4-32`` 148binaries when the universal architecture includes at least one 32-bit 149architecture (that is, for all flavors but ``64-bit``). 150 151Running a specific architecture 152............................... 153 154You can run code using a specific architecture using the ``arch`` command:: 155 156 $ arch -i386 python 157 158Or to explicitly run in 32-bit mode, regardless of the machine hardware:: 159 160 $ arch -i386 -ppc python 161 162NOTE: When you're using a framework install of Python this requires at least 163Python 2.7 or 3.2, in earlier versions the python (and pythonw) commands are 164wrapper tools that execute the real interpreter without ensuring that the 165real interpreter runs with the same architecture. 166 167Using ``arch`` is not a perfect solution as the selected architecture will 168not automatically carry through to subprocesses launched by programs and tests 169under that Python. If you want to ensure that Python interpreters launched in 170subprocesses also run in 32-bit-mode if the main interpreter does, use 171a ``python3.4-32`` binary and use the value of ``sys.executable`` as the 172``subprocess`` ``Popen`` executable value. 173 174Building and using a framework-based Python on Mac OS X. 175======================================================== 176 177 1781. Why would I want a framework Python instead of a normal static Python? 179-------------------------------------------------------------------------- 180 181The main reason is because you want to create GUI programs in Python. With the 182exception of X11/XDarwin-based GUI toolkits all GUI programs need to be run 183from a Mac OS X application bundle (".app"). 184 185While it is technically possible to create a .app without using frameworks you 186will have to do the work yourself if you really want this. 187 188A second reason for using frameworks is that they put Python-related items in 189only two places: "/Library/Framework/Python.framework" and 190"/Applications/Python <VERSION>" where ``<VERSION>`` can be e.g. "3.4", 191"2.7", etc. This simplifies matters for users installing 192Python from a binary distribution if they want to get rid of it again. Moreover, 193due to the way frameworks work, a user without admin privileges can install a 194binary distribution in his or her home directory without recompilation. 195 1962. How does a framework Python differ from a normal static Python? 197------------------------------------------------------------------ 198 199In everyday use there is no difference, except that things are stored in 200a different place. If you look in /Library/Frameworks/Python.framework 201you will see lots of relative symlinks, see the Apple documentation for 202details. If you are used to a normal unix Python file layout go down to 203Versions/Current and you will see the familiar bin and lib directories. 204 2053. Do I need extra packages? 206---------------------------- 207 208Yes, probably. If you want Tkinter support you need to get the OS X AquaTk 209distribution, this is installed by default on Mac OS X 10.4 or later. Be 210aware, though, that the Cocoa-based AquaTk's supplied starting with OS X 21110.6 have proven to be unstable. If possible, you should consider 212installing a newer version before building on OS X 10.6 or later, such as 213the ActiveTcl 8.5. See http://www.python.org/download/mac/tcltk/. If you 214are building with an SDK, ensure that the newer Tcl and Tk frameworks are 215seen in the SDK's ``Library/Frameworks`` directory; you may need to 216manually create symlinks to their installed location, ``/Library/Frameworks``. 217If you want wxPython you need to get that. 218If you want Cocoa you need to get PyObjC. 219 2204. How do I build a framework Python? 221------------------------------------- 222 223This directory contains a Makefile that will create a couple of python-related 224applications (full-blown OS X .app applications, that is) in 225"/Applications/Python <VERSION>", and a hidden helper application Python.app 226inside the Python.framework, and unix tools including "python" into 227/usr/local/bin. In addition it has a target "installmacsubtree" that installs 228the relevant portions of the Mac subtree into the Python.framework. 229 230It is normally invoked indirectly through the main Makefile, as the last step 231in the sequence 232 233 1. ./configure --enable-framework 234 235 2. make 236 237 3. make install 238 239This sequence will put the framework in ``/Library/Framework/Python.framework``, 240the applications in ``/Applications/Python <VERSION>`` and the unix tools in 241``/usr/local/bin``. 242 243Installing in another place, for instance ``$HOME/Library/Frameworks`` if you 244have no admin privileges on your machine, is possible. This can be accomplished 245by configuring with ``--enable-framework=$HOME/Library/Frameworks``. 246The other two directories will then also be installed in your home directory, 247at ``$HOME/Applications/Python-<VERSION>`` and ``$HOME/bin``. 248 249If you want to install some part, but not all, read the main Makefile. The 250frameworkinstall is composed of a couple of sub-targets that install the 251framework itself, the Mac subtree, the applications and the unix tools. 252 253There is an extra target frameworkinstallextras that is not part of the 254normal frameworkinstall which installs the Tools directory into 255"/Applications/Python <VERSION>", this is useful for binary 256distributions. 257 258What do all these programs do? 259=============================== 260 261"IDLE.app" is an integrated development environment for Python: editor, 262debugger, etc. 263 264"Python Launcher.app" is a helper application that will handle things when you 265double-click a .py, .pyc or .pyw file. For the first two it creates a Terminal 266window and runs the scripts with the normal command-line Python. For the 267latter it runs the script in the Python.app interpreter so the script can do 268GUI-things. Keep the ``Option`` key depressed while dragging or double-clicking 269a script to set runtime options. These options can be set persistently 270through Python Launcher's preferences dialog. 271 272The program ``pythonx.x`` runs python scripts from the command line. 273Previously, various compatibility aliases were also installed, including 274``pythonwx.x`` which in early releases of Python on OS X was required to run 275GUI programs. As of 3.4.0, the ``pythonwx.x`` aliases are no longer installed. 276 277How do I create a binary distribution? 278====================================== 279 280Download and unpack the source release from http://www.python.org/download/. 281Go to the directory ``Mac/BuildScript``. There you will find a script 282``build-installer.py`` that does all the work. This will download and build 283a number of 3rd-party libaries, configures and builds a framework Python, 284installs it, creates the installer package files and then packs this in a 285DMG image. The script also builds an HTML copy of the current Python 286documentation set for this release for inclusion in the framework. The 287installer package will create links to the documentation for use by IDLE, 288pydoc, shell users, and Finder user. 289 290The script will build a universal binary so you'll therefore have to run this 291script on Mac OS X 10.4 or later and with Xcode 2.1 or later installed. 292However, the Python build process itself has several build dependencies not 293available out of the box with OS X 10.4 so you may have to install 294additional software beyond what is provided with Xcode 2. OS X 10.5 295provides a recent enough system Python (in ``/usr/bin``) to build 296the Python documentation set. It should be possible to use SDKs and/or older 297versions of Xcode to build installers that are compatible with older systems 298on a newer system but this may not be completely foolproof so the resulting 299executables, shared libraries, and ``.so`` bundles should be carefully 300examined and tested on all supported systems for proper dynamic linking 301dependencies. It is safest to build the distribution on a system running the 302minimum OS X version supported. 303 304All of this is normally done completely isolated in /tmp/_py, so it does not 305use your normal build directory nor does it install into /. 306 307Because of the way the script locates the files it needs you have to run it 308from within the BuildScript directory. The script accepts a number of 309command-line arguments, run it with --help for more information. 310 311Configure warnings 312================== 313 314The configure script sometimes emits warnings like the one below:: 315 316 configure: WARNING: libintl.h: present but cannot be compiled 317 configure: WARNING: libintl.h: check for missing prerequisite headers? 318 configure: WARNING: libintl.h: see the Autoconf documentation 319 configure: WARNING: libintl.h: section "Present But Cannot Be Compiled" 320 configure: WARNING: libintl.h: proceeding with the preprocessor's result 321 configure: WARNING: libintl.h: in the future, the compiler will take precedence 322 configure: WARNING: ## -------------------------------------- ## 323 configure: WARNING: ## Report this to http://bugs.python.org/ ## 324 configure: WARNING: ## -------------------------------------- ## 325 326This almost always means you are trying to build a universal binary for 327Python and have libraries in ``/usr/local`` that don't contain the required 328architectures. Temporarily move ``/usr/local`` aside to finish the build. 329 330 331Uninstalling a framework install, including the binary installer 332================================================================ 333 334Uninstalling a framework can be done by manually removing all bits that got installed. 335That's true for both installations from source and installations using the binary installer. 336OS X does not provide a central uninstaller. 337 338The main bit of a framework install is the framework itself, installed in 339``/Library/Frameworks/Python.framework``. This can contain multiple versions 340of Python, if you want to remove just one version you have to remove the 341version-specific subdirectory: ``/Library/Frameworks/Python.framework/Versions/X.Y``. 342If you do that, ensure that ``/Library/Frameworks/Python.framework/Versions/Current`` 343is a symlink that points to an installed version of Python. 344 345A framework install also installs some applications in ``/Applications/Python X.Y``, 346 347And lastly a framework installation installs files in ``/usr/local/bin``, all of 348them symbolic links to files in ``/Library/Frameworks/Python.framework/Versions/X.Y/bin``. 349 350 351Resources 352========= 353 354 * http://www.python.org/download/mac/ 355 356 * http://www.python.org/community/sigs/current/pythonmac-sig/ 357 358 * http://docs.python.org/devguide/