The open source OpenXR runtime
doc: Add information for Linux distribution packagers.
authored by
Rylie Pavlik
and committed by
Simon Zeni
a983b03b
099e971b
+85
+1
doc/mainpage.md
+1
doc/mainpage.md
+84
doc/packaging-notes.md
+84
doc/packaging-notes.md
···
1
+
# Packaging Notes {#packaging-notes}
2
+
3
+
<!--
4
+
Copyright 2023-2024, Collabora, Ltd. and the Monado contributors
5
+
SPDX-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
11
+
to a subdirectory of the library path?"_
12
+
13
+
To understand this, it helps to keep in mind how OpenXR works from an
14
+
application point of view. Applications are intended to be runtime-independent
15
+
and 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:
17
+
it provides a layer of indirection. It also allows for the use of API layers
18
+
with runtimes, and handles runtime finding. Follow that link for more
19
+
information from the design documents.
20
+
21
+
The TL;DR version is this: `libopenxr_monado` not having a versioned SONAME yet
22
+
being installed in the default library path is **not an error or oversight**,
23
+
but a carefully-reasoned technical decision. Do not patch this or change it in
24
+
distribution packages without understanding what design choices and features you
25
+
break 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
+
31
+
Monado (as well as OpenXR API layers) are like Vulkan drivers (technically ICDs)
32
+
and API layers, in that they are only used behind a loader doing runtime dynamic
33
+
linking/late loading. A versioned `SONAME` makes no real sense for them, but
34
+
sometimes you do want them in the default dynamic library load path.
35
+
36
+
You never link against the OpenXR runtime interface of Monado directly, it's
37
+
loaded dynamically at runtime by the OpenXR loader after reading configurations
38
+
and manifest files. The OpenXR loader _does_ have a versioned SONAME on Linux,
39
+
where it might be system installed. This is why it makes no sense to have a
40
+
SONAME for the runtime SO: the compatibility of that SO is defined by the
41
+
manifest that is installed and the OpenXR spec itself.
42
+
43
+
At 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
45
+
than its compliance with external rules that do not consider how the software is
46
+
designed or used. Furthermore, it would likely lead to increased
47
+
misunderstandings in how OpenXR and Monado are intended to be used by
48
+
developers. The only public interface of that `libopenxr_monado.so` is strictly
49
+
specified by the [OpenXR specification][] in general, with its exported symbols
50
+
specified 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
+
55
+
Note: `libmonado`, which _does_ have a public API as a management interface for
56
+
software serving as a Monado front-end or dashboard, _does_ have a versioned
57
+
SONAME.
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
+
61
+
Why can we not move that library off of the main dynamic loader path? It is true
62
+
that OpenXR API layers can live in a subdirectory of the dynamic library path,
63
+
because the loader will try to load layers from all the manifests and ignore the
64
+
ones whose library it cannot load, resolving multi-arch issues by trying all
65
+
architectures. 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
+
74
+
When this is done, the loader uses the normal library search path to find the
75
+
runtime, which gives you the right architecture for the application.
76
+
Essentially, it lets the loader use the same argument to `dlopen` regardless of
77
+
architecture, and get the right library. This allows, e.g. a 32-bit application
78
+
to use the 32-bit version of `libopenxr_monado`, typically to talk to the 64-bit
79
+
`monado-service` instance.
80
+
81
+
At some point it would be nice to generate the architecture-specific runtime
82
+
manifests for Monado. However, it makes selecting runtimes system-wide using
83
+
`alternatives` or similar more complex, as you would need to update multiple
84
+
symlinks.