Name |
Date |
Size |
#Lines |
LOC |
||
---|---|---|---|---|---|---|
.. | - | - | ||||
BuildScript/ | 12-May-2024 | - | 2,548 | 1,948 | ||
IDLE/IDLE.app/Contents/ | 12-May-2024 | - | 159 | 99 | ||
Icons/ | 12-May-2024 | - | 4 | 2 | ||
PythonLauncher/ | 12-May-2024 | - | 1,323 | 1,136 | ||
Resources/ | 12-May-2024 | - | 93 | 91 | ||
Tools/ | 12-May-2024 | - | 347 | 208 | ||
Extras.install.py | D | 12-May-2024 | 1.6 KiB | 55 | 48 | |
Makefile.in | D | 12-May-2024 | 8.4 KiB | 278 | 245 | |
README.rst | D | 12-May-2024 | 17.6 KiB | 407 | 299 |
README.rst
1====================== 2Python on macOS README 3====================== 4 5:Authors: 6 Jack Jansen (2004-07), 7 Ronald Oussoren (2010-04), 8 Ned Deily (2012-06) 9 10This document provides a quick overview of some macOS specific features in 11the Python distribution. 12 13macOS specific arguments to configure 14===================================== 15 16* ``--enable-framework[=DIR]`` 17 18 If this argument is specified the build will create a Python.framework rather 19 than a traditional Unix install. See the section 20 _`Building and using a framework-based Python on macOS` for more 21 information on frameworks. 22 23 If the optional directory argument is specified the framework is installed 24 into that directory. This can be used to install a python framework into 25 your home directory:: 26 27 $ ./configure --enable-framework=/Users/ronald/Library/Frameworks 28 $ make && make install 29 30 This will install the framework itself in ``/Users/ronald/Library/Frameworks``, 31 the applications in a subdirectory of ``/Users/ronald/Applications`` and the 32 command-line tools in ``/Users/ronald/bin``. 33 34* ``--with-framework-name=NAME`` 35 36 Specify the name for the python framework, defaults to ``Python``. This option 37 is only valid when ``--enable-framework`` is specified. 38 39* ``--enable-universalsdk[=PATH]`` 40 41 Create a universal binary build of Python. This can be used with both 42 regular and framework builds. 43 44 The optional argument specifies which macOS SDK should be used to perform the 45 build. In most cases on current systems, you do not need to specify PATH or 46 you can just use ``/``; the default MacOSX SDK for the active Xcode or Command 47 Line Tools developer directory will be used. See the macOS ``xcrun`` man page 48 for more information. Current versions of macOS and Xcode no longer install 49 system header files in their traditional locations, like ``/usr/include`` and 50 ``/System/Library/Frameworks``; instead they are found within a MacOSX SDK. 51 The Apple-supplied build tools handle this transparently and current 52 versions of Python now handle this as well. So it is no longer necessary, 53 and since macOS 10.14, no longer possible to force the installation of system 54 headers with ``xcode-select``. 55 56* ``--with-universal-archs=VALUE`` 57 58 Specify the kind of universal binary that should be created. This option is 59 only valid when ``--enable-universalsdk`` is specified. The default is 60 ``32-bit`` if building with a SDK that supports PPC, otherwise defaults 61 to ``intel``. Note that ``intel`` means a universal build of both 32-bit 62 and 64-bit binaries and that may not be what you want; for example, 63 as of macOS 10.15 Catalina, 32-bit execution is no longer supported by 64 the operating system. Thus it is best to either explicitly specify 65 values for ``--with-universal-archs``: 66 67 ``--enable-universalsdk --with-universal-archs=intel-64`` 68 69 or avoid using either. 70 71 72Building and using a universal binary of Python on macOS 73======================================================== 74 751. What is a universal binary 76----------------------------- 77 78A universal binary build of Python contains object code for more than one 79CPU architecture. A universal macOS executable file or library combines the 80architecture-specific code into one file and can therefore run at native 81speed on all supported architectures. Universal files were introduced in 82macOS 10.4 to add support for Intel-based Macs to the existing PowerPC (PPC) 83machines. In macOS 10.5 support was extended to 64-bit Intel and 64-bit PPC 84architectures. It is possible to build Python with various combinations 85of architectures depending on the build tools and macOS version in use. 86Note that PPC support was removed in macOS 10.7 and 32-bit Intel support 87was removed in macOS 10.15. So currently as of macOS 10.15, macOS only 88supports one execution architecture, 64-bit Intel (``x86_64``). 89 902. How do I build a universal binary 91------------------------------------ 92 93You can enable universal binaries by specifying the "--enable-universalsdk" 94flag to configure:: 95 96 $ ./configure --enable-universalsdk 97 $ make 98 $ make install 99 100This flag can be used with a framework build of python, but also with a classic 101unix build. Universal builds were first supported with macOS 10.4 with Xcode 2.1 102and the 10.4u SDK. Starting with Xcode 3 and macOS 10.5, more configurations are 103available. 104 105In general, universal builds depend on specific features provided by the 106Apple-supplied compilers and other build tools included in Apple's Xcode 107development tools. You should install Xcode or the command line tools 108component appropriate for the macOS release you are running on. See the 109Python Developer's Guide (https://devguide.python.org/setup/) 110for more information. 111 1122.1 Flavors of universal binaries 113................................. 114 115It is possible to build a number of flavors of the universal binary build, 116the default is a 32-bit only binary (i386 and ppc) in build environments that 117support ppc (10.4 with Xcode 2, 10.5 and 10.6 with Xcode 3) or an 118Intel-32/-64-bit binary (i386 and X86_64) in build environments that do not 119support ppc (Xcode 4 on 10.6 and later systems). The flavor can be specified 120using the configure option ``--with-universal-archs=VALUE``. The following 121values are available: 122 123 * ``universal2``: ``arm64``, ``x86_64`` 124 125 * ``intel``: ``i386``, ``x86_64`` 126 127 * ``intel-32``: ``i386`` 128 129 * ``intel-64``: ``x86_64`` 130 131 * ``32-bit``: ``ppc``, ``i386`` 132 133 * ``3-way``: ``i386``, ``x86_64``, ``ppc`` 134 135 * ``64-bit``: ``ppc64``, ``x86_64`` 136 137 * ``all``: ``ppc``, ``ppc64``, ``i386``, ``x86_64`` 138 139To build a universal binary that includes a 64-bit architecture, you must build 140on a system running macOS 10.5 or later. The ``all`` and ``64-bit`` flavors can 141only be built with a 10.5 SDK because ``ppc64`` support was only included with 142macOS 10.5. Although legacy ``ppc`` support was included with Xcode 3 on macOS 14310.6, it was removed in Xcode 4, versions of which were released on macOS 10.6 144and which is the standard for macOS 10.7. To summarize, the 145following combinations of SDKs and universal-archs flavors are available: 146 147 * 10.4u SDK with Xcode 2 supports ``32-bit`` only 148 149 * 10.5 SDK with Xcode 3.1.x supports all flavors 150 151 * 10.6 SDK with Xcode 3.2.x supports ``intel``, ``intel-32``, 152 ``intel-64``, ``3-way``, and ``32-bit`` 153 154 * 10.6 SDK with Xcode 4 supports ``intel``, ``intel-32``, and ``intel-64`` 155 156 * 10.7 through 10.14 SDKs support ``intel``, ``intel-32``, and ``intel-64`` 157 158 * 10.15 and later SDKs support ``intel-64`` only 159 160 * 11.0 and later SDKs support ``universal2`` 161 162The makefile for a framework build will also install ``python3.x-32`` 163binaries when the universal architecture includes at least one 32-bit 164architecture (that is, for all flavors but ``64-bit`` and ``intel-64``). 165It will also install ``python3.x-intel64`` binaries in the ``universal2`` 166case to allow easy execution with the Rosetta 2 Intel emulator on Apple 167Silicon Macs. 168 169Running a specific architecture 170............................... 171 172You can run code using a specific architecture using the ``arch`` command:: 173 174 $ arch -i386 python 175 176Or to explicitly run in 32-bit mode, regardless of the machine hardware:: 177 178 $ arch -i386 -ppc python 179 180Using ``arch`` is not a perfect solution as the selected architecture will 181not automatically carry through to subprocesses launched by programs and tests 182under that Python. If you want to ensure that Python interpreters launched in 183subprocesses also run in 32-bit-mode if the main interpreter does, use 184a ``python3.x-32`` binary and use the value of ``sys.executable`` as the 185``subprocess`` ``Popen`` executable value. 186 187Likewise, use ``python3.x-intel64`` to force execution in ``x86_64`` mode 188with ``universal2`` binaries. 189 190Building and using a framework-based Python on macOS 191==================================================== 192 193 1941. Why would I want a framework Python instead of a normal static Python? 195-------------------------------------------------------------------------- 196 197The main reason is because you want to create GUI programs in Python. With the 198exception of X11/XDarwin-based GUI toolkits all GUI programs need to be run 199from a macOS application bundle (".app"). 200 201While it is technically possible to create a .app without using frameworks you 202will have to do the work yourself if you really want this. 203 204A second reason for using frameworks is that they put Python-related items in 205only two places: "/Library/Framework/Python.framework" and 206"/Applications/Python <VERSION>" where ``<VERSION>`` can be e.g. "3.8", 207"2.7", etc. This simplifies matters for users installing 208Python from a binary distribution if they want to get rid of it again. Moreover, 209due to the way frameworks work, usera without admin privileges can install a 210binary distribution in their home directory without recompilation. 211 2122. How does a framework Python differ from a normal static Python? 213------------------------------------------------------------------ 214 215In everyday use there is no difference, except that things are stored in 216a different place. If you look in /Library/Frameworks/Python.framework 217you will see lots of relative symlinks, see the Apple documentation for 218details. If you are used to a normal unix Python file layout go down to 219Versions/Current and you will see the familiar bin and lib directories. 220 2213. Do I need extra packages? 222---------------------------- 223 224Yes, probably. If you want Tkinter support you need to get the macOS AquaTk 225distribution, this is installed by default on macOS 10.4 or later. Be 226aware, though, that the Cocoa-based AquaTk's supplied starting with macOS 22710.6 have proven to be unstable. If possible, you should consider 228installing a newer version before building on macOS 10.6 or later, such as 229the ActiveTcl 8.6. See https://www.python.org/download/mac/tcltk/. If you 230are building with an SDK, ensure that the newer Tcl and Tk frameworks are 231seen in the SDK's ``Library/Frameworks`` directory; you may need to 232manually create symlinks to their installed location, ``/Library/Frameworks``. 233If you want wxPython you need to get that. 234If you want Cocoa you need to get PyObjC. 235 2364. How do I build a framework Python? 237------------------------------------- 238 239This directory contains a Makefile that will create a couple of python-related 240applications (full-blown macOS .app applications, that is) in 241"/Applications/Python <VERSION>", and a hidden helper application Python.app 242inside the Python.framework, and unix tools including "python" into 243/usr/local/bin. In addition it has a target "installmacsubtree" that installs 244the relevant portions of the Mac subtree into the Python.framework. 245 246It is normally invoked indirectly through the main Makefile, as the last step 247in the sequence 248 249 1. ./configure --enable-framework 250 251 2. make 252 253 3. make install 254 255This sequence will put the framework in ``/Library/Framework/Python.framework``, 256the applications in ``/Applications/Python <VERSION>`` and the unix tools in 257``/usr/local/bin``. 258 259Installing in another place, for instance ``$HOME/Library/Frameworks`` if you 260have no admin privileges on your machine, is possible. This can be accomplished 261by configuring with ``--enable-framework=$HOME/Library/Frameworks``. 262The other two directories will then also be installed in your home directory, 263at ``$HOME/Applications/Python-<VERSION>`` and ``$HOME/bin``. 264 265If you want to install some part, but not all, read the main Makefile. The 266frameworkinstall is composed of a couple of sub-targets that install the 267framework itself, the Mac subtree, the applications and the unix tools. 268 269There is an extra target frameworkinstallextras that is not part of the 270normal frameworkinstall which installs the Tools directory into 271"/Applications/Python <VERSION>", this is useful for binary 272distributions. 273 274What do all these programs do? 275=============================== 276 277"IDLE.app" is an integrated development environment for Python: editor, 278debugger, etc. 279 280"Python Launcher.app" is a helper application that will handle things when you 281double-click a .py, .pyc or .pyw file. For the first two it creates a Terminal 282window and runs the scripts with the normal command-line Python. For the 283latter it runs the script in the Python.app interpreter so the script can do 284GUI-things. Keep the ``Option`` key depressed while dragging or double-clicking 285a script to set runtime options. These options can be set persistently 286through Python Launcher's preferences dialog. 287 288The program ``pythonx.x`` runs python scripts from the command line. 289Previously, various compatibility aliases were also installed, including 290``pythonwx.x`` which in early releases of Python on macOS was required to run 291GUI programs. As of 3.4.0, the ``pythonwx.x`` aliases are no longer installed. 292 293How do I create a binary distribution? 294====================================== 295 296Download and unpack the source release from https://www.python.org/download/. 297Go to the directory ``Mac/BuildScript``. There you will find a script 298``build-installer.py`` that does all the work. This will download and build 299a number of 3rd-party libraries, configures and builds a framework Python, 300installs it, creates the installer package files and then packs this in a 301DMG image. The script also builds an HTML copy of the current Python 302documentation set for this release for inclusion in the framework. The 303installer package will create links to the documentation for use by IDLE, 304pydoc, shell users, and Finder user. 305 306The script will build a universal binary so you'll therefore have to run this 307script on macOS 10.4 or later and with Xcode 2.1 or later installed. 308However, the Python build process itself has several build dependencies not 309available out of the box with macOS 10.4 so you may have to install 310additional software beyond what is provided with Xcode 2. 311It should be possible to use SDKs and/or older 312versions of Xcode to build installers that are compatible with older systems 313on a newer system but this may not be completely foolproof so the resulting 314executables, shared libraries, and ``.so`` bundles should be carefully 315examined and tested on all supported systems for proper dynamic linking 316dependencies. It is safest to build the distribution on a system running the 317minimum macOS version supported. 318 319All of this is normally done completely isolated in /tmp/_py, so it does not 320use your normal build directory nor does it install into /. 321 322Because of the way the script locates the files it needs you have to run it 323from within the BuildScript directory. The script accepts a number of 324command-line arguments, run it with --help for more information. 325 326Configure warnings 327================== 328 329The configure script sometimes emits warnings like the one below:: 330 331 configure: WARNING: libintl.h: present but cannot be compiled 332 configure: WARNING: libintl.h: check for missing prerequisite headers? 333 configure: WARNING: libintl.h: see the Autoconf documentation 334 configure: WARNING: libintl.h: section "Present But Cannot Be Compiled" 335 configure: WARNING: libintl.h: proceeding with the preprocessor's result 336 configure: WARNING: libintl.h: in the future, the compiler will take precedence 337 configure: WARNING: ## --------------------------------------- ## 338 configure: WARNING: ## Report this to https://bugs.python.org/ ## 339 configure: WARNING: ## --------------------------------------- ## 340 341This almost always means you are trying to build a universal binary for 342Python and have libraries in ``/usr/local`` that don't contain the required 343architectures. Temporarily move ``/usr/local`` aside to finish the build. 344 345 346Uninstalling a framework install, including the binary installer 347================================================================ 348 349Uninstalling a framework can be done by manually removing all bits that got installed. 350That's true for both installations from source and installations using the binary installer. 351macOS does not provide a central uninstaller. 352 353The main bit of a framework install is the framework itself, installed in 354``/Library/Frameworks/Python.framework``. This can contain multiple versions 355of Python, if you want to remove just one version you have to remove the 356version-specific subdirectory: ``/Library/Frameworks/Python.framework/Versions/X.Y``. 357If you do that, ensure that ``/Library/Frameworks/Python.framework/Versions/Current`` 358is a symlink that points to an installed version of Python. 359 360A framework install also installs some applications in ``/Applications/Python X.Y``, 361 362And lastly a framework installation installs files in ``/usr/local/bin``, all of 363them symbolic links to files in ``/Library/Frameworks/Python.framework/Versions/X.Y/bin``. 364 365Weak linking support 366==================== 367 368The CPython sources support building with the latest SDK while targeting deployment 369to macOS 10.9. This is done through weak linking of symbols introduced in macOS 37010.10 or later and checking for their availability at runtime. 371 372This requires the use of Apple's compiler toolchain on macOS 10.13 or later. 373 374The basic implementation pattern is: 375 376* ``HAVE_<FUNCTION>`` is a macro defined (or not) by the configure script 377 378* ``HAVE_<FUNCTION>_RUNTIME`` is a macro defined in the relevant source 379 files. This expands to a call to ``__builtin_available`` when using 380 a new enough Apple compiler, and to a true value otherwise. 381 382* Use ``HAVE_<FUNCTION>_RUNTIME`` before calling ``<function>``. This macro 383 *must* be used a the sole expression in an if statement:: 384 385 if (HAVE_<FUNCTION>_RUNTIME) { 386 /* <function> is available */ 387 } 388 389 Or: 390 391 if (HAVE_<FUNCTION>_RUNTIME) {} else { 392 /* <function> is not available */ 393 } 394 395 Using other patterns (such as ``!HAVE_<FUNCTION>_RUNTIME``) is not supported 396 by Apple's compilers. 397 398 399Resources 400========= 401 402 * https://www.python.org/downloads/macos/ 403 404 * https://www.python.org/community/sigs/current/pythonmac-sig/ 405 406 * https://devguide.python.org/ 407