From c64be225cfd75a16fe5c726b79a3ddc3bad59bac Mon Sep 17 00:00:00 2001 From: cc0006-coder Date: Sat, 17 Oct 2026 11:17:52 +0800 Subject: [PATCH] PEP 831: clarify build backend flag propagation --- peps/pep-0831.rst | 45 ++++++++++++++++++++++++++++----------------- 1 file changed, 28 insertions(+), 17 deletions(-) diff --git a/peps/pep-0831.rst b/peps/pep-0831.rst index 70c401a563c..944bf26085f 100644 --- a/peps/pep-0831.rst +++ b/peps/pep-0831.rst @@ -23,8 +23,10 @@ This PEP proposes two things: them.** The default build configuration is changed to compile the interpreter with ``-fno-omit-frame-pointer`` and ``-mno-omit-leaf-frame-pointer``. The flags are added to ``CFLAGS``, so they - apply to the interpreter itself and propagate to C extension modules built - against this Python via ``sysconfig``. An opt-out ``configure`` flag + apply to the interpreter itself and are exposed through ``sysconfig`` to + build systems that deliberately consume CPython's reported compiler flags, + including Setuptools. They do not propagate automatically through every + PEP 517 build backend. An opt-out ``configure`` flag (``--without-frame-pointers``) is provided for deployments that require maximum raw throughput. @@ -397,11 +399,13 @@ breaks the chain for the entire process. The need for a continuous chain is precisely why the flags must propagate to extension builds. If only the interpreter has frame pointers but extensions do not, the chain is still broken at every C extension boundary. By adding the -flags to ``CFLAGS`` as reported by ``sysconfig``, extension builds that consume -CPython's compiler flags (for example via ``pip install``, Setuptools, or -other build backends) will inherit frame pointers by default. Extensions -and libraries with independent build systems still need to enable the same -flags themselves for the frame-pointer chain to remain continuous. +flags to ``CFLAGS`` as reported by ``sysconfig``, extension builds that +deliberately consume CPython's compiler flags (for example, Setuptools or a +direct ``sysconfig`` consumer) will inherit frame pointers by default. Other +PEP 517 backends do not necessarily inspect ``sysconfig`` and will not inherit +the flags automatically. Extensions and libraries with independent build +systems still need to enable the same flags themselves for the frame-pointer +chain to remain continuous. The JIT Compiler Needs Frame Pointers to Be Debuggable ------------------------------------------------------ @@ -483,8 +487,11 @@ they propagate to third-party builds via ``sysconfig``. This ensures: the ``python`` binary, ``libpython``, and built-in extension modules under ``Modules/``. 2. The flags **are** written into the ``sysconfig`` data, so that third-party C - extensions built against this Python (via ``pip``, Setuptools, or direct - ``sysconfig`` queries) inherit frame pointers by default. + extensions built with Setuptools or other build systems that deliberately + query ``sysconfig`` inherit frame pointers by default. Other PEP 517 + backends do not necessarily inspect ``sysconfig`` and will not inherit the + flags automatically. The future standardized interface for exposing these + build details to build backends is ``build-details.json`` (see :pep:`739`). Several architectures need adjustments to produce a walkable frame-pointer chain: @@ -532,9 +539,11 @@ Ecosystem Impact ---------------- Because the flags are in ``CFLAGS``, they propagate automatically to consumers -that build against CPython's reported compiler flags, such as C extensions -built via ``pip``, Setuptools, or direct ``sysconfig`` queries. Those -consumers need take no additional action to benefit from this change. +that deliberately build against CPython's reported compiler flags, notably +Setuptools and projects that query ``sysconfig`` directly. Those consumers +need take no additional action to benefit from this change. Other PEP 517 +backends do not necessarily inspect ``sysconfig`` and will not inherit the +flags automatically. Not all compiled code in the Python ecosystem inherits CPython's ``CFLAGS``. Rust extensions built with ``pyo3`` or ``maturin``, C++ libraries with their @@ -890,11 +899,13 @@ unacceptable may use ``--without-frame-pointers``. Extension Build Impact ---------------------- -C extensions built against Python 3.15+ will inherit -``-fno-omit-frame-pointer`` and ``-mno-omit-leaf-frame-pointer`` in their -default ``CFLAGS`` from ``sysconfig``. This is the same mechanism by which -extensions already inherit ``-O2``, warning flags, and other compilation -defaults. +C extensions built against Python 3.15+ with Setuptools or another build +backend that deliberately consumes CPython's reported compiler flags will +inherit ``-fno-omit-frame-pointer`` and ``-mno-omit-leaf-frame-pointer`` in +their default ``CFLAGS`` from ``sysconfig``. This is the same mechanism by +which extensions already inherit ``-O2``, warning flags, and other compilation +defaults. Other PEP 517 backends do not necessarily inspect ``sysconfig`` and +will not inherit these flags automatically. Extensions that set their own ``CFLAGS`` or use ``extra_compile_args`` in ``setup.py`` / ``pyproject.toml`` can override this default. The last flag on