Project Organization and selection

2.5. Project Organization and selection#

2.5.1. KDE Software Organization#

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

  1. At the lowest level comes the 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. KDE Builder 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 are collected under a kf6-support module grouping but are not considered part of the "Frameworks" libraries.

  3. On top of these essential libraries come the KDE Frameworks, sometimes abbreviated as KF, which are essential libraries for the KDE Plasma desktop, KDE Applications, and other third-party software.

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

    • "Third-party" applications. These are applications that use the KDE Frameworks or are designed to run under KDE Plasma but are not authored by or in association with the KDE project.

    • Plasma, which is a full "workspace" desktop environment. This is what users normally see when they "log-in to KDE".

    • The KDE Application suite. This is a collection of useful software included with the Platform and Plasma Desktop, grouped into individual projects, including utilities like Dolphin, games like KSudoku, and productivity software released by KDE such as Kontact.

    • Finally, there is a collection of software (also collected in projects) whose development is supported by KDE resources (such as translation, source control, bug tracking, etc.) but is not released by KDE as part of Plasma or the Application suite. These projects are known as "Extragear".

2.5.2. Selecting projects to build#

Selecting which of the possible projects to build is controlled by the configuration file. After the global section is a list of projects to build. An example entry for a project is shown below:

Example project entry in the configuration file#
project kde-builder-git:
  # Options for this module go here, example:
  repository: kde:kde-builder
  make-options: -j4 # Run 4 compiles at a time

Note

In practice, this project construct is not usually used directly. Instead most projects are specified viagroups as described below.

When using only project entries, KDE Builder builds them in the order you list, and does not attempt to download any other repositories other than what you specify directly.

2.5.3. Groups#

The KDE source code is decomposed into a great number of relatively small git repositories. To make it easier to manage the large number of repositories involved in any useful KDE-based install, KDE Builder supports grouping multiple projects and treating the group as a "group".

2.5.3.1. The basic group concept#

By using a group, you can quickly declare many git projects to be downloaded and built, as if you'd typed out a separate project nodes for each one. The repository option is handled specially to set up where each project is downloaded from, and every other option contained in the group is copied to every project generated in this fashion.

Using groups#
global:
  git-repository-base: kde-git kde:

project qt:
  # Options removed for brevity

group kde-support-libs:
  repository: kde-git
  use-projects:
    - automoc
    - attica
    - akonadi

# Other modules as necessary...
project kdesupport:
  ...

In the example above, a brief group is shown. When KDE Builder encounters this group, it acts as if, for every project given in use-projects, that an individual project has been declared, with its repository equal to the group's repository followed immediately by the given project name.

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

2.5.3.2. Special Support for KDE groups#

The group support described so far is general to any projects. For the KDE repositories, KDE Builder includes additional features to make things easier for users and developers. This support is enabled by specifying kde-projects as the repository for the group.

KDE Builder normally only builds the projects you have listed in your configuration file, in the order you list them. But with a kde-projects group, KDE Builder can do dependency resolution of KDE-specific projects, and in addition automatically include modules into the build even if only indirectly specified.

Using kde-projects groups#
# Only adds a project for juk (the kde/kdemultimedia/juk repo)
group juk-set:
  repository: kde-projects
  use-projects:
    - juk

# Adds all projects that are in kde/multimedia/*, including juk,
# but no other dependencies
group multimedia-set:
  repository: kde-projects
  use-projects:
    - kde/multimedia

# Adds all projects that are in kde/multimedia/*, and all kde-projects
# dependencies from outside of kde/kdemultimedia
group multimedia-deps-set:
  repository: kde-projects
  use-projects:
    - kde/multimedia
  include-dependencies: true

# All projects created out of these three groups are automatically put in
# proper dependency order, regardless of the setting for include-dependencies

Tip

This kde-projects group construct is the main method of declaring which projects you want to build.

All groups use the repository and use-projects options. kde-projects groups have a predefined repository value, but other types of groups also will use the git-repository-base option.

2.5.4. The official KDE module database#

KDE projects in invent.kde.org are placed in groups, for example kdegraphics. KDE Builder can understand these groups, using groups with a repository option set to kde-projects.

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

  • Download the latest repository metadata (the repo which is a database about all other projects).

  • Try to find a project with the name given in the group's use-projects setting in that database.

  • For every project that is found, KDE Builder will lookup the appropriate repository in the database, based upon the branch-group setting in effect. If a repository exists and is active for the branch group, KDE Builder will automatically use that to download or update the source code.

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

group media-support:
  # This option must be kde-projects to use the project database.
  repository: kde-projects

  # This option chooses what projects to look for in the database.
  use-projects:
    - phonon/phonon
    - phonon-gstreamer
    - phonon-vlc

Tip

phonon/phonon is used since (with the current project database) KDE Builder would otherwise have to decide between the group of projects called "phonon" or the individual project named "phonon". Currently KDE Builder 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 project database: Building all of the KDE graphics applications with only a single declaration.

group kdegraphics:
  # This option must be kde-projects to use the project database.
  repository: kde-projects

  # This option chooses what projects to look for in the database.
  use-projects:
    - kdegraphics/libs
    - kdegraphics/*

There are two important abilities demonstrated here:

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

  2. KDE Builder will also not add a given project 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. This used to be required for proper dependency handling, and today remains a fallback option in case the KDE project database is missing dependency metadata.

2.5.5. Filtering out KDE project projects#

You might decide that you'd like to build all programs within a KDE project 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.

You can achieve this by using the ignore-projects configuration option. Alternatively, you can use --ignore-projects option in the command line in case you want to ignore some projects just once.

Example for ignoring a kde-project project in a group#
group utils:
  repository: kde-projects

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

  # This option "subtracts out" projects from the projects chosen by use-projects, above.
  ignore-projects:
    - kremotecontrol

group graphics:
  repository kde-projects

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

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