1 Building a Python Mac OS X distribution 2 ======================================= 3 4 The ``build-install.py`` script creates Python distributions, including 5 certain third-party libraries as necessary. It builds a complete 6 framework-based Python out-of-tree, installs it in a funny place with 7 $DESTROOT, massages that installation to remove .pyc files and such, creates 8 an Installer package from the installation plus other files in ``resources`` 9 and ``scripts`` and placed that on a ``.dmg`` disk image. 10 11 For Python 3.4.0, PSF practice is to build two installer variants 12 for each release. 13 14 1. 32-bit-only, i386 and PPC universal, capable on running on all machines 15 supported by Mac OS X 10.5 through (at least) 10.9:: 16 17 /path/to/bootstrap/python2.7 build-installer.py \ 18 --sdk-path=/Developer/SDKs/MacOSX10.5.sdk \ 19 --universal-archs=32-bit \ 20 --dep-target=10.5 21 22 - builds the following third-party libraries 23 24 * NCurses 5.9 (http://bugs.python.org/issue15037) 25 * SQLite 3.8.11 26 * XZ 5.0.5 27 28 - uses system-supplied versions of third-party libraries 29 30 * readline module links with Apple BSD editline (libedit) 31 32 - requires ActiveState ``Tcl/Tk 8.4`` (currently 8.4.20) to be installed for building 33 34 - recommended build environment: 35 36 * Mac OS X 10.5.8 Intel or PPC 37 * Xcode 3.1.4 38 * ``MacOSX10.5`` SDK 39 * ``MACOSX_DEPLOYMENT_TARGET=10.5`` 40 * Apple ``gcc-4.2`` 41 * bootstrap non-framework Python 2.7 for documentation build with 42 Sphinx (as of 3.4.1) 43 44 - alternate build environments: 45 46 * Mac OS X 10.6.8 with Xcode 3.2.6 47 - need to change ``/System/Library/Frameworks/{Tcl,Tk}.framework/Version/Current`` to ``8.4`` 48 * Note Xcode 4.* does not support building for PPC so cannot be used for this build 49 50 2. 64-bit / 32-bit, x86_64 and i386 universal, for OS X 10.6 (and later):: 51 52 /path/to/bootstrap/python2.7 build-installer.py \ 53 --sdk-path=/Developer/SDKs/MacOSX10.6.sdk \ 54 --universal-archs=intel \ 55 --dep-target=10.6 56 57 - builds the following third-party libraries 58 59 * NCurses 5.9 (http://bugs.python.org/issue15037) 60 * SQLite 3.8.11 61 * XZ 5.0.5 62 63 - uses system-supplied versions of third-party libraries 64 65 * readline module links with Apple BSD editline (libedit) 66 67 - requires ActiveState Tcl/Tk 8.5.15.1 (or later) to be installed for building 68 69 - recommended build environment: 70 71 * Mac OS X 10.6.8 (or later) 72 * Xcode 3.2.6 73 * ``MacOSX10.6`` SDK 74 * ``MACOSX_DEPLOYMENT_TARGET=10.6`` 75 * Apple ``gcc-4.2`` 76 * bootstrap non-framework Python 2.7 for documentation build with 77 Sphinx (as of 3.4.1) 78 79 - alternate build environments: 80 81 * none. Xcode 4.x currently supplies two C compilers. 82 ``llvm-gcc-4.2.1`` has been found to miscompile Python 3.3.x and 83 produce a non-functional Python executable. As it appears to be 84 considered a migration aid by Apple and is not likely to be fixed, 85 its use should be avoided. The other compiler, ``clang``, has been 86 undergoing rapid development. While it appears to have become 87 production-ready in the most recent Xcode 5 releases, the versions 88 available on the deprecated Xcode 4.x for 10.6 were early releases 89 and did not receive the level of exposure in production environments 90 that the Xcode 3 gcc-4.2 compiler has had. 91 92 93 * For Python 2.7.x and 3.2.x, the 32-bit-only installer was configured to 94 support Mac OS X 10.3.9 through (at least) 10.6. Because it is 95 believed that there are few systems still running OS X 10.3 or 10.4 96 and because it has become increasingly difficult to test and 97 support the differences in these earlier systems, as of Python 3.3.0 the PSF 98 32-bit installer no longer supports them. For reference in building such 99 an installer yourself, the details are:: 100 101 /usr/bin/python build-installer.py \ 102 --sdk-path=/Developer/SDKs/MacOSX10.4u.sdk \ 103 --universal-archs=32-bit \ 104 --dep-target=10.3 105 106 - builds the following third-party libraries 107 108 * Bzip2 109 * NCurses 110 * GNU Readline (GPL) 111 * SQLite 3 112 * XZ 113 * Zlib 1.2.3 114 * Oracle Sleepycat DB 4.8 (Python 2.x only) 115 116 - requires ActiveState ``Tcl/Tk 8.4`` (currently 8.4.20) to be installed for building 117 118 - recommended build environment: 119 120 * Mac OS X 10.5.8 PPC or Intel 121 * Xcode 3.1.4 (or later) 122 * ``MacOSX10.4u`` SDK (later SDKs do not support PPC G3 processors) 123 * ``MACOSX_DEPLOYMENT_TARGET=10.3`` 124 * Apple ``gcc-4.0`` 125 * system Python 2.5 for documentation build with Sphinx 126 127 - alternate build environments: 128 129 * Mac OS X 10.6.8 with Xcode 3.2.6 130 - need to change ``/System/Library/Frameworks/{Tcl,Tk}.framework/Version/Current`` to ``8.4`` 131 132 133 134 General Prerequisites 135 --------------------- 136 137 * No Fink (in ``/sw``) or MacPorts (in ``/opt/local``) or other local 138 libraries or utilities (in ``/usr/local``) as they could 139 interfere with the build. 140 141 * The documentation for the release is built using Sphinx 142 because it is included in the installer. For 2.7.x and 3.x.x up to and 143 including 3.4.0, the ``Doc/Makefile`` uses ``svn`` to download repos of 144 ``Sphinx`` and its dependencies. Beginning with 3.4.1, the ``Doc/Makefile`` 145 assumes there is an externally-provided ``sphinx-build`` and requires at 146 least Python 2.6 to run. Because of this, it is no longer possible to 147 build a 3.4.1 or later installer on OS X 10.5 using the Apple-supplied 148 Python 2.5. 149 150 * It is safest to start each variant build with an empty source directory 151 populated with a fresh copy of the untarred source. 152 153 * It is recommended that you remove any existing installed version of the 154 Python being built:: 155 156 sudo rm -rf /Library/Frameworks/Python.framework/Versions/n.n 157 158 159 The Recipe 160 ---------- 161 162 Here are the steps you need to follow to build a Python installer: 163 164 * Run ``build-installer.py``. Optionally you can pass a number of arguments 165 to specify locations of various files. Please see the top of 166 ``build-installer.py`` for its usage. 167 168 Running this script takes some time, it will not only build Python itself 169 but also some 3th-party libraries that are needed for extensions. 170 171 * When done the script will tell you where the DMG image is (by default 172 somewhere in ``/tmp/_py``). 173 174 Building other universal installers 175 ................................... 176 177 It is also possible to build a 4-way universal installer that runs on 178 OS X 10.5 Leopard or later:: 179 180 /usr/bin/python /build-installer.py \ 181 --dep-target=10.5 182 --universal-archs=all 183 --sdk-path=/Developer/SDKs/MacOSX10.5.sdk 184 185 This requires that the deployment target is 10.5, and hence 186 also that you are building on at least OS X 10.5. 4-way includes 187 ``i386``, ``x86_64``, ``ppc``, and ``ppc64`` (G5). ``ppc64`` executable 188 variants can only be run on G5 machines running 10.5. Note that, 189 while OS X 10.6 is only supported on Intel-based machines, it is possible 190 to run ``ppc`` (32-bit) executables unmodified thanks to the Rosetta ppc 191 emulation in OS X 10.5 and 10.6. The 4-way installer variant must be 192 built with Xcode 3. It is not regularly built or tested. 193 194 Other ``--universal-archs`` options are ``64-bit`` (``x86_64``, ``ppc64``), 195 and ``3-way`` (``ppc``, ``i386``, ``x86_64``). None of these options 196 are regularly exercised; use at your own risk. 197 198 199 Testing 200 ------- 201 202 Ideally, the resulting binaries should be installed and the test suite run 203 on all supported OS X releases and architectures. As a practical matter, 204 that is generally not possible. At a minimum, variant 1 should be run on 205 a PPC G4 system with OS X 10.5 and at least one Intel system running OS X 206 10.9, 10.8, 10.7, 10.6, or 10.5. Variant 2 should be run on 10.9, 10.8, 207 10.7, and 10.6 systems in both 32-bit and 64-bit modes.:: 208 209 /usr/local/bin/pythonn.n -m test -w -u all,-largefile 210 /usr/local/bin/pythonn.n-32 -m test -w -u all 211 212 Certain tests will be skipped and some cause the interpreter to fail 213 which will likely generate ``Python quit unexpectedly`` alert messages 214 to be generated at several points during a test run. These are normal 215 during testing and can be ignored. 216 217 It is also recommend to launch IDLE and verify that it is at least 218 functional. Double-click on the IDLE app icon in ``/Applications/Python n.n``. 219 It should also be tested from the command line:: 220 221 /usr/local/bin/idlen.n 222 223
