Get Involved/development/More
This page is the continuation with more advanced topics of the page Get_Involved/development.
kdesrc-build Qt5
kdesrc-build by default uses Qt6. Your kdesrc-build installation is configured for Qt6 if in the configuration file kdesrc-buildrc
you have branch-group kf6-qt6
.
You can convert your kdesrc-build installation from Qt6 to Qt5 by editing the existing kdesrc-buildrc file to replace all occurrences of "6" with "5".
Set up kdesrc-build following the "Set up kdesrc-build" procedure. The resulting kdesrc-build installation will be of type kf6-qt6. In kdesrc-buildrc in the "global" section you will have "branch-group kf6-qt6".
Edit the file ~/.config/kdesrc-buildrc
- Replace all "6" with "5".
Example:
# Make sure that you do not already have a kdesrc-build
# installation that uses the configuration file
# ~/.config/kdesrc-buildrc
# Make a backup:
mv ~/.config/kdesrc-buildrc ~/.config/kdesrc-buildrc~bak 2> /dev/null
mv ~/kde5 ~/kde5~bak 2> /dev/null
mkdir -p ~/kde5/src
cd ~/kde5/src
git clone https://invent.kde.org/sdk/kdesrc-build.git && cd kdesrc-build
./kdesrc-build --initial-setup <<< 'N'
mv ~/.config/kdesrc-buildrc .
# Edit the file ~/kde5/src/kdesrc-build/kdesrc-buildrc:
# A. Replace "/home/username/kde5/src/kdesrc-build/" with "".
sed -i 's_/home/.*/src/kdesrc-build/__g' kdesrc-buildrc
# B. Replace "~/kde/" with "~/kde5/".
sed -i 's_~/kde/_~/kde5/_g' kdesrc-buildrc
# C. Replace "num-cores 4" with the count of your CPU threads (nproc) minus two. E.g. if you have 16 CPU threads, use "num-cores 14".
# D. If you plan to use the C++ debugger, replace "-DCMAKE_BUILD_TYPE=RelWithDebInfo" with "-DCMAKE_BUILD_TYPE=Debug".
# E. Replace "6" with "5".
sed -i 's/6/5/g' kdesrc-buildrc
# Make sure that the configuration file
# ~/kde5/src/kdesrc-build/kdesrc-buildrc looks OK
# E.g. kate ~/kde5/src/kdesrc-build/kdesrc-buildrc &
# From now on you will need to be in the directory
# ~/kde5/src/kdesrc-build before you can run kdesrc-build or kdesrc-run
# E.g.
cd ~/kde5/src/kdesrc-build
./kdesrc-build kconfig
./kdesrc-build kcalc
./kdesrc-run kcalc
./kdesrc-build frameworks
kde-builder
kde-builder is a drop in replacement of kdesrc-build. kdesrc-build is written in Perl. kde-builder is written in Python.
mkdir -p ~/Development cd ~/Development git clone https://invent.kde.org/ashark/kde-builder.git cd kde-builder python3 -m venv .venv # I use bash. source .venv/bin/activate pip install pipenv pipenv install ./kde-builder --initial-setup <<< 'N' mv ~/.config/kdesrc-buildrc . sed -i 's_~/kde/_~/Development/_g' kdesrc-buildrc # Edit the file ./kdesrc-buildrc as needed. kate kdesrc-buildrc & # meld kdesrc-buildrc ~/kde/src/kdesrc-build/kdesrc-buildrc # kde-builder is installed. # Use ./kde-builder instead of ./kdesrc-build. The command lines are the same. # Use ./kde-builder-launch instead of ./kdesrc-run. The command lines are the same. ./kde-builder kconfig ./kde-builder kcalc ./kde-builder-launch kcalc ./kde-builder frameworks
Develop in a Linux container
When you start programming for KDE, it is recommended that you use kdesrc-build in your main operating system or in a virtual machine running on a rolling-release Linux distribution (Arch, openSUSE Tumbleweed, KDE neon) or running on e.g. the latest version of Fedora KDE Spin or Kubuntu.
As an alternative, you can run kdesrc-build in a Linux container (docker, podman, toolbx, distrobox).
Option 1. The KDE PIM Docker image
You can install Docker and the KDE PIM Docker image. It provides a development environment that is isolated from your day-to-day system. It is based on KDE Neon Unstable.
Option 2. distrobox
It is possible to start developing KDE software using container images that are able to see inside your home folder. This can be done using distrobox and podman.
First, 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
Building without kdesrc-build
You can build a single repository using the KDE Neon Unstable docker image. We will be using the plasma:unstable
image, which comes with the latest KDE software and libraries, and we will be using the minimal version, which requires you to install development libraries before compiling your projects.
After installing distrobox and podman, run the following to create a new distrobox container:
podman pull invent-registry.kde.org/neon/docker-images/plasma:unstable distrobox create --image invent-registry.kde.org/neon/docker-images/plasma:unstable
This will create a distrobox container named plasma-unstable.
Lastly, enter the generated container:
distrobox enter plasma-unstable
You can then just clone the desired repository in your home folder and build it while being inside the container. If any development libraries are missing, you can just install them the same way you would install on Debian/Ubuntu/KDE Neon:
sudo apt install packagename-dev
You can also use build-dep
to let apt install the required libraries for the program you will be compiling. For example, to install the development libraries for Kate, you can run:
sudo apt-get build-dep kate
Building with kdesrc-build
First, install distrobox and podman from your distribution repositories. Then run:
distrobox enter
This should create a container based on your current Linux OS and enter it. It is preferable to use one of the Linux distributions that is better suited for kdesrc-build, as mentioned in this wiki page, so if your distribution does not provide very up-to-date packages, you can download and use a different container image for your distrobox from Dockerhub. For example, with openSUSE Tumbleweed:
podman pull opensuse/tumbleweed distrobox create --image opensuse/tumbleweed --name tumbleweed distrobox enter tumbleweed
Then it's a matter of downloading and running kdesrc-build as detailed in Get_Involved/development/Set_up_a_development_environment:
mkdir -p ~/kde/src
cd ~/kde/src
git clone https://invent.kde.org/sdk/kdesrc-build.git
cd kdesrc-build
./kdesrc-build --initial-setup
source ~/.bashrc
From this point on, one important thing to bear in mind is that a distrobox container is transparent in its user space and containerized in its root space: when you are inside a distrobox container, you can see the content of system's home folder, but not your system's root folders, only the container's root folders. This means that you can install packages inside the container using root privileges and access those packages to compile your programs stored in your home, without ever installing those packages in your actual system!
You can take advantage of this by installing, for instance, Qt development packages used for kdesrc-build from inside the container. This way, it is not necessary to compile Qt with kdesrc-build. This is particularly convenient if you want to compile KDE software with Qt6 quickly.
Likewise, you should install the required dependencies from inside the distrobox rather than from your system's repositories. Then you can start compiling as usual.
After compiling your program with kdesrc-build from inside the distrobox, you can run it with kdesrc-build run
, and despite it originating from inside a container and using the libraries from the container, it will run just fine as a GUI application on your system!
The only few gotchas to using this method are:
- You cannot use a full Plasma Desktop session made from git.
- You will need qqc2-desktop-style and Breeze to show the correct theme for your applications.
- You will need the QtWayland library and its respective development package to run your applications natively on a Wayland session.
Other operating systems
Kubuntu 23.10
The default configuration of kdesrc-build requires Qt version 6.6. Kubuntu 23.10 has Qt version 6.4.2. It is recommended that you build Qt in Kubuntu or use a Linux OS that is better supported by kdesrc-build.
FreeBSD
Install the latest release of FreeBSD with KDE Plasma Desktop on your hardware computer or in a virtual machine.
Your user should be member of the "wheel" user group (e.g. this can be configured in the FreeBSD installer, when creating your user you can select additional user groups for your user). Your user should be able to use sudo:
pkg install sudo visudo # Uncomment the line: %wheel ALL=(ALL:ALL) ALL
Then set up kdesrc-build using the same procedure as when installing kdesrc-build on a Linux operating system. FreeBSD is currently supported by kdesrc-build. See https://www.youtube.com/watch?v=8MqBnb3Y9JU
Microsoft Windows
You can build and develop KDE projects using the Microsoft Windows operating system.
Apple macOS
You can build and develop KDE projects using the Apple macOS operating system.
What to do if CMake configure fails because a build dependency is missing
See https://community.kde.org/Get_Involved/development/Install_the_dependencies .
Advanced kdesrc-build
After you have edited a git repository and you want to build it, --no-src
will make sure that kdesrc-build
does not overwrite your local source code changes with the latest source code from the official git repository (remote "origin" / https://invent/kde.org).
--no-include-dependencies
only builds the git repository that you give as parameter to kdesrc-build
.
--debug
shows verbose output.
--refresh-build
forces a rebuild (not an incremental build) and a full reinstall.
E.g. you have edited kcalc. You run:
kdesrc-build kcalc --no-src --no-include-dependencies --refresh-build --debug |& tee ~/a.txt
For details, see:
kdesrc-build --help
Note: the resources below might not be up to date.
See the kdesrc-build manual, Readme #1, Readme #2, Document #3 for more kdesrc-build information and options.
Qt 6 installed using Qt online installer
The homepage of the Qt Framework is https://www.qt.io . Go to this web page, create an online account. https://www.qt.io/download-open-source > "Download the Qt Online Installer" > Linux > "Qt Online Installer for Linux (64-bit)" > download a file named e.g. "qt-unified-linux-x64-4.6.1-online.run" into the directory e.g. "~/Downloads".
ls -la ~/Downloads # The downloaded file needs to have the "executable" chmod bit set. chmod +x ~/Downloads/qt-unified-linux-x64-4.6.1-online.run ~/Downloads/qt-unified-linux-x64-4.6.1-online.run
Login using your Qt online account. Next > check the checkbox "I have read and agree to the terms and conditions of using OpenSource Qt", check the checkbox "I'm an individual and do not use Qt for any company" > Next > Next > enable "Help us improve" > Next > "Custom installation", notice that the install directory is "~/Qt" > Next. Install the latest version of Qt6 and the latest version of the Qt Creator integrated development environment (IDE). There are some Qt6 components that are not used by KDE and can be left out when installing Qt6 e.g. WebAssembly, Android, Sources, "Qt Quick 3D", "Qt 3D", "Quick: 3D Physics", "Qt debug Information Files".
In the KDE Plasma app launcher you now have the application "Qt Maintenance Tool".
Set up kdesrc-build from scratch as usual.
Edit the file kdesrc-buildrc to look like:
global ... qt-install-dir ~/Qt/6.6.0/gcc_64 # Where Qt6 is installed libname lib ... end global ...
Make gpgme build:
sudo su mkdir -p /home/qt/work chown -R username:username /home/qt/work ln -s /home/username/Qt/6.6.0/gcc_64 /home/qt/work/install ls -la /home/qt/work
kf6-qt6 vs. kf5-qt5
Many KDE git repositories can build correctly and run correctly using "kdesrc-build kf6-qt6".
The KDE git repositories that can build correctly and run correctly using "kdesrc-build kf6-qt6" have two long lived git branches:
- A long lived git branch that does not contain the deprecated symbols from kf5-qt5, named e.g. "master".
- And another long lived git branch for qt5-kf5, where the deprecated symbols still exist.
What is "kf6-qt6"? You just set up kdesrc-build following the procedure. The resulting kdesrc-build installation will be of type kf6-qt6. In kdesrc-buildrc in the "global" section you will have "branch-group kf6-qt6". The git repositories that have only one long lived git branch e.g. named "master" will use that. The git repositories that have a second long lived git branch, will use the git branch where the deprecated symbols do not exist e.g. named "master".
What is "kf5-qt5"? Follow the chapter "kdesrc-build Qt5". The resulting kdesrc-build installation will be of type kf5-qt5. In kdesrc-buildrc in the "global" section you will have "branch-group kf5-qt5". The git repositories that have only one long lived git branch e.g. named "master" will use that. The git repositories that have a second long lived git branch where the deprecated symbols still exist e.g. named "kf5" will use that.
Build Qt6 using kdesrc-build
If you cannot build the KDE frameworks using kdesrc-build
and the Qt6 provided by your Linux distribution is outdated, you might want to build Qt6 using kdesrc-build
.
In your configuration file use the qt-install-dir
option (in the global section) with non-empty value, for example:
global qt-install-dir ~/kde6/usr_qt end global
Then build it:
kdesrc-build qt6-set
To compile Qt6 with Qt X11 Extras (which is a necessary library to compile KWindowSystem), you should enable XCB feature during compilation
kdesrc-build qt6-set --cmake-options="-DQT_FEATURE_xcb=ON"
After that, you can build other modules.
Portable installation of kdesrc-build
The current directory (pwd
) is important when running kdesrc-build. If there exists a file kdesrc-buildrc
in the the current directory (pwd
), kdesrc-build will prefer that file over ~/.config/kdesrc-buildrc
.
If you are interested in or need separate builds of KDE software, like when building with Qt5 or Qt6, you can create a self-contained, portable installation of kdesrc-build in its own folder. This way, you can manage your kdesrc-build configuration files each in their own environment without mixing configurations or having to rebuild the universe every time you want to test a different one.
# To not lose your previous build, make a backup:
mv ~/.config/kdesrc-buildrc ~/.config/kdesrc-buildrc~bak && mv ~/kde ~/kde~bak
# Edit ~/.bashrc file and remove the kdesrc-build block.
# Set up kdesrc-build by following just the chapter https://community.kde.org/Get_Involved/development/Set_up_a_development_environment
# Make sure to answer "No" (or press the Enter key) when it asks if
# you want to add the kdesrc-build block to ~/.bashrc.
# Do not source ~/.bashrc.
# Edit ~/.bashrc file and remove the kdesrc-build block.
# Reboot the computer or relogin such that the $PATH environment variable
# does not contain the string "~/kde" or sub directories of "~/kde".
# You should not have built anything using kdesrc-build yet.
# Then move the generated kdesrc-buildrc to the directory where
# you git cloned kdesrc-build:
cd ~/kde/src/kdesrc-build
mv ~/.config/kdesrc-buildrc .
# If the current directory is ~/kde/src/kdesrc-build, kdesrc-build will use
# the file ~/kde/src/kdesrc-build/kdesrc-buildrc even if the file
# ~/.config/kdesrc-buildrc exists.
# Edit the file paths in the file ~/kde/src/kdesrc-build/kdesrc-buildrc by
# replacing the string "/home/username/kde/src/kdesrc-build/"
# with the empty string.
# Before running kdesrc-build or kdesrc-run, always make sure that
# you are in the directory ~/kde/src/kdesrc-build
cd ~/kde/src/kdesrc-build
# Calling ~/kde/src/kdesrc-build/kdesrc-build will then use the file
# kdesrc-buildrc from the current directory:
./kdesrc-build kconfig
Whenever you move or copy this portable installation of kdesrc-build to another directory, do the following:
# E.g. copy the existing portable kdesrc-build installation # from the directory ~/kde to the directory ~/kdenew cp -r ~/kde ~/kdenew # Or to any other directory. # Edit the file paths in the file ~/kdenew/src/kdesrc-build/kdesrc-buildrc # E.g. replace "~/kde/" with "~/kdenew/". # Cleanup. Binary files contain file full paths starting with "~/kde" rm -rf ~/kdenew/usr rm -rf ~/kdenew/build cd ~/kdenew/src/kdesrc-build ./kdesrc-build frameworks
Two independent kdesrc-build installations on the same machine: kf6-qt6 and kf5-qt5
Make a backup of your existing kdesrc-build setup.
mv ~/.config/kdesrc-buildrc ~/.config/kdesrc-buildrc~bak && mv ~/kde ~/kde~bak
Set up a portable kdesrc-build from scratch in the directory ~/kde
. See the chapter #Portable installation of kdesrc-build for details. But do not run kdesrc-build to build anything.
In the directory ~/kde
there will be a new kdesrc-build installation of type kf6-qt6
.
At the end of this procedure there will be two independent and portable kdesrc-build installations:
- In the directory
~/kde
a kdesrc-build installation for Qt6 - In the directory
~/kde5
a kdesrc-build installation for Qt5
# You have a kdesrc-build kf6-qt6 installation in ~/kde
# kf5-qt5 kdesrc-build installation.
cp -r ~/kde ~/kde5
# Edit the file ~/kde5/src/kdesrc-build/kdesrc-buildrc such that the kdesrc-build installation becomes one of type kf5-qt5, see chapter "kdesrc-build Qt5".
# Edit the file paths in the file ~/kde5/src/kdesrc-build/kdesrc-buildrc
# E.g. replace "~/kde/" with "~/kde5/".
# Now you have a kdesrc-build kf5-qt5 installation in ~/kde5
Usage:
# Use different terminal windows or tabs (e.g. different Konsole tabs) for
# kf5-qt5 and kf6-qt6
# Go to the terminal window or tab for kf6-qt6.
cd ~/kde/src/kdesrc-build
./kdesrc-build kcalc
./kdesrc-run kcalc
# Go to the terminal window or tab for kf5-qt5.
cd ~/kde5/src/kdesrc-build
./kdesrc-build plasma-systemmonitor
./kdesrc-run plasma-systemmonitor
What is the command line of the processes started by kdesrc-build
E.g. what are the command lines that are run by kdesrc-build in order to run the CMake configure step for the kconfig KDE git repository?
kdesrc-build kconfig --no-src --no-include-dependencies --debug --refresh-build |& tee ~/a.txt
kate ~/a.txt &
Returns:
Building kconfig (build system KDE CMake) from frameworks (1/1)
Queueing PKG_CONFIG_PATH to be set to /home/username/kde/usr/lib/pkgconfig
Queueing LD_LIBRARY_PATH to be set to /home/username/kde/usr/lib
Queueing PATH to be set to /home/username/kde/usr/bin:/home/username/kde/src/kdesrc-build:/home/username/.local/bin:/home/username/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin
Not prepending /home/username/kde/usr/lib/pkgconfig to PKG_CONFIG_PATH as it appears to already be defined in PKG_CONFIG_PATH.
Queueing PKG_CONFIG_PATH to be set to /home/username/kde/usr/lib/pkgconfig
Not prepending /home/username/kde/usr/lib to LD_LIBRARY_PATH as it appears to already be defined in LD_LIBRARY_PATH.
Queueing LD_LIBRARY_PATH to be set to /home/username/kde/usr/lib
Not prepending /home/username/kde/usr/bin to PATH as it appears to already be defined in PATH.
Queueing PATH to be set to /home/username/kde/usr/bin:/home/username/kde/src/kdesrc-build:/home/username/.local/bin:/home/username/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin
Queueing CMAKE_PREFIX_PATH to be set to /home/username/kde/usr
Queueing CMAKE_MODULE_PATH to be set to /home/username/kde/usr/lib64/cmake:/home/username/kde/usr/lib/cmake
Queueing XDG_DATA_DIRS to be set to /home/username/kde/usr/share:/usr/share/plasma:/home/username/.local/share/flatpak/exports/share:/var/lib/flatpak/exports/share:/usr/local/share:/usr/share:/var/lib/snapd/desktop
Source update complete for kconfig: Skipped
cd /home/username/kde/build
Preparing build system for kconfig.
Removing files in build directory for kconfig
Old build system cleaned, starting new build system.
cd /home/username/kde/build/kconfig
Running cmake targeting Unix Makefiles...
run_logged_p(): Module kconfig, Command: {'cmake', '-B', '.', '-S', '/home/username/kde/src/kconfig', '-G', 'Unix Makefiles', '-DCMAKE_EXPORT_COMPILE_COMMANDS:BOOL=ON', '-DCMAKE_BUILD_TYPE=Debug', '-DQT_MAJOR_VERSION=6', '-DBUILD_WITH_QT6=ON', '-DBUILD_TESTING=TRUE', '-DBUILD_WITH_QT6=ON', '-DCMAKE_CXX_FLAGS:STRING=-pipe', '-DCMAKE_INSTALL_PREFIX=/home/username/kde/usr'} from /home/username/kde/build/kconfig
cd /home/username/kde/build/kconfig
log_command(): Module kconfig, Command: cmake -B . -S /home/username/kde/src/kconfig -G Unix Makefiles -DCMAKE_EXPORT_COMPILE_COMMANDS:BOOL=ON -DCMAKE_BUILD_TYPE=Debug -DQT_MAJOR_VERSION=6 -DBUILD_WITH_QT6=ON -DBUILD_TESTING=TRUE -DBUILD_WITH_QT6=ON -DCMAKE_CXX_FLAGS:STRING=-pipe -DCMAKE_INSTALL_PREFIX=/home/username/kde/usr
run_logged_p(): kconfig cmake complete: 0
Therefore, kdesrc-build has run the following commands:
# Preparing build system for kconfig. Removing files in build directory for kconfig. Old build system cleaned, starting new build system.
rm -rf /home/username/kde/build/kconfig
mkdir -p /home/username/kde/build/kconfig
# Queueing X to be set to ...
PKG_CONFIG_PATH=/home/username/kde/usr/lib/pkgconfig
LD_LIBRARY_PATH=/home/username/kde/usr/lib
PATH=/home/username/kde/usr/bin:/home/username/kde/src/kdesrc-build:/home/username/.local/bin:/home/username/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin
CMAKE_PREFIX_PATH=/home/username/kde/usr
CMAKE_MODULE_PATH=/home/username/kde/usr/lib64/cmake:/home/username/kde/usr/lib/cmake
XDG_DATA_DIRS=/home/username/kde/usr/share:/usr/share/plasma:/home/username/.local/share/flatpak/exports/share:/var/lib/flatpak/exports/share:/usr/local/share:/usr/share:/var/lib/snapd/desktop
cd /home/username/kde/build/kconfig
cmake -B . -S /home/username/kde/src/kconfig -G Unix\ Makefiles -DCMAKE_EXPORT_COMPILE_COMMANDS:BOOL=ON -DCMAKE_BUILD_TYPE=Debug -DQT_MAJOR_VERSION=6 -DBUILD_WITH_QT6=ON -DBUILD_TESTING=TRUE -DBUILD_WITH_QT6=ON -DCMAKE_CXX_FLAGS:STRING=-pipe -DCMAKE_INSTALL_PREFIX=/home/username/kde/usr
How to write the entire verbose STDOUT and STDERR of kdesrc-build to a file
script -eq -c "kdesrc-build kconfig --no-src --no-include-dependencies --refresh-build --debug" ~/a.txt ; sed -i $'s/\033\[[0-9]\+m//g' ~/a.txt
The sed
part removes the terminal ANSI color escape codes.
script -eq -c "command" ~/a.txt
is better than command |& tee ~/a.txt
because kdesrc-build behaves differently if it is run in a user interactive terminal session (isatty
).
If using tee
, part of the output of kdesrc-build will not be written to file. E.g. the output of the cmake
step, the final part of the make -j
step, the final part of the make install
step.
Other CPU architectures than x86_64/amd64 and x86
You can build and develop KDE projects using a Linux OS installed on an ARM architecture CPU.
kdesrc-build issues
See https://community.kde.org/Get_Involved/development/Install_the_dependencies
wayland-protocols is too old, e.g. "kdesrc-build kidletime" fails
mkdir -p ~/kde/misc && cd ~/kde/misc wget https://gitlab.freedesktop.org/wayland/wayland-protocols/-/releases/1.31/downloads/wayland-protocols-1.31.tar.xz tar -xJvf wayland-protocols-*.tar.xz && mv wayland-protocols-*/ wayland-protocols cd wayland-protocols meson setup builddir --prefix $HOME/kde/usr meson compile -C builddir meson install -C builddir
"kdesrc-build kpat" fails because of black-hole-solitaire
This happens on Debian/Ubuntu/Kubuntu. Because there is no Linux distribution binary package for https://github.com/shlomif/black-hole-solitaire.
Solution: append at the end of kdesrc-buildrc file:
options kpat cmake-options -DWITH_BH_SOLVER=OFF end options
libdisplay-info is not available
If your Linux OS does not have a package for libdisplay-info.
Append at the end of the file kdesrc-buildrc
:
module libdisplay-info repository https://gitlab.freedesktop.org/emersion/libdisplay-info.git end module