PEP 656: Clarification on platform definition and musl detection

pep-0656.rst

@@ -14,9 +14,9 @@ Abstract
 ========
 
 This PEP proposes a new platfrom tag series ``musllinux`` for
-binary Python package distributions for a Python installation linked
-against musl on a Linux distribution. The tag works similarly to the
-"perennial manylinux" platform tags specified in :pep:`600`, but
+binary Python package distributions for a Python installation that
+depends on musl on a Linux distribution. The tag works similarly to
+the "perennial manylinux" platform tags specified in :pep:`600`, but
 targeting platforms based on musl instead.
 
 
@@ -46,6 +46,14 @@ Logic behind the new platform tag largely follows :pep:`600`, and
 require wheels using this tag make similar promises. Please refer to
 the PEP for more details on rationale and reasoning behind the design.
 
+The ``musllinux`` platform tags only apply to Python interpreters
+dynamically linked aginst the musl libc and executed on the runtime
+shared library, on a Linux operating system. Statically linked
+interpreters or mixed builds with other libc implementations (such as
+glibc) are out of scope and not supported by platform tags defined in
+this document. Such interpreters should not claim compatibility with
+``musllinux`` platform tags.
+
 
 Specification
 =============
@@ -54,6 +62,48 @@ Tags using the new scheme will take the form::
 
     musllinux_${MUSLMAJOR}_${MUSLMINOR}_${ARCH}
 
+Reading the musl version
+------------------------
+
+The musl version values can be obtains by executing the musl libc
+shared library the Python interpreter is currently running on, and
+parsing the output::
+
+    import re
+    import subprocess
+
+    def get_musl_major_minor(so: str) -> tuple[int, int] | None:
+        """Detect musl runtime version.
+
+        Returns a two-tuple ``(major, minor)`` that indicates musl
+        library's version, or ``None`` if the given value does not
+        output expected information.
+
+        The libc library should output something like this to stderr::
+
+            musl libc (x86_64)
+            Version 1.2.2
+            Dynamic Program Loader
+        """
+        proc = subprocess.run([so], stderr=subprocess.PIPE, text=True)
+        lines = (line.strip() for line in proc.stderr.splitlines())
+        lines = [line for line in lines if line]
+        if len(lines) < 2 or lines[0][:4] != "musl":
+            return None
+        match = re.match(r"Version (\d+)\.(\d+)", lines[1])
+        if match:
+            return (int(match.group(1)), int(match.group(2)))
+        return None
+
+There are currently two possible ways to find the musl library's
+location that a Python interpreter is running on, either with the
+system ``ldd`` command [ldd]_, or by parsing the ``PT_INTERP``
+section's value from the executable's ELF header [elf]_.
+
+
+Formatting the tag
+------------------
+
 Distributions using the tag make similar promises to those described
 in :pep:`600`, including:
 
@@ -77,6 +127,9 @@ The value can be formatted with the following Python code::
         arch = arch.replace("-", "_")
         return f"musllinux_{musl_version[0]}_{musl_version[1]}_{arch}"
 
+Recommendations to package indexes
+----------------------------------
+
 It is recommended for Python package repositories, including PyPI, to
 accept platform tags matching the following regular expression::
 
@@ -85,7 +138,8 @@ accept platform tags matching the following regular expression::
 Python package repositories may impose additional requirements to
 reject Wheels with known issues, including but not limited to:
 
-* A ``musllinux_1_1`` wheel containing symbols only available in musl 1.2.
+* A ``musllinux_1_1`` wheel containing symbols only available in musl
+  1.2 or later.
 * Wheel that depends on external libraries not considered generally
   available to the intended audience of the package index.
 * A platform tag claiming compatibility to a non-existent musl version
@@ -126,6 +180,10 @@ References
 
 .. [musl-compat-ml] https://mail.python.org/archives/list/distutils-sig@python.org/message/VRXSTNXWHPAVUW253ZCWWMP7WDTBAQDL/
 
+.. [ldd] https://www.unix.com/man-page/posix/1/ldd/
+
+.. [elf] https://refspecs.linuxfoundation.org/elf/elf.pdf
+
 
 Copyright
 =========