Add portals configuration file for desktop environments

[ebassi]

Replace the UseIn key in each portal implementation with a per-desktop configuration file.

Desktop environments (either upstream or downstream) are supposed to ship the configuration file to describe which portal implementation to use for each portal interface.

Fixes: #906

[ebassi]

Open questions:

• deprecation policy for UseIn; add a warning, or just silently discard it?

The CI failure on 16.04 is unrelated, and seems to be an infrastructure issue.

[Sodivad]

This doesn't seem to work as I expect

[preferred]
default=kde
org.freedesktop.impl.portal.FileChooser=gtk

[matthiasclasen]

Open questions:

* deprecation policy for `UseIn`; add a warning, or just silently discard it?

I think a warning would be appropriate.

[matthiasclasen]

I sadly don't find UseIn mentioned in any docs we ship, so portal configuration is probably entirely undocumented.

It might be nice to start changing that by including a manpage for the portals.conf file format.

[ebassi]

I think a warning would be appropriate.

Switched to a warning.

It might be nice to start changing that by including a manpage for the portals.conf file format.

Done. I've added an optional dependency on rst2man to generate the man page. I can also commit the generated man page.

[rpigott]

Can I ask why XDG_DATA_HOME / XDG_DATA_DIRS was chosen for this config instead of XDG_CONFIG_HOME / XDG_CONFIG_DIRS? Isn't this a user configuration?

[WhyNotHugo]

With this merged in, if I'm using a portals.conf file to define which portals to use, I no longer need to set the XDG_CURRENT_DESKTOP variable for xdg-desktop-portal, right?

[Sodivad]

XDG_CURRENT_DESKTOP affects more than just portal backend selection

[ebassi]

You should not be setting XDG_CURRENT_DESKTOP yourself: it's up to whatever governs your session to do so.

The portals.conf file is a replacement for the UseIn key inside the portal implementation files; it is also a replacement for people disabling portal support.

If you don't have XDG_CURRENT_DESKTOP defined in your session, and if you don't have any session shipping a ${DESKTOP}-portals.conf then xdg-desktop-portal will read ${XDG_CONFIG_HOME}/xdg-desktop-portal/portals.conf.

For more information, xdg-desktop-portal ships a portals.conf(5) man page: https://github.com/flatpak/xdg-desktop-portal/blob/main/doc/portals-conf.rst

[WhyNotHugo]

~~What else is it used for?~~ Please disregard, I missed the second reply above.

[WhyNotHugo]

You should not be setting XDG_CURRENT_DESKTOP yourself: it's up to whatever governs your session to do so.

I'm not using a session governor, so I have to set this manually.

With the new portals.conf in my $XDG_CONFIG_HOME, I'm wondering if I need to set $XDG_CURRENT_DESKTOP for anything else or if it would no longer be necessary.

[smcv]

@rpigott:

Can I ask why XDG_DATA_HOME / XDG_DATA_DIRS was chosen for this config instead of XDG_CONFIG_HOME / XDG_CONFIG_DIRS? Isn't this a user configuration?

It's both. The original version in this PR only searched the configuration directories, and my followup #1082 added the data directories as a lower priority.

XDG_CONFIG_HOME / XDG_CONFIG_DIRS are read as the highest priority, so that user configuration overrides OS vendor or upstream defaults; but if there is no user or sysadmin configuration, the OS vendor or upstream project for the desktop environment needs to be able to provide reasonable defaults, and those should live in /usr.

This is exactly the same as mimeapps.list (and also Vulkan layers, and I expect that there are more specifications like this or will be soon). Some of the paths (like XDG_DATA_HOME) are only there for completeness and to be consistent with other specifications, and are not expected to be actually used or useful in practice.

[smcv]

@WhyNotHugo:

I'm not using a session governor, so I have to set this manually.

If you are building a desktop environment out of individual pieces, then yes, it's up to you to be your own system integrator, because there is nobody else in that scenario who can take responsibility for doing this for you.

With the new portals.conf in my $XDG_CONFIG_HOME, I'm wondering if I need to set $XDG_CURRENT_DESKTOP for anything else or if it would no longer be necessary.

XDG_CURRENT_DESKTOP is not a new invention, and is used by several other freedesktop.org specifications. The ones I know about are mimeapps.list (desktop-specific defaults for MIME and URI handlers, so that by default you'll get GNOME apps in a GNOME session and KDE apps in a Plasma session if both are installed) and the OnlyShowIn/NotShowIn keys in the desktop entry specification (so apps that are inappropriate for a particular desktop environment won't show there). I'm sure there are others.

Again, if you're building a desktop environment out of individual pieces, then it's up to you to carry out the system-integrator role.

[Sodivad]

xdg-utils are also using XDG_CURRENT_DESKTOP to choose a strategy to fulfill what you requested a tool to do. Note that for instance there are also applications that don't implement the mimeapps.list spec themselves but just do xdg-open $file

[smcv]

As a hint for system integrators who are assembling their own desktop environments, the usual way to set XDG_CURRENT_DESKTOP=Foo:Bar for your desktop session is to put DesktopNames=Foo;Bar; into /usr/share/xsessions/foo.desktop or /usr/share/wayland-sessions/foo.desktop, which will make many display managers (lightdm, gdm, sddm, probably others) set XDG_CURRENT_DESKTOP for the session.

Budgie (XDG_CURRENT_DESKTOP=Budgie:GNOME) is a good example of the non-trivial case where the desktop environment declares that it is a variant of something better-known, so that various specifications and components will use Budgie-specific behaviour if they know one, falling back to GNOME-specific behaviour or non-desktop-specific defaults otherwise.

[rpigott]

@WhyNotHugo See [1] for example, which filters desktop entries as intended by the spec. You should continue to set XDG_CURRENT_DESKTOP.

[1] https://codeberg.org/dnkl/fuzzel/pulls/235#issue-316968

[rpigott]

It's both. The original version in this PR only searched the configuration directories, and my followup #1082 added the data directories as a lower priority.

Ah, I didn't notice that the config dirs were checked. Thanks.

[WhyNotHugo]

Thanks for all the detailed replies! :)

It's both. The original version in this PR only searched the configuration directories, and my follow-up #1082 added the data directories as a lower priority.

XDG_CONFIG_HOME / XDG_CONFIG_DIRS are read as the highest priority, so that user configuration overrides OS vendor or upstream defaults; but if there is no user or sysadmin configuration, the OS vendor or upstream project for the desktop environment needs to be able to provide reasonable defaults, and those should live in /usr.

This makes perfect sense. It can be configured by the distribution, overridden by the system administrator and overridden by the end-user in a way that's pretty standard.

Should upstream compositors ship the configuration for their portals? Portals like xdg-desktop-portal-wlr are used by multiple compositors. Is the expectation that each compositor ships the corresponding portal file?

From what I can tell, for general purpose portals (e.g.: darkman, a dark mode / light mode daemon that exposes its value via the settings portal, or xdp-access-portal, a standalone org.freedesktop.impl.portal.Access implementation) there's no correct place to ship any configuration, and it is entirely the responsibility of the user to configure it.

However, given that only the first matching configuration file is used, the user would have to copy their existing one (e.g.: from /etc or /usr) and append any customisations into that (also making sure to keep their copy in sync in future).

Wouldn't it be best to read all configuration files, and each one overrides the previous one? So that users can append configurations easily?