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