Build Your First Project on KDE (and Why My First Attempt Failed)

How to get started with KDE development by building real projects

Building KDE projects from source was something I always wanted to try, but my first attempt turned out to be much harder than I expected. In this post, I share what went wrong, what I learned, and how I finally managed to build real KDE applications.

***Not a Medium member? Keep reading for free by clicking here.***

kde-builder

KDE is a desktop environment and software ecosystem that is widely used in Linux-based systems. It is especially popular for projects written with C++ and Qt, and many open-source applications are developed under the KDE umbrella.

At the very beginning, I tried to build a KDE project on Ubuntu 22.04, which I installed on macOS as a virtual machine. Since this setup was running on Apple Silicon, the architecture was ARM64. At the time, Ubuntu 22.04 was the available option compatible with ARM64, so I went with that.

If I had managed to build a KDE project successfully, this would have been my first time building an open-source project from source. I had no real experience with this kind of workflow, so I relied heavily on both AI tools and KDE documentation. Looking back, this was my first mistake. Asking AI questions is very tempting, once you start, you keep asking more and more. After a while, instead of helping, it actually started to mislead me, especially when I was trying to debug build errors.

There were a lot of issues related to dependencies and every attempt to fix one problem seemed to introduce another. At some point, I realized that my build environment had become completely dirty. One major reason I struggled so much (besides my lack of experience) was related to the Qt version. The system-provided Qt setup was not suitable for building KDE projects. Installing Qt6 via apt looked easy at first, but it turned out to be insufficient for building KDE projects. I eventually had to build Qt from source, and also some other required tools needed to be built from source. This quickly became frustrating. Errors kept piling up and dependencies started to conflict with each other.

That was the end of my first attempt…

After that, I decided to change the environment and I switched to another PC running Windows. I created a new development setup by installing Kubuntu 25.04 on Oracle VirtualBox.

kubuntu 25.04

Kubuntu is a Linux distribution that uses the KDE Plasma desktop environment instead of GNOME in Ubuntu. Since Kubuntu is officially recommended for KDE development, I thought it would be a much better choice.

Based on my previous experience, I chose a different approach this time and decided to stick only to KDE’s official documentation. According to the documentation, the first step is setting up a proper development environment, so I installed kde-builder. kde-builder is a KDE meta build tool that manages dependencies automatically, including KDE libraries and Qt toolkit.

Here are the steps I followed to build my first KDE project.

1- Add~/.local/bin to the PATH environment variable:

echo $PATH | grep ~/.local/bin
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

2- Run the following commands to install kde-builder and some necessary packages for it:

cd ~
curl 'https://invent.kde.org/sdk/kde-builder/-/raw/master/scripts/initial_setup.sh' > initial_setup.sh
bash initial_setup.sh

After this, I verified that kde-builder was installed correctly:

kde-builder --version

3- Generate configuration and install distro packages

At this point, still following the documentation, I ran these commands:

kde-builder --generate-config
kde-builder --install-distro-packages

4- Build the first KDE project: kcalc

To test the environment, I tried building kcalc:

kde-builder kcalc

kcalc is the default open source calculator application in KDE Plasma. If this project builds successfully, it usually means that the basic KDE development environment is set up correctly.

During the build process, I encountered an error related to Qt tools. At that moment, I honestly felt tired of seeing errors again, but this time I went back to the documentation.

If the Linux distribution does not provide a suitable Qt version, KDE recommends building Qt using kde-builder. So I modified the configuration file:

vi ~/.config/kde-builder.yaml

• First, I uncommented the following line in the default configuration file to allow kde-builder to build Qt:

qt-install-dir: ~/kde/qt

• Then I decided to build Qt 6.10 and added the following block near the end of the global section:

override:
  qt6-set:
    branch: "6.10"

It should be added before this line:

include ${build-configs-dir}/kde6.yaml

• After saving the configuration, I ran these commands to clear it:

rm -rf ~/kde/build/qt*
rm -rf ~/kde/src/qt*

• I reran following command to build kcalc:

kde-builder kcalc

kcalc successfully built using kde-builder.

This time, the build completed successfully. Finally, I was able to build my first KDE project :)

After building kcalc, I moved on to another KDE project: Okular. Since most of the required dependencies were already installed during the kcalc build, this step was much smoother. Only a few additional packages were missing, and I installed them manually:

sudo apt install discount libmarkdown2-dev libpoppler-qt6-dev libspectre-dev libdjvulibre-dev

After installing the missing packages, Okular built successfully with kde-builder. Compared to my first attempt, this felt surprisingly smooth.

Building a second KDE project made it clear that once the environment is set up correctly, things start to make sense. More importantly, it reminded me that struggling at the beginning is a normal part of learning, especially in open source development.

Okular successfully built using kde-builder.

In the end, building these first KDE projects was less about the tools and more about learning how to approach open source development. With the right setup and a bit of patience, things eventually fall into place.

I’m still learning my way around KDE development, so feel free to share any feedback or tips :)