Skip to content

Clarify docs for activating stable ABI #940

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Oct 25, 2024
Merged

Clarify docs for activating stable ABI #940

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5ecd537
Normalize API vs ABI in cmakelists.md
eirrgang Oct 25, 2024
a5c625a
Elaboration.
eirrgang Oct 25, 2024
ef238b1
style: pre-commit fixes
pre-commit-ci[bot] Oct 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 18 additions & 8 deletions docs/cmakelists.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ You always want to find at least `Interpreter` and the "Module" component of the
as that include "Embed" component, which is not always present and is not
related to making Python extension modules.

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

Expand Down Expand Up @@ -115,18 +115,28 @@ configuration, with the variables:

## Limited API / Stable ABI

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

```toml
[tool.scikit-build]
wheel.py-api = "cp37"
```

When you do that, `${SKBUILD_SABI_COMPONENT}` will be set to
`Development.SABIModule` if you can target this (new enough CPython), and will
remain an empty string otherwise (PyPy). This allows the following idiom:

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

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

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