Developer – Compiling with kde-builder

Docs: Set up a development environment

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

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 install git and uv.

Then run the following:

uv tool install git+https://invent.kde.org/sdk/kde-builder.git

This will install kde-builder, 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. 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

Install dependencies

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

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

First build – Hello, World!

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

Updating kde-builder

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

This can be done by running

uv tool upgrade kde-builder

Setting up Qt

Qt is the fundamental framework that is needed for all KDE development. A recent enough version of Qt6 is required to proceed.

Any of the recommended, sufficiently up-to-date Linux distributions listed in Building KDE software should have recent enough Qt6.

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 version of Qt, see the dedicated page Setting up Qt.

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

The Search field in System Settings.

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.

Docs: Building KDE software with kde-builder

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

In this section, you will learn how to use KDE's kde-builder tool to build KDE software once you have a development environment set up.

If you haven't set up kde-builder already, please follow the steps in Set up a development environment before proceeding.

It can take an hour or more to compile a KDE application, Framework, or Plasma itself for the first time. The reason for this is that kde-builder also builds all KDE dependencies of a project by default. The next time you want to compile that or any other piece of KDE software, it will be much faster since most of the dependencies will have already been compiled.

If you don't want to build all dependencies (for instance if you are using a rolling release distro that provides recent versions of software), you can:

edit the configuration file at ~/.config/kde-builder.yaml and set include-dependencies: false
or add the --no-include-dependencies flag when running kde-builder.

Building and running applications

To build KCalc for example, run:

kde-builder kcalc

You can replace kcalc with any other project. You can also build more than one project by listing them here. When you tell kde-builder to build a module, it will automatically download the sources using git, configure, build, and install them.

The project's source code is downloaded to a folder under ~/kde/src. The build files are stored under ~/kde/build, and installed to ~/kde/usr. If the build failed for any reason, please see our instructions on how to proceed with Troubleshooting.

To run the self-compiled KCalc, use the kde-builder --run command, which launches the built-from-source version of KCalc (from the directory ~/kde/usr) instead of the version installed using your package manager.

kde-builder --run kcalc

Did it run? If so, then congratulations, you just compiled your own version of KCalc from source code! 🎉

Building and Running Plasma

kde-builder has several aliases for building groups of modules that belong together. These include

workspace: All projects necessary to run a full Plasma Desktop session.
mobile: All projects required for running a Plasma Mobile session.

You can build these like you would a single project, for example with:

kde-builder workspace

After building the workspace alias, kde-builder will prompt you for password in order to install session files in your system. After this, you can start your self-built Plasma session by choosing it in SDDM before logging in.

You can also install these files manually by running a script that is provided by plasma-workspace:

~/kde/build/plasma-workspace/login-sessions/install-sessions.sh

About SELinux

SELinux can interfere with the new D-Bus services working correctly, and the path of least resistance may be to turn off enforcement if you are using a distro that ships with it on by default (like Fedora). To do this, set the value of SELINUX to permissive in the file /etc/selinux.

Alternatively, you can run the new instance of Plasma on top of your existing system for quick testing like so:

source ~/kde/build/plasma-workspace/prefix.sh
~/kde/usr/bin/plasmashell --replace

Plasma Mobile

You can run your custom-built Plasma Mobile in an emulated phone session using a phone-sized window within your existing desktop. To do this, we first set some environment variables that configure the session to behave like a phone and then start a nested KWin session with the mobile shell:

export XDG_RUNTIME_DIR=/tmp/
export QT_QPA_PLATFORM=wayland
export QT_QPA_PLATFORMTHEME=KDE
export QT_WAYLAND_DISABLE_WINDOWDECORATION=1
export XDG_CURRENT_DESKTOP=KDE
export KSCREEN_BACKEND=QScreen
export KDE_FULL_SESSION=1
export KDE_SESSION_VERSION=5
export QT_QUICK_CONTROLS_MOBILE=1
export PLASMA_PLATFORM=phone:handheld
export $(dbus-launch)
source ~/kde/build/plasma-mobile/prefix.sh
dbus-run-session kwin_wayland --width 360 --height 720 --xwayland "plasmashell -p org.kde.plasma.mobileshell"

Plasma Mobile can also be run on a mobile device itself. For more information, see the Plasma Mobile Development Guide.

Building custom projects

Sometimes you want to build your own project using kde-builder, or you'd like to build with a fork of an existing KDE project.

To do this, you can use kde-builder's project configuration option.

New projects

If your project is completely new (not present in the KDE repo-metadata), like in the case of the Kirigami or KXmlGui tutorials, you can create a project at the end of your ~/.config/kde-builder.yaml:

project kirigami-tutorial:
 no-src: true

Then you may use kde-builder to compile the dependencies needed for your project, and after that your project:

kde-builder kirigami ki18n kcoreaddons breeze kiconthemes qqc2-desktop-style
kde-builder kirigami-tutorial

Existing projects

You may want to work on an existing KDE project, for example, KCalc. KDE Builder can handle this case: you can build a project with your changes.

First, build the project as normal. This will download the latest source code of the project and its dependencies, and build them.

kde-builder kcalc

Go to the project directory and create a branch whose name starts with "work/". When kde-builder detects a work branch, it will not update the sources of the project.

cd ~/kde/src/kcalc
git branch work/username/cool_feature
git switch work/username/cool_feature

Make your changes in the source code.

After that, rebuild the project. This time, you can skip building dependencies, as they are already built.

kde-builder kcalc --no-include-dependencies

Next, you may want to push your changes to prepare a merge request. If you have a developer account, you can push your work branch to the original repo. If you do not have a KDE developer account, you can add your fork remote, and push changes to it. See wiki page for more information.

cd ~/kde/src/kcalc
git remote add fork git@invent.kde.org:username/kcalc.git
git push fork

To summarize, you have now seen how to:

compile standalone apps, frameworks, or other projects: kde-builder kcalc
compile Plasma Desktop: kde-builder workspace
compile Plasma Mobile: kde-builder mobile
run what you've built: kde-builder --run kcalc

Useful flags

The following sections will show some useful options for kde-builder. They're not required for normal operation, but can be useful in some situations. If you want, you can skip this part and get started with developing.

Check the list of things that will be built

To get a general idea of how many and which dependencies are going to be built for a certain project, you can use the --pretend or --dry-run flag:

kde-builder --pretend kcalc

Rebuild a project and stay on current branch

Code changes should be done in a separate git branch, not in the master branch.

By default, kde-builder will always attempt to go back to the master branch before rebuilding. To avoid this, you can use the --no-src flag:

kde-builder --no-src kcalc

Rebuild only a single project without updating the source code

As mentioned above, there are times when you want to rebuild the project in the current branch.

By default, kde-builder will rebuild a project and all its dependencies. To avoid this, you can use the --no-include-dependencies flag:

kde-builder --no-include-dependencies --no-src kcalc

Build a specific project while skipping certain modules

Sometimes a particular program somewhere down the dependency chain fails to build and isn't strictly required for a certain project to compile properly, or sometimes you want to use the program installed from your distribution.

In that case, you can avoid building a project by using the --ignore-projects flag, which should come after the module name:

kde-builder kcalc --ignore-projects gpgme

Specifying executable names when running

To run an application, use the flag --run.

kde-builder --run plasma-discover

Note that in Discover's case, the name of the project is discover, but the name of the executable is plasma-discover.

If a project provides more than one executable, you can specify the executable you want as long as you have built the module that provides it:

kde-builder kate
kde-builder --run kate-syntax-highlighter --list-themes

Alternatively, most applications can be run directly from their build directory.

Running an application after making changes to one of its dependencies

Let's say you want to make a change to the KConfig library that should change a behavior in KCalc. In this case, you don't want kde-builder to discard your changes to KConfig. So first build KConfig separately, on its own, without doing a source code update:

kde-builder kconfig --no-src --no-include-dependencies --refresh-build

This will build just KConfig and install the needed build products into ~/kde/usr. Now we want to run KCalc in such a way that it makes use of those changed files. Do it like so:

kde-builder kcalc --no-src --no-include-dependencies --refresh-build
kde-builder --run kcalc

Next Steps

What now?

Perhaps you went through this whole procedure and still have no idea what to work on:

In this case, choose what to work on.

Or perhaps you'd like to further adapt kde-builder to your needs by setting up your preferred IDE. If that's what you need, have a look at IDE Configuration.

If you already know what you want to work on and you are in fact already working on it, then it might be time to learn how to make a merge request and send your changes. See Submit your new software changes for review for more information.

Docs: Setting up Qt

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

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

Use containers
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:

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

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. See Finding the latest Qt version.

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

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"

See Finding the latest Qt version to get the correct version number.

Then run:

kde-builder qt6-set

This will take a long time.

Docs: Basic troubleshooting

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

The project has failed to build

Did one or more modules fail to build (displayed in red font) using kde-builder? This page should tell you the most likely causes and how to fix them.

Remember that you can contact the development team to get assistance with kde-builder.

Missing dependencies

The most likely reason is that you are missing the dependencies necessary for the failing module. Once kde-builder finishes its build and fails, it will display the path to the module's CMake log files (for example: ~/kde/src/log/latest/kwallet/error.log).

You should take a look at the log files to see if anything is missing: you can read more about how to understand the errors you get from CMake in Install the dependencies. That page will also tell you how to search for dependencies in your distribution.

When you have the necessary dependencies, you can save time and resume from the failing module with the --resume-from flag:

kde-builder [module you want to build] --resume-from [the module that failed]

Old cache

Sometimes a project has suffered big enough changes to its code that its cache starts to affect subsequent builds.

To clear the cache, you can use the --refresh-build flag:

kde-builder [failing module] --refresh-build --no-include-dependencies

Broken master branch

It is rare, but if the master branch of a project contains faulty code, it will not compile with kde-builder.

To check, look at the Invent, KDE's Gitlab instance where all code is stored. If the project has a GitLab build pipeline and the pipeline is broken, then it's not your fault.

Where to see if the pipeline is working.

The project has failed to run

Did the project build successfully, but it does not run as intended? Here are a few reasons why.

Changes to the installed files

Sometimes some changes to a project's code (or one of its dependency libraries) lead to its installed files to be renamed or moved. When that happens, the old files might still linger in ~/kde/usr.

There are multiple ways to address this:

You can just always run kde-builder with the --use-clean-install flag. This will call the uninstall target of CMake that KDE projects using extra-cmake-modules have, uninstalling previously installed files before installing new ones. This will decrease the speed of installing files built with kde-builder.
You can nuke your current installed files with rm -rf ~/kde/usr and then rerun kde-builder.
You can start with a new and clean kde-builder installation. This can be done by creating a new user and installing kde-builder from scratch. Another possibility is to rename your existing development setup with mv ~/kde ~/kde~bak and then rerun kde-builder.

Common problems in stable distributions

Distributions that are not sufficiently up-to-date may encounter unavoidable problems that will need to be addressed to .

Sometimes lack a required library for building a specific project, and if you have followed our Qt setup with the online installer, you might have noticed that the default recommended installation is lean by default, which means you might be missing some Qt library.

Cannot build Python bindings / missing stddef.h

To build the Python bindings for KDE Frameworks, the following packages are required:

python3-build
python3-shiboken6 and respective development package
python3-pyside6 and respective development package
clang

The names may vary according to the distribution.

If you get an error similar to this:

(kcoreaddons) Clang: 1 diagnostic messages:
/usr/include/c++/14/cstddef:50:10: fatal: 'stddef.h' file not found

This means you need to install clang.

If you encounter other errors referencing shiboken or pyside, you might be missing some of the other packages.

Note that by default you won't encounter this issue on most major distributions if you have allowed kde-builder to install the necessary distro packages with either kde-builder --initial-setup or kde-builder --install-distro-packages.

Alternatively, you may disable building the Python bindings altogether by adding the following to the global cmake-options section of your ~/.config/kde-builder.yaml:

cmake-options: >
 -DBUILD_WITH_PYTHON_BINDINGS=OFF

Qt online installer: missing libraries

We opt to recommend a leaner installation of Qt with the online installer in our Qt setup, but sometimes this might mean you will end up missing a major optional Qt library such as QtWebengine, QtTextToSpeech, or QtVirtualKeyboard.

To install the missing libraries, open the "Qt Maintenance Tool" entry in your menu and select the optional library that you need that matches the Qt version you have installed.

Alternatively, many projects offer to disable specific features that require optional libraries. To do this, first attempt to compile them once with kde-builder. Afterwards, run ccmake in its respective build directory:

ccmake ~/kde/build/ktextwidgets

You will see that in the KTextWidgets case there is a setting to disable building WITH_TEXT_TO_SPEECH, which bypasses the need for you to have QtTextToSpeech installed on your system.

You can then override KTextWidgets to disable this option by adding the following to the end of your ~/.config/kde-builder.yaml file:

override ktextwidgets:
 cmake-options: >
 -DWITH_TEXT_TO_SPEECH=OFF

Missing non-KDE library that is not managed by kde-builder

By default kde-builder does build third-party libraries that are required by bleeding edge KDE applications or libraries, such as gpgme, poppler and wayland-protocols. You can list them with kde-builder --dry-run workspace | grep third.

Sometimes a KDE application might require a third-party library that is not managed by kde-builder and is not available on your distribution. For such cases, the only solution is to build that library manually with kde-builder. This makes sure that the library will be accessible by applications compiled and run with kde-builder, as it will be installed in ~/kde/usr like the rest of the compiled projects.

To achieve this, you may add a project to your ~/.config/kde-builder.yaml, similarly to Building custom projects:

project outside-project:
 repository: git@invent.kde.org:youruser/outside-project.git

Thus allowing you to run:

kde-builder outside-project

Docs: Tips and tricks

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

Opening logs directly from Konsole / Yakuake

Konsole and Yakuake, two terminal applications by KDE, have the ability to open files by clicking directly on their path on the screen.

For example, if you build Kirigami using kde-builder and you happen to face an error like this:

<<< PACKAGES FAILED TO BUILD >>>
kirigami - /home/youruser/kde/src/log/2024-03-17-01/kirigami/build.log

Clicking on the file path text will open the log file with your preferred text editor.

To enable this functionality in Konsole or Yakuake:

Right click the terminal -> Edit Current Profile... -> Mouse -> Miscellaneous -> enable Underline Files.

Colorizing build logs correctly in Kate

By default, when you open a .log file in Kate, its syntax will be highlighted as "Log File (simplified)". The mode "Log File (advanced)" applies full syntax highlighting which makes it easier to read log files.

There are two ways to change from simplified to advanced mode:

Through the menu: Tools | Highlighting | Other | Log File (advanced)
Through the syntax highlighting button at the bottom right of Kate (where it says "Log File (simplified)")

To avoid applying this manually each time you open log file, change the priority of the Filetype:

In the main menu, go to Settings | Configure Kate. In the Configure Kate window choose Open/Save | Modes & Filetypes. In the Filetype dropdown list:

select Other/Log File (advanced) and set its Priority to "-10"
select Other/Log File (simplified) and set its Priority to "-11"

Apply changes and close the window.

Viewing colored build logs

The log files include escape symbols (that are used to color the text, or format it as bold for example). To view it properly, you will need to open the log with a suitable tool.

There are two main possibilities for this:

Opening the log files with your preferred text editor.

Any editor that does syntax highlighting for .log files will do. KDE provides Kate / KWrite, which has both "Log File (simple)" and "Log File (advanced)" highlighting options selectable from the bottom right of the window.

Sublime Text has the ANSI color plugin.

This method also works with the above tip Open logs directly with Konsole / Yakuake.

Opening the log files with a terminal application.

You can view log files with a terminal application like cat or bat.

Preventing accidental src/ folder deletion

When you want to start the whole build from scratch, by deleting your ~/kde/build and ~/kde/usr, you may accidentally delete your ~/kde/src. To protect yourself from that, you can set the immutable flag to that directory:

sudo chattr +i ~/kde/src

Now you have write permissions to the folder, but you cannot delete it.

Faster compile times

It is possible to change various CMake options globally in kde-builder so that projects will build faster, which is convenient especially for building KDE software on weaker machines. By setting these options globally, if you ever need them enabled for a specific project, you can then use kde-builder config overrides.

⚠️ Tread with caution

Disabling certain CMake options, while providing build speed improvements, can make major changes to your build, most notably CMAKE_BUILD_TYPE and BUILD_TESTING. You should be aware of these customizations and mention them whenever you request for assistance from other developers.

These options can be set in the global section of your ~/.config/kde-builder.yaml, under cmake-options, for example:

cmake-options: -DOPTION=OFF -DANOTHER_OPTION=value2

Or with multiline:

cmake-options: >
 -DOPTION=OFF
 -DANOTHER_OPTION=value

Then, at the end of the file, you can set overrides for each individual option that go against the global cmake-options values:

override kirigami:
 cmake-options: -DOPTION=ON

If it is a custom project (not a KDE project), you can use project instead:

project kirigami-tutorial:
 cmake-options: -DOPTION=ON

Faster iterative compiling with Debug mode

By default, kde-builder compiles projects in RelWithDebInfo mode, that is, Release with Debug Info.

You might want to set it to Debug mode which is optimal for iterative compilation:

cmake-options: >
 -DCMAKE_BUILD_TYPE=Debug

Building without tests

All KDE projects that use extra-cmake-modules have tests set to build by default together with the main project. This ensures that developers catch bugs easily and quickly, but it also takes significant time when building dozens of modules.

cmake-options: >
 -DBUILD_TESTING=OFF

Building without docs

KDE projects can make use of multiple ways of generating documentation: Qt Help projects (.qhp) and compressed Qt Help files (.qch), Doxygen HTML or manpages, Sphinx, and recently QDoc. The first two can be globally disabled, although the speed improvements are not as significant as the build type or tests.

cmake-options: >
 -DBUILD_QTHELP_DOCS=OFF
 -DBUILD_QCH=OFF
 -DBUILD_HTML_DOCS=OFF
 -DBUILD_MAN_DOCS=OFF

Building with a different linker

On Linux, the default linker used for C and C++ is LD (using the GNU BFD library) which is single threaded.

You can take advantage of the multithreaded nature of LLVM's LLD linker to speed compile times significantly:

cmake-options: >
 -DCMAKE_LINKER_TYPE=LLD

Building with ccache or sccache

Compiler cache, or ccache, can be used to increase build speed only when recompiling projects.

Running it your first time building KDE projects will not make any difference whatsoever, and even subsequent runs will only see some improvement. Where ccache excels at is when switching between different branches, stashes, rebases or bisects and recompiling repeatedly, that is to say, when you are developing a patch.

⚠️ Tread with caution

There are certain caveats that you must be aware when using ccache, most notably that you can have compilation failures caused specifically by ccache, and that lookup in large caches can actually make compilation slower. See Ccache caveats on the Arch wiki.

While you will still likely perceive some improvement by setting this globally, you might prefer to override each individual project you are likely to work on instead to minimize these issues.

Before reporting compilation issues, disable this option for the project you are working on.

To use ccache you will first need to install it.

cmake-options: >
 -DCMAKE_C_COMPILER_LAUNCHER=ccache
 -DCMAKE_CXX_COMPILER_LAUNCHER=ccache

If you prefer, you may also want to experiment with sccache, a newer alternative to accomplish the same job:

cmake-options: >
 -DCMAKE_C_COMPILER_LAUNCHER=sccache
 -DCMAKE_CXX_COMPILER_LAUNCHER=sccache

Building without PO processing

By default, KDE projects will always include translations during compilation. This is ordinarily not a problem, but KDE infrastructure uses an automated script to update translations via commits. It might not be desirable to always recompile a project whenever a new translation gets added or changed.

Whether to process new translations can be disabled globally in the configuration file:

cmake-options: >
 -DKF_SKIP_PO_PROCESSING=ON

Enabling the QML language server

Up until Qt 6.10, the QML language server qmlls only works if you write or generate a .qmlls.ini file in the source of your project.

It is possible to generate it for all projects built with kde-builder with a CMake option:

cmake-options: >
 -DQT_QML_GENERATE_QMLLS_INI=ON

It will be located in the same directory where a qt_add_qml_module() or ecm_add_qml_module() call is made.

After Qt 6.10, .qmlls.ini is no longer necessary and you only need the qmlls language server to be running. You may still configure its behavior with the INI file.