Advanced features

5.3. Advanced features#

5.3.1. Partially building a project#

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

5.3.1.1. Removing directories from a build#

It is possible to have the build system leave out a few directories when it does the build of a project. This requires that the project uses CMake and that the project's build system allows the directory to remove to be optional.

This is controlled with the do-not-compile option.

Important

This option requires at least that the build system for the project is reconfigured after changing it. This is done using the kde-builder --reconfigure module command.

Note

Possibly outdated info. Curently there is no any active repo under kde/kdebindings.

To remove the python directory from the kdebindings build process:

project kdebindings:
  do-not-compile: python

Note

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

5.3.2. Stopping the build early#

5.3.2.1. Decide the stopping on failures strategy#

KDE Builder can update, build and install all projects in the specified list of projects to build, even if a project 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 KDE Builder to stop what it is doing once a project fails to build and install. This can help save you time that will be wasted trying to make progress when projects remaining in the build list will not be able to successfully build either, especially if you have not ever successfully built the projects in the list.

The primary method to do this is to use the --no-stop-on-failure command line option when you run kde-builder.

This option can also be set in the configuration file to make it the normal mode of operation.

It is also possible to tell kde-builder at runtime to stop building after completing the current project it is working on. This is as opposed to interrupting kde-builder using a shortcut like Ctrl+C, which interrupts kde-builder immediately, losing the progress of the current project.

Important

Interrupting kde-builder during a project install when the use-clean-install option is enabled will mean that the interrupted project will be unavailable until kde-builder is able to successfully build the project!

If you need to interrupt kde-builder without permitting a graceful shutdown in this situation, at least try to avoid doing this while kde-builder is installing a project.

5.3.2.2. Stopping kde-builder gracefully when stop-on-failure is false#

As mentioned above, it is possible to cause kde-builder 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 kde-builder.

You can do this with a command such as pkill (on Linux systems) as follows:

$ pkill -HUP kde-builder

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

[build process] recv SIGHUP, will end after this module

Note

kde-builder may show this message multiple times depending on the number of individual kde-builder processes that are active. This is normal and not an indication of an error.

Once kde-builder has acknowledged the signal, it will stop processing after the current project is built and installed. If kde-builder is still updating source code when the request is received, kde-builder will stop after the project source code update is complete. Once both the update and build processes have stopped early, kde-builder will print its partial results and exit.

5.3.3. How kde-builder tries to ensure a successful build#

5.3.3.1. Automatic rebuilds#

There are situations where KDE Builder will automatically attempt to rebuild the project:

  • If you change configure-flags or cmake-options for a project, then kde-builder will detect that and automatically re-run configure or cmake for that project.

  • If the buildsystem does not exist (even if kde-builder did not delete it) then kde-builder will automatically re-create it. This is useful to allow for performing a full --refresh-build for a specific project without having that performed on other modules.

5.3.3.2. Manually rebuilding a project#

If you make a change to a project's option settings, or the project's source code changes in a way kde-builder does not recognize, you may need to manually rebuild the module.

You can do this by simply running kde-builder --refresh-build project.

If you would like to have kde-builder automatically rebuild the project during the next normal build update instead, you can create a special file. Every project has a build directory. If you create a file called .refresh-me in the build directory for a project, kde-builder will rebuild the project next time the build process occurs, even if it would normally perform the faster incremental build.

Rebuild using .refresh-me for project kcalc:

touch ~/kde/build/kcalc/.refresh-me
kde-builder kcalc

Tip

By default, the build directory is ~/kde/build/project-name/. If you change the setting of the build-dir option, then use that instead of ~/kde/build.

5.3.4. Changing environment variable settings#

Normally kde-builder 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 kde-builder from the command line.

However, you may want to change the setting for environment variables that kde-builder does not provide an option for directly. For instance, to set up any required environment variables when running kde-builder on a timer such as Cron. This is possible with the set-env 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 projects:

global:
  set-env:
    - DISTRO: BSD

Note

Todo: Check the words about setting it more than once.

5.3.5. Resuming builds#

5.3.5.1. Resuming a failed or canceled build#

You can tell kde-builder to start building from a different project than it normally would. This can be useful when a set of projects failed, or if you canceled a build run in the middle. You can control this using the --resume-from option and the --resume-after option.

Resuming the build starting from kxmlgui:

kde-builder --resume-from kxmlgui

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

kde-builder --resume-after kxmlgui

If the last kde-builder build ended with a build failure, you can also use the --resume command line option, which resumes the last build starting at the project 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).

5.3.5.2. Ignoring projects in a build#

Similar to the way you can resume the build from a project, you can instead choose to update and build everything normally, but ignore a set of projects.

You can do this using the --ignore-projects option. This option tells kde-builder to ignore all the projects on the command line when performing the update and build.

Ignoring extragear/multimedia and kdereview during a full run:

kde-builder --ignore-projects extragear/multimedia kdereview

5.3.6. Changing options from the command line#

5.3.6.1. 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.

kde-builder allows you to change options named like <option-name> by passing an argument on the command line in the form --option-name=value. kde-builder 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.

Note

Todo: Check the statement about unrecognised option and searching it in its list.

Setting the source-dir option to /dev/null for testing:

kde-builder --pretend --source-dir=/dev/null

5.3.6.2. Changing project options#

It is also possible to change options only for a specific project. The syntax is similar: --<project>,<option-name>=<value>.

This change overrides any duplicate setting for the project found in the configuration file, and applies only while the option is passed on the command line.

Using a different build directory for the kcalc project:

kde-builder --kcalc,build-dir=temp-build

5.3.7. Installing login session#

It is possible to log into the Plasma session built by KDE Builder. This can be used for testing new features.

In your configuration file, enable the install-login-session option. Build the plasma-workspace project. KDE Builder will install the session at the end of the process.

The installation script requires write access to these locations, so you will be asked to enter a sudo password:

  • /usr/local/share/xsessions/

  • /usr/local/share/wayland-sessions/

  • /opt/kde-dbus-scripts/

  • /etc/dbus-1/session.d/

After that, you can log out, and select the Development session in SDDM session chooser:

Select the development session in SDDM

Kde-builder will keep track of when it needs to rerun the session installation script. This happens when some of the files that are handled by installation script are changed. When installation is not needed, it is not run, so it will not bother you to enter sudo password.