PR#1368: Initial unversioned SONAME handling policy. - packaging-committee

packaging-committee

#1368 Initial unversioned SONAME handling policy.

Merged 2 months ago by james. Opened 4 months ago by jsteffan.

Unknown source unversioned-sonames into master

Jonathan Steffan • 3 months ago

c29853b

guidelines/modules/ROOT/pages/Unversioned_shared_objects.adoc

file added

+112

		`@@ -0,0 +1,112 @@`
		`+ = Unversioned Dynamic Shared Objects`
		`+`
		`+ The standard policy`
		`+ is to have versioned SONAMES`
		`+ for all dynamic shared objects (DSO).`
		+ Packagers ``SHOULD`` work with upstreams
		`+ that do not have versioned SONAMES`
		`+ to enable this capability.`
		`+ This is a hard requirement`
		`+ if the DSO is being linked`
		`+ between different software.`
		`+`
		`+ This policy`
		`+ helps to ensure ABI compatibility`
		`+ when DSOs are dynamically linked`
		`+ between different software.`
		`+`
		`+ == When Are Unversioned Dynamic Shared Objects Acceptable`
		`+`
		`+ There are a few conditions`
		`+ that need to exist in which DSOs are allowed to remain unversioned.`
		`+`
		+ * The DSO ``MUST NOT`` be visible
		`+ to the dynamic linker`
		+ (i.e. the DSO does not show up in ``ldconfig -p`` output)
		`+`
		+ * The DSO ``MUST`` be located in a private directory
		`+ (i.e. not located directly in /usr/lib[64] or in another directory listed as a library path for the linker)`
		`+`
		+ * The DSO ``MUST NOT`` be linked against and is loaded at runtime
		`+ by the implementing application`
		+ (i.e. ``dlopen()``)
		`+`
		`+ If these conditions are met,`
		`+ the unversioned DSOs`
		`+ do not need to be placed in a -devel package.`
		`+`
		`+ == Implementation Details`
		`+`
		`+ Listed below is information`
		`+ for each known use-case for unversioned DSOs.`
		`+ Evaluate if your situation matches any of these`
		`+ and ask for any clarification`
		`+ by opening a ticket with the {packaging-committee}.`
		`+`
		`+ === Vulkan`
		`+`
		`+ The https://vulkan.org[Vulkan] ecosystem`
		`+ continues to grow in capabilities and adoption.`
		`+ One of the core concepts`
		`+ is the https://docs.vulkan.org/guide/latest/loader.html[Vulkan Loader].`
		`+ This component is responsible for initializing the stack`
		`+ and includes loading unversioned DSOs,`
		`+ called Drivers and Layers.`
		`+`
		`+ Vulkan Drivers need to be visible to the default loader`
		`+ and are a special exception.`
		`+`
		`+ Drivers have the following requirements:`
		`+`
		+ * The DSO ``SHOULD`` be located in a private directory in /usr/lib[64]
		+ (i.e. ``%{_libdir}/%{name}/driver``)
		`+`
		+ * The directory ``SHOULD`` be added to the loader path using a ``ld.conf.d`` configuration
		+ (i.e. ``%{_sysconfdir}/ld.conf.d/%{name}.conf`` definition)
		`+`
		`+ Vulkan Layers are loaded by configuration as defined by the Vulkan Loader specification.`
		`+`
		`+ Layers have the following requirements:`
		`+`
		+ * The DSO ``MUST`` be located in a private directory in /usr/lib[64]
		+ (i.e. ``%{_libdir}/%{name}/layer``)
		`+ and loaded by configuration`
		`+`
		`+ === OpenXR`
		`+`
		`+ The https://www.khronos.org/openxr/[OpenXR] ecosystem`
		`+ enables users to run XR applications built against the SDK.`
		`+ One of the core concepts`
		`+ is the https://registry.khronos.org/OpenXR/specs/1.1/loader.html[OpenXR Loader].`
		`+ This component is responsible for initializing the stack`
		`+ and includes loading unversioned DSOs,`
		`+ called Runtimes and Layers.`
		`+`
		`+ OpenXR Runtimes are loaded by configuration as defined by the OpenXR Loader specification.`
		`+`
		`+ Runtimes have the following requirements:`
		`+`
		+ * The DSO ``MUST`` be located in a private directory in /usr/lib[64]
		+ (i.e. ``%{_libdir}/%{name}/runtime``)
		`+`
		+ * The directory ``SHOULD`` be added to the loader path using a ``ld.conf.d`` configuration
		+ (i.e. ``%{_sysconfdir}/ld.conf.d/%{name}.conf``definition)
		`+`
		`+ OpenXR Layers are loaded by configuration as defined by the OpenXR Loader specification.`
		`+`
		`+ Layers have the following requirements:`
		`+`
		+ * The DSO ``MUST`` be located in a private directory in /usr/lib[64]
		+ (i.e. ``%{_libdir}/%{name}/layer``)
		`+ and loaded by configuration`
		`+`
		`+ === Other Cases`
		`+`
		`+ An example of another case`
		`+ is an unversioned DSO`
		`+ that is loaded at runtime`
		`+ within the same application.`
		`+ This allows an application`
		`+ to load an optional feature, ship modular capabilities,`
		+ or otherwise ``dlopen()`` it's own capabilities.
		`+ These are allowed as long as the main requirements are met.`

guidelines/modules/ROOT/pages/index.adoc

file modified

+18 -13

		`@@ -1363,21 +1363,26 @@`
		`If upstream versions the shared library file at a future point,`
		`packagers must be careful to move to the versioned layout described above.`

		`+ === Unversioned Shared Objects`
		`+`
		`As an additional complication,`
		`- some software generates unversioned shared objects`
		`+ some software generates xref:Unversioned_shared_objects.`
		`+ adoc[unversioned shared objects]`
		`which are not intended to be used as system libraries.`
		`- These files are usually plugins or modular functionality`
		`- specific to an application,`
		`- and are not located in the ld library paths or cache.`
		`- This means that they are not located directly in /usr/lib or /usr/lib64,`
		`- or in a directory listed as a library path in /etc/ld.so.conf`
		`- (or an /etc/ld.so.conf.d/config file).`
		`- Usually, these unversioned shared objects can be found`
		`- in a dedicated subdirectory under /usr/lib or /usr/lib64`
		`- (e.g. /usr/lib/purple-2/ is the plugin directory`
		`- used for libpurple applications).`
		`- In these cases,`
		`- the unversioned shared objects do not need to be placed in a -devel package.`
		`+ These files are usually plugins or modular functionality specific to an application,`
		`+ and are not to be located in the ld library paths or cache.`
		`+ These types of unversioned shared objects`
		`+ do not need to go into a -devel package.`
		`+ They are only loaded at runtime`
		`+ and should be included in a private directory of the main package.`
		`+`
		`+ For specific details`
		`+ about how to deal with these types of DSOs,`
		`+ please see xref:Unversioned_shared_objects.`
		`+ adoc[unversioned shared objects]`
		`+ for detailed guidance.`
		`+`
		`+ === Exceptions`

		`There are some notable exceptions to this packaging model, specifically:`