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