Skip to content

Commit 56caae5

Browse files
ngoldbaumrgommers
authored andcommitted
DOC: add limited API build howto page
1 parent a46bbf5 commit 56caae5

3 files changed

Lines changed: 183 additions & 5 deletions

File tree

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

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
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+
We recommend making them opt-in to avoid failures or special handling
18+
when building for interpreters that do not support the stable ABI, such
19+
as free-threaded CPython 3.14. Using the version-specific C API can also
20+
`improve performance`_ for source installations and distribution packages
21+
that do not need the stable ABI.
22+
23+
Compile your extension modules for the limited API by specifying the
24+
``limited_api`` argument to the ``extension_module()`` function in the
25+
Meson Python module. The version passed to ``limited_api`` selects
26+
the limited API your extension uses. Meson converts this version to
27+
the corresponding value of the ``Py_LIMITED_API`` preprocessor macro.
28+
29+
The wheel's :ref:`Python compatibility tag <limited-api-wheel-tags>`
30+
still corresponds to the interpreter used for the build, regardless of
31+
the ``limited_api`` version you select.
32+
33+
Enabling the
34+
:option:`tool.meson-python.limited-api` setting declares that all the
35+
extension modules in your package target the limited API and adjusts the
36+
wheel filename ABI tag accordingly:
37+
38+
.. code-block:: meson
39+
40+
py = import('python').find_installation(pure: false)
41+
42+
py.extension_module(
43+
'_core',
44+
'_core.c',
45+
limited_api: '3.10',
46+
install: true,
47+
subdir: 'example',
48+
)
49+
50+
.. code-block:: toml
51+
52+
[tool.meson-python]
53+
limited-api = true
54+
55+
56+
For limited API builds, on platforms where Python extension modules
57+
targeting the stable ABI use a dedicated filename suffix, ``meson-python``
58+
verifies that all the extension modules included in the wheel use the
59+
stable ABI filename suffix and fails the build otherwise.
60+
61+
62+
.. _opt-in-limited-api-example:
63+
64+
Set up Limited API support as opt-in
65+
------------------------------------
66+
67+
To make limited API builds opt-in, add
68+
``python.allow_limited_api=false`` to the ``default_options`` in your
69+
existing ``project()`` call in ``meson.build``:
70+
71+
.. code-block:: meson
72+
73+
project(
74+
'example',
75+
'c',
76+
default_options: ['python.allow_limited_api=false'],
77+
)
78+
79+
Keep ``limited-api = true`` in ``pyproject.toml`` and the ``limited_api``
80+
argument to ``extension_module()`` as shown above. When
81+
``python.allow_limited_api`` is false, Meson ignores the ``limited_api``
82+
argument, compiles extension modules for the ABI of the interpreter
83+
used for the build, and produces a wheel tagged as compatible with
84+
the build interpreter.
85+
86+
To build a stable ABI wheel, explicitly enable limited API builds:
87+
88+
.. tab-set::
89+
90+
.. tab-item:: pypa/build
91+
:sync: key_pypa_build
92+
93+
.. code-block:: console
94+
95+
$ python -m build --wheel -Csetup-args="-Dpython.allow_limited_api=true" .
96+
97+
.. tab-item:: pip
98+
:sync: key_pip
99+
100+
.. code-block:: console
101+
102+
$ python -m pip wheel -Csetup-args="-Dpython.allow_limited_api=true" .
103+
104+
105+
.. _limited-api-wheel-tags:
106+
107+
Limited API compatibility
108+
-------------------------
109+
110+
``meson-python`` conservatively chooses the wheel's Python compatibility
111+
tag based only on the interpreter used for the build, regardless of the
112+
target ``limited_api`` version. For example, a wheel built with CPython
113+
3.12 for the 3.10 limited API is tagged ``cp312-abi3`` and can be
114+
installed only on GIL-enabled CPython 3.12 and later. When building
115+
stable ABI wheels for distribution, for example on PyPI, build with the
116+
oldest CPython version you want the wheel to support, as `recommended by
117+
CPython`_. If you are installing from source into a particular
118+
environment, use that environment's interpreter; you do not need to
119+
build with the oldest supported version.
120+
121+
PyPy supports the limited API, but does not implement a stable ABI, thus
122+
the :option:`tool.meson-python.limited-api` setting has no effect on the
123+
wheel tags when building with PyPy.
124+
125+
126+
The ``abi3t`` stable ABI
127+
------------------------
128+
129+
CPython 3.15 introduces the ``abi3t`` stable ABI. Extension modules built
130+
for ``abi3t`` can be loaded by both the GIL-enabled and the free-threaded
131+
builds of CPython 3.15 and later: a single wheel tagged ``abi3.abi3t``
132+
supports all CPython interpreters from version 3.15 on.
133+
134+
``abi3t`` extension modules require limited API version 3.15 or later
135+
and, currently, a free-threaded interpreter for the build: compiling
136+
for ``abi3t`` with a GIL-enabled interpreter is not supported yet.
137+
Once you have made the source changes described in the
138+
`abi3t migration guide`_, no additional build configuration is required:
139+
the CPython headers select ``abi3t`` when ``Py_LIMITED_API`` is defined
140+
while compiling for a free-threaded interpreter.
141+
142+
Meson refuses a ``limited_api`` version newer than the interpreter
143+
used for the build. If you build ``abi3`` wheels for older
144+
CPython versions and ``abi3.abi3t`` wheels for CPython 3.15 and later,
145+
you can select the limited API version by querying the ``Py_GIL_DISABLED``
146+
sysconfig variable, which is 1 for free-threaded builds:
147+
148+
.. code-block:: meson
149+
150+
py = import('python').find_installation(pure: false)
151+
152+
limited_api = '3.10'
153+
if py.language_version().version_compare('>=3.15')
154+
if py.get_variable('Py_GIL_DISABLED') == 1
155+
limited_api = '3.15'
156+
endif
157+
endif
158+
159+
py.extension_module(
160+
'_core',
161+
'_core.c',
162+
limited_api: limited_api,
163+
install: true,
164+
subdir: 'example',
165+
)
166+
167+
Free-threaded CPython 3.13 and 3.14 do not support the limited API:
168+
disable limited API builds when using these interpreters.
169+
The :ref:`opt-in configuration above <opt-in-limited-api-example>`
170+
disables them by default.
171+
172+
.. _limited API: https://docs.python.org/3/c-api/stable.html#limited-c-api
173+
.. _stable ABI: https://docs.python.org/3/c-api/stable.html#stable-application-binary-interface
174+
.. _recommended by CPython: https://docs.python.org/3/c-api/stable.html#limited-api-caveats
175+
.. _improve performance: https://docs.python.org/3/c-api/stable.html#limited-api-scope-and-performance
176+
.. _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
@@ -84,6 +84,7 @@ the use of ``meson-python`` and Meson for Python packaging.
8484
how-to-guides/meson-args
8585
how-to-guides/debug-builds
8686
how-to-guides/shared-libraries
87+
how-to-guides/limited-api
8788
reference/limitations
8889
projects-using-meson-python
8990

‎docs/reference/pyproject-settings.rst‎

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

4950
.. option:: tool.meson-python.meson
5051

@@ -98,7 +99,7 @@ use them and examples.
9899
glob pattern is useful exclusively to limit the effect of an exclude
99100
pattern that matches too many files.
100101

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

0 commit comments

Comments
 (0)