Advanced features

Partially building a module
It is possible to build only pieces from a single module. For example, you may want to compile only one program from a module. has features to make this easy. There are several complementing ways to do this.

Removing directories from a build
It is possible to download an entire repository but have the build system leave out a few directories when it does the build. This requires that the module uses and that the module's build system allows the directory to remove to be optional.
This is controlled with the option.
This option requires at least that the build system for the module is reconfigured after changing it. This is done using the kdesrc-build module command.
To remove the python directory from the kdebindings build process:

module kdebindings
   python
end module

This function depends on some standard conventions used in most modules. Therefore it may not work for all programs.

Branching and tagging support for

What are branches and tags?
supports managing the history of the source code. uses this support to create branches for development, and to tag the repository every so often with a new version release.
For example, the developers may be working on a new feature in a different branch in order to avoid breaking the version being used by most developers. This branch has development ongoing inside it, even while the main branch (called master) may have development going on inside of it.
A tag, on the other hand, is a specified point in the source code repository at a position in time. This is used by the administration team to mark off a version of code suitable for release and still allow the developers to work on the code.

How to use branches and tags
Support for branches and tags is handled by a set of options, which range from a generic request for a version, to a specific to download for advanced users.
The easiest method is to use the and options. You simply use the option along with the name of the desired branch or tag for a module, and will try to determine the appropriate location within the repository to download from. For most modules this works very well.
To download kdelibs from 4.6 (which is simply known as the 4.6 branch):

module kdelibs
  branch 4.6
  # other options...
end module

Or, to download kdemultimedia as it was released with 4.6.1:

module kdemultimedia
  tag 4.6.1
  # other options...
end module

You can specify a global branch value. But if you do so, do not forget to specify a different branch for modules that should not use the global branch!

Stopping the build early

The build normally continues even if failures occur
normally will update, build and install all modules in the specified list of modules to build, even if a module fails to build. This is usually a convenience to allow you to update software packages even if a simple mistake is made in one of the source repositories during development that causes the build to break.
However you may wish for to stop what it is doing once a module fails to build and install. This can help save you time that will be wasted trying to make progress when modules remaining in the build list will not be able to successfully build either, especially if you have not ever successfully built the modules in the list.

Not stopping early with --no-stop-on-failure
The primary method to do this is to use the --no-stop-on-failure command line option when you run .
This option can also be set in the configuration file to make it the normal mode of operation.
It is also possible to tell at runtime to stop building after completing the current module it is working on. This is as opposed to interrupting using a command like C, which interrupts immediately, losing the progress of the current module.
Interrupting during a module install when the use-clean-install option is enabled will mean that the interrupted module will be unavailable until is able to successfully build the module!
If you need to interrupt without permitting a graceful shutdown in this situation, at least try to avoid doing this while is installing a module.

Stopping gracefully when stop-on-failure is false
As mentioned above, it is possible to cause to gracefully shutdown early once it has completed the module it is currently working on. To do this, you need to send the POSIX HUP signal to
You can do this with a command such as pkill (on systems) as follows:

$ pkill -HUP kdesrc-build

If done successfully, you will see a message in the output similar to:

[ build ] recv SIGHUP, will end after this module

may show this message multiple times depending on the number of individual processes that are active. This is normal and not an indication of an error.
Once has acknowledged the signal, it will stop processing after the current module is built and installed. If is still updating source code when the request is received, will stop after the module source code update is complete. Once both the update and build processes have stopped early, will print its partial results and exit.

How tries to ensure a successful build

Automatic rebuilds
used to include features to automatically attempt to rebuild the module after a failure (as sometimes this re-attempt would work, due to bugs in the build system at that time). Thanks to switching to the build system no longer suffers from these bugs, and so will not try to build a module more than once. There are situations where will automatically take action though:
If you change configure-flags or cmake-options for a module, then will detect that and automatically re-run configure or cmake for that module.
If the buildsystem does not exist (even if did not delete it) then will automatically re-create it. This is useful to allow for performing a full --refresh-build for a specific module without having that performed on other modules.

Manually rebuilding a module
If you make a change to a module's option settings, or the module's source code changes in a way does not recognize, you may need to manually rebuild the module.
You can do this by simply running kdesrc-build --refresh-build module.
If you would like to have automatically rebuild the module during the next normal build update instead, you can create a special file. Every module has a build directory. If you create a file called .refresh-me in the build directory for a module, will rebuild the module next time the build process occurs, even if it would normally perform the faster incremental build.
By default, the build directory is ~/kde/build/module/. If you change the setting of the option, then use that instead of ~/kde/build.
Rebuild using .refresh-me for module kdelibs:

% touch ~/kdesrc/build/kdelibs/.refresh-me
% kdesrc-build

Changing environment variable settings
Normally uses the environment that is present when starting up when running programs to perform updates and builds. This is useful for when you are running from the command line.
However, you may want to change the setting for environment variables that does not provide an option for directly. (For instance, to setup any required environment variables when running on a timer such as ) This is possible with the option.
Unlike most options, it can be set more than once, and it accepts two entries, separated by a space. The first one is the name of the environment variable to set, and the remainder of the line is the value.
Set DISTRO=BSD for all modules:

global
  set-env DISTRO BSD
end global

Resuming builds

Resuming a failed or canceled build
You can tell to start building from a different module than it normally would. This can be useful when a set of modules failed, or if you canceled a build run in the middle. You can control this using the option and the option.
Older versions of would skip the source update when resuming a build. This is no longer done by default, but you can always use the --no-src command line option to skip the source update.
Resuming the build starting from kdebase:

% kdesrc-build --resume-from=kdebase

Resuming the build starting after kdebase (in case you manually fixed the issue and installed the module yourself):

% kdesrc-build --resume-after=kdebase

If the last build ended with a build failure, you can also use the --resume command line option, which resumes the last build starting at the module that failed. The source and metadata updates are skipped as well (but if you need these, it's generally better to use --resume-from instead).

Ignoring modules in a build
Similar to the way you can resume the build from a module, you can instead choose to update and build everything normally, but ignore a set of modules.
You can do this using the option. This option tells to ignore all the modules on the command line when performing the update and build.
Ignoring extragear/multimedia and kdereview during a full run:

% kdesrc-build --ignore-modules extragear/multimedia kdereview

Changing options from the command line

Changing global options
You can change the setting of options read from the configuration file directly from the command line. This change will override the configuration file setting, but is only temporary. It only takes effect as long as it is still present on the command line.
allows you to change options named like option-name by passing an argument on the command line in the form --option-name=value. will recognize whether it does not know what the option is, and search for the name in its list of option names. If it does not recognize the name, it will warn you, otherwise it will remember the value you set it to and override any setting from the configuration file.
Setting the option to /dev/null for testing:

% kdesrc-build --pretend --source-dir=/dev/null

Changing module options
It is also possible to change options only for a specific module. The syntax is similar: --module,option-name=value.
This change overrides any duplicate setting for the module found in the configuration file, and applies only while the option is passed on the command line.
Using a different build directory for the kdeedu module:

% kdesrc-build --kdeedu,build-dir=temp-build