Set up a development environment

Installing and configuring kde-builder

Source code for KDE software lives on KDE Invent. Before you can work on it, you'll need to set up a development environment: a set of tools that allows you to access and edit the source code, compile it into a form that the computer can run, and deploy it to a safe location. To accomplish this, you will need to enter commands using a terminal program.

If you're not familiar with the command line interface, you can find tutorials here. However, advanced command line skills are not required, and you will learn what you need along the way.

If you're a visual learner, we also provide useful video tutorials.

The tool we will be using here for setting up a development environment and building KDE software is kde-builder. It will let you set up your development environment and compile applications on Linux and FreeBSD. You can find out more about it in its repository and the README.

💡 Keep in mind

You only need to set up your environment once, and then you will be able to compile (and recompile) KDE software as often as needed later on.

Why kde-builder?

kde-builder is the official KDE meta build system tool. It is used to manage the building of many software repositories in an automated fashion.

Its primary purpose is to manage dependencies. Every software has dependencies: other pieces of software that provide lower-level functionality they rely on. In order to compile any piece of software, its dependencies must be available.

KDE software has two types of dependencies:

dependencies on other pieces of KDE software
dependencies on 3rd-party software

For example, the KDE application KCalc depends on more than 20 other KDE libraries as well as the Qt toolkit.

Some Linux distributions do not provide development packages for KDE Frameworks and of other libraries that are up-to-date enough for us to build from the master branch of the KDE git repositories (the branch where the development of the next software versions takes place), so we use kde-builder to compile them ourselves. The goal is to avoid using KDE binaries, KDE libraries and other KDE files from the operating system where possible.

Set up kde-builder

Before setting things up, you will need to make sure you have some free disk space. kde-builder itself is a very lightweight tool, but downloading the source code of lots of software, generating build artifacts during compilation, and installing the necessary files takes space.

If you plan on building an application or on following our Kirigami tutorial, you should allocate at least 15 GB of storage space.

If you plan on building Plasma Desktop, you should allocate at least 50 GB of storage space.

If you cannot afford this storage, you might want to consider building projects manually or with distrobox.

Then run the following:

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

kde-builder will install git, a few runtime packages, and will install its executable in your PATH so you can run it from the terminal, as in the next step.

Dependening on your distribution, you may need to add ~/.local/bin to the PATH environment variable. The kde-builder installer will tell you if this is required.

After the initial setup, you will need to generate a configuration file for kde-builder. Run:

kde-builder --generate-config

This will create a new file ~/.config/kde-builder.yaml. See the documentation for a list of available options.

Debian/Ubuntu-based distributions

Some distributions need source repositories enabled before you can install the development packages you need. Do that now, if needed:

Click here to see how to enable source repos

If the file /etc/apt/sources.list exists

Open the file /etc/apt/sources.list with a text editor such as Kate or nano. Each line that starts with deb should be followed by a similar line beginning with deb-src , for example:

deb http://us.archive.ubuntu.com/ubuntu/ noble main restricted
deb-src http://us.archive.ubuntu.com/ubuntu/ noble main restricted

Note: The URL might differ depending on your country, and instead of noble the name of the Debian or Ubuntu version should appear instead, for example bookworm or jammy.

If the deb-src line is commented out with a #, remove the # character.

Lastly, run:

sudo apt update

If the file /etc/apt/sources.list does not exist

Starting with Kubuntu 24.04, the configuration file for apt repositories has moved to /etc/apt/sources.list.d/ubuntu.sources.

Open the file /etc/apt/sources.list.d/ubuntu.sources with an editor like Kate or nano. Change the contents of the file by replacing all occurrences of Types: deb with Types: deb deb-src. For example, replacing the following:

Types: deb
URIs: http://archive.ubuntu.com/ubuntu
Suites: noble noble-updates noble-backports
Components: main universe restricted multiverse
Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg

With:

Types: deb deb-src
URIs: http://archive.ubuntu.com/ubuntu
Suites: noble noble-updates noble-backports
Components: main universe restricted multiverse
Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg

Note: The URL might differ depending on your country, and instead of noble the name of the Debian or Ubuntu version should appear instead, for example bookworm or jammy.

Lastly, run:

sudo apt update

During initial setup, kde-builder installed the essentials to run the tool itself. To install the distribution packages required to actually build KDE software, run:

kde-builder --install-distro-packages

Finally, perform your first build:

kde-builder kcalc

This will build KCalc, a calculator app, and its KDE dependencies. If you happen to find any build issues, don't fret! That means kde-builder is working.

In the next section, Building KDE software with kde-builder, we have a more in-depth look into the build process. To solve any build issues, you can check out Installing build dependencies.

kde-builder is now set up for building! 🎉

💡 A chance to contribute

If you discover any external dependencies needed to build KDE software that were not installed with kde-builder --install-distro-packages, for example using our guide on Installing Build Dependencies, please send a merge request to the repo-metadata/distro-dependencies repository to include the needed packages in the list.

Updating kde-builder

You should occasionally update kde-builder to get its latest changes.

This can be done by running

kde-builder --self-update

If this does not work, your version of kde-builder does not support updating itself yet. In this case, you can update it by running

cd ~
bash initial_setup.sh

Setting up Qt

Qt is the fundamental framework that is needed for all KDE development. A recent enough version of Qt 6 (currently version 6.7 or later) is required to proceed.

The initial setup of kde-builder should have installed the required Qt6 packages for you already, in which case you don't need to do anything and may skip directly to the Configure git section.

If your Linux distribution does not provide a recent enough versoin of Qt, you have the following options:

Use Craft or containers, as mentioned in Building KDE software
Install Qt6 using the Qt online installer
Install Qt6 using the unofficial aqtinstall installer
Build Qt6 using kde-builder
Switch to a more up-to-date distro

Use Qt6 from the online installer

Instead of letting kde-builder build Qt for you, you may want to use Qt's official installer.

First, create an account on Qt's website. Then, download the installer from the Qt for Open Source Development page.

Run the downloaded file, log in with your Qt account, and follow the wizard. During the installation, choose the option Custom installation, and:

Uncheck Qt Design Studio
Uncheck Qt Creator
Make sure the Desktop item for the latest version of Qt is selected

This will install only the essential Qt libraries in ~/Qt by default, occupying a little less than 2 GB of storage.

Once installed, open ~/.config/kde-builder.yaml, uncomment the line with qt-install-dir: ~/kde/qt, and change it to point to your Qt installation. The actual path should be similar to this, depending on your Qt version:

qt-install-dir: ~/Qt/6.9.0/gcc_64

Once this is done, kde-builder will know to use the Qt provided by the online installer to build KDE software.

If you ever need to install more Qt components, you can do so using the Qt Maintenance Tool that was added by the installer.

Use Qt6 from aqtinstall

⚠️ Experimental

This method was not fully tested yet.

If you do not want to create a Qt account to use Qt's official installer and do not want to build Qt yourself, you can try using the unofficial installer aqtinstall which downloads Qt from the same sources as the official installer.

First, install aqtinstall:

pipx install aqtinstall

If you don't have pipx installed, you can install it from your distribution.

You can then install Qt using:

aqt install-qt linux desktop 6.9 linux_gcc_64 --outputdir ~/Qt --modules all

replacing 6.9 with the latest Qt version number.

This will install all Qt modules available in the latest version and will occupy a bit more than 8 GB of storage.

Once installed, open the file ~/.config/kde-builder.yaml, uncomment the line with qt-install-dir: ~/kde/qt, and change it to point to your Qt installation. The actual path should be similar to this, depending on your Qt version:

qt-install-dir: ~/Qt/6.9.0/gcc_64

Once this is done, kde-builder will know to use the Qt provided by the online installer to build KDE software.

Build Qt6 using kde-builder

⚠️ Work in Progress

This method is undergoing testing to make sure it works on most systems.

It is possible to build Qt with kde-builder, but it requires a minimum of 30 GB of storage and has a long compilation time, up to a few hours depending on your machine.

To do this, open the file ~/.config/kde-builder.yaml and uncomment the line containing:

qt-install-dir: ~/kde/qt

Near the end of the file, add an override so you build Qt from the latest release instead of the development branch (the default):

override qt6-set:
  branch: "6.9"

Then run:

kde-builder qt6-set

This will take a long time.

Configure git

To properly track who created a commit, your name and email must be configured in git. If this is not done correctly, invent.kde.org might reject your changes when you push them. To configure name and email, run:

git config --global user.name "Your Name"
git config --global user.email "you@email.com"

The name given here must be a human name, not the username of your KDE account or similar. The email should be the same as configured in GitLab and for your account on bugs.kde.org, if you have one. This is required for some integrations to work correctly.

You should take the chance to create a KDE Identity account that you can use to access KDE's Gitlab instance where all KDE code resides, Invent. Take a look at Infrastructure: Gitlab to learn more about this.

For convenience, you can enable a feature that will become useful when starting to push code to GitLab:

git config --global push.autoSetupRemote true

Next, in order to authenticate yourself when pushing code changes, you need to add an SSH key to your Invent profile as described in the Invent SSH documentation. Once you are done, we can start using kde-builder.

Disable indexing for your development environment

You'll want to disable indexing for your development-related git repos and the files they will build and install.

To do that, add the ~/kde directory to the exclusions list in System Settings › Search › File Search > Stop Indexing a Folder...

Next Steps

Your development environment is now set up and ready to build software.

You installed kde-builder.
You generated a configuration file for it.
You installed the necessary packages to start building KDE software.
You have set it up to use Qt (optional).
You have set up git so you can start working on code.

The next section explains how to use kde-builder to build software from source code.

Installing build dependencies

Building KDE software with kde-builder