@@ -33,6 +33,89 @@ name collision if the same library is being bundled by a different package, and
33
33
check if the packages confirm to standards like [ PEP600] (` manylinux_X_Y ` ).
34
34
These tools do not allow to have cross wheel library dependency.
35
35
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
+
36
119
## Manual patching
37
120
38
121
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))
71
154
[ cibuildwheel ] : https://cibuildwheel.pypa.io/en/stable/
72
155
[ repair wheel ] : https://cibuildwheel.pypa.io/en/stable/options/#repair-wheel-command
73
156
[ PEP600 ] : https://peps.python.org/pep-0600
157
+ [ wheel repair tools ] : #wheel-repair-tools
74
158
75
159
<!-- prettier-ignore-end -->
0 commit comments