This option was used to allow for building KDE module API documentation. It was removed in kdesrc-build 1.6.3 due to lack of support. Online API documentation is available from kde.org. In addition it is possible to build KDE API documentation using the kdedoxygen.sh script included in the kde-dev-scripts module. See KDE TechBase for more details.

This option enables the asynchronous mode of operation, where the source code update and the build process will be performed in parallel, instead of waiting for all of the source code updates before starting the build process. This option defaults to enabling asynchronous mode. To disable, set this option to false

This option is available since the 1.6 release.

Set this option to set the environment variable PATH while building. You cannot override this setting in a module option. The default value is the $PATH that is set when the script starts. This environment variable should include the colon-separated paths of your development toolchain. The paths $KDEDIR/bin and $QTDIR/bin are automatically added. You may use the tilde (~) for any paths you add using this option.

Set this option to checkout from a branch of KDE instead of the default of master (for Git modules) or trunk (for Subversion), where KDE development occurs.

For instance, to checkout KDE 4.6 branch, you would set this option to 4.6.

If kdesrc-build fails to properly download a branch with this option, you may have to manually specify the URL to download from using the module-base-path or override-url options.

Set this option to a general group from which you want modules to be chosen.

For supported Git module types, kdesrc-build will determine the actual branch to use automatically based on rules encoded by the KDE developers (these rules may be viewed in the kde-build-metadata source repository in your source directory). After a branch is determined that branch is used as if you had specified it yourself using the branch option.

This is useful if you're just trying to maintain up-to-date on some normal development track without having to pay attention to all the branch name changes.

The current branch groups (as of 2013-08-11) are:

Note that if you do choose a branch yourself, that it will override this setting. The same is true of other specific branch selection options such as tag.

This option was added in kdesrc-build 1.16-pre2.

Use this option in order to control whether kdesrc-build always tries to build a module that has not had any source code updates.

By setting build-when-unchanged to true, kdesrc-build always attempts the build phase for a module, even if the module did not have any source code updates. This is the default setting since it is more likely to lead to a correct build.

By setting build-when-unchanged to false, kdesrc-build will only attempt to run the build phase for a module if the module has a source code update, or in other situations where it is likely that a rebuild is actually required. This can save time, especially if you run kdesrc-build daily, or more frequently.

This option was removed in January 2022. It used to control the ability to checkout subsets of a module from a Subversion repository.

Use this option to specify which generator to use with CMake. Currently both Ninja and Unix Makefiles as well as extra generators based on them like Eclipse CDT4 - Ninja are supported. Invalid (unsupported) values are ignored and treated as if unset. If not set Unix Makefiles will be used by default.

Note that if a valid generator is also specified through cmake-options it will override the value for cmake-generator.

Use this option to specify a toolchain file to use with CMake.

When a valid toolchain file is configured, kdesrc-build will no longer set environment variables automatically. You can use set-env, binpath and libpath to fix up the environment manually if your toolchain file does not work out of the box with kdesrc-build. Refer to the overview of standard flags added by kdesrc-build for more information.

Note that if a valid toolchain is also specified through cmake-options it will override the value for cmake-toolchain.

Use this option to specify what flags to pass to CMake when creating the build system for the module. When this is used as a global option, it is applied to all modules that this script builds. When used as a module option, it is added to the end of the global options. This allows you to specify common CMake options in the global section.

This option does not apply to qt (which does not use CMake). Use configure-flags instead.

If a valid generator is specified among the listed options it will override the value of cmake-generator. Invalid (unsupported) generators are ignored and will not be passed to CMake.

If a valid toolchain file is specified among the listed options it will override the value of cmake-toolchain. Invalid toolchains are ignored and will not be passed to CMake.

Since these options are passed directly to the CMake command line, they should be given as they would be typed into CMake. For example:

  cmake-options -DCMAKE_BUILD_TYPE=RelWithDebInfo

Since this is a hassle, kdesrc-build takes pains to ensure that as long as the rest of the options are set correctly, you should be able to leave this option blank. (In other words, required CMake parameters are set for you automatically)

Enables the generation of a compile_commands.json via CMake inside the build directory. This option defaults to true, set it to false to disable this behavior.

Enables the creation of symbolic links from compile_commands.json generated via CMake inside the build directory to the matching source directory. This option defaults to false, set it to true to enable the automatic symbolic link creation.

Use this option to specify what flags to pass to ./configure when creating the build system for the module. When this is used as a global-option, it is applied to all modules that this script builds. This option only works for qt.

To change configuration settings for KDE modules, see cmake-options.

This option can be set to run a different command (other than make, for example) in order to perform the build process. kdesrc-build should in general do the right thing, so you should not need to set this option. However it can be useful to use alternate build systems.

The value of this option is used as the command line to run, modified by the make-options option as normal.

Use this option to specify what flags to use for building the module. This option is specified here instead of with configure-flags or cmake-options because this option will also set the environment variable CXXFLAGS during the build process.

Note that for KDE 4 and any other modules that use CMake, it is necessary to set the CMAKE_BUILD_TYPE option to none when configuring the module. This can be done using the cmake-options option.

Use this option to select a specific set of directories not to be built in a module (instead of all of them). The directories not to build should be space-separated.

Note that the sources to the programs will still be downloaded.

For example, to disable building the codeeditor and minimaltest directories of the syntaxhighlighting framework, you would add do-not-compile codeeditor minimaltest compiling, you would add "do-not-compile juk kscd" to your syntaxhighlighting options.

See the section called “Removing directories from a build” for an example.

This option was removed in kdesrc-build 1.14.

This option was removed in kdesrc-build 1.14.

This option only applies to modules from a KDE project repository.

What this option actually does is configure which network protocol to prefer when pushing source code for these modules. Normally the very-efficient git protocol is used, but this may be blocked in some networks (e.g. corporate intranets, public Wi-Fi). An alternative protocol which is much better supported is the https protocol used for Internet web sites.

If you are using one of these constrained networks you can set this option to http to prefer https communications instead.

In any other situation you should not set this option as the default protocol is most efficient.

This option was added in kdesrc-build 1.16. Prior to 20.06 this option was used to configure the fetch URL instead of the push URL. As of 20.06 https is always used when updating KDE projects.

This option, added in version 1.12.1, is used to create a short name to reference a specific Git repository base URL in later module set declarations, which is useful for quickly declaring many Git modules to build.

You must specify two things (separated by a space): The name to assign to the base URL, and the actual base URL itself. For example:

global
   # other options

   # This is the common path to all anonymous Git server modules.
   git-repository-base kde-git kde:
end global

# Module declarations

module-set
   # Now you can use the alias you defined earlier, but only
   # in a module-set.
   repository kde-git

   use-modules module1.git module2.git
end module-set

The module-set's use-modules option created two modules internally, with kdesrc-build behaving as if it had read:

module module1
    repository kde:module1.git
end module

module module2
    repository kde:module2.git
end module

The kde: Git repository prefix used above is a shortcut which will be setup by kdesrc-build automatically. See the TechBase URL Renaming article for more information. Note that unlike most other options, this option can be specified multiple times in order to create as many aliases as necessary.

This option is intended for KDE developers. If set, it will be used to automatically setup identity information for the Git source control software for newly downloaded Git modules (including the vast majority of KDE modules).

Specifically, the user's name and email fields for each new Git repository are filled in to the values set by this option.

The value must be specified in the form User Name <email@example.com>.

    git-user Foo Barbaz <foo@abc.xyz>

This option was introduced in kdesrc-build 15.09.

This option, if set, uses the specified URL as a proxy server to use for any HTTP network communications (for example, when downloading snapshots for new modules, or the KDE project database).

In addition, kdesrc-build will try to ensure that the tools it depends on also use that proxy server, if possible, by setting the http_proxy environment variable to the indicated server, if that environment variable is not already set.

This option was introduced with kdesrc-build 1.16.

This option is deprecated and will be removed (again) in a future release.

Please use directory-layout instead, which offers more options.

This option is used to configure the layout which kdesrc-build should use when creating source and build directories.

Currently, there are three possible values: flat, invent, and metadata.

The flat layout is the default value, and will group all modules directly underneath the top level source and build directories. For example, source/extragear/network/telepathy/ktp-text-ui in the metadata layout would be source/ktp-text-ui using the flat layout instead.

The invent layout creates a directory hierarchy mirroring the relative paths of repositories on invent.kde.org. For example source/kde/applications/kate in the metadata layout would be source/utilities/kate using the invent layout instead. This layout only affects KDE projects. It is a good choice for people starting out with kdesrc-build.

Finally, the metadata layout is the same as the old default behaviour. This layout organises KDE projects according to the project paths specified in the project metadata for these modules. This is a good choice if you want a directory layout which tracks with certain KDE processes, but note that this path is therefore not always stable. As a result, kdesrc-build may abandon an old copy of the repository and clone a new one for a project due to changes in the project metadata.

Modules named by this option, which would be chosen by kdesrc-build due to a use-modules option, are instead skipped entirely. Use this option when you want to build an entire kde-projects project grouping except for some specific modules.

The option value does not necessarily have to name the module directly. Any module that has full consecutive parts of its KDE projects module path match one of the option values will be ignored, so you can ignore multiple modules this way.

For example, an option value of libs would result in both kde/kdegraphics/libs and playground/libs being excluded (though not kde/kdelibs since the full part “kdelibs” is what is compared).

This option was introduced with kdesrc-build 1.16.

This option, when set to true requests that kdesrc-build also include known dependencies of this module in its build, without requiring you to mention those dependencies (even indirectly).

This option is enabled by default, to support building applications that need versions of Qt™ or Plasma™ more recent than supported on common operating systems.

By default, kdesrc-build will install a shell script that can be sourced in a user's profile setup scripts to easily establish needed environment variables to run the Plasma desktop built by kdesrc-build.

This driver will alter the following files:

The kde-env-user.sh is optional. It is intended for user customizations (see the Troubleshooting and Debugging section of the KDE UserBase for examples of customizable settings), but these settings can be set elsewhere by the user in their existing profile setup scripts.

You can disable this feature by setting this option to false, and ensuring that the install-session-driver option is also disabled.

This option was introduced with kdesrc-build 17.08.

If enabled, kdesrc-build will try to install a driver for the graphical login manager that allows you to login to your kdesrc-build-built KDE desktop.

This driver will alter the following files:

If you maintain your own login driver then you can disable this feature by setting this option to false. If enabled, this feature also enables the install-environment-driver feature.

This option was introduced with kdesrc-build 1.16.

This option allows you to choose to download and install localization packages along with KDE. You might do this if you do not live in the United States and would like to use KDE translated into your native language.

To use this option, set it to a space-separated list of languages to install. Each language has a language code associated with it, which you can look up at this page: http://l10n.kde.org/teams-list.php.

It is alright to choose only one language. By default, none are downloaded, which means KDE will display in American English.

For instance, to choose to install French, you would set the option to something like: kde-languages fr. You would still need to use System Settings in order to choose the French language, however.

Set this variable in order to pass command line options to the make command. This is useful for programs such as distcc or systems with more than one processor core.

Note that not all supported build systems use make. For build systems that use ninja for build (such as the Meson build system), see the ninja-options setting.

Set this option to override kdesrc-build's default directory path to the module in question. This can be used, for example, to pull specific branches or tagged versions of libraries. The KDE Source Viewer is invaluable in helping to pick the right path.

Note that kdesrc-build constructs the final path according to the following template: $svn-server/home/kde/$module-base-path.

The default value is either trunk/$module or trunk/KDE/$module, depending on the module name.

Set this variable in order to pass command line options to the ninja build command. This can be useful to enable “verbose” output or to manually reduce the number of parallel build jobs that ninja would use.

options qtwebengine
    # Restrict make and ninja to using no more than 6 separate compile jobs even
    # when more CPU is available, to avoid running out of memory
    make-options -j6 NINJAFLAGS=-j6
end options

This option is defined by kdesrc-build (when using the kdesrc-build-setup tool or kdesrc-build --initial-setup), set to be the number of available CPUs (as indicated by the external application nproc). If kdesrc-build cannot detect the number of CPUs, this value is set to 4.

See Example 2.1, “Configuring Make to use all available CPUs, with exceptions” for an example of this option's usage. This option was added in version 20.07.

This option is defined by kdesrc-build (when using the kdesrc-build-setup tool or kdesrc-build --initial-setup), set to be the number of CPUs that is deemed safe for heavyweight or other highly-intensive modules, such as qtwebengine, to avoid running out of memory during the build.

The typical calculation is one CPU core for every 2 gigabytes (GiB) of total memory. At least 1 core will be specified, and no more than num-cores cores will be specified.

Although this option is intended to support Qt™ modules, you can use it for your any module in the same way that num-cores is used.

If kdesrc-build cannot detect available memory then this value will be set to 2.

This option was added in version 20.07.

This is an advanced option, added in kdesrc-build 1.16.

Normally kdesrc-build will detect the appropriate build system to use for a module after it is downloaded. This is done by checking for the existence of specific files in the module's source directory.

Some modules may include more than one required set of files, which could confuse the auto-detection. In this case you can manually specify the correct build type.

Currently supported build types that can be set are:

Use this option to change where kdesrc-build stores its persistent data. The default is to store this data in a file called .kdesrc-build-data, placed in the same directory as the configuration file in use. If the global configuration file is in use, it will be saved to ~/.local/state/kdesrc-build-data ($XDG_STATE_HOME/kdesrc-build-data, if $XDG_STATE_HOME is set). If you have multiple available configurations in the same directory, you may want to manually set this option, so that different configurations do not end up with conflicting persistent data.

This option was added with kdesrc-build 1.15.

This option controls where to install the module (normally the kdedir setting is used). Using this option allows you to install a module to a different directory than where the KDE Platform libraries are installed, such as if you were using kdesrc-build only to build applications.

You can use ${MODULE} or $MODULE in the path to have them expanded to the module's name.

This option controls whether old log directories are automatically deleted or not. The default value is true.

Any options specified here are passed to the qmake command, for modules that use the qmake build system. For instance, you can use the PREFIX=/path/to/qt option to qmake to override where it installs the module.

This option was added to kdesrc-build 1.16.

If you are low on hard disk space, you may want to use this option in order to automatically delete the build directory (or both the source and build directories for one-time installs) after the module is successfully installed.

Possible values for this option are:

Note that using this option can have a significant detrimental impact on both your bandwidth usage (if you use all) and the time taken to compile KDE software, since kdesrc-build will be unable to perform incremental builds.

This option was introduced with version 1.10, and is used to specify the Git repository to download the source code for the module. Qt™ (and therefore qt) would need this option, as well as various KDE modules that are in the process of conversion to use Git.

If this option is set to a value other than 0 (zero), kdesrc-build will force the source update to bring the module to the exact revision given, even if options like branch are in effect. If the module is already at the given revision then it will not be updated further unless this option is changed or removed from the configuration.

This option accepts a space-separated set of values, where the first value is the environment variable to set, and the rest of the values is what you want the variable set to. For example, to set the variable RONALD to McDonald, you would put in the appropriate section this command:

set-env RONALD McDonald

This option is special in that it can be repeated without overriding earlier set-env settings in the same section of the configuration file. This way you can set more than one environment variable per module (or globally).

Set this option to control which private SSH key file is passed to the ssh-add command when kdesrc-build is downloading source code from repositories that require authentication. See also: the section called “SSH Agent checks”.

This option was added in version 1.14.2.

This option is used to set the server used to check out from Subversion. The default is the anonymous Subversion repository, svn://anonsvn.kde.org/

Use this option to download a specific release of a module.

Note: The odds are very good that you do not want to use this option. KDE releases are available in tarball form from the KDE download site.

Set this option to true in order to have kdesrc-build run make uninstall directly before running make install.

This can be useful in ensuring that there are not stray old library files, CMake metadata, etc. that can cause issues in long-lived KDE installations. However this only works on build systems that support make uninstall.

This option was added with kdesrc-build 1.12, but was not documented until kdesrc-build 1.16.

This option, added in kdesrc-build 1.12.1, allows you to easily specify many different modules to build at the same point in the configuration file.

This option must be used within a module-set. Every identifier passed to this option is internally converted to a kdesrc-build module, with a repository option set to the module-set's repository combined with the identifier name in order to setup the final repository to download from. All other options that are assigned in the module-set are also copied to the generated modules unaltered.

The order that modules are defined in this option is important, because that is also the order that kdesrc-build will process the generated modules when updating, building, and installing. All modules defined in the given module-set will be handled before kdesrc-build moves to the next module after the module-set.

If you need to change the options for a generated module, simply declare the module again after it is defined in the module-set, and set your options as needed. Although you will change the options set for the module this way, the module will still be updated and built in the order set by the module-set (i.e. you can't reorder the build sequence doing this).

See the section called “Module Sets” and git-repository-base for a description of its use and an example.

This option is deprecated and will be removed (again) in a future release.

Please use the branch-group instead, which offers more selectivity.