Skip to content

Commit a95743c

Browse files
committed
DOC: add limited API build howto page
1 parent e5ba90f commit a95743c

3 files changed

Lines changed: 160 additions & 5 deletions

File tree

‎docs/how-to-guides/limited-api.rst‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
.. SPDX-FileCopyrightText: 2026 The meson-python developers
2+
..
3+
.. SPDX-License-Identifier: MIT
4+
5+
.. _howto-limited-api:
6+
7+
***********************************
8+
Targeting the CPython Limited C API
9+
***********************************
10+
11+
This page describes how to configure your package to build against the
12+
CPython `limited API`_ and build `stable ABI`_ wheels. Limited API builds
13+
target a minimum interpreter version and produce a single wheel that
14+
can support newer interpreter versions.
15+
16+
You can enable limited API builds by default or make them opt-in.
17+
If your package does not yet use the limited API, we recommend making
18+
limited API builds opt-in so you can transition to stable ABI wheels
19+
gradually or distribute stable ABI wheels only on selected platforms.
20+
21+
Compile your extension modules for the limited API by specifying the
22+
``limited_api`` argument to the ``extension_module()`` function in the
23+
Meson Python module. Enabling the
24+
:option:`tool.meson-python.limited-api` setting declares that all the
25+
extension modules in your package target the limited API and adjusts the
26+
wheel filename ABI tag accordingly:
27+
28+
.. code-block:: meson
29+
30+
py = import('python').find_installation(pure: false)
31+
32+
py.extension_module(
33+
'_core',
34+
'_core.c',
35+
limited_api: '3.10',
36+
install: true,
37+
subdir: 'example',
38+
)
39+
40+
.. code-block:: toml
41+
42+
[tool.meson-python]
43+
limited-api = true
44+
45+
Building against the limited API produces a wheel with a Python version
46+
compatibility tag derived from the interpreter used for the build, not
47+
from the ``limited_api`` version: a wheel built with CPython 3.12 for
48+
the 3.10 limited API is tagged ``cp312-abi3`` and can be installed only
49+
on GIL-enabled CPython 3.12 and later. When building stable ABI wheels
50+
for distribution, for example on PyPI, build with the oldest CPython
51+
version you want the wheel to support. For a source installation in a
52+
particular environment, use that environment's interpreter.
53+
54+
For limited API builds, ``meson-python`` verifies that all the extension
55+
modules included in the wheel use the stable ABI filename suffix and
56+
fails the build otherwise. PyPy does not support the limited API thus
57+
the :option:`tool.meson-python.limited-api` setting has no effect when
58+
building with PyPy.
59+
60+
61+
.. _opt-in-limited-api-example:
62+
63+
Set up Limited API support as opt-in
64+
------------------------------------
65+
66+
To make limited API builds opt-in, add
67+
``python.allow_limited_api=false`` to the ``default_options`` in your
68+
existing ``project()`` call in ``meson.build``:
69+
70+
.. code-block:: meson
71+
72+
project(
73+
'example',
74+
'c',
75+
default_options: ['python.allow_limited_api=false'],
76+
)
77+
78+
Keep ``limited-api = true`` in ``pyproject.toml`` and the ``limited_api``
79+
argument to ``extension_module()`` as shown above. When
80+
``python.allow_limited_api`` is false, Meson ignores the ``limited_api``
81+
argument, compiles extension modules for the ABI of the interpreter
82+
used for the build, and produces a wheel tagged as compatible with
83+
the build interpreter.
84+
85+
To build a stable ABI wheel, explicitly enable limited API builds:
86+
87+
.. tab-set::
88+
89+
.. tab-item:: pypa/build
90+
:sync: key_pypa_build
91+
92+
.. code-block:: console
93+
94+
$ python -m build --wheel -Csetup-args="-Dpython.allow_limited_api=true" .
95+
96+
.. tab-item:: pip
97+
:sync: key_pip
98+
99+
.. code-block:: console
100+
101+
$ python -m pip wheel -Csetup-args="-Dpython.allow_limited_api=true" .
102+
103+
104+
The ``abi3t`` stable ABI
105+
------------------------
106+
107+
CPython 3.15 introduces the ``abi3t`` stable ABI, see :pep:`803` and
108+
the `abi3t migration guide`_. Extension modules built for ``abi3t``
109+
can be loaded by both the GIL-enabled and the free-threaded builds of
110+
CPython 3.15 and later: a single wheel tagged ``abi3.abi3t`` supports
111+
all CPython interpreters from version 3.15 on.
112+
113+
``abi3t`` extension modules require limited API version 3.15 or later
114+
and, currently, a free-threaded interpreter for the build: compiling
115+
for ``abi3t`` with a GIL-enabled interpreter is not supported yet.
116+
Nothing else is required: the CPython headers select ``abi3t`` when
117+
``Py_LIMITED_API`` is defined while compiling for a free-threaded
118+
interpreter.
119+
120+
Meson refuses a ``limited_api`` version newer than the interpreter
121+
used for the build. If you build ``abi3`` wheels for older
122+
CPython versions and ``abi3.abi3t`` wheels for CPython 3.15 and later,
123+
you can select the limited API version by querying the ``Py_GIL_DISABLED``
124+
sysconfig variable, which is 1 for free-threaded builds:
125+
126+
.. code-block:: meson
127+
128+
py = import('python').find_installation(pure: false)
129+
130+
limited_api = '3.10'
131+
if py.language_version().version_compare('>=3.15')
132+
if py.get_variable('Py_GIL_DISABLED') == 1
133+
limited_api = '3.15'
134+
endif
135+
endif
136+
137+
py.extension_module(
138+
'_core',
139+
'_core.c',
140+
limited_api: limited_api,
141+
install: true,
142+
subdir: 'example',
143+
)
144+
145+
Free-threaded CPython 3.13 and 3.14 do not support the limited API:
146+
disable limited API builds when using these interpreters.
147+
The :ref:`opt-in configuration above <opt-in-limited-api-example>`
148+
disables them by default.
149+
150+
.. _limited API: https://docs.python.org/3/c-api/stable.html#limited-c-api
151+
.. _stable ABI: https://docs.python.org/3/c-api/stable.html#stable-application-binary-interface
152+
.. _improve performance: https://docs.python.org/3/c-api/stable.html#limited-api-scope-and-performance
153+
.. _abi3t migration guide: https://docs.python.org/3.15/howto/abi3t-migration.html

‎docs/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,7 @@ the use of ``meson-python`` and Meson for Python packaging.
8383
how-to-guides/meson-args
8484
how-to-guides/debug-builds
8585
how-to-guides/shared-libraries
86+
how-to-guides/limited-api
8687
reference/limitations
8788
projects-using-meson-python
8889

‎docs/reference/pyproject-settings.rst‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -33,11 +33,12 @@ use them and examples.
3333
modules can be compiled for the Python limited API specifying the
3434
``limited_api`` argument to the |extension_module()|_ function
3535
in the Meson Python module. When this setting is set to true, the
36-
value ``abi3`` is used for the Python wheel filename ABI tag.
37-
38-
This setting is automatically reverted to false when the
36+
Python wheel filename ABI tag is set to ``abi3``, or ``abi3.abi3t``
37+
when building with free-threaded CPython 3.15 or later. This
38+
setting is automatically reverted to false when the
3939
``-Dpython.allow_limited_api=false`` option is passed to ``meson
40-
setup``.
40+
setup``. See :ref:`howto-limited-api` for more information on limited
41+
API builds.
4142

4243
.. option:: tool.meson-python.meson
4344

@@ -91,7 +92,7 @@ use them and examples.
9192
glob pattern is useful exclusively to limit the effect of an exclude
9293
pattern that matches too many files.
9394

94-
.. _python limited api: https://docs.python.org/3/c-api/stable.html?highlight=limited%20api#stable-application-binary-interface
95+
.. _python limited api: https://docs.python.org/3/c-api/stable.html#stable-application-binary-interface
9596
.. _extension_module(): `https://mesonbuild.com/Python-module.html#extension_module
9697
.. _meson introspection data: https://mesonbuild.com/IDE-integration.html#install-plan
9798

0 commit comments

Comments
 (0)