docs: cross compile additions & authoring additions (#510)

Some docs additions. Works toward addressing
scikit-build/scikit-build#1013.

Signed-off-by: Henry Schreiner <[email protected]>

Author: henryiii

docs/changelog.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## Version 0.5.1
+
+Features:
+
+- Add `{build_type}` and `{state}` to `build-dir` by @henryiii in #504
+- Include 'python' dir as an auto search path by @henryiii in #499
+
+Fixes:
+
+- Parse CMake version strings containing '-' by @jllllll in #508
+- Set NumPy include directory if known by @henryiii in #482
+- Adapt for `setuptools_scm` 8 writing change by @henryiii in #509
+- (setuptools) Support `build_type` set in toml by @henryiii in #498
+
+Tests and internal:
+
+- Nicer nox for docs by @henryiii in #479
+- Some extra Ruff checks by @henryiii in #478
+- Packit sync by @LecrisUT in #476
+
+Docs:
+
+- Fix template-file with template-path by @Freed-Wu in #485
+- `wheel.py.api` -> `wheel.py-api` by @njzjz in #488
+- A single-letter change in Configuration by @wojdyr in #490
+- Fix typo in `SKBUILD_CMAKE_DEFINE` env var by @aloisklink in #501
+- Typo in Configuration by @elazarcoh in #493
+- Update and add discord link by @henryiii in #477
+- Add page on cross-compiling by @henryiii in #510
+
 ## Version 0.5.0
 
 Features:

docs/cmakelists.md

@@ -9,6 +9,15 @@ scikit-build-core using the `${SKBUILD}` variable. This will be defined to "2"
 for scikit-build-core (and "1" for classic scikit-build). You can also detect
 the version of scikit-build-core with `${SKBUILD_CORE_VERSION}`.
 
+## Accessing information
+
+Scikit-build-core provides several useful variables:
+
+- `${SKBUILD_PROJECT_NAME}`: The name of the project.
+- `${SKBUILD_PROJECT_VERSION}`: The version of the project.
+- `${SKBUILD_STATE}`: The run state, one of `sdist`, `wheel`, `metadata_wheel`,
+  `editable`, or `metadata_editable`.
+
 ## Finding Python
 
 You can directly use FindPython:
@@ -26,6 +35,14 @@ If you are making a Limited ABI / Stable API package, you'll need the
 `Development.SABIModule` component instead. You can use the
 `SKBUILD_LIMITED_API` variable to check to see if it was requested.
 
+:::{warning}
+
+If you want to cross-compile to Windows ARM, you'll need to use
+`${SKBUILD_SOABI}`, which is always correct, instead of trusting FindPython's
+`Python_SOABI` value.
+
+:::
+
 If you want to use the old, deprecated FindPythonInterp and FindPythonLibs
 instead, you can. Though it should be noted that FindPythonLibs requires a trick
 to make it work properly if a Python library is not preset (like in manylinux):

docs/crosscompile.md

@@ -0,0 +1,46 @@
+# Cross-compiling
+
+## macOS
+
+### Intel to AppleSilicon
+
+On macOS, AppleClang has excellent support for making Apple Silicon and
+Universal2 binaries (both architectures in one binary). Scikit-build-core
+respects `ARCHFLAGS` if `CMAKE_SYSTEM_PROCESSOR` is not in the cmake args. These
+values are set by cibuildwheel when cross-compiling.
+
+:::{warning}
+
+If you link to any binaries, they need to be Universal2, so that you get the
+Apple Silicon component. This means you cannot use homebrew binaries (which are
+always native, and not designed to be used for building portable binaries
+anyway). Header-only dependencies, including NumPy, do not need to be
+Universal2.
+
+:::
+
+## Windows
+
+### Intel to ARM
+
+Scikit-build-core respects setuptools-style `DIST_EXTRA_CONFIG`. If is set to a
+file, then scikit-build-core reads the `build_ext.library_dirs` paths to find
+the library to link to. You will also need to set `SETUPTOOLS_EXT_SUFFIX` to the
+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.
+
+### Intel to Emscripten (Pyodide)
+
+When using pyodide-build, Python is set up to report the cross-compiling values
+by setting `_PYTHON_SYSCONFIGDATA_NAME`. This causes values like `SOABI` and
+`EXT_SUFFIX` to be reported by `sysconfig` as the cross-compiling values.
+
+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.

docs/index.md

@@ -21,6 +21,7 @@ system, allowing you to make Python modules with CMake.
 getting_started
 configuration
 cmakelists
+crosscompile
 migration_guide
 changelog
 ```