docs: add FAQ entry on repairing wheels (#731)

Follow up to #698.
The statement about producing `linux` wheels in build.md has been there
since well before this bug was fixed. :) Hopefully this will make it a
bit more discoverable.

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

docs/build.md

@@ -110,6 +110,10 @@ The three new items here (compared to SDists) are the [compatibility tags][]:
 - `platform tag`: This is the platform the wheel is valid on, such as `any`,
   `linux_x86_64`, or `manylinux_2_17_x86_64`.
 
+(repairing-wheels)=
+
+## Repairing
+
 The wheels produced by default are not designed to be redistributable. Making
 them redistributable depends on platform:
 
@@ -122,16 +126,21 @@ them redistributable depends on platform:
   tag, and can be uploaded to PyPI.
 - macOS: The wheels should be build with the official CPython releases, and
   target a reasonable `MACOSX_DEPLOYMENT_TARGET` value (10.9 or newer). You
-  should run the wheels through `develwheel` to bundle external dependencies.
-  You'll also want to (carefully) cross compile for Apple Silicon.
+  should run the wheels through `develocate` to bundle external dependencies.
+  You'll also want to (carefully) cross compile for Apple Silicon or build on
+  Apple Silicon runners (`macos-14`+ on GHA).
 - Windows: this is the easiest, usually, as the wheels don't have special rules
   on what Python or OS is being used. However, if you want to bundle
   dependencies, you'll need `delvewheel`, which is a bit younger than the other
   two packages, and has to do a few more intrusive workarounds, but otherwise
   works like those packages.
 
 The easiest way to handle all the above for all Python versions, OSs,
-architectures, including testing, is to use [cibuildwheel][].
+architectures, including testing, is to use [cibuildwheel][]. There's also a
+fairly new tool, [repairwheel][], that combines all these tools. Tools usually
+allow extra flags that can be used for trickier repairs, like ignoring CUDA
+libraries when bundling (which technically is not a true manylinux wheel, but is
+the current workaround).
 
 <!-- prettier-ignore-start -->
 
@@ -143,6 +152,7 @@ architectures, including testing, is to use [cibuildwheel][].
       `setup.py bdist_wheel`! You can avoid this whole mess with
       scikit-build-core.
 
+[repairwheel]: https://github.com/jvolkman/repairwheel
 [cibuildwheel]: https://cibuildwheel.readthedocs.io
 [compatibility tags]: https://packaging.python.org/en/latest/specifications/binary-distribution-format
 

docs/faqs.md

@@ -69,6 +69,23 @@ printout of the current settings using:
 python -m scikit_build_core.builder
 ```
 
+## Repairing wheels
+
+Like most other backends[^1], scikit-build-core produced `linux` wheels, which
+are not redistrubutable cannot be uploaded to PyPI[^2]. You have to run your
+wheels through `auditwheel` to make `manylinux` wheels. `cibuildwheel`
+automatically does this for you. See [repairing](#repairing-wheels).
+
+[^1]:
+    Due to a [bug in packaging](https://github.com/pypa/packaging/issues/160),
+    some backends may mistakenly produce the wrong tags (including
+    scikit-build-core < 0.9), but the wheels are not actually
+    manylinux/musllinux, just mistagged.
+
+[^2]:
+    Platforms like ARMv6 that do not have a manylinux spec are exempt from this
+    rule.
+
 <!-- prettier-ignore-start -->
 
 [scientific python cookie]: https://github.com/scientific-python/cookie