Module Organization and selection

KDE Software Organization

KDE software is split into different components, many of which can be built by kdesrc-build. Understanding this organization will help you properly select the software modules that you want built.

  1. At the lowest level comes Digia's Qt™ library, which is a very powerful, cross-platform toolkit library. KDE is based on Qt™, and some of the non-KDE libraries required by KDE are also based on Qt™. kdesrc-build can build Qt™, or use the one already installed on your system if it is a recent enough version.

  2. On top of Qt™ are required libraries that are necessary for KDE software to work. Some of these libraries are not considered part of KDE itself due to their generic nature, but are still essential to the KDE Platform. These libraries tended to get combined into a single kdesupport module.

    Note

    As of KDE Platform 4.6, many of the libraries in the kdesupport module are being migrated over to git.kde.org, although they are still not considered part of the Platform.

  3. On top of these essential libraries comes the KDE Platform. These are the libraries that are required for KDE applications to work. A full desktop environment is not provided by the Platform however.

    For kdesrc-build, the Platform layer consists of the kdelibs, kdepimlibs, and kde-runtime modules.

  4. On top of the Platform, come several different things:

    • Third-party applications. These are applications that use the KDE Platform but are not authored by or in association with the KDE project.

    • A full workspace desktop environment. This is what users normally see when they log-in to KDE. This is provided by the Plasma Desktop, mostly in kde-workspace.

    • The KDE Software Compilation. This is a collection of useful software included with the Platform and Plasma Desktop, grouped into individual modules. These are the modules that have names starting with kde. For example, kdepim is a component of the Software Compilation that contains email, news-reading, calendar/organizational software, etc., while kdegames contains a collection of high-quality games to while away the time.

    • Finally, there is a collection of software (also collected in modules) whose development is supported by KDE resources (such as translation, source control, bug tracking, etc.) but is not released by KDE or considered part of the Software Compilation. These modules are known as Extragear, and have module names such as extragear/network. As with kdesupport, some of these Extragear applications are migrating to git.kde.org.

Selecting modules to build

Selecting which of the possible modules to build is controlled by the configuration file. After the global section is a list of modules to build, bracketed by module ... end module lines. An example entry for a module is shown in Example 2.1, “Example module entry in the configuration file”.

Example 2.1. Example module entry in the configuration file

module module-name
    # Options for this module go here, example:
    make-options -j4 # Run 4 compiles at a time
end module

Tip

It is possible to declare a module with no options. In fact, most of your modules will likely be declared this way.

kdesrc-build only builds the modules you have listed in your configuration file. In addition, the modules are built in the order specified in the configuration file. For this reason you should ensure that the order of modules in your configuration file is consistent with the organization given in the section called “KDE Software Organization”.

There is a sample file that comes with kdesrc-build called kdesrc-buildrc-sample. It is recommended to copy this file to a file called ~/.kdesrc-buildrc (Note the leading period in front of kdesrc-buildrc!). Afterwards, edit the new file to adjust the default options to your liking. (Each option is described in more detail in Chapter 4, Configuring kdesrc-build). The default modules should be enough to ensure a fairly complete KDE installation, however you can remove many of the modules that show up after kdebase if you'd like to save disk space or build time.

Module Sets

kdesrc-build is usually able to guess where to download the source code for a given module quite easily, by using your setting for svn-server and the module name for each module to create a single Subversion URL, which describes exactly where to download the source code from.

With the move to Git, many larger Subversion modules were further sub-divided in the process, and there was no guarantee of where to find a module based just on the module name. Because of this, a concept called module sets was developed for kdesrc-build 1.12.1.

By using a module set, you can quickly declare many Git modules to be downloaded and built, as if you'd typed out a separate module declaration for each one. The repository option is handled specially to setup where each module is downloaded from, which every other option contained in the module set is copied to every module generated in this fashion.

Example 2.2. Using module sets

global
    git-repository-base kde-git kde:
end global

module qt
    # Options removed for brevity
end module

module-set kde-support-libs
    repository kde-git
    use-modules automoc attica akonadi
end module-set

# Other modules as necessary...
module kdesupport
end module

In Example 2.2, “Using module sets” a brief module set is shown. When kdesrc-build encounters this module set, it acts as if, for every module given in use-modules, that an individual module has been declared, with its repository equal to the module-set's repository followed immediately by the given module name.

In addition, other options can be passed in a module set, which are copied to every new module that is created this way. By using module-set it is possible to quickly declare many Git modules that are all based on the same repository URL. In addition, since kdesrc-build 1.13, it is possible to give module-sets a name (as shown in the example), which allows you to quickly refer to the entire group of modules from the command line.

Note

Module sets are used in supporting module downloads from the KDE projects.kde.org module database. See also the section called “Automatically finding modules from the official KDE module database”.

Module sets use the options

git-repository-base
use-modules

Automatically finding modules from the official KDE module database

With the migration of KDE source code to be hosted on git.kde.org, there has been an explosive growth in the number of modules (for instance, a single Subversion module called kdegraphics becomes 16 different Git modules).

This was done mostly because each Git module contains the entire project history (this is actually less wasteful of disk space than it sounds for the vast majority of KDE repositories as Git is highly efficient at storing repositories).

KDE allows for grouping Git repositories into collections of related modules (e.g. kdegraphics). These modules can themselves be grouped (e.g. KDE Software Compilation). Git doesn't recognize these groupings, but kdesrc-build can be configured to handle these groups.

The way this is done is by using module sets. Instead of using a specific git:// repository, or a repository name created by git-repository-base, a special repository name, kde-projects is used.

kdesrc-build will recognize that the kde-projects repository requires special handling, and adjust the build process appropriately. Among other things, kdesrc-build will:

  • Download the latest module database from projects.kde.org.

  • Try to find a module with the name given in the module set's use-modules setting.

  • For every module that is found, kdesrc-build will see if a repository setting exists for that module in the database. If there is a repository, kdesrc-build will automatically use that to download or update the source code. If there is no repository, kdesrc-build treats that module like a group, and tries to include all Git source repositories that it finds in that group.

Note

In the current database, some module groups not only have a collection of modules, but they also declare their own Git repository. In these situations kdesrc-build will currently prefer the group's Git repository instead of including the childrens' repositories.

The following example shows how to use the KDE module database to install the Phonon multimedia library.

module-set media-support
    # This option must be kde-projects to use the module database.
    repository kde-projects

    # This option chooses what modules to look for in the database.
    use-modules phonon/phonon phonon-gstreamer phonon-vlc
end module-set

Tip

phonon/phonon is used since (with the current project database) kdesrc-build would otherwise have to decide between the group of projects called phonon or the individual project named phonon. Currently kdesrc-build would pick the former, which would build many more backends than needed.

The following example is perhaps more realistic, and shows a feature only available with the KDE module database: Building all of the KDE graphics applications with only a single declaration.

module-set kdegraphics
    # This option must be kde-projects to use the module database.
    repository kde-projects

    # This option chooses what modules to look for in the database.
    use-modules kdegraphics/libs kdegraphics/*
end module-set

There are two important abilities demonstrated here:

  1. kdesrc-build allows you to specify modules that are descendents of a given module, without building the parent module, by using the syntax module-name/*. It is actually required in this case since the base module, kdegraphics, is marked as inactive so that it is not accidentally built along with its children modules. Specifying the descendent modules allows kdesrc-build to skip around the disabled module.

  2. kdesrc-build will also not add a given module to the build list more than once. This allows us to manually set kdegraphics/libs to build first, before the rest of kdegraphics, without trying to build kdegraphics/libs twice.

Note

It is worth noting that kdesrc-build will try to build modules in the right order, such as if only kdegraphics/* had been listed above, but this depends on other databases being kept up-to-date. You can manually list modules in the proper order if necessary by using the technique described above.

Filtering out KDE project modules

You might decide that you'd like to build all programs within a KDE module grouping except for a given program.

For instance, the kdeutils group includes a program named kremotecontrol. If your computer does not have the proper hardware to receive the signals sent by remote controls then you may decide that you'd rather not download, build, and install kremotecontrol every time you update kdeutils.

As of kdesrc-build 1.16, you can achieve this by using the ignore-modules configuration option.

Example 2.3. Example for ignoring a kde-project module in a group

module-set utils
    repository kde-projects

    # This option chooses what modules to look for in the database.
    use-modules kdeutils

    # This option "subtracts out" modules from the modules chosen by use-modules, above.
    ignore-modules kremotecontrol
end module-set

module-set graphics
    repository kde-projects

    # This option chooses what modules to look for in the database.
    use-modules extragear/graphics

    # This option "subtracts out" modules from the modules chosen by use-modules, above.
    # In this case, *both* extragear/graphics/kipi-plugins and
    # extragear/graphics/kipi-plugins/kipi-plugins-docs are ignored
    ignore-modules extragear/graphics/kipi-plugins
end module-set