Skip to content

Commit 36e8c26

Browse files
committed
Document the wheel repair feature
Signed-off-by: Cristian Le <[email protected]>
1 parent 751b8ad commit 36e8c26

File tree

1 file changed

+84
-0
lines changed

1 file changed

+84
-0
lines changed

docs/guide/dynamic_link.md

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,89 @@ name collision if the same library is being bundled by a different package, and
3333
check if the packages confirm to standards like [PEP600] (`manylinux_X_Y`).
3434
These tools do not allow to have cross wheel library dependency.
3535

36+
## scikit-build-core wheel repair
37+
38+
:::{warning}
39+
40+
This feature is experimental and API and effects may change.
41+
42+
:::
43+
44+
scikit-build-core also provides a built-in wheel repair which is enabled from
45+
`wheel.repair.enable`. Unlike the [wheel repair tools], this feature uses the
46+
linking information used during the CMake steps.
47+
48+
:::{note}
49+
50+
Executables, libraries, dependencies installed in `${SKBUILD_SCRIPTS_DIR}` or
51+
`${SKBUILD_DATA_DIR}` are not considered. Only files in `wheel.install-dir` or
52+
`${SKBUILD_PLATLIB_DIR}` are considered.
53+
54+
:::
55+
56+
So far there are 3 repair features implemented, which can be activated
57+
independently.
58+
59+
### `wheel.repair.in-wheel`
60+
61+
If this feature is enabled, it patches the executable/libraries so that, if the
62+
dependency is packaged in the _same_ wheel, the executable/libraries point to
63+
the dependency files inside the wheel.
64+
65+
### `wheel.repair.cross-wheel`
66+
67+
If this feature is enabled, it patches the executable/libraries so that, if the
68+
dependency is packaged in a _different_ wheel available from
69+
`build-system.requires`, the executable/libraries point to the dependency files
70+
in that other wheel.
71+
72+
The same/compatible library that was used in the `build-system.requires` should
73+
be used in the project's dependencies. The link to the other wheel will have
74+
priority, but if that wheel is not installed or is incompatible, it will
75+
fall-through to the system dependencies.
76+
77+
### `wheel.repair.bundle-external`
78+
79+
This feature is enabled by providing a list of regex patterns of the dynamic
80+
libraries that should be bundled. Only the filename is considered for the regex
81+
matching. The dependency files are then copied to a folder `{project.name}.libs`
82+
and the dependents are patched to point to there.
83+
84+
External libraries linked from a different wheel available from
85+
`build-system.requires` are not considered.
86+
87+
:::{warning}
88+
89+
Unlike the [wheel repair tools], this feature does not mangle the library names,
90+
which may cause issues if multiple dependencies link to the same library with
91+
the same `SONAME`/`SOVERSION` (usually just the library file name).
92+
93+
:::
94+
95+
### Windows repairs
96+
97+
The windows wheel repairs are done by adding `os.add_dll_directory` commands to
98+
the top-level python package/modules in the current wheel. Thus, the library
99+
linkage is only available when executing a python script/module that import the
100+
current wheel's top-level python package/modules.
101+
102+
In contrast, in Unix systems the libraries and executable are patched directly
103+
and are available outside of the python environment as well.
104+
105+
### Beware of library load order
106+
107+
Beware if there are multiple dynamic libraries in other wheels or even on the
108+
system with the same `SONAME`/`SOVERSION` (usually just the library file name).
109+
Depending on the order of python or other script execution, the other libraries
110+
(not the ones that were patched to be linked to) may be loaded first, and when
111+
your libraries are loaded, the dependencies that have already been loaded will
112+
be used instead of the ones that were patched to be linked to.
113+
114+
If you want to avoid this, consider using the [wheel repair tools] which always
115+
bundle and mangle the libraries appropriately to preserve the consistency.
116+
However, this also makes it impossible to link/fallback to system libraries or
117+
link to a shared library in a different wheel.
118+
36119
## Manual patching
37120

38121
You can manually make a relative RPath. This has the benefit of working when not
@@ -71,5 +154,6 @@ os.add_dll_directory(str(dependency_dll_path))
71154
[cibuildwheel]: https://cibuildwheel.pypa.io/en/stable/
72155
[repair wheel]: https://cibuildwheel.pypa.io/en/stable/options/#repair-wheel-command
73156
[PEP600]: https://peps.python.org/pep-0600
157+
[wheel repair tools]: #wheel-repair-tools
74158

75159
<!-- prettier-ignore-end -->

0 commit comments

Comments
 (0)