• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1Building a Python Mac OS X distribution
2=======================================
3
4The ``build-install.py`` script creates Python distributions, including
5certain third-party libraries as necessary.  It builds a complete
6framework-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
11For Python 3.4.0, PSF practice is to build two installer variants
12for each release.
13
141.  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
502.  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
134General 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
159The Recipe
160----------
161
162Here 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
174Building other universal installers
175...................................
176
177It is also possible to build a 4-way universal installer that runs on
178OS 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
185This requires that the deployment target is 10.5, and hence
186also that you are building on at least OS X 10.5.  4-way includes
187``i386``, ``x86_64``, ``ppc``, and ``ppc64`` (G5).  ``ppc64`` executable
188variants can only be run on G5 machines running 10.5.  Note that,
189while OS X 10.6 is only supported on Intel-based machines, it is possible
190to run ``ppc`` (32-bit) executables unmodified thanks to the Rosetta ppc
191emulation in OS X 10.5 and 10.6.  The 4-way installer variant must be
192built with Xcode 3.  It is not regularly built or tested.
193
194Other ``--universal-archs`` options are ``64-bit`` (``x86_64``, ``ppc64``),
195and ``3-way`` (``ppc``, ``i386``, ``x86_64``).  None of these options
196are regularly exercised; use at your own risk.
197
198
199Testing
200-------
201
202Ideally, the resulting binaries should be installed and the test suite run
203on all supported OS X releases and architectures.  As a practical matter,
204that is generally not possible.  At a minimum, variant 1 should be run on
205a PPC G4 system with OS X 10.5 and at least one Intel system running OS X
20610.9, 10.8, 10.7, 10.6, or 10.5.  Variant 2 should be run on 10.9, 10.8,
20710.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
212Certain tests will be skipped and some cause the interpreter to fail
213which will likely generate ``Python quit unexpectedly`` alert messages
214to be generated at several points during a test run.  These are normal
215during testing and can be ignored.
216
217It is also recommend to launch IDLE and verify that it is at least
218functional.  Double-click on the IDLE app icon in ``/Applications/Python n.n``.
219It should also be tested from the command line::
220
221    /usr/local/bin/idlen.n
222
223