afb81b8278
Some checks failed
Docker. / Ubuntu (push) Has been cancelled
User-agent updater. / User-agent (push) Failing after 15s
Lock Threads / lock (push) Failing after 10s
Waiting for answer. / waiting-for-answer (push) Failing after 22s
Needs user action. / needs-user-action (push) Failing after 8s
Can't reproduce. / cant-reproduce (push) Failing after 8s
Close stale issues and PRs / stale (push) Has been cancelled
168 lines
5.7 KiB
ReStructuredText
168 lines
5.7 KiB
ReStructuredText
============
|
|
portals.conf
|
|
============
|
|
|
|
--------------------------------
|
|
XDG desktop portal configuration
|
|
--------------------------------
|
|
|
|
:Manual section: 5
|
|
:Manual group: File Formats Manual
|
|
|
|
.. _synopsis:
|
|
|
|
SYNOPSIS
|
|
========
|
|
|
|
*$XDG_CONFIG_HOME/xdg-desktop-portal/{\*-}portals.conf*
|
|
|
|
*$XDG_CONFIG_DIRS/xdg-desktop-portal/{\*-}portals.conf*
|
|
|
|
*@SYSCONFDIR@/xdg-desktop-portal/{\*-}portals.conf*
|
|
|
|
*$XDG_DATA_HOME/xdg-desktop-portal/{\*-}portals.conf*
|
|
|
|
*$XDG_DATA_DIRS/xdg-desktop-portal/{\*-}portals.conf*
|
|
|
|
*@DATADIR@/xdg-desktop-portal/{\*-}portals.conf*
|
|
|
|
DESCRIPTION
|
|
===========
|
|
|
|
xdg-desktop-portal uses a configuration file to determine which portal backend
|
|
should be used to provide the implementation for the requested interface.
|
|
This mechanism is very similar to the freedesktop.org specification for
|
|
"Association between MIME types and applications" (mime-apps).
|
|
|
|
Desktop environments and OS vendors should provide a default configuration
|
|
for their chosen portal backends in
|
|
``/usr/share/xdg-desktop-portal/DESKTOP-portals.conf``, where ``DESKTOP``
|
|
is the desktop environment name as it would appear in the
|
|
``XDG_CURRENT_DESKTOP`` environment variable, after case-folding ASCII
|
|
upper case to lower case.
|
|
For example, KDE should provide ``/usr/share/xdg-desktop-portal/kde-portals.conf``.
|
|
|
|
Users can override those defaults, or provide configuration for an otherwise
|
|
unsupported desktop environment, by writing a file
|
|
``~/.config/xdg-desktop-portal/portals.conf``. Users of more than one
|
|
desktop environment can use desktop-specific filenames such as
|
|
``kde-portals.conf`` which will only be used in the appropriate desktop
|
|
environment.
|
|
|
|
Similarly, system administrators can provide a default configuration for
|
|
all users in ``/etc/xdg-desktop-portal/DESKTOP-portals.conf`` or
|
|
``/etc/xdg-desktop-portal/portals.conf``.
|
|
|
|
The following locations are searched for configuration, highest precedence
|
|
first:
|
|
|
|
- ``$XDG_CONFIG_HOME``, defaulting to ``~/.config``
|
|
- each directory in ``$XDG_CONFIG_DIRS``, defaulting to ``/etc/xdg``
|
|
- the build-time ``sysconfdir`` for xdg-desktop-portal, usually ``/etc``
|
|
- ``$XDG_DATA_HOME``, defaulting to ``~/.local/share``
|
|
(searched only for consistency with other specifications, writing
|
|
configuration here is not recommended)
|
|
- each directory in ``$XDG_DATA_DIRS``, defaulting to ``/usr/local/share:/usr/share``
|
|
- the build-time ``datadir`` for xdg-desktop-portal, usually ``/usr/share``
|
|
|
|
In each of those locations, for each desktop environment name listed in the
|
|
``XDG_CURRENT_DESKTOP`` environment variable, xdg-desktop-portal checks for
|
|
``xdg-desktop-portal/DESKTOP-portals.conf``, where ``DESKTOP`` is the
|
|
desktop environment name in lower-case. If a desktop-environment-specific
|
|
configuration file is not found, a non-desktop-specific file
|
|
``xdg-desktop-portal/portals.conf`` will be read.
|
|
For example, if ``XDG_CURRENT_DESKTOP`` is set to ``Budgie:GNOME``,
|
|
then xdg-desktop-portal will look for
|
|
``xdg-desktop-portal/budgie-portals.conf``,
|
|
``xdg-desktop-portal/gnome-portals.conf`` and
|
|
``xdg-desktop-portal/portals.conf`` in that order.
|
|
|
|
Only the first configuration file found is read, and lower-precedence
|
|
configuration files are ignored. All possible configuration files within
|
|
one directory are tried before moving on to the next directory, so for
|
|
example ``~/.config/xdg-desktop-portal/portals.conf`` is higher-precedence
|
|
than ``/usr/share/xdg-desktop-portal/kde-portals.conf``.
|
|
|
|
FILE FORMAT
|
|
-----------
|
|
|
|
The format of the portals configuration file is the same ``.ini`` format used by
|
|
systemd unit files or application desktop files.
|
|
|
|
``[preferred]``
|
|
|
|
The main configuration group for preferred portals.
|
|
|
|
The following keys can be present in the ``preferred`` group:
|
|
|
|
``default`` *(string)*
|
|
|
|
The default portal backend to use for every interface, unless the interface
|
|
is listed explicitly.
|
|
|
|
``org.freedesktop.impl.portal.*`` *(string)*
|
|
|
|
One of the valid portal interface implementations exposed by
|
|
xdg-desktop-portal.
|
|
|
|
Each key in the group contains a semi-colon separated list of portal backend
|
|
implementation, to be searched for an implementation of the requested interface,
|
|
in the same order as specified in the configuration file. Additionally, the
|
|
special values ``none`` and ``*`` can be used:
|
|
|
|
``none``
|
|
|
|
Do not provide a portal implementation for this interface.
|
|
|
|
``*``
|
|
|
|
Use the first portal implementation found, in lexicographical order.
|
|
|
|
EXAMPLE
|
|
-------
|
|
|
|
::
|
|
|
|
[preferred]
|
|
# Use xdg-desktop-portal-gtk for every portal interface...
|
|
default=gtk
|
|
# ... except for the ScreenCast interface
|
|
org.freedesktop.impl.portal.ScreenCast=gnome
|
|
|
|
|
|
ENVIRONMENT
|
|
-----------
|
|
|
|
``XDG_CURRENT_DESKTOP``
|
|
|
|
A colon-separated list of desktop environments, most specific first,
|
|
used to choose a desktop-specific portal configuration.
|
|
The default is an empty list.
|
|
|
|
``XDG_CONFIG_HOME``
|
|
|
|
The per-user ``portals.conf`` file is located in this directory. The default
|
|
is ``$HOME/.config``.
|
|
|
|
``XDG_CONFIG_DIRS``
|
|
|
|
A colon-separated list of system configuration directories and secondary
|
|
per-user configuration directories. The default is ``/etc/xdg``.
|
|
|
|
``XDG_DATA_HOME``
|
|
|
|
A per-user data directory, searched for consistency with other
|
|
specifications. The default is ``$HOME/.local/share``.
|
|
|
|
``XDG_DATA_DIRS``
|
|
|
|
A colon-separated list of system data directories and secondary per-user
|
|
data directories. The default is ``/usr/local/share:/usr/share``.
|
|
|
|
SEE ALSO
|
|
--------
|
|
|
|
- `XDG Base Directory Specification <https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html>`_
|
|
- `XDG Desktop Entry specification <https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html>`_
|
|
- `XDG Association between MIME type and applications specification <https://specifications.freedesktop.org/mime-apps-spec/mime-apps-spec-latest.html>`_
|