Debian Codegraph @

docs/rst/daemon/locations.rst

raw
1 .. _daemon_file_locations:
2
3 Locations of WirePlumber's files
4 ================================
5
6 .. _config_locations:
7
8 Location of configuration files
9 -------------------------------
10
11 WirePlumber's default locations of its configuration files are the following,
12 in order of priority:
13
14 1. ``$XDG_CONFIG_HOME/wireplumber``
15 2. ``$XDG_CONFIG_DIRS/wireplumber``
16 3. ``$sysconfdir/wireplumber``
17 4. ``$XDG_DATA_DIRS/wireplumber``
18 5. ``$datadir/wireplumber``
19
20 Notes:
21
22 * ``$syscondir`` and ``$datadir`` refer to
23 `meson's directory options <https://mesonbuild.com/Builtin-options.html#directories>`_
24 and are hardcoded at build time
25 * ``$XDG_`` variables refer to the
26 `XDG Base Directory Specification <https://specifications.freedesktop.org/basedir-spec/latest/index.html>`_
27
28 It is recommended that user specific overrides are placed in
29 ``$XDG_CONFIG_HOME/wireplumber``, while host-specific configuration is placed in
30 ``$XDG_CONFIG_DIRS/wireplumber`` or ``$sysconfdir/wireplumber`` and
31 distribution-provided configuration is placed in ``$XDG_DATA_DIRS/wireplumber``
32 or ``$datadir/wireplumber``.
33
34 At runtime, WirePlumber will seek out the directory with the highest priority
35 that contains the required configuration file. This setup allows a user or
36 system administrator to effortlessly override the configuration files provided
37 by the distribution. They can achieve this by placing a file with an identical
38 name in a higher priority directory.
39
40 It is also possible to override the configuration directory by setting the
41 ``WIREPLUMBER_CONFIG_DIR`` environment variable:
42
43 .. code-block:: bash
44
45 WIREPLUMBER_CONFIG_DIR=src/config wireplumber
46
47 ``WIREPLUMBER_CONFIG_DIR`` supports listing multiple directories, using the
48 standard path list separator ``:``. If multiple directories are specified,
49 the first one has the highest priority and the last one has the lowest.
50
51 .. note::
52
53 When the configuration directory is overridden with
54 ``WIREPLUMBER_CONFIG_DIR``, the default locations are ignored and
55 configuration files are *only* looked up in the directories specified by this
56 variable.
57
58 .. _config_locations_fragments:
59
60 Configuration fragments
61 ^^^^^^^^^^^^^^^^^^^^^^^
62
63 WirePlumber also supports configuration fragments. These are configuration files
64 that are loaded in addition to the main configuration file, allowing to
65 override or extend the configuration without having to copy the whole file.
66 See also the :ref:`config_conf_file_fragments` section for semantics.
67
68 Configuration fragments are always loaded from subdirectories of the main search
69 directories that have the same name as the configuration file, with the ``.d``
70 suffix appended. For example, if WirePlumber loads ``wireplumber.conf``, it will
71 also load ``wireplumber.conf.d/*.conf``. Note also that the fragment files need
72 to have the ``.conf`` suffix.
73
74 When WirePlumber loads a configuration file from the default locations, it will
75 also load all configuration fragments that are present in all of the default
76 locations, but following the reverse order of priority. This allows
77 configuration fragments that are installed in more system-wide locations to be
78 overridden by the system administrator or the users.
79
80 For example, assuming WirePlumber loads ``wireplumber.conf``, from any of the
81 search locations, it will also locate and load the following fragments, in this
82 order:
83
84 1. ``$datadir/wireplumber/wireplumber.conf.d/*.conf``
85 2. ``$XDG_DATA_DIRS/wireplumber/wireplumber.conf.d/*.conf``
86 3. ``$sysconfdir/wireplumber/wireplumber.conf.d/*.conf``
87 4. ``$XDG_CONFIG_DIRS/wireplumber/wireplumber.conf.d/*.conf``
88 5. ``$XDG_CONFIG_HOME/wireplumber/wireplumber.conf.d/*.conf``
89
90 Within each search location that contains fragments, the individual fragment
91 files are opened in alphanumerical order. This can be important to know, because
92 the parsing order matters in merging. See :ref:`config_conf_file_fragments`
93
94 .. note::
95
96 When ``WIREPLUMBER_CONFIG_DIR`` is set, the default locations are ignored and
97 fragment files are *only* looked up in the directories specified by this
98 variable.
99
100 .. _config_locations_scripts:
101
102 Location of scripts
103 -------------------
104
105 WirePlumber's default locations of its data files are the following,
106 in order of priority:
107
108 1. ``$XDG_DATA_HOME/wireplumber``
109 2. ``$XDG_DATA_DIRS/wireplumber``
110 3. ``$datadir/wireplumber``
111
112 At runtime, WirePlumber will search the directories for the highest-priority
113 directory to contain the needed data file.
114
115 Scripts are a specific kind of "data" files and are expected to be located
116 within a ``scripts`` subdirectory in the above data search locations. The "data"
117 directory is a somewhat more generic path that may be used for other kinds of
118 data files in the future.
119
120 It is also possible to override the data directory by setting the
121 ``WIREPLUMBER_DATA_DIR`` environment variable:
122
123 .. code-block:: bash
124
125 WIREPLUMBER_DATA_DIR=src wireplumber
126
127 As with the default data directories, script files in particular are expected
128 to be located within a ``scripts`` subdirectory, so in the above example the
129 scripts would actually reside in ``src/scripts``.
130
131 ``WIREPLUMBER_DATA_DIR`` supports listing multiple directories, using the
132 standard path list separator ``:``. If multiple directories are specified,
133 the first one has the highest priority and the last one has the lowest.
134
135 .. note::
136
137 When ``WIREPLUMBER_DATA_DIR`` is set, the default locations are ignored and
138 scripts are *only* looked up in the directories specified by this variable.
139
140 Location of modules
141 -------------------
142
143 WirePlumber modules
144 ^^^^^^^^^^^^^^^^^^^
145
146 WirePlumber's default location of its modules is
147 ``$libdir/wireplumber-$api_version``, where ``$libdir`` is set at compile time
148 by the build system. Typically, it ends up being ``/usr/lib/wireplumber-0.5``
149 (or ``/usr/lib/<arch-triplet>/wireplumber-0.5`` on multiarch systems)
150
151 It is possible to override this directory at runtime by setting the
152 ``WIREPLUMBER_MODULE_DIR`` environment variable:
153
154 .. code-block:: bash
155
156 WIREPLUMBER_MODULE_DIR=build/modules wireplumber
157
158 ``WIREPLUMBER_MODULE_DIR`` supports listing multiple directories, using the
159 standard path list separator ``:``. If multiple directories are specified, the
160 first one has the highest priority and the last one has the lowest.
161
162 .. note::
163
164 When ``WIREPLUMBER_MODULE_DIR`` is set, the default locations are ignored and
165 scripts are *only* looked up in the directories specified by this variable.
166
167 PipeWire and SPA modules
168 ^^^^^^^^^^^^^^^^^^^^^^^^
169
170 PipeWire and SPA modules are not loaded from the same location as WirePlumber's
171 modules. They are loaded from the location that PipeWire loads them.
172
173 It is also possible to override these locations by using environment variables:
174 ``SPA_PLUGIN_DIR`` and ``PIPEWIRE_MODULE_DIR``. For more details, refer to
175 PipeWire's documentation.