Document iOS, Android and macOS platform tag schemes.

source/specifications/platform-compatibility-tags.rst

@@ -109,8 +109,8 @@ subset of Linux platforms, and allows building wheels tagged with the
 ``manylinux`` platform tag which can be used across most common Linux
 distributions.
 
-The current standard is the future-proof ``manylinux_x_y`` standard. It defines
-tags of the form ``manylinux_x_y_arch``, where ``x`` and ``y`` are glibc major
+The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. It defines
+tags of the form :file:`manylinux_{x}_{y}_{arch}`, where ``x`` and ``y`` are glibc major
 and minor versions supported (e.g. ``manylinux_2_24_xxx`` should work on any
 distro using glibc 2.24+), and ``arch`` is the architecture, matching the value
 of :py:func:`sysconfig.get_platform()` on the system as in the "simple" form above.
@@ -151,7 +151,7 @@ auditwheel  ``>=1.0.0``     ``>=2.0.0``        ``>=3.0.0``        ``>=3.3.0`` [#
 
 The ``musllinux`` family of tags is similar to ``manylinux``, but for Linux
 platforms that use the musl_ libc rather than glibc (a prime example being Alpine
-Linux). The schema is ``musllinux_x_y_arch``, supporting musl ``x.y`` and higher
+Linux). The schema is :file:`musllinux_{x}_{y}_{arch}``, supporting musl ``x.y`` and higher
 on the architecture ``arch``.
 
 The musl version values can be obtained by executing the musl libc shared
@@ -189,6 +189,106 @@ There are currently two possible ways to find the musl library’s location that
 Python interpreter is running on, either with the system ldd_ command, or by
 parsing the ``PT_INTERP`` section’s value from the executable’s ELF_ header.
 
+.. _macos:
+
+macOS
+-----
+
+macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical
+artefact of Apple's official macOS naming scheme). The schema for compatibility
+tags is :file:`macosx_{x}_{y}_{arch}``, indicating that the wheel is compatible
+with macOS ``x.y`` or later on the architecture ``arch``.
+
+The value of ``x`` and ``y`` correspond to the major and minor version number of
+the macOS release, respectively. They must both be positive integers, with the
+``x`` value being ``>= 10``. The version number always includes a major *and*
+minor version, even if Apple's official version numbering only refers to
+the major value. For example, a ``macosx_11_0_arm64`` indicates compatibility
+with macOS 11 or later.
+
+macOS binaries can be compiled for a single architecture, or can include support
+for multiple architectures in the same binary (sometimes called "fat" binaries).
+To indicate support for a single architecture, the value of ``arch`` must match
+the value of :py:func:`platform.machine()` on the system. To indicate
+support multiple architectures, the ``arch`` tag should be an identifier from
+the following list that describes the set of supported architectures:
+
+============== ========================================
+``arch``       Architectures supported
+============== ========================================
+``universal2`` ``arm64``, ``x86_64``
+``universal``  ``i386``, ``ppc``, ``ppc64``, ``x86_64``
+``intel``      ``i386``, ``x86_64``
+``fat``        ``i386``, ``ppc``
+``fat3``       ``i386``, ``ppc``, ``x86_64``
+``fat64``      ``ppc64``, ``x86_64``
+============== ========================================
+
+The minimum supported macOS version may also be constrained by architecture. For
+example, macOS 11 (Big Sur) was the first release to support arm64. These
+additional constraints are enforced transparently by the macOS compilation
+toolchain when building binaries that support multiple architectures.
+
+.. _android:
+
+Android
+-------
+
+Android uses the schema :file:`android_{api_level}_{abi}`, indicating compatibility
+with the given Android API level or later, on the given ABI. Android makes no
+distinction between physical devices and emulated devices.
+
+The API level should be a positive integer. Note that this value is the API
+level, and *not* the user-facing Android version. The release known as Android
+12 (code named "Snow Cone") uses API level 31 or 32, depending on the specific
+Android version in use. Android's release documentation contains the `full list
+of Android versions and their corresponding API levels
+<https://developer.android.com/tools/releases/platforms>`__.
+
+There are 4 `supported ABIs <https://developer.android.com/ndk/guides/abis>`__.
+Normalized according to the rules above, they are:
+
+* ``armeabi_v7a``
+* ``arm64_v8a``
+* ``x86``
+* ``x86_64``
+
+Virtually all current physical devices use one of the ARM architectures. ``x86``
+and ``x86_64`` are supported for use in the emulator. ``x86`` has not been
+supported as a development platform since 2020, and no new emulator images have
+been released since then.
+
+.. _ios:
+
+iOS
+---
+
+iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating compatibility with
+iOS ``x.y`` or later, on the ``arch`` architecture, using the ``sdk`` SDK.
+
+The value of ``x`` and ``y`` correspond to the major and minor version number of
+the iOS release, respectively. They must both be positive integers. The version
+number always includes a major *and* minor version, even if Apple's official
+version numbering only refers to the major value. For example, a
+``ios_13_0_arm64_iphonesimulator`` indicates compatibility with iOS 13 or later.
+
+The value of ``arch`` must match the value of :py:func:`platform.machine()` on
+the system.
+
+The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or
+``iphonesimulator`` (for device simulators). These SDKs have the same API
+surface, but are incompatible at the binary level, even if they are running on
+the same CPU architecture. Code compiled for an arm64 simulator will not run on
+an arm64 device.
+
+The combination of :file:`{arch}_{sdk}` is referred to as the "multiarch". There
+are three possible values for multiarch:
+
+* ``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every
+  iOS device manufactured since ~2015;
+* ``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS
+  hardware; and
+* ``x86_64_iphonesimulator``, for simulators running on x86_64 hardware.
 
 Use
 ===
@@ -339,7 +439,8 @@ History
 - November 2019: The ``manylinux_x_y`` perennial tag was approved through
   :pep:`600`.
 - April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`.
-
+- December 2023: The tags for iOS were approved through :pep:`730`.
+- March 2024: The tags for Android were approved through :pep:`738`.
 
 
 .. _musl: https://musl.libc.org