diff --git a/README.md b/README.md new file mode 100644 index 0000000..33e689d --- /dev/null +++ b/README.md @@ -0,0 +1,168 @@ +# Python Apple Support + +This is a meta-package for building a version of Python that can be +embedded into a macOS, iOS, tvOS, watchOS, or visionOS project. + +**This branch builds a packaged version of Python 3.14**. Other Python +versions are available by cloning other branches of the main repository: + +- [Python 3.9](https://github.com/beeware/Python-Apple-support/tree/3.9) +- [Python + 3.10](https://github.com/beeware/Python-Apple-support/tree/3.10) +- [Python + 3.11](https://github.com/beeware/Python-Apple-support/tree/3.11) +- [Python + 3.12](https://github.com/beeware/Python-Apple-support/tree/3.12) +- [Python + 3.13](https://github.com/beeware/Python-Apple-support/tree/3.13) + +It works by downloading, patching, and building a fat binary of Python +and selected pre-requisites, and packaging them as frameworks that can +be incorporated into an Xcode project. The binary modules in the Python +standard library are distributed as binaries that can be dynamically +loaded at runtime. + +The macOS package is a re-bundling of the official macOS binary, +modified so that it is relocatable, with the IDLE, Tkinter and turtle +packages removed, and the App Store compliance patch applied. + +The iOS, tvOS, watchOS, and visionOS packages compiled by this project +use the official [PEP 730](https://peps.python.org/pep-0730/) code that +is part of Python 3.13 to provide iOS support; the relevant patches have +been backported to 3.9-3.12. Additional patches have been applied to add +tvOS, watchOS, and visionOS support. + +The binaries support x86_64 and arm64 for macOS; arm64 for iOS and +appleTV devices; arm64_32 for watchOS devices; and arm64 for visionOS +devices. It also supports device simulators on both x86_64 and M1 +hardware, except for visionOS, for which x86_64 simulators are +officially unsupported. This should enable the code to run on: + +- macOS 11 (Big Sur) or later, on: + - MacBook (including MacBooks using Apple Silicon) + - iMac (including iMacs using Apple Silicon) + - Mac Mini (including Apple Silicon Mac minis) + - Mac Studio (all models) + - Mac Pro (all models) + +- iOS 13.0 or later, on: + - iPhone (6s or later) + - iPad (5th gen or later) + - iPad Air (all models) + - iPad Mini (2 or later) + - iPad Pro (all models) + - iPod Touch (7th gen or later) + +- tvOS 12.0 or later, on: + - Apple TV (4th gen or later) + +- watchOS 4.0 or later, on: + - Apple Watch (4th gen or later) + +- visionOS 2.0 or later, on: + - Apple Vision Pro + +## Quickstart + +The easist way to use these packages is by creating a project with +[Briefcase](https://github.com/beeware/briefcase). Briefcase will +download pre-compiled versions of these support packages, and add them +to an Xcode project (or pre-build stub application, in the case of +macOS). + +Pre-built versions of the frameworks can be downloaded from the [Github +releases page](https://github.com/beeware/Python-Apple-support/releases) +and added to your project. + +Alternatively, to build the frameworks on your own, download/clone this +repository, and then in the root directory, and run: + +- `make` (or `make all`) to build everything. +- `make macOS` to build everything for macOS. +- `make iOS` to build everything for iOS. +- `make tvOS` to build everything for tvOS. +- `make watchOS` to build everything for watchOS. +- `make visionOS` to build everything for visionOS. + +This should: + +1. Download the original source packages +2. Patch them as required for compatibility with the selected OS +3. Build the packages as Xcode-compatible XCFrameworks. + +The resulting support packages will be packaged as `.tar.gz` files in +the `dist` folder. + +Each support package contains: + +- `VERSIONS`, a text file describing the specific versions of code used + to build the support package; +- `Python.xcframework`, a multi-architecture build of the Python runtime + library. + +On iOS/tvOS/watchOS/visionOS, the `Python.xcframework` contains a slice +for each supported ABI (device and simulator). The folder containing the +slice can also be used as a `PYTHONHOME`, as it contains a `bin`, +`include` and `lib` directory. + +The `bin` folder does not contain Python executables (as they can't be +invoked). However, it *does* contain shell aliases for the compilers +that are needed to build packages. This is required because Xcode uses +the `xcrun` alias to dynamically generate the name of binaries, but a +lot of C tooling expects that `CC` will not contain spaces. + +Each slice of an iOS/tvOS/watchOS/visionOS XCframework also contains a +`platform-config` folder with a subfolder for each supported +architecture in that slice. These subfolders can be used to make a macOS +Python environment behave as if it were on an iOS/tvOS/watchOS/visionOS +device. This works in one of two ways: + +1. **A sitecustomize.py script**. If the `platform-config` subfolder is + on your `PYTHONPATH` when a Python interpreter is started, a site + customization will be applied that patches methods in `sys`, + `sysconfig` and `platform` that are used to identify the system. +2. **A make_cross_venv.py script**. If you call `make_cross_venv.py`, + providing the location of a virtual environment, the script will add + some files to the `site-packages` folder of that environment that + will automatically apply the same set of patches as the + `sitecustomize.py` script whenever the environment is activated, + without any need to modify `PYTHONPATH`. If you use `build` to + create an isolated PEP 517 environment to build a wheel, these + patches will also be applied to the isolated build environment that + is created. + +iOS and visionOS distributions also contain a copy of the iOS or +visionOS `testbed` project - an Xcode project that can be used to run +test suites of Python code. See the [CPython documentation on testing +packages](https://docs.python.org/3/using/ios.html#testing-a-python-package) +for details on how to use this testbed. + +For a detailed instructions on using the support package in your own +project, see the [usage guide](./USAGE.md) + +## Building binary wheels + +This project packages the Python standard library, but does not address +building binary wheels. Binary wheels for macOS can be obtained from +PyPI. [Mobile Forge](https://github.com/beeware/mobile-forge) is a +project that provides the tooling to build build binary wheels for iOS +(and potentially for tvOS, watchOS, and visionOS, although that hasn't +been tested). + +## Historical support + +The following versions were supported in the past, but are no longer +maintained: + +- [Python 2.7](https://github.com/beeware/Python-Apple-support/tree/2.7) + (EOL January 2020) +- [Python 3.4](https://github.com/beeware/Python-Apple-support/tree/3.4) + (EOL March 2019) +- [Python 3.5](https://github.com/beeware/Python-Apple-support/tree/3.5) + (EOL February 2021) +- [Python 3.6](https://github.com/beeware/Python-Apple-support/tree/3.6) + (EOL December 2021) +- [Python 3.7](https://github.com/beeware/Python-Apple-support/tree/3.7) + (EOL September 2022) +- [Python 3.8](https://github.com/beeware/Python-Apple-support/tree/3.8) + (EOL October 2024) diff --git a/README.rst b/README.rst deleted file mode 100644 index 06fde6c..0000000 --- a/README.rst +++ /dev/null @@ -1,154 +0,0 @@ -Python Apple Support -==================== - -This is a meta-package for building a version of Python that can be embedded -into a macOS, iOS, tvOS, watchOS, or visionOS project. - -**This branch builds a packaged version of Python 3.14**. -Other Python versions are available by cloning other branches of the main -repository: - -* `Python 3.9 `__ -* `Python 3.10 `__ -* `Python 3.11 `__ -* `Python 3.12 `__ -* `Python 3.13 `__ - -It works by downloading, patching, and building a fat binary of Python and -selected pre-requisites, and packaging them as frameworks that can be -incorporated into an Xcode project. The binary modules in the Python standard -library are distributed as binaries that can be dynamically loaded at runtime. - -The macOS package is a re-bundling of the official macOS binary, modified so that -it is relocatable, with the IDLE, Tkinter and turtle packages removed, and the -App Store compliance patch applied. - -The iOS, tvOS, watchOS, and visionOS packages compiled by this project use the -official `PEP 730 `__ code that is part of -Python 3.13 to provide iOS support; the relevant patches have been backported -to 3.9-3.12. Additional patches have been applied to add tvOS, watchOS, and -visionOS support. - -The binaries support x86_64 and arm64 for macOS; arm64 for iOS and appleTV -devices; arm64_32 for watchOS devices; and arm64 for visionOS devices. It also -supports device simulators on both x86_64 and M1 hardware, except for visionOS, -for which x86_64 simulators are officially unsupported. This should enable the -code to run on: - -* macOS 11 (Big Sur) or later, on: - * MacBook (including MacBooks using Apple Silicon) - * iMac (including iMacs using Apple Silicon) - * Mac Mini (including Apple Silicon Mac minis) - * Mac Studio (all models) - * Mac Pro (all models) -* iOS 13.0 or later, on: - * iPhone (6s or later) - * iPad (5th gen or later) - * iPad Air (all models) - * iPad Mini (2 or later) - * iPad Pro (all models) - * iPod Touch (7th gen or later) -* tvOS 12.0 or later, on: - * Apple TV (4th gen or later) -* watchOS 4.0 or later, on: - * Apple Watch (4th gen or later) -* visionOS 2.0 or later, on: - * Apple Vision Pro - -Quickstart ----------- - -The easist way to use these packages is by creating a project with `Briefcase -`__. Briefcase will download pre-compiled -versions of these support packages, and add them to an Xcode project (or -pre-build stub application, in the case of macOS). - -Pre-built versions of the frameworks can be downloaded from the `Github releases page -`__ and added to your project. - -Alternatively, to build the frameworks on your own, download/clone this -repository, and then in the root directory, and run: - -* ``make`` (or ``make all``) to build everything. -* ``make macOS`` to build everything for macOS. -* ``make iOS`` to build everything for iOS. -* ``make tvOS`` to build everything for tvOS. -* ``make watchOS`` to build everything for watchOS. -* ``make visionOS`` to build everything for visionOS. - -This should: - -1. Download the original source packages -2. Patch them as required for compatibility with the selected OS -3. Build the packages as Xcode-compatible XCFrameworks. - -The resulting support packages will be packaged as ``.tar.gz`` files -in the ``dist`` folder. - -Each support package contains: - -* ``VERSIONS``, a text file describing the specific versions of code used to build the - support package; -* ``Python.xcframework``, a multi-architecture build of the Python runtime library. - -On iOS/tvOS/watchOS/visionOS, the ``Python.xcframework`` contains a -slice for each supported ABI (device and simulator). The folder containing the -slice can also be used as a ``PYTHONHOME``, as it contains a ``bin``, ``include`` -and ``lib`` directory. - -The ``bin`` folder does not contain Python executables (as they can't be -invoked). However, it *does* contain shell aliases for the compilers that are -needed to build packages. This is required because Xcode uses the ``xcrun`` -alias to dynamically generate the name of binaries, but a lot of C tooling -expects that ``CC`` will not contain spaces. - -Each slice of an iOS/tvOS/watchOS/visionOS XCframework also contains a -``platform-config`` folder with a subfolder for each supported architecture in -that slice. These subfolders can be used to make a macOS Python environment -behave as if it were on an iOS/tvOS/watchOS/visionOS device. This works in one -of two ways: - -1. **A sitecustomize.py script**. If the ``platform-config`` subfolder is on - your ``PYTHONPATH`` when a Python interpreter is started, a site - customization will be applied that patches methods in ``sys``, ``sysconfig`` - and ``platform`` that are used to identify the system. - -2. **A make_cross_venv.py script**. If you call ``make_cross_venv.py``, - providing the location of a virtual environment, the script will add some - files to the ``site-packages`` folder of that environment that will - automatically apply the same set of patches as the ``sitecustomize.py`` - script whenever the environment is activated, without any need to modify - ``PYTHONPATH``. If you use ``build`` to create an isolated PEP 517 - environment to build a wheel, these patches will also be applied to the - isolated build environment that is created. - -iOS and visionOS distributions also contain a copy of the iOS or visionOS -``testbed`` project - an Xcode project that can be used to run test suites of -Python code. See the `CPython documentation on testing packages -`__ for -details on how to use this testbed. - -For a detailed instructions on using the support package in your own project, -see the `usage guide <./USAGE.md>`__ - -Building binary wheels ----------------------- - -This project packages the Python standard library, but does not address building -binary wheels. Binary wheels for macOS can be obtained from PyPI. `Mobile Forge -`__ is a project that provides the -tooling to build build binary wheels for iOS (and potentially for tvOS, watchOS, -and visionOS, although that hasn't been tested). - -Historical support ------------------- - -The following versions were supported in the past, but are no longer -maintained: - -* `Python 2.7 `__ (EOL January 2020) -* `Python 3.4 `__ (EOL March 2019) -* `Python 3.5 `__ (EOL February 2021) -* `Python 3.6 `__ (EOL December 2021) -* `Python 3.7 `__ (EOL September 2022) -* `Python 3.8 `__ (EOL October 2024)