fdo-mirrors/wireplumber
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/pipewire/wireplumber.git synced 2026-05-07 13:28:05 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: update the documentation around file search locations

Browse source
This commit is contained in:
George Kiagiadakis 2024-03-07 19:58:52 +02:00
parent 22de7513c1
commit f24edf67fa
2 changed files with 112 additions and 73 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

29
docs/rst/daemon/configuration/conf_file.rst
View file

@ -4,8 +4,8 @@ Configuration file
==================
WirePlumber's configuration file is by default ``wireplumber.conf`` and resides
in the ``pipewire`` configuration directory (see :ref:`config_locations` for
more details on that).
in one of the WirePlumber specific
:ref:`configuration file search locations <config_locations>`.
The default configuration file can be changed on the command line by passing
the ``--config-file`` or ``-c`` option:
@ -25,8 +25,8 @@ the ``--config-file`` or ``-c`` option:
Note that Lua is still the scripting language for WirePlumber, but it is only
used for actual scripting and not for configuration.
Format
------
The SPA-JSON Format
-------------------
The format of this configuration file is a variant of JSON that is also
used in PipeWire configuration files (also known as SPA-JSON). The file consists
@ -103,17 +103,18 @@ When loading the configuration file, WirePlumber will also look for
additional files in the directory that has the same name as the configuration
file suffixed with ``.d`` and will load all of them as well. For example,
loading ``wireplumber.conf`` will also load any ``.conf`` files under
``wireplumber.conf.d/``. This directory is searched in all the search paths
for configuration files (see :ref:`config_locations`) and the fragments are
loaded from *all* of them.
``wireplumber.conf.d/``. This directory is searched in all the configuration
search locations and the fragments are loaded from *all* of them, starting
from the most system-wide locations and moving towards the most user-specific
locations, in alphanumerical order within each location (see also
:ref:`config_locations_fragments`).
The fragments are loaded in alphabetical order, after the main configuration
file. When a JSON object appears in multiple files, the properties of the
objects are merged together. When a JSON array appears in multiple files, the
arrays are concatenated together. When merging objects, if specific properties
appear in many of those objects, the last one to be parsed always overwrites
previous ones, unless the value is also an object or array; if it is, then the
value is recursively merged using the same rules.
When a JSON object appears in multiple files, the properties of the objects are
merged together. When a JSON array appears in multiple files, the arrays are
concatenated together. When merging objects, if specific properties appear in
many of those objects, the last one to be parsed always overwrites previous
ones, unless the value is also an object or array; if it is, then the value is
recursively merged using the same rules.
Sections
--------

156
docs/rst/daemon/configuration/locations.rst
View file

@ -6,23 +6,34 @@ Locations of files
Location of configuration files
-------------------------------
WirePlumber's default locations of its configuration files are the same as
pipewire's. Typically, those end up being ``$XDG_CONFIG_HOME/pipewire``,
``/etc/pipewire``, and ``/usr/share/pipewire``, in that order of priority.
WirePlumber's default locations of its configuration files are the following,
in order of priority:
.. note::
1. ``$XDG_CONFIG_HOME/wireplumber``
2. ``$XDG_CONFIG_DIRS/wireplumber``
3. ``$sysconfdir/wireplumber``
4. ``$XDG_DATA_DIRS/wireplumber``
5. ``$datadir/wireplumber``
Starting with WirePlumber 0.5, the configuration files are located in
the ``pipewire`` directory. In previous versions they used to be in the
``wireplumber`` directory.
Notes:
The three designated locations are purposed for custom user configuration,
host-specific configuration, and distribution-provided configuration,
respectively. At runtime, WirePlumber will seek out the directory with the
highest priority that contains the required configuration file. This setup
allows a user or system administrator to effortlessly override the configuration
files provided by the distribution. They can achieve this by placing a file with
an identical name in a higher priority directory.
* ``$syscondir`` and ``$datadir`` refer to
`meson's directory options <https://mesonbuild.com/Builtin-options.html#directories>`_
and are hardcoded at build time
* ``$XDG_`` variables refer to the
`XDG Base Directory Specification <https://specifications.freedesktop.org/basedir-spec/latest/index.html>`_
It is recommended that user specific overrides are placed in
``$XDG_CONFIG_HOME/wireplumber``, while host-specific configuration is placed in
``$XDG_CONFIG_DIRS/wireplumber`` or ``$sysconfdir/wireplumber`` and
distribution-provided configuration is placed in ``$XDG_DATA_DIRS/wireplumber``
or ``$datadir/wireplumber``.
At runtime, WirePlumber will seek out the directory with the highest priority
that contains the required configuration file. This setup allows a user or
system administrator to effortlessly override the configuration files provided
by the distribution. They can achieve this by placing a file with an identical
name in a higher priority directory.
It is also possible to override the configuration directory by setting the
``WIREPLUMBER_CONFIG_DIR`` environment variable:
@ -31,15 +42,18 @@ It is also possible to override the configuration directory by setting the
WIREPLUMBER_CONFIG_DIR=src/config wireplumber
This is the same as the ``PIPEWIRE_CONFIG_DIR`` environment variable, which has
the same effect. But for convenience, WirePlumber also supports the
``WIREPLUMBER_CONFIG_DIR`` environment variable. When the
``WIREPLUMBER_CONFIG_DIR`` environment variable is set, the
``PIPEWIRE_CONFIG_DIR`` environment variable is ignored.
``WIREPLUMBER_CONFIG_DIR`` supports listing multiple directories, using the
standard path list separator ``:``. If multiple directories are specified,
the first one has the highest priority and the last one has the lowest.
When the configuration directory is overriden with ``WIREPLUMBER_CONFIG_DIR`` or
``PIPEWIRE_CONIFG_DIR``, the default locations are ignored and configuration
files are *only* looked up in this directory.
.. note::
When the configuration directory is overriden with
``WIREPLUMBER_CONFIG_DIR``, the default locations are ignored and
configuration files are *only* looked up in the directories specified by this
variable.
.. _config_locations_fragments:
Configuration fragments
^^^^^^^^^^^^^^^^^^^^^^^
@ -47,7 +61,7 @@ Configuration fragments
WirePlumber also supports configuration fragments. These are configuration files
that are loaded in addition to the main configuration file, allowing to
override or extend the configuration without having to copy the whole file.
See also the :ref:`config_conf_file` section for semantics.
See also the :ref:`config_conf_file_fragments` section for semantics.
Configuration fragments are always loaded from subdirectories of the main search
directories that have the same name as the configuration file, with the ``.d``
@ -56,47 +70,68 @@ also load ``wireplumber.conf.d/*.conf``. Note also that the fragment files need
to have the ``.conf`` suffix.
When WirePlumber loads a configuration file from the default locations, it will
also load all configuration fragments that are present in any of the search
directories in the default locations. For example, if the main configuration
file is ``/etc/pipewire/wireplumber.conf``, WirePlumber will also load
``$XDG_CONFIG_HOME/pipewire/wireplumber.conf.d/*.conf`` and
``/etc/pipewire/wireplumber.conf.d/*.conf`` and
``/usr/share/pipewire/wireplumber.conf.d/*.conf``, in that order. It does not
matter where the main configuration file was loaded from.
also load all configuration fragments that are present in all of the default
locations, but following the reverse order of priority. This allows
configuration fragments that are installed in more system-wide locations to be
overriden by the system administrator or the users.
However, when WirePlumber loads a configuration file from a directory specified
via ``WIREPLUMBER_CONFIG_DIR`` or ``PIPEWIRE_CONFIG_DIR``, it will only load
configuration fragments from that directory.
For example, assuming WirePlumber loads ``wireplumber.conf``, from any of the
search locations, it will also locate and load the following fragments, in this
order:
1. ``$datadir/wireplumber/wireplumber.conf.d/*.conf``
2. ``$XDG_DATA_DIRS/wireplumber/wireplumber.conf.d/*.conf``
3. ``$sysconfdir/wireplumber/wireplumber.conf.d/*.conf``
4. ``$XDG_CONFIG_DIRS/wireplumber/wireplumber.conf.d/*.conf``
5. ``$XDG_CONFIG_HOME/wireplumber/wireplumber.conf.d/*.conf``
Within each search location that contains fragments, the individual fragment
files are opened in alphanumerical order. This can be important to know, because
the parsing order matters in merging. See :ref:`config_conf_file_fragments`
.. note::
When ``WIREPLUMBER_CONFIG_DIR`` is set, the default locations are ignored and
fragment files are *only* looked up in the directories specified by this
variable.
Location of scripts
-------------------
WirePlumber's default locations of its scripts are similar as the ones for the
configuration files, but they reside in ``wireplumber/scripts/``, relative to
the base path, unlike the configuration files which reside in ``pipewire/``.
Typically, these end up being ``$XDG_CONFIG_HOME/wireplumber/scripts``,
``/etc/wireplumber/scripts``, and ``/usr/share/wireplumber/scripts``,
in that order of priority.
WirePlumber's default locations of its data files are the following,
in order of priority:
1. ``$XDG_DATA_HOME/wireplumber``
2. ``$XDG_DATA_DIRS/wireplumber``
3. ``$datadir/wireplumber``
The three locations are intended for custom user scripts,
host-specific scripts and distribution-provided scripts, respectively.
At runtime, WirePlumber will search the directories for the highest-priority
directory to contain the needed script.
directory to contain the needed data file.
It is also possible to override the scripts directory by setting the
Scripts are a specific kind of "data" files and are expected to be located
within a ``scripts`` subdirectory in the above data search locations. The "data"
directory is a somewhat more generic path that may be used for other kinds of
data files in the future.
It is also possible to override the data directory by setting the
``WIREPLUMBER_DATA_DIR`` environment variable:
.. code-block:: bash
WIREPLUMBER_DATA_DIR=src wireplumber
The "data" directory is a somewhat more generic path that may be used for
other kinds of data files in the future. For scripts, WirePlumber still expects
to find a ``scripts`` subdirectory in this "data" directory, so in the above
example the scripts would be in ``src/scripts``.
As with the default data directories, script files in particular are expected
to be located within a ``scripts`` subdirectory, so in the above example the
scripts would actually reside in ``src/scripts``.
If ``WIREPLUMBER_DATA_DIR`` is set, the default locations are ignored and
scripts are *only* looked up in this directory.
``WIREPLUMBER_DATA_DIR`` supports listing multiple directories, using the
standard path list separator ``:``. If multiple directories are specified,
the first one has the highest priority and the last one has the lowest.
.. note::
When ``WIREPLUMBER_DATA_DIR`` is set, the default locations are ignored and
scripts are *only* looked up in the directories specified by this variable.
Location of modules
-------------------
@ -104,16 +139,10 @@ Location of modules
WirePlumber modules
^^^^^^^^^^^^^^^^^^^
Like with configuration files, WirePlumber's default location of its modules is
determined at compile time by the build system. Typically, it ends up being
``/usr/lib/wireplumber-0.5`` (or ``/usr/lib/<arch-triplet>/wireplumber-0.5`` on
multiarch systems)
In more detail, this is controlled by the ``--libdir`` meson option. When
this is set to an absolute path, such as ``/lib``, the location of the
modules is set to be ``$libdir/wireplumber-$abi_version``. When this is set
to a relative path, such as ``lib``, then the installation prefix (``--prefix``)
is prepended to the path: ``$prefix/$libdir/wireplumber-$abi_version``.
WirePlumber's default location of its modules is
``$libdir/wireplumber-$api_version``, where ``$libdir`` is set at compile time
by the build system. Typically, it ends up being ``/usr/lib/wireplumber-0.5``
(or ``/usr/lib/<arch-triplet>/wireplumber-0.5`` on multiarch systems)
It is possible to override this directory at runtime by setting the
``WIREPLUMBER_MODULE_DIR`` environment variable:
@ -122,6 +151,15 @@ It is possible to override this directory at runtime by setting the
WIREPLUMBER_MODULE_DIR=build/modules wireplumber
``WIREPLUMBER_MODULE_DIR`` supports listing multiple directories, using the
standard path list separator ``:``. If multiple directories are specified, the
first one has the highest priority and the last one has the lowest.
.. note::
When ``WIREPLUMBER_MODULE_DIR`` is set, the default locations are ignored and
scripts are *only* looked up in the directories specified by this variable.
PipeWire and SPA modules
^^^^^^^^^^^^^^^^^^^^^^^^