diff --git a/README.md b/README.md index c532f74d3..64697767a 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -![Portals](doc/website/assets/readme.png) +[![Portals](doc/website/assets/readme.png)](https://flatpak.github.io/xdg-desktop-portal/) -# XDG Desktop Portal +# [XDG Desktop Portal](https://flatpak.github.io/xdg-desktop-portal/) A portal frontend service for [Flatpak](http://www.flatpak.org) and other desktop containment frameworks. @@ -12,143 +12,8 @@ path (`/org/freedesktop/portal/desktop`). The portal interfaces include APIs for file access, opening URIs, printing and others. -Documentation for the available D-Bus interfaces can be found +Documentation about the Common Conventions, as well as documentation for +App Developers, Desktop Developers and Contributors can be found [here](https://flatpak.github.io/xdg-desktop-portal/docs/). -## Version Numbering -xdg-desktop-portal uses even minor version numbers for stable versions, and odd -minor version numbers for unstable versions. During an unstable version cycle, -portal APIs can make backward incompatible changes, meaning that applications -should only depend on APIs defined in stable xdg-desktop-portal versions in -production. - -## Building xdg-desktop-portal - -xdg-desktop-portal depends on GLib and Flatpak. -To build the documentation, you will need xmlto and the docbook stylesheets. -For more instructions, please read [the contribution guidelines](https://flatpak.github.io/xdg-desktop-portal/docs/for-contributors.html). - -## Using Portals - -Flatpak grants sandboxed applications _talk_ access to names in the -org.freedesktop.portal.\* prefix. One possible way to use the portal APIs -is thus just to make D-Bus calls. For many of the portals, toolkits (e.g. -GTK) are expected to support portals transparently if you use suitable -high-level APIs. - -To implement most portals, xdg-desktop-portal relies on a backend -that provides implementations of the org.freedesktop.impl.portal.\* interfaces. - -Here are some examples of available backends: - -- GTK [xdg-desktop-portal-gtk](http://github.com/flatpak/xdg-desktop-portal-gtk) -- GNOME [xdg-desktop-portal-gnome](https://gitlab.gnome.org/GNOME/xdg-desktop-portal-gnome/) -- KDE [xdg-desktop-portal-kde](https://invent.kde.org/plasma/xdg-desktop-portal-kde) -- LXQt [xdg-desktop-portal-lxqt](https://github.com/lxqt/xdg-desktop-portal-lxqt) -- Pantheon (elementary OS) [xdg-desktop-portal-pantheon](https://github.com/elementary/portals) -- wlroots [xdg-desktop-portal-wlr](https://github.com/emersion/xdg-desktop-portal-wlr) -- Deepin [xdg-desktop-portal-dde](https://github.com/linuxdeepin/xdg-desktop-portal-dde) -- Xapp (Cinnamon, MATE, Xfce) [xdg-desktop-portal-xapp](https://github.com/linuxmint/xdg-desktop-portal-xapp) - -## Design Considerations - -There are several reasons for the frontend/backend separation of the portal -code: - -- We want to have _native_ portal dialogs that match the session desktop (i.e. - GTK dialogs for GNOME, Qt dialogs for KDE) -- One of the limitations of the D-Bus proxying in flatpak is that allowing a - sandboxed app to talk to a name implicitly also allows it to talk to any other - name owned by the same unique name. Therefore, sandbox-facing D-Bus APIs - should generally be hosted on a dedicated bus connection. For portals, the - frontend takes care of this for us. -- The frontend can handle all the interaction with _portal infrastructure_, such - as the permission store and the document store, freeing the backends to focus - on just providing a user interface. -- The frontend can also handle argument validation, and be strict about only - letting valid requests through to the backend. - -The portal apis are all following the pattern of an initial method call, whose -response returns an object handle for an _org.freedesktop.portal.Request_ object -that represents the portal interaction. The end of the interaction is done via a -_Response_ signal that gets emitted on that object. This pattern was chosen over -a simple method call with return, since portal APIs are expected to show dialogs -and interact with the user, which may well take longer than the maximum method -call timeout of D-Bus. Another advantage is that the caller can cancel an -ongoing interaction by calling the _Cancel_ method on the request object. - -One consideration for deciding the shape of portal APIs is that we want them to -'hide' behind existing library APIs where possible, to make it as easy as -possible to have apps use them _transparently_. For example, the OpenFile portal -is working well as a backend for the GtkFileChooserNative API. - -When it comes to files, we need to be careful to not let portal APIs subvert the -limited filesystem view that apps have in their sandbox. Therefore, files should -only be passed into portal APIs in one of two forms: - -- As a document ID referring to a file that has been exported in the document - portal -- As an open fd. The portal can work its way back to a file path from the fd, - and passing an fd proves that the app inside the sandbox has access to the - file to open it. - -When it comes to processes, passing PIDs around is not useful in a sandboxed -world where apps are likely in their own PID namespace. And passing PIDs from -inside the sandbox is problematic, since the app can just lie. - -## System Integration - -### D-Bus Activation Environment - -xdg-desktop-portal and its portal backends are activatable D-Bus services. -This means that they inherit environment variables from the -"activation environment" maintained by either `systemd --user` -(on systems that use systemd) or `dbus-daemon` (on systems that do not). -They do not inherit environment variables from the GUI environment or -from the shell, unless some component of the overall system takes -responsibility for taking the necessary environment variables from the -GUI environment and sending them to `systemd` or `dbus-daemon` to be -added to the activation environment. - -In integrated desktop environments such as GNOME and KDE Plasma, and in -OS distributions with a high level of integration, this should be done -automatically by desktop environment or OS infrastructure. - -Variables that might need to be propagated in this way include, but are -not limited to: - -- `DISPLAY` -- `PATH` -- `WAYLAND_DISPLAY` -- `XAUTHORITY` -- `XDG_CURRENT_DESKTOP` -- `XDG_DATA_DIRS` - -In environments that are assembled out of individual components by -the user, it is the user's responsibility to ensure that this system -integration has been done, for example by using -[dbus-update-activation-environment(1)][dbus-update-activation-environment] -or [`systemctl --user import-environment VAR…`][systemctl]. - -### Desktop Environment Requirements - -The display manager or GUI environment is responsible for setting -`XDG_CURRENT_DESKTOP` to an appropriate value. - -The GUI environment should provide a -[portal configuration file][portals.conf] with a name based on its -`XDG_CURRENT_DESKTOP`, to select appropriate portal backends. - -The GUI environment should arrange for its required portal backend or -backends to be installed as dependencies (possibly as optional -dependencies, if it is packaged in a loosely-coupled operating system). - -In environments that are assembled out of individual components by -the user, it is the user's responsibility to ensure that this system -integration has been done. - -[contributing]: https://github.com/flatpak/xdg-desktop-portal/blob/main/CONTRIBUTING.md -[dbus-update-activation-environment]: https://dbus.freedesktop.org/doc/dbus-update-activation-environment.1.html -[portals.conf]: https://flatpak.github.io/xdg-desktop-portal/docs/portals.conf.html -[systemctl]: https://www.freedesktop.org/software/systemd/man/latest/systemctl.html