9. KDE modules and source code organization

9.1. The “Module”

KDE groups its software into “modules” of various size. This was initially a loose grouping of a few large modules, but with the introduction of the Git-based source code repositories, these large modules were further split into many smaller modules.

kdesrc-build uses this module concept as well. In essence, a “module” is a grouping of code that can be downloaded, built, tested, and installed.

9.1.1. Individual modules

It is easy to set kdesrc-build to build a single module. The following listing is an example of what a declaration for a Git-based module would look like in the configuration file.

module kdefoo
    cmake-options -DCMAKE_BUILD_TYPE=Debug
end module

Tip

This is a Git-based module since it doesn't use a repository option. Also, the cmake-options option is listed as an example only, it is not required.

9.1.2. Groups of related modules

Now most KDE source modules are Git-based KDE, and are normally combined into groups of modules.

kdesrc-build therefore supports groups of modules as well, using module sets. An example:

module-set base-modules
    repository kde-projects
    use-modules kde-runtime kde-workspace kde-baseapps
end module-set

Tip

You can leave the module set name (<base-modules> in this case) empty if you like. This repository setting tells kdesrc-build where to download the source from, but you can also use a git:// URL.

One special feature of the “repository kde-projects” is that kdesrc-build will automatically include any Git modules that are grouped under the modules you list (in the KDE Project database).

9.1.3. Module “branch groups”

Taking the concept of a group of modules further, the KDE developers eventually found that synchronizing the names of the Git branches across a large number of repositories was getting difficult, especially during the development push for the new KDE Frameworks for Qt 5.

So the concept of “branch groups” was developed, to allow users and developers to select one of only a few groups, and allow the script to automatically select the appropriate Git branch.

kdesrc-build supports this feature as of version 1.16-pre2, via the branch-group option.

branch-group can be used in the configuration file as follows:

Example of using branch-group

global
    # Select KDE Frameworks 5 and other Qt5-based apps
    branch-group kf5-qt5

    # Other global options here ...
end global

module-set
    # branch-group only works for kde-projects
    repository kde-projects

    # branch-group is inherited from the one set globally, but could
    # specified here.

    use-modules kdelibs kde-workspace
end module-set

# kdelibs's branch will be "frameworks"
# kde-workspace's branch will be "master" (as of August 2013)

In this case the same branch-group gives different branch names for each Git module.

This feature requires some data maintained by the KDE developers in a Git repository named kde-build-metadata, however this module will be included automatically by kdesrc-build (though you may see it appear in the script output).

Tip

KDE modules that do not have a set branch name for the branch group you choose will default to an appropriate branch name, as if you had not specified branch-group at all.