Here are tables of various options, containing the following information:
The option name
The scope of the option: global, module or module-set. Options in module or/and module-set scope can also be defined in options sections.
Special comments on the purpose and usage of the option.
Table 4.1. Global scope only options
Option name | Description | ||||||
---|---|---|---|---|---|---|---|
async |
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. Related command-line option: --async, | ||||||
colorful-output |
Set this option to Related command-line option: --color (or | ||||||
disable-agent-check |
If you are using SSH to download the Git sources (such as if you are using the git+ssh protocol), this option controls if kdesrc-build will try and make sure that if you are using ssh-agent, it is actually managing some SSH identities. This is to try and prevent SSH from asking for your pass phrase for every module. Related command-line option: --disable-agent-check, --no-disable-agent-check | ||||||
git-desired-protocol |
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
If you are using one of these constrained networks you can set this
option to TipYou may also need the http-proxy option if an HTTP proxy is also needed for network traffic. In any other situation you should not set this option as the default protocol is most efficient. | ||||||
git-repository-base |
This option 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
The module-set's module module1 repository kde: The TipIt is not required to use this option to take advantage of module-set, this option exists to make it easy to use the same repository across many different module sets. | ||||||
install-environment-driver |
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 You can disable this feature by setting this option to
Tipkdesrc-build will not overwrite your existing files (if present)
unless you also pass the Related command-line option: --install-environment-driver, --no-install-environment-driver | ||||||
install-session-driver |
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 Tipkdesrc-build will not overwrite your existing files (if present)
unless you also pass the Related command-line option: --install-session-driver, --no-install-session-driver | ||||||
niceness |
Set this option to a number between 20 and 0. The higher the number, the lower a priority kdesrc-build will set for itself, i.e. the higher the number, the "nicer" the program is. Related command-line option: --nice (or | ||||||
num-cores |
This option is defined by kdesrc-build (when using kdesrc-build --generate-config), 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. Related command-line option: --num-cores | ||||||
num-cores-low-mem |
This option is defined by kdesrc-build (when using kdesrc-build --generate-config), set to be the number of
CPUs that is deemed safe for heavyweight or other highly-intensive modules,
such as 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 Although this option is intended to support Qt™ modules, you can use it for your
any module in the same way that If kdesrc-build cannot detect available memory then this value will be set to 2. Related command-line option: --num-cores-low-mem | ||||||
persistent-data-file |
Use this option to change where kdesrc-build stores its
persistent data. The default is to store this data in a file called
Related command-line option: --persistent-data-file | ||||||
ssh-identity-file |
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”. | ||||||
use-idle-io-priority |
Use lower priority for disk and other I/O, which can significantly improve the responsiveness of the rest of the system at the expense of slightly longer running times for kdesrc-build. Related command-line option: --use-idle-io-priority, --no-use-idle-io-priority | ||||||
use-inactive-modules |
Allow kdesrc-build to also clone and pull from repositories marked as inactive. Related command-line option: --use-inactive-modules, --no-use-inactive-modules |
Table 4.2. All scopes (module, module-set and global) options
Option name | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|
binpath |
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 $ Related command-line option: --binpath | ||||||||
branch |
Checkout the specified branch instead of the default branch. NoteFor most KDE modules you probably wish to use the branch-group option instead and use this option for case-by-case exceptions. Related command-line option: --branch | ||||||||
branch-group |
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
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. Note that if you do choose a
NoteThis option only applies to Related command-line option: --branch-group | ||||||||
build-dir |
Use this option to change the directory to contain the built sources. There are three different ways to use it:
Perhaps surprisingly, this option can be changed per module. Related command-line option: --build-dir | ||||||||
build-when-unchanged |
Control whether kdesrc-build always tries to build a module that has not had any source code updates. If set to If set to ImportantThis feature is provided as an optimization only. Like many other optimizations, there are trade-offs for the correctness of your installation. For instance, changes to the qt or kdelibs modules may cause a rebuild of other modules to be necessary, even if the source code doesn't change at all. Related command-line option: --build-when-unchanged (or | ||||||||
cmake-generator |
Specify which generator to use with CMake.
Currently both Note that if a valid generator is also specified through
cmake-options it will override the
value for Related command-line option: --cmake-generator | ||||||||
cmake-toolchain |
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 Related command-line option: --cmake-toolchain | ||||||||
cmake-options |
Appends to global options for the default buildsystem, overrides global for other buildsystems. 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) Related command-line option: --cmake-options | ||||||||
compile-commands-export |
Enables the generation of a Related command-line option: --compile-commands-export, --no-compile-commands-export | ||||||||
compile-commands-linking |
Enables the creation of symbolic links from Related command-line option: --compile-commands-linking, --no-compile-commands-linking | ||||||||
configure-flags |
Appends to global options for the default buildsystem, overrides global for other buildsystems. 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. Related command-line option: --configure-flags | ||||||||
custom-build-command |
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. Related command-line option: --custom-build-command | ||||||||
cxxflags |
Appends to global options for the default buildsystem, overrides global for other buildsystems. 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 Note that for KDE 4 and any other modules that use CMake, it is
necessary to set the CMAKE_BUILD_TYPE option to Related command-line option: --cxxflags | ||||||||
dest-dir |
Use this option to change the name a module is given on disk. For example, if your module was extragear/network, you could rename it to extragear-network using this option. Note that although this changes the name of the module on disk, it is not a good idea to include directories or directory separators in the name as this will interfere with any build-dir or source-dir options. Related command-line option: --dest-dir | ||||||||
do-not-compile |
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 See the section called “Removing directories from a build” for an example. Related command-line option: --do-not-compile | ||||||||
git-user |
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 For instance, a developer named “Foo Barbaz” with the email address “foo@abc.xyz” would use:
git-user
| ||||||||
http-proxy |
This option, if set, uses the specified URL as a proxy server to use for any HTTP network communications (for example, when downloading 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
Related command-line option: --http-proxy | ||||||||
directory-layout |
This option is used to configure the layout which kdesrc-build should use when creating source and build directories. The The Finally, the Related command-line option: --directory-layout | ||||||||
generate-vscode-project-config |
Module setting overrides global Set this option to The .vscode folder will be created in the project source directory, only if it does not already exist. The configurations will enable the use of LSP, building, debugging, and running the project from within VS Code. The configuration also recommends extensions to install that are useful for working on most KDE projects. Related command-line option: --generate-vscode-project-config, | ||||||||
include-dependencies |
Controls if kdesrc-build will include known dependencies of this module in its build, without requiring you to mention those dependencies (even indirectly). NoteThis option only works for This is to support building applications that need versions of Qt™ or Plasma™ more recent than supported on common operating systems. Related command-line option: --include-dependencies (or | ||||||||
install-after-build |
This option is used to install the package after it successfully builds.
You can also use the Related command-line option: --install-after-build, --no-install-after-build | ||||||||
install-dir |
This option controls where to install the module after it is built. If you change this to a directory needing root access, you may want to read about the make-install-prefix option as well. Changing this option for specific module allows you to install it 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 Related command-line option: --install-dir | ||||||||
libname |
Set this option to change the default name of the installed library directory inside ${install-dir} and ${qt-install-dir}. On many systems this is either "lib" or "lib64". Auto-detection is attempted to set the correct name by default, but if the guess is wrong then it can be changed with this setting. Related command-line option: --libname | ||||||||
libpath |
Set this option to set the environment variable
Related command-line option: --libpath | ||||||||
log-dir |
Use this option to change the directory used to hold the log files generated by the script. Related command-line option: --log-dir | ||||||||
make-install-prefix |
Set this variable to a space-separated list, which is interpreted as a
command and its options to precede the Related command-line option: --make-install-prefix | ||||||||
make-options |
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. Related command-line option: --make-options | ||||||||
manual-build |
Set the option value to | ||||||||
manual-update |
Set the option value to | ||||||||
ninja-options |
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. NoteNote that this setting only controls ninja when used by kdesrc-build.
The Qt™ “webengine” module uses ninja indirectly, but
only officially supports being built by make.
In this situation, you can set options Related command-line option: --ninja-options | ||||||||
override-build-system |
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:
Related command-line option: --override-build-system | ||||||||
purge-old-logs |
This option controls whether old log directories are automatically deleted or not. Related command-line option: --purge-old-logs, --no-purge-old-logs | ||||||||
qmake-options |
Any options specified here are passed to the
qmake command, for modules that use the
qmake build system. For instance, you can use the
Related command-line option: --qmake-options | ||||||||
qt-install-dir |
This option controls where to install qt modules after build. If you do not specify this option, kdesrc-build will assume that Qt™ is provided by the operating system. Related command-line option: --qt-install-dir | ||||||||
remove-after-install |
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 Related command-line option: --remove-after-install | ||||||||
repository |
This option 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. | ||||||||
revision |
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. Related command-line option: --revision | ||||||||
run-tests |
If set to Related command-line option: --run-tests, --no-run-tests | ||||||||
set-env |
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 set-env 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). | ||||||||
source-dir |
This option is used to set the directory on your computer to store the KDE Git sources at. You may use the tilde (~) to represent the home directory if using this option. Related command-line option: --source-dir | ||||||||
stop-on-failure |
Setting this option to Related command-line option: --stop-on-failure, | ||||||||
tag |
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. Related command-line option: --tag | ||||||||
use-clean-install |
Set this option to 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. Related command-line option: --use-clean-install, --no-use-clean-install |
These options do not require any value (except "filter-out-phases"). They are applied if they are presented in a section.
Table 4.3. Phase selection options
Option name | Scope | Description | |||
---|---|---|---|---|---|
no-src |
|
Remove update phase. The other phases that were presented will still be processed. Related command-line option: --no-src (or | |||
no-install |
|
Remove install phase. The other phases that were presented will still be processed. Related command-line option: --no-install | |||
no-tests |
|
Remove test phase. The other phases that were presented will still be processed. Related command-line option: --no-tests | |||
no-build |
|
Remove build phase. The other phases that were presented will still be processed. Related command-line option: --no-build | |||
build-only |
|
If had build phase, remove any other phases. Otherwise, remove all phases. Related command-line option: --build-only | |||
install-only |
|
If had install phase, remove any other phases. Otherwise, remove all phases. Related command-line option: --install-only | |||
uninstall |
|
If had uninstall phase, remove any other phases. Otherwise, remove all phases. Related command-line option: --uninstall | |||
filter-out-phases |
|
Remove those phases that are listed (space separated) in this option. The other phases that were presented will still be processed. |
Table 4.4. Modules selection options
Option name | Scope | Description | ||||||
---|---|---|---|---|---|---|---|---|
ignore-modules |
|
Note that when specified in global section, --ignore-modules cmdline option does not override this, but instead appends. 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 Related command-line option: --ignore-modules (or | ||||||
use-modules |
|
This option allows you to easily specify many different modules to build at the same point in the configuration file. Every identifier passed to this option is
internally converted to a kdesrc-build module, with a 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). ImportantThe name to use for the module if you do this is simply the
name that you passed to See the section called “Module Sets” and git-repository-base for a description of its use and an example. |