blob: de2f5cb359c62d09d4d85009fa148ceb73aa9878 [file] [log] [blame]
Ned Deily22726702011-01-15 04:44:12 +00001Building a Python Mac OS X distribution
2=======================================
Thomas Wouters477c8d52006-05-27 19:21:47 +00003
Ned Deily22726702011-01-15 04:44:12 +00004The ``build-install.py`` script creates Python distributions, including
5certain third-party libraries as necessary. It builds a complete
Thomas Wouters477c8d52006-05-27 19:21:47 +00006framework-based Python out-of-tree, installs it in a funny place with
7$DESTROOT, massages that installation to remove .pyc files and such, creates
8an Installer package from the installation plus other files in ``resources``
9and ``scripts`` and placed that on a ``.dmg`` disk image.
10
Ned Deily22726702011-01-15 04:44:12 +000011As of Python 2.7.x and 3.2, PSF practice is to build two installer variants
12for each release:
Thomas Wouters477c8d52006-05-27 19:21:47 +000013
Ned Deily22726702011-01-15 04:44:12 +0000141. 32-bit-only, i386 and PPC universal, capable on running on all machines
15 supported by Mac OS X 10.3.9 through (at least) 10.6::
Thomas Wouters0e3f5912006-08-11 14:57:12 +000016
Ned Deilye59e4c52011-01-29 18:56:28 +000017 python build-installer.py \
Ned Deily22726702011-01-15 04:44:12 +000018 --sdk-path=/Developer/SDKs/MacOSX10.4u.sdk \
19 --universal-archs=32-bit \
20 --dep-target=10.3
21 # These are the current default options
Thomas Wouters0e3f5912006-08-11 14:57:12 +000022
Ned Deily22726702011-01-15 04:44:12 +000023 - builds the following third-party libraries
24
25 * Bzip2
26 * Zlib 1.2.3
27 * GNU Readline (GPL)
28 * SQLite 3
29 * NCurses
30 * Oracle Sleepycat DB 4.8 (Python 2.x only)
31
32 - requires ActiveState ``Tcl/Tk 8.4`` (currently 8.4.19) to be installed for building
33
34 - current target build environment:
35
36 * Mac OS X 10.5.8 PPC or Intel
37 * Xcode 3.1.4 (or later)
38 * ``MacOSX10.4u`` SDK (later SDKs do not support PPC G3 processors)
39 * ``MACOSX_DEPLOYMENT_TARGET=10.3``
40 * Apple ``gcc-4.0``
Ned Deilye59e4c52011-01-29 18:56:28 +000041 * Python 2.n (n >= 4) for documentation build with Sphinx
Ned Deily22726702011-01-15 04:44:12 +000042
43 - alternate build environments:
44
45 * Mac OS X 10.4.11 with Xcode 2.5
46 * Mac OS X 10.6.6 with Xcode 3.2.5
47 - need to change ``/System/Library/Frameworks/{Tcl,Tk}.framework/Version/Current`` to ``8.4``
48
492. 64-bit / 32-bit, x86_64 and i386 universal, for OS X 10.6 (and later)::
50
Ned Deilye59e4c52011-01-29 18:56:28 +000051 python build-installer.py \
Ned Deily22726702011-01-15 04:44:12 +000052 --sdk-path=/Developer/SDKs/MacOSX10.6.sdk \
53 --universal-archs=intel \
54 --dep-target=10.6
55
56 - uses system-supplied versions of third-party libraries
57
58 * readline module links with Apple BSD editline (libedit)
59 * builds Oracle Sleepycat DB 4.8 (Python 2.x only)
60
61 - requires ActiveState Tcl/Tk 8.5.9 (or later) to be installed for building
62
63 - current target build environment:
64
65 * Mac OS X 10.6.6 (or later)
66 * Xcode 3.2.5 (or later)
67 * ``MacOSX10.6`` SDK
68 * ``MACOSX_DEPLOYMENT_TARGET=10.6``
69 * Apple ``gcc-4.2``
Ned Deilye59e4c52011-01-29 18:56:28 +000070 * Python 2.n (n >= 4) for documentation build with Sphinx
Ned Deily22726702011-01-15 04:44:12 +000071
72 - alternate build environments:
73
74 * none
75
76
77General Prerequisites
78---------------------
79
80* No Fink (in ``/sw``) or MacPorts (in ``/opt/local``) or other local
81 libraries or utilities (in ``/usr/local``) as they could
Thomas Wouters0e3f5912006-08-11 14:57:12 +000082 interfere with the build.
83
Ned Deily22726702011-01-15 04:44:12 +000084* The documentation for the release is built using Sphinx
Thomas Wouters0e3f5912006-08-11 14:57:12 +000085 because it is included in the installer.
86
Ned Deily22726702011-01-15 04:44:12 +000087* It is safest to start each variant build with an empty source directory
88 populated with a fresh copy of the untarred source.
89
Thomas Wouters0e3f5912006-08-11 14:57:12 +000090
91The Recipe
92----------
93
Ned Deily22726702011-01-15 04:44:12 +000094Here are the steps you need to follow to build a Python installer:
Thomas Wouters0e3f5912006-08-11 14:57:12 +000095
Ned Deily22726702011-01-15 04:44:12 +000096* Run ``build-installer.py``. Optionally you can pass a number of arguments
97 to specify locations of various files. Please see the top of
Thomas Wouters477c8d52006-05-27 19:21:47 +000098 ``build-installer.py`` for its usage.
Thomas Wouters477c8d52006-05-27 19:21:47 +000099
Ned Deily22726702011-01-15 04:44:12 +0000100 Running this script takes some time, it will not only build Python itself
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000101 but also some 3th-party libraries that are needed for extensions.
102
103* When done the script will tell you where the DMG image is (by default
104 somewhere in ``/tmp/_py``).
105
Ned Deily22726702011-01-15 04:44:12 +0000106Building other universal installers
107...................................
Ronald Oussoren1943f862009-03-30 19:39:14 +0000108
109It is also possible to build a 4-way universal installer that runs on
Ned Deily22726702011-01-15 04:44:12 +0000110OS X Leopard or later::
Ronald Oussoren1943f862009-03-30 19:39:14 +0000111
Ned Deily22726702011-01-15 04:44:12 +0000112 python 2.6 /build-installer.py \
113 --dep-target=10.5
114 --universal-archs=all
115 --sdk-path=/Developer/SDKs/MacOSX10.5.sdk
Ronald Oussoren1943f862009-03-30 19:39:14 +0000116
Ned Deily22726702011-01-15 04:44:12 +0000117This requires that the deployment target is 10.5, and hence
118also that you are building on at least OS X 10.5. 4-way includes
119``i386``, ``x86_64``, ``ppc``, and ``ppc64`` (G5). ``ppc64`` executable
120variants can only be run on G5 machines running 10.5. Note that,
121while OS X 10.6 is only supported on Intel-based machines, it is possible
122to run ``ppc`` (32-bit) executables unmodified thanks to the Rosetta ppc
123emulation in OS X 10.5 and 10.6.
124
125Other ``--universal-archs`` options are ``64-bit`` (``x86_64``, ``ppc64``),
126and ``3-way`` (``ppc``, ``i386``, ``x86_64``). None of these options
127are regularly exercised; use at your own risk.
128
Ronald Oussoren1943f862009-03-30 19:39:14 +0000129
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000130Testing
131-------
132
Ned Deily22726702011-01-15 04:44:12 +0000133Ideally, the resulting binaries should be installed and the test suite run
134on all supported OS X releases and architectures. As a practical matter,
135that is generally not possible. At a minimum, variant 1 should be run on
136at least one Intel, one PPC G4, and one PPC G3 system and one each of
137OS X 10.6, 10.5, 10.4, and 10.3.9. Not all tests run on 10.3.9.
138Variant 2 should be run on 10.6 in both 32-bit and 64-bit modes.::
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000139
Ned Deily22726702011-01-15 04:44:12 +0000140 arch -i386 /usr/local/bin/pythonn.n -m test.regrtest -w -u all
141 arch -X86_64 /usr/local/bin/pythonn.n -m test.regrtest -w -u all
142
143Certain tests will be skipped and some cause the interpreter to fail
144which will likely generate ``Python quit unexpectedly`` alert messages
145to be generated at several points during a test run. These can
146be ignored.
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000147