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 ``notarytool`` 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 should still be 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 built 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 56build-installer.py requires Apple Developer tools, either from the 57Command Line Tools package or from a full Xcode installation. 58You should use the most recent version of either for the operating 59system version in use. (One notable exception: on macOS 10.6, 60Snow Leopard, use Xcode 3, not Xcode 4 which was released later 61in the 10.6 support cycle.) build-installer.py also must be run 62with recent versions of Python 3.x. On older systems, 63due to changes in TLS practices, it may be easier to manually 64download and cache third-party source distributions used by 65build-installer.py rather than have it attempt to automatically 66download them. 67 681. 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 98General 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 113