feat: Better support for cross-compilation

README.md

@@ -181,6 +181,14 @@ cmake.source-dir = "."
 # DEPRECATED in 0.10; use build.targets instead.
 cmake.targets = ""
 
+# The CMAKE_TOOLCHAIN_FILE used for cross-compilation.
+cmake.toolchain-file = ""
+
+# Do not pass the current environment's python hints such as
+# ``Python_EXECUTABLE``. Primarily used for cross-compilation where the
+# CMAKE_TOOLCHAIN_FILE should handle it instead.
+cmake.python-hints = true
+
 # The versions of Ninja to allow. If Ninja is not present on the system or does
 # not pass this specifier, it will be downloaded via PyPI if possible. An empty
 # string will disable this check.
@@ -257,6 +265,12 @@ wheel.exclude = []
 # The build tag to use for the wheel. If empty, no build tag is used.
 wheel.build-tag = ""
 
+# Manually specify the wheel tags to use, ignoring other inputs such as
+# ``wheel.py-api``. Each tag must be of the format
+# {interpreter}-{abi}-{platform}. If not specified, these tags are automatically
+# calculated.
+wheel.tags = []
+
 # If CMake is less than this value, backport a copy of FindPython. Set to 0
 # disable this, or the empty string.
 backport.find-python = "3.26.1"

docs/conf.py

@@ -134,6 +134,7 @@
 myst_substitutions = {
     "version": version,
 }
+myst_heading_anchors = 2
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section)

docs/guide/crosscompile.md

@@ -1,5 +1,9 @@
 # Cross-compiling
 
+Generally scikit-build-core will try to account for environment variables that
+specify to CMake directly how to cross-compile. Alternatively, you can define
+manually how to cross-compile as detailed in [manual cross compilation] section.
+
 ## macOS
 
 Unlike the other platforms, macOS has the ability to target older operating
@@ -50,10 +54,7 @@ correct suffix. These values are set by cibuildwheel when cross-compiling.
 
 ## Linux
 
-It should be possible to cross-compile to Linux, but due to the challenges of
-getting the manylinux RHEL devtoolkit compilers, this is currently a TODO. See
-`py-build-cmake <https://tttapa.github.io/py-build-cmake/Cross-compilation.html>`\_
-for an alternative package's usage of toolchain files.
+See [manual cross compilation] section for the general approach.
 
 ### Intel to Emscripten (Pyodide)
 
@@ -64,3 +65,71 @@ by setting `_PYTHON_SYSCONFIGDATA_NAME`. This causes values like `SOABI` and
 This is unfortunately incorrectly stripped from the cmake wrapper pyodide uses,
 so FindPython will report the wrong values, but pyodide-build will rename the
 .so's afterwards.
+
+## Manual cross compilation
+
+The manual cross compilation assumes you have [toolchain file] prepared defining
+the cross-compilers and where to search for the target development files,
+including the python library. A simple setup of this is to use the clang
+compiler and point `CMAKE_SYSROOT` to a mounted copy of the target system's root
+
+```cmake
+set(CMAKE_SYSTEM_NAME Linux)
+set(CMAKE_SYSTEM_PROCESSOR aarch64)
+
+set(triple aarch64-linux-gnu)
+
+set(CMAKE_C_COMPILER clang)
+set(CMAKE_CXX_COMPILER clang++)
+set(CMAKE_C_COMPILER_TARGET ${triple})
+set(CMAKE_CXX_COMPILER_TARGET ${triple})
+
+set(CMAKE_SYSROOT "/path/to/aarch64/mount/")
+```
+
+For more complex environments such as embedded devices, Android or iOS see
+CMake's guide on how to write the [toolchain file].
+
+You can pass the toolchain file using the environment variable
+`CMAKE_TOOLCHAIN_FILE`, or the `cmake.toolchain-file` pyproject option. You may
+also need to use `wheel.tags` to manually specify the wheel tags to use for the
+file and `cmake.no-python-hints` if the target python should be detected using
+the toolchain file instead.
+
+:::{note}
+
+Because most of the logic in [`FindPython`] is gated by the
+`CMAKE_CROSSCOMPILING`, you generally should _not_ include the `Interpreter`
+component in the `find_package` command or use the `Python_ARTIFACTS_PREFIX`
+feature to distinguish the system and target components.
+
+:::
+
+:::{versionadded} 0.11
+
+:::
+
+### Crossenv
+
+[Crossenv] cross compilation is supported in scikit-build-core. This tool
+creates a fake virtual environment where configuration hints such as
+`EXT_SUFFIX` are overwritten with the target's values. This should work without
+specifying `wheel.tags` overwrites manually.
+
+:::{note}
+
+Because the target Python executable is being faked, the usage of
+`CMAKE_CROSSCOMPILING_EMULATOR` for the `Interpreter` would not be correct in
+this case.
+
+:::
+
+:::{versionadded} 0.11
+
+:::
+
+[manual cross compilation]: #manual-cross-compilation
+[toolchain file]:
+  https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html#cross-compiling
+[crossenv]: https://crossenv.readthedocs.io/en/latest/
+[`FindPython`]: https://cmake.org/cmake/help/git-master/module/FindPython.html

docs/reference/configs.md

@@ -176,6 +176,14 @@ print(mk_skbuild_docs())
   DEPRECATED in 0.8; use version instead.
 ```
 
+```{eval-rst}
+.. confval:: cmake.python-hints
+  :type: ``bool``
+  :default: true
+
+  Do not pass the current environment's python hints such as ``Python_EXECUTABLE``. Primarily used for cross-compilation where the CMAKE_TOOLCHAIN_FILE should handle it instead.
+```
+
 ```{eval-rst}
 .. confval:: cmake.source-dir
   :type: ``Path``
@@ -191,6 +199,13 @@ print(mk_skbuild_docs())
   DEPRECATED in 0.10; use build.targets instead.
 ```
 
+```{eval-rst}
+.. confval:: cmake.toolchain-file
+  :type: ``Path``
+
+  The CMAKE_TOOLCHAIN_FILE used for cross-compilation.
+```
+
 ```{eval-rst}
 .. confval:: cmake.verbose
   :type: ``bool``
@@ -440,4 +455,11 @@ print(mk_skbuild_docs())
   The Python tags. The default (empty string) will use the default Python version. You can also set this to "cp38" to enable the CPython 3.8+ Stable ABI / Limited API (only on CPython and if the version is sufficient, otherwise this has no effect). Or you can set it to "py3" or "py2.py3" to ignore Python ABI compatibility. The ABI tag is inferred from this tag.
 ```
 
+```{eval-rst}
+.. confval:: wheel.tags
+  :type: ``list[str]``
+
+  Manually specify the wheel tags to use, ignoring other inputs such as ``wheel.py-api``. Each tag must be of the format {interpreter}-{abi}-{platform}. If not specified, these tags are automatically calculated.
+```
+
 <!-- [[[end]]] -->

src/scikit_build_core/build/wheel.py

@@ -10,6 +10,7 @@
 from typing import TYPE_CHECKING, Any, Literal
 
 from packaging.requirements import Requirement
+from packaging.tags import Tag
 from packaging.utils import canonicalize_name
 
 from .._compat import tomllib
@@ -260,6 +261,10 @@
         f"{{red}}({state})",
     )
 
+    override_wheel_tags = None
+    if settings.wheel.tags:
+        override_wheel_tags = {Tag(*tag.split("-")) for tag in settings.wheel.tags}
+
     with tempfile.TemporaryDirectory() as tmpdir:
         build_tmp_folder = Path(tmpdir)
         wheel_dir = build_tmp_folder / "wheel"
@@ -364,7 +369,7 @@
             wheel = WheelWriter(
                 metadata,
                 Path(metadata_directory),
-                tags.as_tags_set(),
+                override_wheel_tags or tags.as_tags_set(),
                 WheelMetadata(
                     root_is_purelib=targetlib == "purelib",
                     build_tag=settings.wheel.build_tag,
@@ -480,7 +485,7 @@
         with WheelWriter(
             metadata,
             Path(wheel_directory),
-            tags.as_tags_set(),
+            override_wheel_tags or tags.as_tags_set(),
             WheelMetadata(
                 root_is_purelib=targetlib == "purelib",
                 build_tag=settings.wheel.build_tag,

src/scikit_build_core/builder/builder.py

@@ -231,25 +231,29 @@
         python_include_dir = get_python_include_dir()
         numpy_include_dir = get_numpy_include_dir()
 
-        # Classic Find Python
-        cache_config["PYTHON_EXECUTABLE"] = Path(sys.executable)
-        cache_config["PYTHON_INCLUDE_DIR"] = python_include_dir
-        if python_library:
-            cache_config["PYTHON_LIBRARY"] = python_library
-
-        # Modern Find Python
-        for prefix in ("Python", "Python3"):
-            cache_config[f"{prefix}_EXECUTABLE"] = Path(sys.executable)
-            cache_config[f"{prefix}_ROOT_DIR"] = Path(sys.prefix)
-            cache_config[f"{prefix}_INCLUDE_DIR"] = python_include_dir
-            cache_config[f"{prefix}_FIND_REGISTRY"] = "NEVER"
-            # FindPython may break if this is set - only useful on Windows
-            if python_library and sysconfig.get_platform().startswith("win"):
-                cache_config[f"{prefix}_LIBRARY"] = python_library
-            if python_sabi_library and sysconfig.get_platform().startswith("win"):
-                cache_config[f"{prefix}_SABI_LIBRARY"] = python_sabi_library
-            if numpy_include_dir:
-                cache_config[f"{prefix}_NumPy_INCLUDE_DIR"] = numpy_include_dir
+        if self.settings.cmake.toolchain_file:
+            cache_config["CMAKE_TOOLCHAIN_FILE"] = self.settings.cmake.toolchain_file
+
+        if self.settings.cmake.python_hints:
+            # Classic Find Python
+            cache_config["PYTHON_EXECUTABLE"] = Path(sys.executable)
+            cache_config["PYTHON_INCLUDE_DIR"] = python_include_dir
+            if python_library:
+                cache_config["PYTHON_LIBRARY"] = python_library
+
+            # Modern Find Python
+            for prefix in ("Python", "Python3"):
+                cache_config[f"{prefix}_EXECUTABLE"] = Path(sys.executable)
+                cache_config[f"{prefix}_ROOT_DIR"] = Path(sys.base_exec_prefix)
+                cache_config[f"{prefix}_INCLUDE_DIR"] = python_include_dir
+                cache_config[f"{prefix}_FIND_REGISTRY"] = "NEVER"
+                # FindPython may break if this is set - only useful on Windows
+                if python_library and sysconfig.get_platform().startswith("win"):
+                    cache_config[f"{prefix}_LIBRARY"] = python_library
+                if python_sabi_library and sysconfig.get_platform().startswith("win"):
+                    cache_config[f"{prefix}_SABI_LIBRARY"] = python_sabi_library
+                if numpy_include_dir:
+                    cache_config[f"{prefix}_NumPy_INCLUDE_DIR"] = numpy_include_dir
 
         cache_config["SKBUILD_SOABI"] = get_soabi(self.config.env, abi3=limited_api)
 

src/scikit_build_core/resources/scikit-build.schema.json

@@ -102,6 +102,15 @@
           },
           "description": "DEPRECATED in 0.10; use build.targets instead.",
           "deprecated": true
+        },
+        "toolchain-file": {
+          "type": "string",
+          "description": "The CMAKE_TOOLCHAIN_FILE used for cross-compilation."
+        },
+        "python-hints": {
+          "type": "boolean",
+          "default": true,
+          "description": "Do not pass the current environment's python hints such as ``Python_EXECUTABLE``. Primarily used for cross-compilation where the CMAKE_TOOLCHAIN_FILE should handle it instead."
         }
       }
     },
@@ -239,6 +248,13 @@
           "type": "string",
           "default": "",
           "description": "The build tag to use for the wheel. If empty, no build tag is used."
+        },
+        "tags": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Manually specify the wheel tags to use, ignoring other inputs such as ``wheel.py-api``. Each tag must be of the format {interpreter}-{abi}-{platform}. If not specified, these tags are automatically calculated."
         }
       }
     },
@@ -566,6 +582,9 @@
                   },
                   "exclude": {
                     "$ref": "#/$defs/inherit"
+                  },
+                  "tags": {
+                    "$ref": "#/$defs/inherit"
                   }
                 }
               },

src/scikit_build_core/settings/skbuild_model.py

@@ -111,6 +111,18 @@ class CMakeSettings:
     DEPRECATED in 0.10; use build.targets instead.
     """
 
+    toolchain_file: Optional[Path] = None
+    """
+    The CMAKE_TOOLCHAIN_FILE used for cross-compilation.
+    """
+
+    python_hints: bool = True
+    """
+    Do not pass the current environment's python hints such as ``Python_EXECUTABLE``.
+    Primarily used for cross-compilation where the CMAKE_TOOLCHAIN_FILE should handle it
+    instead.
+    """
+
 
 @dataclasses.dataclass
 class SearchSettings:
@@ -254,6 +266,13 @@ class WheelSettings:
     The build tag to use for the wheel. If empty, no build tag is used.
     """
 
+    tags: List[str] = dataclasses.field(default_factory=list)
+    """
+    Manually specify the wheel tags to use, ignoring other inputs such as
+    ``wheel.py-api``. Each tag must be of the format {interpreter}-{abi}-{platform}.
+    If not specified, these tags are automatically calculated.
+    """
+
 
 @dataclasses.dataclass
 class BackportSettings: