Advanced features

Partially building a module

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

Checking out portions of a module

This is perhaps the best way to do this. When it works, it will save you download time and disk space. What happens is that Kdesvn-build will download only the parts of a module that you specify. This is done using the checkout-only option for a module, which will specify a list of directories to download.

Tip

If you do not already know what to download from a module, it may be a good idea to browse the Subversion layout for a module first, using WebSVN.

To only grab KUser and KDat from kdeadmin, you could use checkout-only like this:

module kdeadmin
  checkout-only kuser kdat
end module

Important

The directories will be built in the order they are listed in the option. If one of the directories needs something else from the module to compile, then you need to make sure they are both in the checkout-only line, and that the required dependency goes before the directory that needs it.

Also, sometimes an application may need other directories and it is hard to figure out what they are, which may require some trial and error of constantly adding directories to the option to figure out.

One final note to make about this option: If you change the value of this option, you should use kdesvn-build --refresh-build module in order to ensure that the module is reconfigured properly. In addition, Kdesvn-build will never remove existing files if you take away the number of directories from your checkout-only option, or add the option to a module that has already been checked out.

Removing directories from a build

Instead of restricting what is downloaded, it is possible to download everything but have the build system leave out a few directories when it does the build. This may be useful if one directory always breaks and is unnecessary to the rest of the module.

This is controlled with the do-not-compile option. It works similar to the checkout-only option just described, in that it is simply a list of directories that should not be compiled.

Important

Also like checkout-only, this option requires at least that the configure script is run again for the module after changing it. This is done using the kdesvn-build --reconfigure module command.

To remove the dcoppython directory from the kdebindings build process:

module kdebindings
  do-not-compile dcoppython
end module

Compiling a few directories from a full module

You can use the inst-apps option to specify that only a few directories out of a full module are to be built (but the entire module is still downloaded).

This option is like the combination of checkout-only and do-not-compile: it downloads the entire module like do-not-compile, but only compiles the directories you specify, like checkout-only. Because of this it is usually better to simply use checkout-only instead.

The same warnings apply as for the other two options: you must reconfigure the module if you change the value of inst-apps.

Using Unsermake

Unsermake is an application designed to hook into the KDE build system and improve the build process by replacing some of the tools normally used (including Automake and Make). It is especially useful for those who are performing distributed compilation as it is much faster than the normal build system in this situation. However, even for a single computer build, Unsermake is faster than the competition.

In addition, Unsermake includes support for estimating the progress of the current build procedure. Kdesvn-build takes advantage of this to provide a build progress indication when compiling. See also the section called “Showing the progress of a module build”.

Kdesvn-build provides support for using Unsermake automatically. Kdesvn-build will use Unsermake by default when it is possible to use it with a module.

To disable Unsermake support for every module, do the following:

global
  use-unsermake false
end global

To enable Unsermake for a single module, even if it is disabled globally, do the following:

module module-name
  use-unsermake true

  # other options go here...
end module

Note

Kdesvn-build will automatically update or checkout Unsermake while performing the other updates. If you prefer to manage Unsermake yourself, then it is possible to do so, by setting the value for use-unsermake to self instead of true.

When this is done, Kdesvn-build will still try to use Unsermake, but will not perform the updates. You can either alter binpath to point to the correct Unsermake directory, or checkout and update Unsermake yourself from its module (currently kdenonbeta/unsermake).

Branching and tagging support for Kdesvn-build

What are branches and tags?

Subversion supports managing the history of the KDE source code. KDE uses this support to create branches for development, and to tag the repository every so often with a new version release.

For example, the KMail 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 /trunk) may have development going on inside of it.

A tag, on the other hand, is a snapshot of the source code repository at a position in time. This is used by the KDE administration team to mark off a version of code suitable for release and still allow the developers to work on the code.

In Subversion, there is no difference between branches, tags, or trunk within the code. It is only a convention used by the developers. This makes it difficult to properly support branches and tags within Kdesvn-build. However, there are some things that can be done.

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 URL to download for advanced users.

The easiest method is to use the branch and tag options. You simply use the option along with the name of the desired branch or tag for a module, and Kdesvn-build will try to determine the appropriate location within the KDE repository to download from. For most KDE modules this works very well.

To download kdelibs from KDE 3.5 (which is simply known as the 3.5 branch):

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

Or, to download kdemultimedia as it was released with KDE 3.4.3:

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

Tip

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!

Advanced branch support options

Kdesvn-build supports two options for situations where branch and tag guess the correct path improperly: module-base-path and override-url.

module-base-path is used to help Kdesvn-build fill in the missing part of a module's path. In the KDE repository, all of the paths are of the form svnRoot/module-base-path/module-name. Normally Kdesvn-build can figure out the appropriate middle part by itself. When it cannot, you can use module-base-path, like this:
```
module qt-copy
  # branch does not work here yet
  module-base-path branches/qt/3.3
end module
```
This would cause Kdesvn-build to download qt-copy from (in this example), svn://anonsvn.kde.org/home/kde/branches/qt/3.3/qt-copy.
The override-url option, on the other hand, requires you to specify the exact path to download from. However, this allows you to pull from paths that Kdesvn-build would have no hope of downloading from.
```
module qt-copy
  # Specify exact path to grab.
  override-url svn://anonsvn.kde.org/home/kde/branches/qt/3.3/qt-copy
end module
```
Important
Kdesvn-build will not touch or correct the value you specify for override-url at all, so if you change your svn-server setting, you may need to update this as well.

How Kdesvn-build tries to ensure a successful build

Automatic rebuilds

Due to various issues with the KDE build system, some of which are mitigated by using Unsermake, Kdesvn-build will automatically perform a series of steps to automatically try to get a module to compile when it fails.

On the first failure, Kdesvn-build will simply re-run the make. Believe it or not, but this sometimes actually works, and is quick to fail if it will not work.
On the second failure, Kdesvn-build will try to reconfigure the module and then rebuild it. This usually catches situations where a build-system file that requires reconfiguration changed, but the build system did not perform that step automatically.
The module build directory is left intact for this step, so, except for the reconfigure step, this will also fail quickly if the build cannot be performed.
If the module still fails to build, Kdesvn-build will give up and move on to the next module. There are still things that you can do to manually try to get the module to build, however.

Note

Kdesvn-build will detect most cases where the build system needs to be reconfigured, and will reconfigure automatically in that case.

Also, if Kdesvn-build was building the module for the first time, all of these steps are skipped, since the clean rebuild does not usually fail except for a real error.

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 Kdesvn-build does not recognize, you may need to manually rebuild the module.

You can do this by simply running kdesvn-build --refresh-build module.

If you would like to have Kdesvn-build 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, Kdesvn-build will rebuild the module next time the build process occurs, even if it would normally perform the faster incremental build.

Tip

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

Rebuild using .refresh-me for module arts:

% touch ~/kdesvn/build/arts
% kdesvn-build

Controlling rebuild behavior

You may not want Kdesvn-build to always try and rebuild a module. You can permanently disable this behavior by changing the option no-rebuild-on-fail to have the value true.

You can disable this behavior temporarily (for one command) by using the --no-rebuild-on-fail command line option.

% kdesvn-build --no-rebuild-on-fail

Changing environment variable settings

Kdesvn-build does not read the environment from the caller like the vast majority of most programs do. Instead, it uses the settings it reads from the configuration file to construct the environment. This is done mainly to ensure that builds are repeatable. In other words, Kdesvn-build can build a module even if you forgot what you set your environment variables to in the shell you ran Kdesvn-build from.

However, you may want to change the setting for environment variables that Kdesvn-build does not provide an option for directly. 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 modules:

global
  set-env DISTRO BSD
end global

Resuming builds

Resuming a failed or canceled build

You can tell Kdesvn-build 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 --resume-from option.

Note

Using --resume-from will skip the source code update.

Resuming the build starting from kdebase:

% kdesvn-build --resume-from=kdebase

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 --ignore-modules option. This option tells Kdesvn-build to ignore all the modules on the command line when performing the update and build.

Ignoring extragear/multimedia and kdenonbeta during a full run:

% kdesvn-build --ignore-modules extragear/multimedia kdenonbeta

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.

Kdesvn-build allows you to change options named like option-name by passing an argument on the command line in the form --option-name=value. Kdesvn-build 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 source-dir option to /dev/null for testing:

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

Disabling Unsermake from the command line. --refresh-build is used to force the changes to Unsermake to take effect.

% kdesvn-build --pretend --refresh-build --use-unsermake=false

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:

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