6.1. Development Environment Setup

This section gives guidance on setting up a development environment suitable for working on KDE Builder itself. For regular installation options for end users, please consult the Getting Started section instead.

Note

If you're new to KDE Development, and are looking for guidance on setting up a development environment for working on KDE software in general, please read this tutorial instead!

6.1.1. Create an Editable Installation

If you want to develop KDE Builder or test some changes from a merge request, you can use an editable installation. This kind of installation maps your version of KDE Builder to the kde-builder command for your user, and allows you to test your modifications immediately without having to reinstall the tool.

To create an editable installation, run the following command from your local copy of the Git repository:

uv tool install --editable .

To test that your local copy is now the active version, compare the version string against the hash of the Git commit you were on when you performed the installation. To have kde-builder print the version string, run

$ kde-builder --version
26.10.post5+g123abc789

In this example, .post5 indicates that you are 5 commits after the release tagged as version 26.10, while +g123abc789 contains the abbreviated hash of the corresponding commit.

If you had any uncommitted changes when you performed the installation, the date is appended to the version string. For example:

$ kde-builder --version
kde-builder 26.10.post5+g123abc789.d20261128

This version string remains unchanged until you reinstall KDE Builder, either as a regular installation or as a fresh editable installation. Newly added commits won't be reflected in the version string.

6.1.2. Use Linters to Check for Issues

If you set up your development environment using the method described above, you will automatically have access to some of the tools that are also used in the CI pipeline.

Important

Please make use of these tools before submitting a new merge request or adding more commits to an existing one. It is cheaper and quicker to run them locally instead of triggering an entire CI pipeline.

6.1.2.1. Ruff

We use Ruff as a linter for our Python sources. To check the entire project for issues, use

uv run ruff check

Ruff is very fast, so you may want to consider adding it to a pre-commit hook. This will prevent you from committing Python sources that violate KDE Builder's conventions.

6.1.2.2. Reuse

We use reuse to ensure we comply with the KDE Licensing Policy. Check your sources for policy violations such as missing SPDX annotations by running

uv run reuse lint

This tool does not run as quickly as Ruff, so you may not want to add it to a pre-commit hook. You may want to add it to a pre-push hook instead, since you can always add missing license information with git history fixup.

6.1.3. Testing

Warning

Do not run the tests inside of a Git hook!

There is currently an unmitigated interaction between the environment as set up by some Git hooks and the integration tests that will break the repository.

KDE Builder comes with unit tests and integration tests built on pytest. You can run the entire test suite using

uv run pytest

To also generate a coverage report, run

uv run pytest --cov --cov-report=term --cov-report=xml

6.1.4. Building Documentation

The sources for the documentation you are currently reading are also included in the Git repository. To build them locally, use the helper script:

./scripts/build_docs.sh

If you intend to work on them, you can start a watcher that automatically builds the documentation whenever the sources change and renders a live preview in your browser:

./scripts/build_docs.sh --watch

For more details, consult the README.md file in the doc folder.