Skip to content

Commit f6e60f4

Browse files
docs: clarify activating stable ABI (#940)
Normalize some terminology and expand some incomplete guidance. --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
1 parent d6b0ff0 commit f6e60f4

File tree

1 file changed

+18
-8
lines changed

1 file changed

+18
-8
lines changed

docs/cmakelists.md

Lines changed: 18 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ You always want to find at least `Interpreter` and the "Module" component of the
3434
as that include "Embed" component, which is not always present and is not
3535
related to making Python extension modules.
3636

37-
If you are making a Limited ABI / Stable API package, you'll need the
37+
If you are making a Limited API / Stable ABI package, you'll need the
3838
`Development.SABIModule` component instead (CMake 3.26+). You can use the
3939
`SKBUILD_LIMITED_API` variable to check to see if it was requested.
4040

@@ -115,18 +115,28 @@ configuration, with the variables:
115115

116116
## Limited API / Stable ABI
117117

118-
You can activate the limited ABI by setting When you do that,
119-
`${SKBUILD_SABI_COMPONENT}` will be set to `Development.SABIModule` if you can
120-
target this (new enough CPython), and will remain an empty string otherwise
121-
(PyPy). This allows the following idiom:
118+
You can activate the Stable ABI by setting `tool.scikit-build.wheel.py-api`
119+
equal to a valid CPython
120+
[Python Tag](https://packaging.python.org/en/latest/specifications/platform-compatibility-tags/#python-tag)
121+
in your `pyproject.toml`:
122+
123+
```toml
124+
[tool.scikit-build]
125+
wheel.py-api = "cp37"
126+
```
127+
128+
When you do that, `${SKBUILD_SABI_COMPONENT}` will be set to
129+
`Development.SABIModule` if you can target this (new enough CPython), and will
130+
remain an empty string otherwise (PyPy). This allows the following idiom:
122131

123132
```cmake
124133
find_package(Python REQUIRED COMPONENTS Interpreter Development.Module ${SKBUILD_SABI_COMPONENT})
125134
```
126135

127-
This will add this only if scikit-build-core is driving the compilation and is
128-
targeting ABI3. If you want to support limited ABI from outside
129-
scikit-build-core, look into the `OPTIONAL_COMPONENTS` flag for `find_package`.
136+
This will require the `Development.SABIModule` component only if
137+
scikit-build-core is driving the compilation and is targeting ABI3. If you want
138+
to support Stable ABI from outside scikit-build-core, look into the
139+
`OPTIONAL_COMPONENTS` flag for `find_package`.
130140

131141
When defining your module, if you only support the Stable ABI after some point,
132142
you should use (for example for 3.11):

0 commit comments

Comments
 (0)