Guidelines and HOWTOs/Flatpak: Difference between revisions

From KDE Community Wiki
(flatpak-install needs the repo name)
(→‎Applications: explain the two repos, explain software stores before terminal, give example of picking which repo, section mentioning binary-factory.kde.org)
(30 intermediate revisions by 12 users not shown)
Line 1: Line 1:
Flatpak is a solution for creating sandboxed software builds for GNU/Linux systems. You can find more information [http://flatpak.org/ here].
Flatpak is a solution for creating sandboxed software builds for GNU/Linux systems. You can find more information [http://flatpak.org/ here].


= KDE Runtime =
= Applications =
KDE Software approach to Flatpak is still not ready. Nevertheless, it's being shaped up. If you're interested in helping, please send an e-mail to [mailto:kde-devel@kde.org kde-devel@kde.org].
We are building release versions of most KDE applications and distributing them on flathub, https://flathub.org.
We are also building nightlies of most KDE applications and distributing them at https://distribute.kde.org. This has the master version of the applications, so expect some unstable development quirks; on the bright side, if you find one, you get to tell the developers so they can fix it!


The idea behind flatpak is that your applications will depend on a runtime. KDE provides a runtime with Qt and all KDE Frameworks 5 (except for the 4th tier) to make sure it's easily adaptable for any KDE Application and possibly most Qt-based applications as well.
The "app store" or software center in many distributions is able to install Flatpaks.
You can simply open the flatpakrepo files with Discover or your otherwise favorite software center:
* https://flathub.org/repo/flathub.flatpakrepo
* https://distribute.kde.org/kdeapps.flatpakrepo
and then when you search for a KDE application it should offer to install the flatpak version.
 
Here's how to install a Flatpak application from the terminal:
<syntaxhighlight lang="bash">
flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
flatpak remote-add --if-not-exists kdeapps --from https://distribute.kde.org/kdeapps.flatpakrepo
flatpak install kdeapps org.kde.okular
</syntaxhighlight>
 
If you added both the Flathub and kdeapps repos, the `flatpak` command-line tool will prompt you which one you want, something like:
<syntaxhighlight>
flatpak install skrooge
Looking for matches…
Remotes found with refs similar to ‘skrooge’:
 
1) ‘flathub’ (system)
2) ‘kdeapps’ (system)
 
Which do you want to use (0 to abort)? [0-2]: 2
Found ref ‘app/org.kde.skrooge/x86_64/master’ in remote ‘kdeapps’ (system).
Use this ref? [Y/n]: y
</syntaxhighlight>
 
== Build status ==
The Continuous Integration that triggers many of the nightly flatpak builds is at https://binary-factory.kde.org.. If a flatpak is not updated or has a problem, you may be able to look at build logs here and puzzle out why.
 
= Qt and KF5 Runtime =
We provide a runtime with Qt and all KDE Frameworks 5 (except for the 4th tier) to make sure it's easily adaptable for any KDE Application and possibly most Qt-based applications as well.


This runtime can be added by following these instructions:
This runtime can be added by following these instructions:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
wget http://distribute.kde.org/kdeflatpak.asc
flatpak install flathub org.kde.Platform//5.9
flatpak remote-add kde http://distribute.kde.org/flatpak-testing/ --gpg-import=kdeflatpak.asc
flatpak install flathub org.kde.Sdk//5.9
flatpak install kde org.kde.Platform
flatpak install kde org.kde.Sdk
</syntaxhighlight>
</syntaxhighlight>
{{ Warning | Do NOT use this in production, it's work in progress and it doesn't enable important safety features. It might also eat your pet or first-born .}}
 
{{ Note | All flatpak commands (such as <code>remote-add</code> and <code>install</code>) accept a <code>--user</code> option to install things at the user level, without being prompted for the sudo password every time. }}


= Compile your application =
= Compile your application =


Now you get to compile your favorite application. If you want to see how it's done, you can see some of the ones that have already been built. You can find it [https://quickgit.kde.org/?p=scratch%2Fapol%2Fxdgapp-nightly-apps.git&a=tree here].
Now you get to compile your favorite application. If you want to see how it's done, you can see some of the ones that have already been built. You can find it [https://cgit.kde.org/flatpak-kde-applications.git/tree/ here].


To compile an applications, you should create a json file similar to the ones in the previous link. Then you'd just need to trigger the build and get it into a repository. For testing, I recommend just creating a local one (to publish an rsync will be required).
To compile applications, you should create a json file similar to the ones in the previous link. Then you'd just need to trigger the build and get it into a repository. For testing, I recommend just creating a local one (to publish an rsync will be required).


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
mkdir app repo
mkdir app repo
flatpak-builder --ccache --require-changes --repo=repo --subject="Build of AWESOMEAPP `date`" app org.kde.AWESOMEAPP.json
flatpak-builder --ccache --repo=repo --subject="Build of AWESOMEAPP `date`" app org.kde.AWESOMEAPP.json
</syntaxhighlight>
</syntaxhighlight>


Line 37: Line 68:
= Contribute! =
= Contribute! =
In the following repositories you'll find the code in charge of packaging the runtime (Qt 5 and KF5) and then several (but not all, yet) KDE Applications.
In the following repositories you'll find the code in charge of packaging the runtime (Qt 5 and KF5) and then several (but not all, yet) KDE Applications.
* Runtime: https://quickgit.kde.org/?p=flatpak-kde-runtime.git
* Runtime: https://phabricator.kde.org/source/flatpak-kde-runtime/
* Applications: https://quickgit.kde.org/?p=flatpak-kde-applications.git
* Applications: https://phabricator.kde.org/source/flatpak-kde-applications/
* Our XDG portals: https://phabricator.kde.org/source/xdg-desktop-portal-kde/
 
= Flatpak portals =
Portals are high-level session bus APIs that provide selective access to resources to sandboxed applications. The implicit expectation of portals is that the user will always be involved in granting or rejecting a portal request, thus most portal APIs will lead to user interaction in the form of dialogs.
 
Since such dialogs must fit into the user experience of the desktop shell, the portal APIs are implemented by a generic frontend called [https://github.com/flatpak/xdg-desktop-portal xdg-desktop-portal] which calls out to desktop-specific implementations that provide the actual UI. The bus name through which the portal APIs are available is org.freedesktop.portal.Desktop, with the object path /org/freedesktop/portal/desktop implementing the various portal interfaces.
{{ Note | You can find more information about flatpak portals [https://github.com/flatpak/flatpak/wiki/Portals here]. }}
 
== KDE implementation of portals ==
KDE backend for flatpak portals is called [https://cgit.kde.org/xdg-desktop-portal-kde.git/ xdg-desktop-portal-kde] and is now part of Plasma releases (starting with Plasma 5.10). Currently it supports most of the portals. If you want to test KDE flatpak portals, you can use this [https://cgit.kde.org/xdg-portal-test-kde.git/ simple test app].
 
====Debugging portals====
To get some debug information, you first kill the running '''xdg-desktop-portal-kde''' instance. Then first start xdg-desktop-portal-kde with:
<syntaxhighlight lang="bash">
QT_LOGGING_RULES='xdg-desktop*.debug=true' /usr/lib/$(uname -m)-linux-gnu/libexec/xdg-desktop-portal-kde
</syntaxhighlight>
then in another terminal session restart '''xdg-desktop-portal''' with:
<syntaxhighlight lang="bash">
G_MESSAGES_DEBUG=all /usr/libexec/xdg-desktop-portal --verbose --replace
</syntaxhighlight>
You can use above mentioned testing application to test various portals. You should then see debug output from xdp-kde similar to:
<syntaxhighlight lang="bash">
xdg-desktop-portal-kde: Desktop portal registered successfuly
xdg-desktop-portal-kde-file-chooser: OpenFile called with parameters:
xdg-desktop-portal-kde-file-chooser:    handle:  "/org/freedesktop/portal/desktop/request/1_255/t"
xdg-desktop-portal-kde-file-chooser:    parent_window:  "x11:1"
xdg-desktop-portal-kde-file-chooser:    title:  "Flatpak test - open dialog"
xdg-desktop-portal-kde-file-chooser:    options:  QMap(("accept_label", QVariant(QString, "Open (portal)"))("filters", QVariant(QDBusArgument, ))("modal", QVariant(bool, true))("multiple", QVariant(bool, true)))
</syntaxhighlight>
You can see which portal has been called, whether it has been called or when you check output from '''xdg-desktop-portal''' then you should see message in case of portal error (usually related to DBus). You can also monitor dbus messages using '''dbus-monitor''', which indicates whether portals get involved at all as everything goes through DBus.
 
= Styles and integration with other desktops =
We are aware that not everyone is using KDE/Qt applications in Plasma desktop. For this flatpak comes with extensions, where you specify a directory (with themes, icons) where third-party is allowed to install additional stuff as an addition to what we have in our runtimes. At this moment we have added support for Gnome in form of adwaita icons and adwaita-qt style. All you need to is install following extensions using commands below:
<syntaxhighlight lang="bash">
flatpak install kdeapps org.freedesktop.Platform.Icontheme.Adwaita
flatpak install kdeapps org.kde.KStyle.Adwaita
flatpak install kdeapps org.kde.PlatformTheme.QGnomePlatform
</syntaxhighlight>

Revision as of 03:30, 30 April 2019

Flatpak is a solution for creating sandboxed software builds for GNU/Linux systems. You can find more information here.

Applications

We are building release versions of most KDE applications and distributing them on flathub, https://flathub.org. We are also building nightlies of most KDE applications and distributing them at https://distribute.kde.org. This has the master version of the applications, so expect some unstable development quirks; on the bright side, if you find one, you get to tell the developers so they can fix it!

The "app store" or software center in many distributions is able to install Flatpaks. You can simply open the flatpakrepo files with Discover or your otherwise favorite software center:

and then when you search for a KDE application it should offer to install the flatpak version.

Here's how to install a Flatpak application from the terminal:

flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
flatpak remote-add --if-not-exists kdeapps --from https://distribute.kde.org/kdeapps.flatpakrepo
flatpak install kdeapps org.kde.okular

If you added both the Flathub and kdeapps repos, the `flatpak` command-line tool will prompt you which one you want, something like:

flatpak install skrooge
Looking for matches…
Remotes found with refs similar to ‘skrooge’:
  
 1) ‘flathub’ (system)
 2) ‘kdeapps’ (system)
  
Which do you want to use (0 to abort)? [0-2]: 2
Found ref ‘app/org.kde.skrooge/x86_64/master’ in remote ‘kdeapps’ (system).
Use this ref? [Y/n]: y

Build status

The Continuous Integration that triggers many of the nightly flatpak builds is at https://binary-factory.kde.org.. If a flatpak is not updated or has a problem, you may be able to look at build logs here and puzzle out why.

Qt and KF5 Runtime

We provide a runtime with Qt and all KDE Frameworks 5 (except for the 4th tier) to make sure it's easily adaptable for any KDE Application and possibly most Qt-based applications as well.

This runtime can be added by following these instructions:

flatpak install flathub org.kde.Platform//5.9
flatpak install flathub org.kde.Sdk//5.9

Note

All flatpak commands (such as remote-add and install) accept a --user option to install things at the user level, without being prompted for the sudo password every time.


Compile your application

Now you get to compile your favorite application. If you want to see how it's done, you can see some of the ones that have already been built. You can find it here.

To compile applications, you should create a json file similar to the ones in the previous link. Then you'd just need to trigger the build and get it into a repository. For testing, I recommend just creating a local one (to publish an rsync will be required).

mkdir app repo
flatpak-builder --ccache --repo=repo --subject="Build of AWESOMEAPP `date`" app org.kde.AWESOMEAPP.json

This will do everything required and create a repository in ./repo. To test the application we add the repository (called remotes), we install the application and then we run it:

flatpak remote-add awesomeapp repo --no-gpg-verify
flatpak install awesomeapp org.kde.AWESOMEAPP
flatpak run org.kde.AWESOMEAPP

Now you will see that some things don't work and you'll have the privilege to start fixing things!

Contribute!

In the following repositories you'll find the code in charge of packaging the runtime (Qt 5 and KF5) and then several (but not all, yet) KDE Applications.

Flatpak portals

Portals are high-level session bus APIs that provide selective access to resources to sandboxed applications. The implicit expectation of portals is that the user will always be involved in granting or rejecting a portal request, thus most portal APIs will lead to user interaction in the form of dialogs.

Since such dialogs must fit into the user experience of the desktop shell, the portal APIs are implemented by a generic frontend called xdg-desktop-portal which calls out to desktop-specific implementations that provide the actual UI. The bus name through which the portal APIs are available is org.freedesktop.portal.Desktop, with the object path /org/freedesktop/portal/desktop implementing the various portal interfaces.

Note

You can find more information about flatpak portals here.


KDE implementation of portals

KDE backend for flatpak portals is called xdg-desktop-portal-kde and is now part of Plasma releases (starting with Plasma 5.10). Currently it supports most of the portals. If you want to test KDE flatpak portals, you can use this simple test app.

Debugging portals

To get some debug information, you first kill the running xdg-desktop-portal-kde instance. Then first start xdg-desktop-portal-kde with:

QT_LOGGING_RULES='xdg-desktop*.debug=true' /usr/lib/$(uname -m)-linux-gnu/libexec/xdg-desktop-portal-kde

then in another terminal session restart xdg-desktop-portal with:

G_MESSAGES_DEBUG=all /usr/libexec/xdg-desktop-portal --verbose --replace

You can use above mentioned testing application to test various portals. You should then see debug output from xdp-kde similar to:

xdg-desktop-portal-kde: Desktop portal registered successfuly
xdg-desktop-portal-kde-file-chooser: OpenFile called with parameters:
xdg-desktop-portal-kde-file-chooser:     handle:  "/org/freedesktop/portal/desktop/request/1_255/t"
xdg-desktop-portal-kde-file-chooser:     parent_window:  "x11:1"
xdg-desktop-portal-kde-file-chooser:     title:  "Flatpak test - open dialog"
xdg-desktop-portal-kde-file-chooser:     options:  QMap(("accept_label", QVariant(QString, "Open (portal)"))("filters", QVariant(QDBusArgument, ))("modal", QVariant(bool, true))("multiple", QVariant(bool, true)))

You can see which portal has been called, whether it has been called or when you check output from xdg-desktop-portal then you should see message in case of portal error (usually related to DBus). You can also monitor dbus messages using dbus-monitor, which indicates whether portals get involved at all as everything goes through DBus.

Styles and integration with other desktops

We are aware that not everyone is using KDE/Qt applications in Plasma desktop. For this flatpak comes with extensions, where you specify a directory (with themes, icons) where third-party is allowed to install additional stuff as an addition to what we have in our runtimes. At this moment we have added support for Gnome in form of adwaita icons and adwaita-qt style. All you need to is install following extensions using commands below:

flatpak install kdeapps org.freedesktop.Platform.Icontheme.Adwaita
flatpak install kdeapps org.kde.KStyle.Adwaita
flatpak install kdeapps org.kde.PlatformTheme.QGnomePlatform