feat: SKBUILD_SABI_VERSION (#962)

Author: henryiii

docs/cmakelists.md

@@ -36,7 +36,8 @@ related to making Python extension modules.
 
 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_SABI_COMPONENT` variable to check to see if it was requested.
+`SKBUILD_SABI_COMPONENT` variable to check to see if it was requested. You can
+get the version requested with `${SKBUILD_SABI_VERSION}`.
 
 <!-- prettier-ignore-start -->
 :::{warning}
@@ -142,13 +143,25 @@ When defining your module, if you only support the Stable ABI after some point,
 you should use (for example for 3.11):
 
 ```cmake
-if(NOT "${SKBUILD_SABI_COMPONENT}" STREQUAL "")
-  python_add_library(some_ext MODULE WITH_SOABI USE_SABI 3.11 ...)
+if(NOT "${SKBUILD_SABI_VERSION}" STREQUAL "")
+  python_add_library(some_ext MODULE WITH_SOABI USE_SABI ${SKBUILD_SABI_VERSION} ...)
 else()
   python_add_library(some_ext MODULE WITH_SOABI ...)
 endif()
 ```
 
+If you have a lot of libraries, you can conditionally save these two items into
+a variable with `set(USE_SABI USE_SABI ${SKBUILD_SABI_VERSION})` and use it in
+all your `python_add_library` calls:
+
+```
+if(NOT "${SKBUILD_SABI_VERSION}" STREQUAL "")
+  set(USE_SABI "USE_SABI ${SKBUILD_SABI_VERSION}")
+endif()
+
+python_add_library(some_ext MODULE WITH_SOABI ${USE_SABI} ...)
+```
+
 This will define `Py_LIMITED_API` for you. If you want to support building
 directly from CMake, you need to protect this for Python version,
 `Python_INTERPRETER_ID STREQUAL Python`, and free-threading Python 3.13+ doesn't

src/scikit_build_core/builder/builder.py

@@ -233,6 +233,14 @@ def configure(
             "Development.SABIModule" if limited_api else ""
         )
 
+        # Allow users to detect the version requested in settings
+        py_api = self.settings.wheel.py_api
+        cache_config["SKBUILD_SABI_VERSION"] = (
+            f"{py_api[2]}.{py_api[3:]}"
+            if limited_api and py_api.startswith("cp")
+            else ""
+        )
+
         if cache_entries:
             cache_config.update(cache_entries)
 

tests/packages/abi3_pyproject_ext/CMakeLists.txt

@@ -10,8 +10,16 @@ find_package(
   COMPONENTS Interpreter Development.Module ${SKBUILD_SABI_COMPONENT}
   REQUIRED)
 
-if(NOT "${SKBUILD_SABI_COMPONENT}" STREQUAL "")
-  python_add_library(abi3_example MODULE abi3_example.c WITH_SOABI USE_SABI 3.7)
+if(NOT "${SKBUILD_SABI_VERSION}" STREQUAL "")
+  python_add_library(abi3_example MODULE abi3_example.c WITH_SOABI USE_SABI
+                     ${SKBUILD_SABI_VERSION})
+
+  if(NOT SKBUILD_SABI_VERSION STREQUAL "3.7")
+    message(
+      FATAL_ERROR
+        "TEST FAILED: SKBUILD_SABI_VERSION (${SKBUILD_SABI_VERSION}) is not 3.7"
+    )
+  endif()
 else()
   python_add_library(abi3_example MODULE abi3_example.c WITH_SOABI)
 endif()