Graphical Software Apps

Gnome Software (GS) and Plasma Discover (PD) are the default applications for installing other apps in Phosh and Plasma Mobile. These applications do not only allow to install, update and remove other apps, but also include a lot of information for each of the apps available. This information includes icons, screenshots, reviews, and other details. Unfortunately, for the apps to work properly with postmarketOS/alpine linux, some additional work is needed. This page is an attempt to describe all the components involved and give an overview over what is needed to make these apps functional and user-appealing.

Components
In order for these apps to function properly, all components need to be fully functional.

AppStream
AppStream "is a cross-distro effort for enhancing the metadata available about software components in the Linux and free-software ecosystem". Simplified, it works in the following fashion:


 * App developers create and include xml files which provide information about their apps (such as screenshots)
 * Software distributors aka. distros use AppStream Generator to put together all the AppStream data from all the apps and publish it in a public link (alpine, pmOS)
 * GS and PD download and use the public AppStream data to show the information to users inspecting apps.

apk-tools and wrappers
apk-tools is the Alpine Package Keeper and the component responsible for package management. In theory, the library built by apk-tools, libapk, could be directly used by GS and PD to manipulate apps. However, it is too low-level so two components exist to wrap it with different rationales:


 * apk-polkit-rs provides a DBus interface which simplifies common application operations. Currently used by Gnome Software. The main drive for its creation was to support user authentication and privilege granting to GNOME Software users, without executing any of the GNOME Software's code in privileged mode. Additionally, having a DBUS interface could in principle easily support more applications than just GNOME Software.
 * libapk-qt provides simplified C++/QT bindings for libapk. Currently used by Discover. When it was created, it also provided an entrypoint to libapk, which at the time could not be statically compiled.

APK backends
Once there exists an interface for APK, GS and PD need to know how to interact with the said interface. Both apps support a modular approach, so simply a new plugin/backend for APK is needed. For such a reason, there exits:


 * gnome-software-plugin-apk, which is an out-of-tree plugin for GS that uses apk-polkit-rs.
 * alexeymin/discover apk branch from which a patch to plasma-discover in aports repository, which uses libapk-qt.

AppStream
The AppStream data for alpine edge and pmOS master seems to work good enough. At least good enough for testing. However, there exist some issues


 * AppStream data for most apps seem to be of good quality. Errors and warnings are provided by the AppStream Generator for inspection. They can be found in alpine and postmarketOS, although unfortunately postmarketOS reporting seems broken.
 * AppStream data seems to have been latest generated in January 2021 in alpine and July 2021 in postmarketOS.
 * AppStream Generator backend for APK lives upstream. There aren't any tests which check for validity in that repository, so if the APKINDEX or .apk format changes, regressions are likely to happen.
 * AppStream data for stable releases is missing. In alpine, only v3.12 exits. Infra needs fixes at least here and here. In postmarketos only v20.06 is available and I could only find an issue referring to it. Is the backend config public?
 * Although the AppStream data seems properly generated, users of GNOME Software and Plasma Discovery experience that icons for non-installed apps and screenshots in general are often missing. These comes from how this metadata is handled by the distribution:
 * Icons: according to AppStream documentation: "In order to display icons in software-centers, distributors should offer a repository of cached icons for applications defined in their AppStream XML files. The icons should be PNG files or vectorgraphics (PNG is preferred) and match the name referenced in the applications .desktop file. Their size should be 64x64px, it is okay to just provide one size". Not in alpine, nor in pmOS are those icons downloaded by the distribution. Therefore, the icons go mostly missing. Manually downloading the icon tarballs and placing them in the right locations show icons.
 * Screenshots: Screenshots are currently referenced in the AppStream data to their original locations, e.g: this GNOME Software screenshot. In those locations, it is common that screenshots only have a single size, so if any other screenshot size is requested, it will be missing.

apk-tools and wrappers
The apk-tools is a very well maintained and alive project! The wrappers have been projects started by independent people that perform similar tasks. Neither of them has seen a 1.0 release.


 * apk-polkit-rs does it job pretty well in most cases, but there are some small fixes needed and some features and good documentation missing before 1.0.
 * libapk-qt has enough features to support discover plugin. Of course not every single libapk feature is implemented, but basics for package management work fine.

Apk backends

 * In GNOME Software the plugin interface is not stable and evolving constantly, so the APK plugin needs active maintenance and testing. Currently the plugin covers the basic functionality and update is in progress for GNOME 41.Planning for upcoming GNOME 42 has also started. Hopefully one day it will be upstreamable, but lots of work is still needed.
 * Plasma Discover backend interface is stable for long time ago, and for several Plasma releases already proved that it does not require changes to backend pugin code.

AppStream
Cogitri did an amazing work getting apk support merged in the generator upstream and building the alpine infrastructure. However, the issues with the data mentioned above should be fixed. A place for collecting those issues should be established, as otherwise it is very hard for new contributors to help. Additionally, adding support for newer releases should become part of branching for both alpine and pmOS. Otherwise the current situation where most stable releases are missing could easily happen again. As a failover, major fixes that have to be addressed are collected here:


 * Update configuration in pmOS and alpine to make AppStream data be generated again. Includes:
 * Fixing configuration in alpine (and maybe also in pmOS).
 * Improving generation container in alpine to be more general and include cleanups.
 * Set up some way to download icons to their right locations.
 * Fix configuration to create screenshots and reference them in the metadata.

apk-polkit-rs, libapk-qt and backends
Unfortunately, there is a huge amount of code duplication in between projects, both in the plugins/backends and in the wrappers. Possible solutions:


 * Discard everything done until now and try to merge APK support in PackageKit. Both GS and PD have support for it. However, it might be controversial, so it should be carefully thought. It might also not exactly fit alpine and pmOS ideals, as it is a root daemon running in the background.
 * Adapt one of the wrappers so it can be used by both GS and PD. With time, refine the plugins and get them merged upstream. Even in that case, maintenance from downstream might be needed. At least GS main maintainer has stated its reluctance to maintain yet-another-plugin (although they're positive towards merging them).

Contributing
Pick up any of the issues mentioned above and start hacking on them :D

Debugging GNOME Software and plugin
GNOME Sofware is usually started as a background application with which the graphical frontend communicates. Therefore, in order to debug it, the background job needs to be first killed. It can usually be done with. Then, start the application from a terminal with  to get all debugging output printed out.

The plugin is a shared library located in /usr/lib/gnome-software/plugins-API_VER/gs-plugin-apk.so in GNOME 40 and above. Since that version, the plugin is a dynamically linked library that must be in sync with the GNOME Software version in use. Therefore, whenever testing APK functionality, it must be verified that the apk plugin installed is linking against the correct Software library. These packages are usually upgraded together in alpine and postmarketos, so it shouldn't be an issue. Still, during testing this has to be verified.