Set up a development environment

Installing and configuring kde-builder

⚠️ kdesrc-build is no longer supported

Click to see more information

kdesrc-build, the tool that was used previously for this tutorial, is no longer supported.

While the tool is stable and still works for our veteran developers, if you are starting out with KDE development now, we recommend that you switch to kde-builder. Once you run it for the first time after installation, it will ask whether you want to migrate your existing kdesrc-buildrc configuration file to the new kde-builder.yaml file.

Any support questions related to this tutorial can be asked on the KDE New Contributors group on Matrix.

Source code for KDE software lives on KDE Invent. But 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 these tasks, you will need to enter commands using a terminal program, such as KDE's Konsole.

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. Repo README with basic usage

💡 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 "main" 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 (in the Linux case, these files reside in the /usr directory).

Set up kde-builder

About ~/.local/bin

If you've done this before and want the brief step-by-step instructions, have a look at the README.

Let's set it up now! You will need many gigabytes of free disk space. Budget 50 GB of storage space for KDE Frameworks + KDE Plasma, and 10-30 GB more for some apps as well. 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.

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. Documentation is available that lists all possible options and example values.

About ~/.local/bin

Click here if you experience problems with finding `kde-builder` in your PATH

Some Linux distributions might not follow the Freedesktop Base Directory Specification that enforces that the ~/.local/bin directory be added to the $PATH, which is required for an executable to show up in the terminal without its absolute path.

To check if ~/.local/bin is in the $PATH, run: echo $PATH.

If the directory is not listed, then you will need to add it yourself. You can do so by adding the following to your ~/.bashrc (or equivalent in your preferred shell):

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

Closing and reopening your terminal window once should be enough for kde-builder to appear for the next steps.

Don't forget to warn your distribution to follow the specification.

⚠️ Read this if you use a Debian/Ubuntu-based distro

Some distros 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

KDE neon/Debian/Ubuntu/Kubuntu/etc:

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, like 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, like bookworm or jammy.

Lastly, run:

sudo apt update

While during initial setup, kde-builder installed the essentials for itself to run, now it will need to install the required distribution packages to build KDE software. To do that, run:

kde-builder --install-distro-packages

Next, you'll want to test that things are set up correctly. Run this to verify kcalc is able to be built:

kde-builder --pretend kcalc

Finally, perform your first build.

kde-builder dolphin

This will build Dolphin, the Plasma file manager and its KDE-based dependencies. We choose Dolphin since it is a good test case to exercise the whole build process.

Now kde-builder is set up! 🎉 These common command line flags may come in handy.

💡 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 then please send a merge request to the repo-metadata/distro-dependencies repository to include the needed packages in the list.

⏳ With kdesrc-build...

Click here to know how this was done with kdesrc-build

This step used to be done by cloning the repository into a folder, linking the script, and running the script:

kdesrc-build --initial-setup

For details, see: Install kdesrc-build

Updating kde-builder

Once in a while you will want to update kde-builder to get its latest changes. To do so, run the initial_setup.sh file that was created when installing kde-builder:

cd ~
bash initial_setup.sh

⏳ With kdesrc-build...

Click here to know how this was done with kdesrc-build

This step used to be done by going to the directory where kdesrc-build was cloned and pulling the new changes:

cd ~/.local/share/kdesrc-build
git pull

Set up Qt

Qt is the fundamental framework that is needed for pretty much all KDE development. A recent enough version of Qt 6, currently Qt version greater or equal to 6.7, 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 recent versions of Qt packages, you have four options:

Use one of the alternative build methods 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

Finding the latest Qt version

To find out the latest release of Qt, you can visit KDE's Qt repository mirror and check for the right branch:

A screenshot of the main page of the Qt repository mirror showing the branch list that appears once you click on the combobox that has 'dev' written on it.

Use Qt6 from the online installer

Instead of letting kde-builder build Qt for you, you may want to use the online installer that comes directly from Qt. To download Qt you will need to make an account.

First, go to the QtGroup website and create an account.

After creating your new Qt account, go to Qt for Open Source Development, click on "Download the Qt Online Installer", and follow the download process.

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

Uncheck "Qt Design Studio"
Uncheck "Qt Creator"
Click on the collapsible for the latest version of Qt or double-click it
Check "Desktop"

This will install only the essential Qt libraries in ~/Qt by default, occupying a little less than 2 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.8.0/gcc_64

Once it 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 open the newly installed Qt Maintenance Tool available on the menu launcher.

Use Qt6 from aqtinstall

⚠️ Experimental

This method was not fully battle tested yet.

If you are bothered by the fact that the Qt online installer requires a Qt account or if you don't want to undergo the process of building Qt6 with kde-builder, you may try using the unofficial installer aqtinstall which simply downloads Qt from the same sources as the official installer.

First, install aqtinstall:

pipx install --user aqtinstall

If you don't have pipx installed, you may need to install it from your distribution.

You can then install Qt with aqt. You will need to find the latest Qt release first.

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

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

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

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

Build Qt6 using kde-builder

⚠️ WIP

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

It is possible to build Qt with kde-builder, but it will require a minimum of 30 GB of storage and have a long compilation time that may last up until 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.8

Then run:

kde-builder qt6-set

It will take quite a while to finish compiling.

Configure git

The first thing we will need to do after having set up kde-builder is to configure git.

Set your authorship information properly so that any changes you make to code can be properly attributed to you:

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

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.

About username and email

The user.name you provide should be your actual name, not your KDE Identity username or a pseudonym.

The email address must be the same as the email address used for your KDE Bugzilla account, if you have one. If they don't match, then the BUG: and FEATURE: keywords won't work (see Special Keywords in Git for more information).

For convenience, we can enable a feature that will later become useful when we start pushing code to a repository branch:

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 docs. 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.

To recapitulate the essentials:

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.

Time to learn how to use kde-builder to build software from source code!

Installing build dependencies

Building KDE software with kde-builder