Debian Codegraph @

Mac/BuildScript/README.rst

raw
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 The installer package built on the dmg is a macOS bundle format installer
11 package. This format is deprecated and is no longer supported by modern
12 macOS systems; it is usable on macOS 10.6 and earlier systems.
13 To be usable on newer versions of macOS, the bits in the bundle package
14 must be assembled in a macOS flat installer package, using current
15 versions of the pkgbuild and productbuild utilities. To pass macoS
16 Gatekeeper download quarantine, the final package must be signed
17 with a valid Apple Developer ID certificate using productsign.
18 Starting with macOS 10.15 Catalina, Gatekeeper now also requires
19 that installer packages are submitted to and pass Apple's automated
20 notarization service using the ``notarytool`` command. To pass notarization,
21 the binaries included in the package must be built with at least
22 the macOS 10.9 SDK, must now be signed with the codesign utility,
23 and executables must opt in to the hardened run time option with
24 any necessary entitlements. Details of these processes are
25 available in the on-line Apple Developer Documentation and man pages.
26
27 A goal of PSF-provided (python.org) Python binaries for macOS is to
28 support a wide-range of operating system releases with one set of
29 binaries. Currently, the oldest release supported by python.org
30 binaries is macOS 10.9; it should still be possible to build Python and
31 Python installers on older versions of macOS but we not regularly
32 test on those systems nor provide binaries for them.
33
34 Prior to Python 3.9.1, no Python releases supported building on a
35 newer version of macOS that will run on older versions
36 by setting MACOSX_DEPLOYMENT_TARGET. This is because the various
37 Python C modules did not yet support runtime testing of macOS
38 feature availability (for example, by using macOS AvailabilityMacros.h
39 and weak-linking). To build a Python that is to be used on a
40 range of macOS releases, it was necessary to always build on the
41 oldest release to be supported; the necessary shared libraries for
42 that release will normally also be available on later systems,
43 with the occasional exception such as the removal of 32-bit
44 libraries in macOS 10.15. For 3.9.x and recent earlier systems,
45 PSF practice was to provide a "macOS 64-bit Intel installer" variant
46 that was built on 10.9 that would run on macOS 10.9 and later.
47
48 Starting with 3.9.1, Python fully supports macOS "weaklinking",
49 meaning it is now possible to build a Python on a current macOS version
50 with a deployment target of an earlier macOS system. For 3.9.1 and
51 later systems, we provide a "macOS 64-bit universal2 installer"
52 variant, currently built on macOS 11 Big Sur with fat binaries
53 natively supporting both Apple Silicon (arm64) and Intel-64
54 (x86_64) Macs running macOS 10.9 or later.
55
56 build-installer.py requires Apple Developer tools, either from the
57 Command Line Tools package or from a full Xcode installation.
58 You should use the most recent version of either for the operating
59 system version in use. (One notable exception: on macOS 10.6,
60 Snow Leopard, use Xcode 3, not Xcode 4 which was released later
61 in the 10.6 support cycle.) build-installer.py also must be run
62 with recent versions of Python 3.x. On older systems,
63 due to changes in TLS practices, it may be easier to manually
64 download and cache third-party source distributions used by
65 build-installer.py rather than have it attempt to automatically
66 download them.
67
68 1. universal2, arm64 and x86_64, for OS X 10.9 (and later)::
69
70 /path/to/bootstrap/python3 build-installer.py \
71 --universal-archs=universal2 \
72 --dep-target=10.9
73
74 - builds the following third-party libraries
75
76 * OpenSSL 3.0.x
77 * Tcl/Tk 8.6.x
78 * NCurses
79 * SQLite
80 * XZ
81 * mpdecimal
82
83 - uses system-supplied versions of third-party libraries
84
85 * readline module links with Apple BSD editline (libedit)
86 * zlib
87 * bz2
88
89 - recommended build environment:
90
91 * Mac OS X 11 or later
92 * Xcode Command Line Tools 12.5 or later
93 * current default macOS SDK
94 * ``MACOSX_DEPLOYMENT_TARGET=10.9``
95 * Apple ``clang``
96
97
98 General Prerequisites
99 ---------------------
100
101 * No Fink (in ``/sw``) or MacPorts (in ``/opt/local``) or Homebrew or
102 other local libraries or utilities (in ``/usr/local``) as they could
103 interfere with the build.
104
105 * It is safest to start each variant build with an empty source directory
106 populated with a fresh copy of the untarred source or a source repo.
107
108 * It is recommended that you remove any existing installed version of the
109 Python being built::
110
111 sudo rm -rf /Library/Frameworks/Python.framework/Versions/n.n
112