fedora-llm-docs/Documents/pages/Unversioned_shared_objects.txt

= 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.