Docs: Building KDE software with distrobox and podman

Mon, 01 Jan 0001 00:00:00 +0000

If you use a really old Linux distribution that does not have the base system dependencies needed for kde-builder like an older long term support distribution such as RHEL, or use an immutable distribution like openSUSE Kalpa, Fedora Kinoite or the SteamOS on the Steam Deck, you will not be able to build KDE software directly with kde-builder or manually with CMake.

Instead, you can build KDE software inside a container. Distrobox eases the container development workflow by letting you run commands inside the container while still able to see your home directory by default.

Additionally, distrobox has the ability to run graphical applications from within the container.

You will be able to run kde-builder inside a container just fine, with the caveat that you won’t be able to run a Plasma Desktop session from the login screen.

You can also build KDE software by running CMake commands inside the container just like you would outside the container.

Setting up distrobox

If your Linux distribution is not immutable, install distrobox and podman from your distribution repositories:

Debian/Ubuntu: sudo apt install distrobox podman
openSUSE: sudo zypper install distrobox podman
Fedora: sudo dnf install distrobox podman
Arch: sudo pacman --sync distrobox podman

On immutable distributions like openSUSE Kalpa, Fedora Kinoite, and SteamOS on the Steam Deck) you should already have both podman and distrobox available by default.

If you experience any problems, need a more up-to-date version, or your chosen distribution lacks distrobox, you can use an official alternative method to install distrobox:

curl -s https://raw.githubusercontent.com/89luca89/distrobox/main/install | sh -s -- --prefix ~/.local

On the Steam Deck, you will additionally need to add ~/.local/bin to the $PATH in your .bashrc (or equivalent in your preferred shell):

export PATH=$PATH:~/.local/bin

And add the following to a new file ~/.config/distrobox/distrobox.conf. It will allow to run graphical applications directly from the distrobox:

xhost +si:localuser:$USER

Building KDE software with distrobox + kde-builder

Since kde-builder allows to build the most bleeding edge KDE software and its dependencies, all you need to build is a sufficiently up-to-date distribution. In this case it is sufficient to use standard openSUSE Tumbleweed, Fedora, or Arch Linux containers.

After having installed distrobox, run only one of the following commands to create a new distrobox image:

openSUSE Tumbleweed: distrobox create --image docker.io/opensuse/tumbleweed --name opensuse
Fedora: distrobox create --image docker.io/fedora --name fedora
Arch Linux: distrobox create --image docker.io/archlinux --name arch

Distrobox will tell podman to pull the images from Dockerhub, create an appropriate container, and name it as specified in the command.

After it is finished, run the following:

distrobox enter <containername>

Distrobox will take some time to configure the container the first time, and then you will automatically enter the container.

Inside the container you will now have access to development packages like git, CMake, KDE frameworks libraries and other such things.

Follow the tutorial for setting up kde-builder and the experience should be the same as if you were following the kde-builder tutorial in a non-immutable Linux distribution.

Whenever you want to get back to developing with kde-builder inside the container, remember to use the above distrobox enter <containername> command to enter the container before building or running the application.

From this point on, the kde-builder tutorial should be followed instead.

Note that the container size will stay relatively tiny, but kde-builder will require as much disk space as necessary to build the software you specify and all its dependencies.

About the Arch container image

By default, Distrobox uses host-exec in the Arch Linux image to allow to run flatpak applications on the host while inside the container by creating a symlink to flatpak in /usr/bin/flatpak in the container.

This causes kde-builder to fail to install the Arch flatpak binary during initial setup.

To work around this issue, first delete /usr/bin/flatpak in the container, then run kde-builder --install-distro-packages.

Building KDE software with distrobox + manual compilation

In certain cases you may find kde-builder to be overkill for what you want to do, for example if you just intend on working on a specific desktop application. You might otherwise be restricted by storage space and cannot afford to compile dozens of projects just to build the one project you want.

While containers also require a significant amount of storage, they often require much less than kde-builder.

For non-bleeding edge software

You can use sufficiently up-to-date containers like openSUSE Tumbleweed, Fedora, or Arch Linux to develop KDE software, as long as the software does not have bleeding edge dependencies.

After having installed distrobox, run only one of the following commands to create a new distrobox image:

openSUSE Tumbleweed: distrobox create --image docker.io/opensuse/tumbleweed --name opensuse
Fedora: distrobox create --image docker.io/fedora --name fedora
Arch Linux: distrobox create --image docker.io/archlinux --name arch

Distrobox will tell podman to pull the images from Dockerhub, create an appropriate container, and name it as specified in the command.

After it is finished, run the following:

distrobox enter <containername>

Then you can proceed to start building KDE software using our guide on building KDE software manually with CMake.

For bleeding edge software

Some KDE software, such as Itinerary or Neochat, has very rapid development and will require bleeding edge dependencies, in which case the above distribution containers will not suffice. To avoid having to compile and manage dependencies yourself, you can use containers that already come with KDE libraries built from the latest master branch.

There are two main ones:

KDE neon Unstable, which already comes ready to use
openSUSE Krypton, which needs to be manually added to an existing openSUSE Tumbleweed container

KDE neon Unstable is more straightforward to use since there is an official container built for it already.

openSUSE Krypton has a simple unofficial image maintained by a contributor, but no official image from upstream.

For KDE neon Unstable, run the following:

distrobox create --image invent-registry.kde.org/neon/docker-images/plasma:unstable
distrobox enter plasma-unstable

For openSUSE Krypton, run the following:

distrobox create --image codeberg.org/herzenschein/tumbleweed-krypton:latest --name krypton
distrobox enter krypton

You can then start building KDE software using our guide on building KDE software manually with CMake.

Note that the plasma-unstable image size is 5.6 GiB and the krypton image is 3 GiB and they can grow over time, so plan your disk space accordingly.

If you'd like to build your own openSUSE Krypton image, you can either use the manifest for the above image or manually configure an existing Tumbleweed image:

distrobox create --image docker.io/opensuse/tumbleweed --name krypton
distrobox enter krypton

After that, follow openSUSE’s instructions on adding builds from git master on Tumbleweed, using sudo:

sudo zypper addrepo --refresh --priority 75 https://download.opensuse.org/repositories/KDE:/Unstable:/Qt/openSUSE_Tumbleweed/ KDE:Unstable:Qt
sudo zypper addrepo --refresh --priority 75 https://download.opensuse.org/repositories/KDE:/Unstable:/Frameworks/openSUSE_Factory/ KDE:Unstable:Frameworks
sudo zypper addrepo --refresh --priority 75 https://download.opensuse.org/repositories/KDE:/Unstable:/Applications/KDE_Unstable_Frameworks_openSUSE_Factory/ KDE:Unstable:Applications
sudo zypper addrepo --refresh --priority 75 https://download.opensuse.org/repositories/KDE:/Unstable:/Extra/KDE_Unstable_Frameworks_openSUSE_Factory/ KDE:Unstable:Extra
sudo zypper --verbose dist-upgrade --allow-vendor-change

The prepended sudo is necessary to make sure the packages get installed in the container. The instructions above are the same as the openSUSE ones, but with long flags to make the command clearer.

After the distribution upgrade inside the container, Tumbleweed will have turned into Krypton.

If the distribution upgrade process asks you too many questions to resolve, you can press Ctrl + C to cancel it and repeat the last command with an added --force-resolution:

sudo zypper --verbose dist-upgrade --allow-vendor-change --force-resolution

You can now finally start building KDE software using our guide on building KDE software manually with CMake.

Limitations of using containers

Containers are typically designed to be lean, not to provide a full desktop experience. As such, they usually do not come with software that would otherwise come preinstalled in typical desktop systems, and so you will often need to search manually for the missing software.

For that, we have a tutorial on installing missing build dependencies.

In addition to this, there are a few pieces of software with very common use cases that can be missing from containers by default:

qqc2-desktop-style, for QtQuick/Kirigami applications to use the correct Breeze theme
breeze and breeze-icons, for theme support
the QtWayland development library, for applications inside the container to run as native Wayland windows

Another limitation is the inability to run a full Plasma session built with kde-builder from inside containers. While this is theoretically possible, it has not been tested or documented and it is unlikely to be supported.