Here is a table of the various options, containing the following information:
The option name
A description of how kdesrc-build responds if the option is set in both the global section, and the module section of the configuration file while building a module.
Special comments on the purpose and usage of the option.
Table 4.1. Table of Options
|Option-name||Module -> Global Behavior||Notes|
This option was used to allow for building KDE module API documentation. It was removed in kdesrc-build 1.6.3 due to it not being supported in KDE 4. Online API documentation is available from kde.org. In addition it is possible to build KDE 4's API documentation using a script included in the kdesdk module (/scripts directory). See KDE TechBase for more details. It is still possible to manually build API documentation for older modules of course.
|apply-qt-patches||This option was removed in kdesrc-build 1.10. To get the same effect, see the section called “qt support” and the repository option.|
|async||Cannot be overridden|
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
This option is available since the 1.6 release.
|binpath||Module setting overrides global|
Set this option to set the environment variable PATH while building.
You cannot override this setting in a module option. The default value is
|branch||Module setting overrides global|
Set this option to checkout from a branch of KDE instead of the
For instance, to checkout KDE 4.6 branch, you would set this option to
For most KDE modules you probably wish to use the branch-group option instead and use this option for case-by-case exceptions.
|branch-group||Module setting overrides global||
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.
The current branch groups (as of 2013-08-11) are:
Note that if you do choose a
This option was added in kdesrc-build 1.16-pre2.
This option only applies to
|build-dir||Module setting overrides global||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.
|build-when-unchanged||Module setting overrides global|
Use this option in order to control whether kdesrc-build always tries to build a module that has not had any source code updates.
This 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.
|checkout-only||Module setting overrides global|
Set this option to checkout Subversion sources piece by piece. The value for this option should be a space-separated list of directories to checkout. Although this option overrides the global option, be aware that setting this as a global option makes no sense.
Note that this setting has no effect on Git modules due to the operation of the Git source control system.
See the section called “Checking out portions of a module” for an example.
|cmake-options||Appends to global options (not applicable to qt)|
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.
Since these options are passed directly to the CMake command line, they should be given as they would be typed into CMake. For example:
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)
|colorful-output||Cannot be overridden||Set this option to |
|configure-flags||Module setting overrides global|
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 4 modules, see cmake-options.
|custom-build-command||Module setting overrides global||
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.
|cxxflags||Appends to global option|
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
|dest-dir||Module setting overrides global||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.|
|disable-agent-check||Cannot be overridden||Normally if you are using SSH to download the Subversion sources
(such as if you are using the svn+ssh protocol), 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. You can disable this check by setting
|do-not-compile||Module setting overrides global|
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. You can use the checkout-only directive to choose directories that you want to check out.
For example, to hold JuK and KsCD in the kdemultimedia module from compiling, you would add "do-not-compile juk kscd" to your kdemultimedia settings.
See the section called “Removing directories from a build” for an example.
|email-address||Cannot be overridden||
This option was removed in kdesrc-build 1.14.
|email-on-compile-error||Cannot be overridden||
This option was removed in kdesrc-build 1.14.
|inst-apps||This option was removed in version 1.10|
|git-desired-protocol||Cannot be overridden|
This option only applies to modules from a KDE project repository.
What this option actually does is configure which network protocol to
prefer when updating source code for these modules. Normally the very-efficient
If you are using one of these constrained networks you can set this
You 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.
This option was added in kdesrc-build 1.16.
|git-repository-base||Cannot be overridden|
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
module module1 repository kde:
It 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.
|http-proxy||Module setting overrides global|
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
This option was introduced with kdesrc-build 1.16.
|ignore-kde-structure||Module setting overrides global|
This option is used to store the source and the build files directly
in the name of the module. For example,
This option was introduced with kdesrc-build 1.16.
|ignore-modules||Can't be overridden|
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
This option was introduced with kdesrc-build 1.16.
|install-after-build||Module setting overrides global||This option is used to install the package after it successfully builds.
This option is enabled by default. If you want to disable this, you need to set
this option to |
|install-session-driver||Cannot be overridden|
By default, 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
This option was introduced with kdesrc-build 1.16.
kdesrc-build will not overwrite your existing files (if present)
unless you also pass the
|kdedir||Module setting overrides global||This option sets the directory that KDE will be installed to after it
is built. It defaults to |
|kde-languages||Cannot be overridden|
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://i18n.kde.org/teams/.
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
|libpath||Module setting overrides global||Set this option to set the environment variable
|log-dir||Module setting overrides global||Use this option to change the directory used to hold the log files generated by the script.|
|make-install-prefix||Module setting overrides global||Set this variable to a space-separated list, which is interpreted as a
command and its options to precede the |
|make-options||Module setting overrides global||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.|
|manual-build||Module setting overrides global||Set the option value to |
|manual-update||Module setting overrides global||Set the option value to |
|module-base-path||Module setting overrides global|
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
The default value is either
|niceness||Cannot be overridden||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. The default is 10.|
|no-svn||Module setting overrides global||If this option is set to true then kdesrc-build will not update the source code for the module automatically. It will still try to build the module if it normally would have tried anyways.|
|no-rebuild-on-fail||This option was removed in version 1.10, since this behavior no longer helps due to fixes in the underlying build system.|
|override-build-system||Module setting overrides global|
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:
|override-url||Module setting overrides global||If you set this option, kdesrc-build will use its value as the URL to pass to Subversion completely unchanged. You should generally use this if you want to download a specific release but kdesrc-build cannot figure out what you mean using branch.|
|persistent-data-file||Cannot be overridden|
Use this option to change where kdesrc-build stores its persistent
data. The default is to store this data in a file called
This option was added with kdesrc-build 1.15.
|prefix||Module setting overrides global|
This option controls where to install the module (normally the
You can use
|purge-old-logs||Module setting overrides global|
This option controls whether old log directories are automatically
deleted or not. The default value is
|qtdir||Module setting overrides global||Set this option to set the environment variable |
|remove-after-install||Module setting overrides global|
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
|repository||Module setting overrides global|
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.
|revision||Module setting overrides global|
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 did not work for git-based modules (including kde-projects modules) until kdesrc-build version 1.16.
|run-tests||Module setting overrides global||If set to |
|set-env||Module setting overrides global|
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
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||Module setting overrides global||This option is used to set the directory on your computer to store the KDE
Subversion sources at. If you do not specify this value, the default is
|ssh-identity-file||Cannot be overridden||
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.
|stop-on-failure||Module setting overrides global||Set this option value to |
|svn-server||Module setting overrides global|
This option is used to set the server used to check out from Subversion.
The default is the anonymous Subversion repository,
If you are developing for KDE, use the Subversion repository that was provided to you when you received your developer account, instead of the anonymous repository.
|tag||Module setting overrides global|
Use this option to download a specific release of a module.
This option has only been supported for git-based modules since kdesrc-build 1.16.
|use-clean-install||Module setting overrides global|
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.
This option was added with kdesrc-build 1.12, but was not documented until kdesrc-build 1.16.
|use-cmake||This option was removed in kdesrc-build 1.4 as all KDE 4 modules require CMake, and CMake use is not permitted on any other modules.|
|use-idle-io-priority||Cannot be overridden||This option, added in kdesrc-build 1.12, will cause a lower priority
to be used for disk and other I/O usage, which can significantly improve the
responsiveness of the rest of the system at the expense of slightly longer
running times for kdesrc-build. The default is to be disabled, to enable
the lower disk priority set this to |
|use-modules||Can only use in module-set|
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
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).
The name to use for the module if you do this is simply the
name that you passed to
|use-qt-builddir-hack||Module setting overrides global||This option has been removed due to improvements in the Qt™ build system.|
|use-stable-kde||Can't be overridden|
By default, kdesrc-build will build the main line of KDE development (trunk or master branch). You can use the branch option globally or for a module in order to switch to a stable release. However, this is not convenient as a lot of branch options would have to be added to the configuration file and kept up to date when the next stable version is released.
So, if you set this option to
This option can only be set globally, but you can still use the branch or tag options for a module to override this option. This way you can easily choose to download current stable KDE version by default while still choosing the current development version of specific modules.