Document wheel repair feature

Signed-off-by: Cristian Le <[email protected]>

Author: LecrisUT

docs/conf.py

@@ -90,6 +90,7 @@
 
 
 intersphinx_mapping = {
+    "cmake": ("https://cmake.org/cmake/help/latest/", None),
     "python": ("https://docs.python.org/3", None),
     "packaging": ("https://packaging.pypa.io/en/stable", None),
     "setuptools": ("https://setuptools.pypa.io/en/latest", None),
@@ -99,7 +100,7 @@
     val[0]
     for key, val in intersphinx_mapping.items()
     # Only works with RTD hosted intersphinx
-    if key not in ("hatchling", "python")
+    if key not in ("hatchling", "python", "cmake")
 ]
 
 nitpick_ignore = [

docs/guide/dynamic_link.md

@@ -0,0 +1,105 @@
+# Dynamic linking
+
+If you want to support dynamic linkages between python projects or system
+libraries, you will likely encounter some issues in making sure the compiled
+libraries/python bindings work after the wheel is created and the python project
+is installed on the system. The most common issue are the missing hints pointing
+to where the runtime libraries are located, specifically `RPATH` on Linux and
+MacOS systems, and `PATH`/`os.add_dll_directory` on Windows systems. Here are
+some recommendations on how to address them.
+
+## Link to the static libraries
+
+The easiest solution is to make sure you link to the static libraries
+counterparts during the CMake build. How to achieve this depends on the specific
+dependency, how it is imported in the CMake project and how the dependency is
+packaged in each ecosystem.
+
+For example for [Boost][FindBoost] this is controlled via the variable
+`Boost_USE_STATIC_LIBS`.
+
+[FindBoost]: inv:cmake:cmake:module#module:FindBoost
+
+## Wheel repair tools
+
+There are wheel repair tools for each operating system that bundle any dynamic
+libraries used and patch the libraries/python bindings to point to prioritize
+those libraries. The most common tools for these are [auditwheel] for Linux,
+[delocate] for MacOS and [delvewheel] for Windows. [cibuildwheel] incorporates
+these tools in its [repair wheel] feature.
+
+One downside of these tools is that all dependencies are duplicated and bundled
+in each project.
+
+[auditwheel]: https://pypi.org/project/auditwheel/
+[delocate]: https://pypi.org/project/delocate/
+[delvewheel]: https://pypi.org/project/delvewheel/
+[cibuildwheel]: https://cibuildwheel.pypa.io/en/stable/
+[repair wheel]:
+  https://cibuildwheel.pypa.io/en/stable/options/#repair-wheel-command
+
+## scikit-build-core wheel repair
+
+:::{note}
+
+This is an experimental feature currently under development.
+
+:::
+
+The wheel repair provided by scikit-build-core works in a similar way to the
+[wheel repair tools], but for any dependency that is provided in the
+`build-system.requires`, the libraries are linked to the dynamic libraries
+provided in the dependency's wheel.
+
+To enable this feature set `wheel.repair` flag
+
+```toml
+[tool.scikit-build]
+wheel.repair = true
+```
+
+:::{note}
+
+Bundling of dynamic libraries is not yet supported.
+
+:::
+
+:::{note}
+
+For packagers, this feature may need to be disabled in order for the system
+packages to be used as the default.
+
+:::
+
+[wheel repair tools]: #wheel-repair-tools
+
+## Manual patching
+
+For maximum control, you can do the equivalent patching inside CMake manually.
+This is not recommended because it does not have access to the python
+environment metadata.
+
+The `RPATH` patching can be done as
+
+```cmake
+if(APPLE)
+  set(origin_token "@loader_path")
+else()
+  set(origin_token "$ORIGIN")
+endif()
+set_property(TARGET <target> PROPERTY INSTALL_RPATH
+  "${origin_token}/install_path/to/dynamic_library"
+)
+```
+
+For Windows patching, this has to be done at the python files using
+`os.add_dll_directory` at the top-most package `__init__.py` file or top-level
+python module files.
+
+```python
+import os
+from pathlib import Path
+
+dependency_dll_path = Path(__file__).parent / "install_path/to/dynamic_library"
+os.add_dll_directory(str(dependency_dll_path))
+```

docs/index.md

@@ -29,6 +29,7 @@ first Friday of every month at the same time. Our past meeting minutes are
 
 guide/getting_started
 guide/cmakelists
+guide/dynamic_link
 guide/crosscompile
 guide/migration_guide
 guide/build