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