From c29853b9a1cd4ab017e9604dc7457831e87e05e1 Mon Sep 17 00:00:00 2001 From: Jonathan Steffan Date: Jul 18 2024 17:39:00 +0000 Subject: Update DSO Packaging Guidelines - Add dedicated section for unversioned SONAMEs - Detail Vulkan and OpenXR filesystem layout - Detail loader configuration --- diff --git a/guidelines/modules/ROOT/pages/Unversioned_shared_objects.adoc b/guidelines/modules/ROOT/pages/Unversioned_shared_objects.adoc new file mode 100644 index 0000000..4be5a18 --- /dev/null +++ b/guidelines/modules/ROOT/pages/Unversioned_shared_objects.adoc @@ -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. diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index a7e52b0..08902dc 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -1363,21 +1363,26 @@ it must go into the base package. 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: