matrixfurry.com
The open source OpenXR runtime
1# Packaging Notes {#packaging-notes}
2
3<!--
4Copyright 2023-2024, Collabora, Ltd. and the Monado contributors
5SPDX-License-Identifier: BSL-1.0
6-->
7
8## The SONAME and library location question
9
10_AKA, "Why does `libopenxr_monado.so` not have a versioned SONAME? Can I move it
11to a subdirectory of the library path?"_
12
13To understand this, it helps to keep in mind how OpenXR works from an
14application point of view. Applications are intended to be runtime-independent
15and portable, using the user's current runtime wherever they are executed. The
16[OpenXR Loader][] is the library that applications link against to achieve this:
17it provides a layer of indirection. It also allows for the use of API layers
18with runtimes, and handles runtime finding. Follow that link for more
19information from the design documents.
20
21The TL;DR version is this: `libopenxr_monado` not having a versioned SONAME yet
22being installed in the default library path is **not an error or oversight**,
23but a carefully-reasoned technical decision. Do not patch this or change it in
24distribution packages without understanding what design choices and features you
25break by doing so.
26
27[OpenXR Loader]: https://registry.khronos.org/OpenXR/specs/1.1/loader.html
28
29### My package linter is complaining that `libopenxr_monado.so` does not have a versioned SONAME
30
31Monado (as well as OpenXR API layers) are like Vulkan drivers (technically ICDs)
32and API layers, in that they are only used behind a loader doing runtime dynamic
33linking/late loading. A versioned `SONAME` makes no real sense for them, but
34sometimes you do want them in the default dynamic library load path.
35
36You never link against the OpenXR runtime interface of Monado directly, it's
37loaded dynamically at runtime by the OpenXR loader after reading configurations
38and manifest files. The OpenXR loader _does_ have a versioned SONAME on Linux,
39where it might be system installed. This is why it makes no sense to have a
40SONAME for the runtime SO: the compatibility of that SO is defined by the
41manifest that is installed and the OpenXR spec itself.
42
43At some point we might give up and set a versioned SONAME for
44`libopenxr_monado`, but it would not improve anything about the software other
45than its compliance with external rules that do not consider how the software is
46designed or used. Furthermore, it would likely lead to increased
47misunderstandings in how OpenXR and Monado are intended to be used by
48developers. The only public interface of that `libopenxr_monado.so` is strictly
49specified by the [OpenXR specification][] in general, with its exported symbols
50specified by the [Runtime Interface Negotiation][] section.
51
52[OpenXR specification]: https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html
53[Runtime Interface Negotiation]: https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#api-initialization-runtime-interface-negotiation
54
55Note: `libmonado`, which _does_ have a public API as a management interface for
56software serving as a Monado front-end or dashboard, _does_ have a versioned
57SONAME.
58
59### My package linter is complaining that without a versioned SONAME, `libopenxr_monado.so` should move to a private subdirectory of `/usr/lib/...`
60
61Why can we not move that library off of the main dynamic loader path? It is true
62that OpenXR API layers can live in a subdirectory of the dynamic library path,
63because the loader will try to load layers from all the manifests and ignore the
64ones whose library it cannot load, resolving multi-arch issues by trying all
65architectures. However, until a change to the OpenXR loader in OpenXR SDK 1.0.29
66(from late 2023), the only way to get multi-arch support with an OpenXR
67_runtime_ on Linux was to:
68
69- Place the binary in the correct library directory for the architecture
70- Put only the library name in the runtime manifest (rather than a relative or
71 absolute path) - turn off both `XRT_OPENXR_INSTALL_ABSOLUTE_RUNTIME_PATH` and
72 `XRT_OPENXR_INSTALL_ABSOLUTE_RUNTIME_PATH` for this to happen.
73
74When this is done, the loader uses the normal library search path to find the
75runtime, which gives you the right architecture for the application.
76Essentially, it lets the loader use the same argument to `dlopen` regardless of
77architecture, and get the right library. This allows, e.g. a 32-bit application
78to use the 32-bit version of `libopenxr_monado`, typically to talk to the 64-bit
79`monado-service` instance.
80
81At some point it would be nice to generate the architecture-specific runtime
82manifests for Monado. However, it makes selecting runtimes system-wide using
83`alternatives` or similar more complex, as you would need to update multiple
84symlinks.