# &kdesrc-build; Script Manual

## Introduction

&kdesrc-build; is a script to help users install &kde; software from its &subversion; and &git; source repositories.

This software used to be called kdesvn-build, so you may still see references to kdesvn-build on the Internet or in your installed documentation.

This guide is an overview to describe the following aspects of &kdesrc-build; operation:

- An overview of the steps required to get started.

- Notable features.

- The configuration file syntax and options.

- The command line options.

Also documented are the steps which you should perform using other tools, (in other words, steps that are not automatically performed by &kdesrc-build;).

## Getting Started

In this chapter, we show how to use the &kdesrc-build; to checkout modules from the &kde; repository and build them. We also provide a basic explanation of the &kde; &subversion; structure and the steps you have to perform before running the script.

All topics present in this chapter are covered with even more detail in the Building &kde; 4 from Source article, at the &kde; TechBase site. If you are compiling &kde; for the first time, it is a good idea to read it, or consult it as a reference source. You will find detailed information about packaging tools and requirements, common compilation pitfalls and strategies and information about running your new &kde; installation.

### Preparing the System to Build &kde;

#### Setup a new user account

It is recommended that you use a different user account to build, install, and run your &kde; software from, since less permissions are required, and to avoid interfering with your distribution's packages. If you already have &kde; packages installed, the best choice would be to create a different (dedicated) user to build and run the new &kde;.

Leaving your system &kde; untouched also allows you to have an emergency fallback in case a compiled &kde; is unstable for whatever reason.

Later, you can do a system installation if you wish. This document does not cover a system installation. If you are performing a system wide install, you should already know what you are doing. If not, then you may want to consult the documentation, or help sites, for your distribution in order to prepare and use the system installation correctly.

#### Ensure your system is ready to build &kde; source

Before using the &kdesrc-build; script (or any other building strategy) you must install the development tools and libraries needed for &kde;. The complete list of required tools can be found from the KDE TechBase.

Here is a list of some of the things you will need:

- You will need &cmake;. The required version will vary depending on what version of &kde; 4 you are building, see TechBase for specifics.

- Also needed is the &subversion; client program. You can check if you have it by running ``svn `--version```.

- You will also need the Git source control manager installed as well, for &kde;'s git-based projects. .

- You will need a C++ development environment. GCC 4.2 or later is recommended.

Most operating system distributions include a method of easily installing required development tools. Consult the TechBase Getting Started page's Required Packages from your Distribution section to see if these instructions are already available.

One exception to the required libraries is the &Qt; library. &kdesrc-build; will normally install a copy of &Qt; whether you have it installed or not, so it is not necessary for you to have it. If you do not want to use the &Qt; copy, you need to do these things:

- Make sure to remove the qt module from your configuration file, as you will not need it, and having it would add extra time to your build.

- Change the setting of the qtdir option in your configuration file to point to your system &Qt;. This is normally equal to the setting of $`QTDIR` for your system.

- If you do not already have &Qt; installed, install it, including any relevant -dev or -devel packages. You will need at least &Qt; 4.7 if you are building &kde; 4.

Some of these packages are divided into libraries (or programs or utilities), and development packages. You will need at least the program or library and its development package. If in doubt, install all. The libraries you need will change depending on the modules you intend to build, as each module has its own requirements. The &kde; TechBase has more details about the specific tools and techniques used to install and find the required software.

#### Setup &kdesrc-build;

##### Install &kdesrc-build;

You probably already have a version of the &kdesrc-build; script installed in your system. However, if you do not, you can download it from &kdesrc-build; home page, or you can find it from its home in the &kde; source repository.

If you use a more recent &kdesrc-build; by downloading from its website, you should remember to run the &kdesrc-build; script you downloaded. You can use the `--version` option to &kdesrc-build; as a quick way to verify this.

1. To download &kdesrc-build; from its home page, simply go to the &kdesrc-build; home page and download the latest appropriate release. The release is packaged as a compressed tarball archive, which you can extract using &ark; or `tar`. The contents of the archive include the actual &kdesrc-build; script, a sample configuration file (`kdesrc-buildrc-sample`), and a quick-setup program.

2. Or, you can obtain &kdesrc-build; from its source repository, located at: http://quickgit.kde.org/?p=kdesrc-build.git&a=tree&hb=refs/heads/master. You can click on the `kdesrc-build` entry which will bring you to a page where you can download the latest revision. Click on the plain link for the file to download it directly, and save it to a convenient spot on your hard disk. Do the same for `kdesrc-buildrc-sample` if you need to.

No matter which technique you use, you need to make sure that the `kdesrc-build` file is executable. For convenience you should make sure it is in a directory contained in the `PATH` environment variable, otherwise you may get messages saying that the command was not found, or you may run a previously-installed version by mistake.

##### Prepare the configuration file

&kdesrc-build; uses a configuration file (located at `~/.kdesrc-buildrc`) to control which modules are built, where they are installed to, etc.

You can use a program included with &kdesrc-build;, called kdesrc-build-setup in order to prepare a simple kdesrc-build configuration. You can then edit the `~/.kdesrc-buildrc` from there to make any changes you see fit.

kdesrc-build-setup itself runs from a terminal (instead of using a graphical interface), just like &kdesrc-build;, so you can use it even if you have no graphical interface available yet.

You can use the included `kdesrc-buildrc-sample` sample configuration to get explanations as to the various options available.

You can find more information about the syntax of the configuration file in configure-data and in kdesrc-buildrc.

### Setting the Configuration Data

To use &kdesrc-build;, you should have a file in your home directory called `.kdesrc-buildrc`, which sets the general options and sets the modules you would like to download and build.

It is possible to use different configuration files for &kdesrc-build;, which is described in kdesrc-buildrc. If you need to use multiple configurations, please see that section. Here, we will assume the configuration is stored in `~/.kdesrc-buildrc`.

The easiest way to proceed is to use the `kdesrc-buildrc-sample` file as a template, changing global options to match your wants, and also change the list of modules you want to build.

The default settings should actually already be appropriate to perform a &kde; build. Some settings that you may wish to alter include:

- use-stable-kde to change the default version of &kde; modules to build. By default &kdesrc-build; will build the trunk version of &kde;. If you want to build the latest stable release of &kde; instead of using your distribution packages you would set this option to `true`.

  Note that this option relies on information available from the &kde; project database, so this feature only works for these modules. See also kde-projects-module-sets.

- kdedir, which changes the destination directory that &kde; is installed to. This defaults to `~/kde`, which is a single-user installation.

- qtdir, which controls the path to the installation of &Qt; to use. The default is to use a &Qt; compiled by &kdesrc-build;, using the special qt module and the latest available source code. (`~/kdesrc/build/qt`).

  This also controls where to install qt.

- svn-server, which selects what &url; to download the sources from. This is useful if you are a developer with a &kde; &subversion; account.

Continue to kde-modules-and-selection to see how to change how much of &kde; is built.

### Module Organization and selection

#### KDE Software Organization

&kde; software is split into different components, many of which can be built by &kdesrc-build;. Understanding this organization will help you properly select the software modules that you want built.

1. At the lowest level comes Nokia's &Qt; library, which is a very powerful, cross-platform toolkit library. &kde; is based on &Qt;, and some of the non-&kde; libraries required by &kde; are also based on &Qt;. &kdesrc-build; can build &Qt;, or use the one already installed on your system if it is a recent enough version.

2. On top of &Qt; are required libraries that are necessary for &kde; software to work. Some of these libraries are not considered part of &kde; itself due to their generic nature, but are still essential to the &kde; Platform. These libraries tended to get combined into a single `kdesupport` module.

   As of &kde; Platform 4.6, many of these kdesupport modules are being migrated over to git.kde.org, although they are still not considered part of the Platform.

3. On top of these essential libraries comes the &kde; Platform. These are the libraries that are required for &kde; applications to work. A full desktop environment is not provided by the Platform however.

   For &kdesrc-build;, the Platform layer consists of the `kdelibs`, `kdepimlibs`, and `kde-runtime` modules.

4. On top of the Platform, come several different things:

   - Third-party applications. These are applications that use the &kde; Platform but are not authored by or in association with the &kde; project.

   - A full workspace desktop environment. This is what users normally see when they log-in to &kde;. This is provided by the &plasma; Desktop, mostly in `kde-workspace`.

   - The &kde; Software Compilation. This is a collection of useful software included with the Platform and &plasma; Desktop, grouped into individual modules. These are the modules that have names starting with `kde`. For example, `kdepim` is a component of the Software Compilation that contains email, news-reading, calendar/organizational software, &etc;, while `kdegames` contains a collection of high-quality games to while away the time.

   - Finally, there is a collection of software (also collected in modules) whose development is supported by &kde; resources (such as translation, source control, bug tracking, &etc;) but is not released by &kde; or considered part of the Software Compilation. These modules are known as Extragear, and have module names such as `extragear/network`. As with `kdesupport`, some of these Extragear applications are migrating to git.kde.org.

#### Selecting modules to build

Selecting which of the possible modules to build is controlled by the configuration file. After the `global` section is a list of modules to build, bracketed by module ... end module lines. An example entry for a module is shown in conf-module-example.

##### Example module entry in the configuration file

    module module-name
        # Options for this module go here, example:
        make-options -j4 # Run 4 compiles at a time
    end module

It is possible to declare a module with no options. In fact, most of your modules will likely be declared this way.

&kdesrc-build; only builds the modules you have listed in your configuration file. In addition, the modules are built in the order specified in the configuration file. For this reason you should ensure that the order of modules in your configuration file is consistent with the organization given in kde-layers.

There is a sample file that comes with &kdesrc-build; called `kdesrc-buildrc-sample`. It is recommended to copy this file to a file called `~/.kdesrc-buildrc` (Note the leading period in front of kdesrc-buildrc!). Afterwards, edit the new file to adjust the default options to your liking. (Each option is described in more detail in kdesrc-buildrc). The default modules should be enough to ensure a fairly complete &kde; installation, however you can remove many of the modules that show up after `kdebase` if you'd like to save disk space or build time.

#### Module Sets

&kdesrc-build; is usually able to guess where to download the source code for a given module quite easily, by using your setting for svn-server and the module name for each module to create a single Subversion URL, which describes exactly where to download the source code from.

With the move to Git, many larger Subversion modules were further sub-divided in the process, and there was no guarantee of where to find a module based just on the module name. Because of this, a concept called module sets was developed for &kdesrc-build; 1.12.1.

By using a module set, you can quickly declare many Git modules to be downloaded and built, as if you'd typed out a separate module declaration for each one. The repository option is handled specially to setup where each module is downloaded from, which every other option contained in the module set is copied to every module generated in this fashion.

##### Using module sets

    global
        git-repository-base kde-git kde:
    end global

    module qt
        # Options removed for brevity
    end module

    module-set kde-support-libs
        repository kde-git
        use-modules automoc attica akonadi
    end module-set

    # Other modules as necessary...
    module kdesupport
    end module

In example-using-module-sets a brief module set is shown. When &kdesrc-build; encounters this module set, it acts as if, for every module given in `use-modules`, that an individual module has been declared, with its `repository` equal to the module-set's `repository` followed immediately by the given module name.

In addition, other options can be passed in a module set, which are copied to every new module that is created this way. By using module-set it is possible to quickly declare many Git modules that are all based on the same repository URL. In addition, since &kdesrc-build; 1.13, it is possible to give module-sets a name (as shown in the example), which allows you to quickly refer to the entire group of modules from the command line.

Module sets are used in supporting module downloads from the &kde; projects.kde.org module database. See also kde-projects-module-sets.

Module sets use the options

- git-repository-base
- use-modules

#### Automatically finding modules from the official &kde; module database

With the migration of &kde; source code to be hosted on git.kde.org, there has been an explosive growth in the number of modules (for instance, a single Subversion module called `kdegraphics` becomes 16 different Git modules).

This was done mostly because each Git module contains the entire project history (this is actually less wasteful of disk space than it sounds for the vast majority of &kde; repositories as &git; is highly efficient at storing repositories).

&kde; allows for grouping Git repositories into collections of related modules (e.g. kdegraphics). These modules can themselves be grouped (e.g. &kde; Software Compilation). Git doesn't recognize these groupings, but &kdesrc-build; can be configured to handle these groups.

The way this is done is by using module sets. Instead of using a specific `git://` repository, or a repository name created by git-repository-base, a special repository name, `kde-projects` is used.

&kdesrc-build; will recognize that the `kde-projects` repository requires special handling, and adjust the build process appropriately. Among other things, &kdesrc-build; will:

- Download the latest module database from projects.kde.org.

- Try to find a module with the name given in the module set's `use-modules` setting.

- For every module that is found, &kdesrc-build; will see if a repository setting exists for that module in the database. If there is a repository, &kdesrc-build; will automatically use that to download or update the source code. If there is no repository, &kdesrc-build; treats that module like a group, and tries to include all &git; source repositories that it finds in that group.

In the current database, some module groups not only have a collection of modules, but they also declare their own &git; repository. In these situations &kdesrc-build; will currently prefer the group's &git; repository instead of including the childrens' repositories.

The following example shows how to use the &kde; module database to install the Phonon multimedia library.

    module-set media-support
        # This option must be kde-projects to use the module database.
        repository kde-projects

        # This option chooses what modules to look for in the database.
        use-modules phonon/phonon phonon-gstreamer phonon-vlc
    end module-set

`phonon/phonon` is used since (with the current project database) &kdesrc-build; would otherwise have to decide between the group of projects called phonon or the individual project named phonon. Currently &kdesrc-build; would pick the former, which would build many more backends than needed.

The following example is perhaps more realistic, and shows a feature only available with the &kde; module database: Building all of the &kde; graphics applications with only a single declaration.

    module-set kdegraphics
        # This option must be kde-projects to use the module database.
        repository kde-projects

        # This option chooses what modules to look for in the database.
        use-modules kdegraphics/libs kdegraphics/*
    end module-set

There are two important abilities demonstrated here:

1. &kdesrc-build; allows you to specify modules that are descendents of a given module, without building the parent module, by using the syntax ``module-name`/*`. It is actually required in this case since the base module, kdegraphics, is marked as inactive so that it is not accidentally built along with its children modules. Specifying the descendent modules allows &kdesrc-build; to skip around the disabled module.

2. &kdesrc-build; will also not add a given module to the build list more than once. This allows us to manually set `kdegraphics/libs` to build first, before the rest of `kdegraphics`, without trying to build `kdegraphics/libs` twice. This is required at this point because &kdesrc-build; will not perform dependency handling.

### Using the &kdesrc-build; script

Now you are ready to run the script. From a terminal window, log in to the user you are using to compile &kde; and execute the script:

    % kdesrc-build

Afterwards, you should see output similar to that in example-single-module:

#### Example output of building a single module

    % kdesrc-build kdelibs
    Script started processing at Wed Dec 22 13:21:45 2010
    <<<  Build Process  >>>
    Building kdelibs (1/1)
            Waiting for source code update.
            Source update complete for kdelibs: 48 files affected.
            Checking for source conflicts...
            Compiling...
            Build succeeded after 13 minutes, and 6 seconds.
            Installing kdelibs.
            Overall time for kdelibs was 13 minutes, and 53 seconds.

    <<<  Build Done  >>>

    <<<  PACKAGES SUCCESSFULLY BUILT  >>>
    kdelibs

    Script finished processing at Wed Dec 22 13:35:38 2010
    Your logs are saved in /home/kde-src/log-kdesrc-build/2010-12-22-01

At this point, &kdesrc-build; should start downloading the sources and compiling them. Depending on how many modules you are downloading, it is possible that &kdesrc-build; will not succeed the first time you compile &kde;. Do not despair!

&kdesrc-build; logs the output of every command it runs. By default, the log files are kept in `~/kdesrc/log`. To see what the caused an error for a module in the last &kdesrc-build; command, usually it is sufficient to look at `~/kdesrc/log/latest/`module-name`/error.log`.

Perhaps the easiest way to find out what error caused a module to fail to build is to search backward with a case-insensitive search, starting from the end of the file looking for the word `error`. Once that is found, scroll up to make sure there are no other error messages nearby. The first error message in a group is usually the underlying problem.

In that file, you will see the error that caused the build to fail for that module. If the file says (at the bottom) that you are missing some packages, try installing the package (including any appropriate -dev packages) before trying to build that module again. Make sure that when you run &kdesrc-build; again to pass the --reconfigure option so that &kdesrc-build; forces the module to check for the missing packages again.

Or, if the error appears to be a build error (such as a syntax error, incorrect prototype, unknown type, or similar) then it is probably an error with the &kde; source, which will hopefully be resolved within a few days. If it is not resolved within that time, feel free to mail the kde-devel@kde.org mailing list (subscription may be required first) in order to report the build failure.

You can find more common examples of things that can go wrong and their solutions, as well as general tips and strategies to build &kde; in the Building &kde; 4 from Source.

On the other hand, assuming everything went well, you should have a new &kde; install on your computer, and now it is simply a matter of running it, described next in environment.

For more information about &kdesrc-build;'s logging features, please see kdesrc-build-logging.

### Setting the Environment to Run Your Fresh &kde;

Assuming you are using a dedicated user to build &kde;, and you already have an installed &kde; version, running your new &kde; may be a bit tricky, as the new &kde; has to take precedence over the old. Change the environment variables to make sure it does.

#### Changing your startup profile settings

The `.bash_profile` is the login settings file for the popular bash shell used by many &Linux; distributions. If you use a different shell, then you may need to adjust the samples given in this section for your particular shell.

Open or create the `.bash_profile` file in the home directory with your favorite editor, and add to the end of the file: If you are building the qt module (you are by default), add instead:

    QTDIR=(path to qtdir)   # Such as ~/kdesrc/build/qt by default.
    KDEDIR=(path to kdedir) # Such as ~/kde by default.
    KDEDIRS=$KDEDIR
    PATH=$KDEDIR/bin:$QTDIR/bin:$PATH
    MANPATH=$QTDIR/doc/man:$MANPATH

    # Act appropriately if LD_LIBRARY_PATH is not already set.
    if [ -z $LD_LIBRARY_PATH ]; then
      LD_LIBRARY_PATH=$KDEDIR/lib:$QTDIR/lib
    else
      LD_LIBRARY_PATH=$KDEDIR/lib:$QTDIR/lib:$LD_LIBRARY_PATH
    fi

    export QTDIR KDEDIRS PATH MANPATH LD_LIBRARY_PATH

or, if you are not building qt (and are using your system &Qt; instead), add this instead:

    KDEDIR=(path to kdedir)  # Such as ~/kde by default.
    KDEDIRS=$KDEDIR
    PATH=$KDEDIR/bin:$QTDIR/bin:$PATH

    # Act appropriately if LD_LIBRARY_PATH is not already set.
    if [ -z $LD_LIBRARY_PATH ]; then
      LD_LIBRARY_PATH=$KDEDIR/lib
    else
      LD_LIBRARY_PATH=$KDEDIR/lib:$LD_LIBRARY_PATH
    fi

    export KDEDIRS PATH LD_LIBRARY_PATH

If you are not using a dedicated user, set a different $`KDEHOME` for your new environment in your `.bash_profile`:

    export KDEHOME="${HOME}/.kde-svn"

    # Create it if needed
    [ ! -e ~/.kde-svn ] && mkdir ~/.kde-svn

If later your K Menu is empty or too crowded with applications from your distribution, you may have to set the XDG environment variables in your `.bash_profile`:

    XDG_CONFIG_DIRS="/etc/xdg"
    XDG_DATA_DIRS="${KDEDIR}/share:/usr/share"
    export XDG_CONFIG_DIRS XDG_DATA_DIRS

#### Starting &kde;

Now that you have adjusted your environment settings to use the correct &kde;, it is important to ensure that the correct `startkde` script is used as well.

Open the `.xinitrc` text file from the home directory, or create it if necessary. Add the line:

    exec ${KDEDIR}/bin/startkde

On some distributions, it may be necessary to perform the same steps with the `.xsession` file, also in the home directory. This is especially true when using graphical login managers such as &kdm;, gdm, or xdm.

Now start your fresh &kde;: in &BSD; and &Linux; systems with virtual terminal support, &Ctrl;&Alt;F1 ... &Ctrl;&Alt;F12 keystroke combinations are used to switch to Virtual Console 1 through 12. This allows you to run more than one desktop environment at the same time. The fist six are text terminals and the following six are graphical displays.

If when you start your computer you are presented to the graphical display manager instead, you can use the new &kde; environment, even if it is not listed as an option. Most display managers, including &kdm;, have an option to use a Custom Session when you login. With this option, your session settings are loaded from the `.xsession` file in your home directory. If you have already modified this file as described above, this option should load you into your new &kde; installation.

If it does not, there is something else you can try that should normally work: Press &Ctrl;&Alt;F2, and you will be presented to a text terminal. Log in using the dedicated user and type:

    startx -- :1

You can run the &kde; from sources and the old &kde; at the same time! Log in using your regular user, start the stable &kde; desktop. Press &Ctrl;&Alt;F2 (or F1, F3, etc..), and you will be presented with a text terminal. Log in using the dedicated &kde; &subversion; user and type:

    startx -- :1

You can go back to the &kde; desktop of your regular user by pressing the shortcut key for the already running desktop. This is normally &Ctrl;&Alt;F7, you may need to use F6 or F8 instead. To return to your &kdesrc-build;-compiled &kde;, you would use the same sequence, except with the next function key. For example, if you needed to enter &Ctrl;&Alt;F7 to switch to your regular &kde;, you would need to enter &Ctrl;&Alt;F8 to go back to your &kdesrc-build; &kde;.

## Script Features

### Feature Overview

&kdesrc-build; features include:

- You can pretend to do the operations. If you pass `--pretend` or `-p` on the command line, the script will give a verbose description of the commands it is about to execute, without actually executing it.

  For an even more verbose description of what &kdesrc-build; is doing, try using the `--debug` option.

- &kdesrc-build; can (with the assistance of the &kde; FTP server) allow for speedy checkouts of some Subversion modules. If the module you are checking out has already been packaged at the website, then &kdesrc-build; will download the snapshot and prepare it for use on your computer.

  There is generally no need for any special preparation to perform the initial checkout of a Git module, as the entire Git repository must be downloaded anyways, so it is easy for the server to determine what to send.

  This is faster for you, and helps to ease the load on the kde.org anonymous &subversion; servers.

- Another speedup is provided by starting the build process for a module as soon as the source code for that module has been downloaded. (Available since version 1.6)

- Excellent support for building the &Qt; library, including optionally applying &kde;-recommended bugfix and optimization patches to the module.

  For historical reasons, the &kdesrc-build; module used to build &Qt; should be called `qt`. See also using-qt.

- &kdesrc-build; does not require a GUI present to operate. So, you can build &kde; without needing an alternate graphical environment.

- Supports setting default options for all modules (such as the compilation settings or the configuration options). Such options can normally be changed for specific modules as well.

  Also, &kdesrc-build; will add standard flags as appropriate to save you the trouble and possible errors from typing them yourself.

- &kdesrc-build; can checkout a specific branch or tag of a module. You can also ensure that a specific revision is checked out of a module.

- &kdesrc-build; can automatically switch a source directory to checkout from a different repository, branch, or tag. This happens automatically when you change an option that changes what the repository &url; should be, but you must use the --src-only option to let &kdesrc-build; know that it is acceptable to perform the switch.

- &kdesrc-build; can checkout only portions of a module, for those situations where you only need one program from a large module.

- For developers: &kdesrc-build; will remind you if you use svn+ssh:// but ssh-agent is not running, as this will lead to repeated password requests from &ssh;.

- Can delete the build directory of a module after its installation to save space at the expense of future compilation time.

- The locations for the directories used by &kdesrc-build; are configurable (even per module).

- Can use &sudo;, or a different user-specified command to install modules so that &kdesrc-build; does not need to be run as the super user.

- &kdesrc-build; runs with reduced priority by default to allow you to still use your computer while &kdesrc-build; is working.

- Has support for using &kde;'s tags and branches.

- There is support for resuming a build from a given module. You can even ignore some modules temporarily for a given build.

- &kdesrc-build; can quickly perform a partial build of a module directly from the command line, when you only need to update part of a module.

- &kdesrc-build; will show the progress of your build when using &cmake;, and will always time the build process so you know after the fact how long it took.

- Comes built-in with a sane set of default options appropriate for building a base &kde; single-user installation from the anonymous source repositories.

- Tilde-expansion for your configuration options. For example, you can specify:

      qtdir ~/kdesrc/build/qt

- Automatically sets up a build system, with the source directory not the same as the build directory, in order to keep the source directory pristine.

- You can specify global options to apply to every module to check out, and you can specify options to apply to individual modules as well.

- Forced full rebuilds, by running &kdesrc-build; with the `--refresh-build` option.

- You can specify various environment values to be used during the build, including `KDEDIR`, `QTDIR`, `DO_NOT_COMPILE`, and `CXXFLAGS`.

- Command logging. Logs are dated and numbered so that you always have a log of a script run. Also, a special symlink called latest is created to always point to the most recent log entry in the log directory.

- You can check out only a portion of a &kde; &subversion; module. For example, you could check out only the taglib from kdesupport.

### &kdesrc-build;'s build logging

#### Logging overview

Logging is a &kdesrc-build; feature whereby the output from every command that &kdesrc-build; runs is saved to a file for examination later, if necessary. This is done because it is often necessary to have the output of these programs when there is a build failure, because there are so many reasons why a build can fail in the first place.

##### Logging directory layout

The logs are always stored under the log directory. The destination of the log directory is controlled by the log-dir option, which defaults to `${source-dir}/log` (where ${source-dir} is the value of the source-dir option. The in rest of this section, this value will be referred to as ${log-dir}).

Under ${log-dir}, is a set of directories, one for every time that &kdesrc-build; was run. Each directory is named with the date, and the run number. For instance, the second time that &kdesrc-build; is run on May 26, 2004, it would create a directory called `2004-05-26-02`, where the 2004-05-26 is for the date, and the -02 is the run number.

For your convenience, &kdesrc-build; will also create a link to the logs for your latest run, called `latest`. So the logs for the most recent &kdesrc-build; run should always be under `${log-dir}/latest`.

Now, each directory for a &kdesrc-build; run will itself contain a set of directories, one for every &kde; module that &kdesrc-build; tries to build. Also, a file called `build-status` will be contained in the directory, which will allow you to determine which modules built and which failed.

If a module itself has a submodule (such as extragear/multimedia, playground/utils, or KDE/kdelibs), then there would actually be a matching layout in the log directory. For example, the logs for KDE/kdelibs after the last &kdesrc-build; run would be found in `${log-dir}/latest/KDE/kdelibs`, and not under `${log-dir}/latest/kdelibs`.

In each module log directory, you will find a set of files for each operation that &kdesrc-build; performs. If &kdesrc-build; updates a module, you may see filenames such as `svn-co.log` (for a module checkout) or `svn-up.log` (when updating a module that has already been checked out). If the `configure` command was run, then you would expect to see a `configure.log` in that directory.

If an error occurred, you should be able to see an explanation of why in one of the files. To help you determine which file contains the error, &kdesrc-build; will create a link from the file containing the error (such as `build-1.log` to a file called `error.log`).

The upshot to all of this is that to see why a module failed to build after your last &kdesrc-build;, the file you should look at first is `${log-dir}/latest/`module-name`/error.log`.

If the file `error.log` is empty (especially after an installation), then perhaps there was no error. Some of the tools used by the &kde; build system will sometimes mistakenly report an error when there was none.

Also, some commands will evade &kdesrc-build;'s output redirection and bypass the log file in certain circumstances (normally when performing the first &subversion; checkout), and the error output in that case is not in the log file but is instead at the &konsole; or terminal where you ran &kdesrc-build;.

## Configuring &kdesrc-build;

### Overview of &kdesrc-build; configuration

To use the script, you must have a file in your home directory called `.kdesrc-buildrc`, which describes the modules you would like to download and build.

#### Layout of the configuration file

##### Global configuration

The configuration file starts with the global options, specified like the following:

    global
    option-name option-value
    [...]
    end global

##### Module configuration

It is then followed by one or more module sections, specified in one of the following two forms:

-     module module-name
      option-name option-value
      [...]
      end module

-     module-set module-set-name
        repository kde-projects or git://host.org/path/to/repo.git
        use-modules module-names

      # Other options may also be set
      option-name option-value
      [...]
      end module-set

Note that the second form, module sets, only works for Git-based modules.

For Subversion modules, `module-name` must be a module from the &kde; &subversion; repository (for example, kdeartwork or kde-wallpapers), although it is possible to get around this if you manually specify the &subversion; URL.

For Git modules, the module name can be essentially whatever you'd like, as long as it does not duplicate any other module name in the configuration. Keep in mind the source and build directory layout will be based on the module name if you do not use the dest-dir option.

However, for Git module sets the `module-names` must correspond with actual git modules in the chosen `repository`. See git-repository-base or use-modules for more information.

#### Including other configuration files

Within the configuration file, you may reference other files by using the `include` keyword with a file, which will act as if the file referenced had been inserted into the configuration file at that point.

For example, you could have something like this:

    global
        include ~/common-kdesrc-build-options

        # Insert specific options here.

    end global

#### Commonly used configuration options

The following is a list of commonly-used options. Click on the option to find out more about it. To see the full list of options, see conf-options-table.

- cmake-options to define what flags to configure a module with using &cmake;.

- branch, to checkout from a branch instead of /trunk (for &subversion;) or `master` (for Git).

- configure-flags to define what flags to configure &Qt; with.

- kdedir, to set the directory to install &kde; to.

- make-options, to pass options to the &make; program (such as number of CPUs to use).

- qtdir, to set the path to &Qt;.

- source-dir, to change where to download the source code to.

### Table of available configuration options

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 of Options

Option-name | Module -> Global Behavior | Notes
apidox |  | 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 using-qt 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 `false` 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 the $`PATH` that is set when the script starts. This environment variable should include the colon-separated paths of your development toolchain. The paths `$`KDEDIR`/bin` and `$`QTDIR`/bin` are automatically added. You may use the tilde (~) for any paths you add using this option.
branch | Module setting overrides global | Set this option to checkout from a branch of &kde; instead of the default of `trunk`, where &kde; development occurs. For instance, to checkout &kde; 4.6 branch, you would set this option to `4.6`. If &kdesrc-build; fails to properly download a branch with this option, you may have to manually specify the &url; to download from using the module-base-path or override-url options. Note: This option also works with source modules that use &git; instead of &subversion;.
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: Relative to the &kde; &subversion; source directory (see the source-dir option). This is the default, and is selected if you type a directory name that does not start with a tilde (~) or a slash (/). The default value is `build`. Absolute path. If you specify a path that begins with a /, then that path is used directly. For example, `/tmp/kde-obj-dir/`. Relative to your home directory. If you specify a path that begins with a ~, then the path is used relative to your home directory, analogous to the shell's tilde-expansion. For example, `~/builddir` would set the build directory to `/home/user-name/builddir`. 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. By setting `build-when-unchanged` to `true`, &kdesrc-build; always attempts the build phase for a module, even if the module did not have any source code updates. This is the default setting since it is more likely to lead to a correct build. By setting `build-when-unchanged` to `false`, &kdesrc-build; will only attempt to run the build phase for a module if the module has a source code update, or in other situations where it is likely that a rebuild is actually required. This can save time, especially if you run &kdesrc-build; daily, or more frequently. 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 checking-out-parts 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:
      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)
colorful-output | Cannot be overridden | Set this option to `false` to disable the colorful output of &kdesrc-build;. This option defaults to `true`. Note that &kdesrc-build; will not output the color codes to anything but a terminal (such as xterm, &konsole;, or the normal &Linux; console).
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.
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 `CXXFLAGS` during the build process. Note that for &kde; 4 and any other modules that use &cmake;, it is necessary to set the CMAKE_BUILD_TYPE option to "none" when configuring the module. This can be done using the cmake-options option.
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 `disable-agent-check` to `true`.
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 not-compiling for an example.
email-address | Cannot be overridden | This option was removed in kdesrc-build 2.0.
email-on-compile-error | Cannot be overridden | This option was removed in kdesrc-build 2.0.
inst-apps |  | This option was removed in version 1.10
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 kde-git kde:
    end global

    # Module declarations

    module-set
       # Now you can use the alias you defined earlier, but only
       # in a module-set.
       repository kde-git

       use-modules module1.git module2.git
    end module-set
The module-set's `use-modules` option created two modules internally, with &kdesrc-build; behaving as if it had read:
    module module1
        repository kde:module1.git
    end module

    module module2
        repository kde:module2.git
    end module
The `kde:` &git; repository prefix used above is a shortcut which will be setup by &kdesrc-build; automatically. See the TechBase URL Renaming article for more information. Note that unlike most other options, this option can be specified multiple times in order to create as many aliases as necessary. 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.
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 `false` in the configuration file. You can also use the `--no-install` command line flag.
kdedir | Module setting overrides global | This option sets the directory that &kde; will be installed to after it is built. It defaults to `~/kde`. If you change this to a directory needing root access, you may want to read about the make-install-prefix option as well.
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 something like: ``kde-languages` `fr``. You would still need to use &systemsettings; in order to choose the French language, however.
libpath | Module setting overrides global | Set this option to set the environment variable `LD_LIBRARY_PATH` while building. You cannot override this setting in a module option. The default value is blank, but the paths `$`KDEDIR`/lib` and `$`QTDIR`/lib` are automatically added. You may use the tilde (~) for any paths you add using this option.
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` `install`` command used to install modules. This is useful for installing packages with &sudo; for example, but please be careful while dealing with root privileges.
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 `true` to keep the build process from attempting to build this module. It will still be kept up-to-date when updating from &subversion;. This option is exactly equivalent to the `--no-build` command line option.
manual-update | Module setting overrides global | Set the option value to `true` to keep the build process from attempting to update (and by extension, build or install) this module. If you set this option for a module, then you have essentially commented it out.
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 following template: ``$svn-server`/home/kde/`$module-base-path``. The default value is either `trunk/`$module`` or `trunk/KDE/`$module``, depending on the module name. Use the branch or tag options instead whenever they are applicable.
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-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 `.kdesrc-build-data` placed in the same directory as the configuration file in use. If you have multiple available configurations in the same directory you may want to manually set this option so that the different configurations do not end up with conflicting persistent data. This option was added with &kdesrc-build; 1.15.
prefix | Module setting overrides global | This option controls where to install the module (normally the `kdedir` setting is used). Using this option allows you to install a module 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 `${MODULE}` or `$MODULE` in the path to have them expanded to the module's name.
purge-old-logs | Module setting overrides global | This option controls whether old log directories are automatically deleted or not. The default value is `true`.
qtdir | Module setting overrides global | Set this option to set the environment variable `QTDIR` while building. You cannot override this setting in a module option. If you do not specify this option, it defaults to `${source-dir}/build/qt`, which uses the qt module included in the &kde; source repository. You may use a tilde (~) to represent your home directory.
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: none - Do not delete anything (This is the default). builddir - Delete the build directory, but not the source. all - Delete both the source code and build directory. Note that using this option can have a significant detrimental impact on both your bandwidth usage (if you use `all`) and the time taken to compile &kde;, since &kdesrc-build; will be unable to perform incremental builds.
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 &subversion; 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.
run-tests | Module setting overrides global | If set to `true`, then the module will be built with support for running its test suite, and the test suite will be executed as part of the build process. &kdesrc-build; will show a simple report of the test results. This is useful for developers or those who want to ensure their system is setup correctly.
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 `RONALD` to McDonald, you would put in the appropriate section this command:
    set-env RONALD McDonald
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 `~/kdesrc`. You may use the tilde (~) to represent the home directory if using this option.
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: ssh-agent-reminder. This option was added in version 1.14.2.
stop-on-failure | Module setting overrides global | Set this option value to `true` to cause the script to stop execution after an error occurs during the build or install process. This option is off by default.
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, `svn://anonsvn.kde.org/` 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. 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; FTP site or one of its mirrors.
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 `true`.
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 `module-set`. Every identifier passed to this option is internally converted to a &kdesrc-build; module, with a `repository` option set to the module-set's repository combined with the identifier name in order to setup the final repository to download from. All other options that are assigned in the module-set are also copied to the generated modules unaltered. 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-modules`, with the exception that any `.git` is removed. See module-sets and git-repository-base for a description of its use and an example.
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 `true`, &kdesrc-build; will (for a given module) automatically download the version of that module which is marked as stable in kde_projects.xml. 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.

## Command Line Options and Environment Variables

### Command Line Usage

&kdesrc-build; is designed to be run as follows:

    kdesrc-build
    --options
    modules to build

If no modules to build are specified on the command line, then kdesrc-build will build all modules defined in its configuration file, in the order listed in that file (although this can be modified by various configuration file options).

#### Commonly used command line options

The full list of command line options is given in supported-cmdline-params. The most-commonly used options include:

`--pretend` (or `-p`)

- This option causes &kdesrc-build; to indicate what actions it would take, without actually really implementing them. This can be useful to make sure that the modules you think you are building will actually get built.

`--refresh-build`

- This option forces &kdesrc-build; to build the given modules from an absolutely fresh start point. Any existing build directory for that module is removed and it is rebuilt. This option is useful if you have errors building a module, and sometimes is required when &Qt; or &kde; libraries change.

`--no-src`

- This option skips the source update process. You might use it if you have very recently updated the source code (perhaps you did it manually or recently ran &kdesrc-build;) but still want to rebuild some modules.

`--no-build`

- This option is similar to `--no-src` above, but this time the build process is skipped.

#### Specifying modules to build

In general, specifying modules to build is as simple as passing their module name as you defined it in the configuration file. You can also pass modules that are part of a module set, either as named on use-modules, or the name of the entire module set itself, if you have given it a name.

In the specific case of module sets based against the KDE project database, &kdesrc-build; will expand module name components to determine the exact module you want. For example, &kdesrc-build;'s KDE project entry locates the project in `extragear/utils/kdesrc-build`. You could specify any of the following to build &kdesrc-build;:

    % kdesrc-build +extragear/utils/kdesrc-build
    % kdesrc-build +utils/kdesrc-build
    % kdesrc-build +kdesrc-build

The commands in the previous example preceded the module-name with a +. This forces the module name to be interpreted as a module from the KDE project database, even if that module hasn't been defined in your configuration file.

Be careful about specifying very generic projects (e.g. `extragear/utils` by itself), as this can lead to a large amount of modules being built. You should use the `--pretend` option before building a new module set to ensure it is only building the modules you want.

### Supported Environment Variables

&kdesrc-build; does not use environment variables. If you need to set environment variables for the build or install process, please see the set-env option.

### Supported command-line parameters

The script accepts the following command-line options:

`--async`

- Enables the asynchronous mode, which can perform the source code updates and module builds at the same time. This is the default, this option only needs specified if you have disabled it in the configuration.

`--help`

- Only display simple help on this script.

`--version`

- Display the program version.

`--author`

- Display contact information for the author.

`--color`

- Enable colorful output. (This is the default for interactive terminals).

`--nice=`value``

- This value adjusts the computer CPU priority requested by &kdesrc-build;, and should be in the range of 0-20. 0 is highest priority (because it is the least nice), 20 is lowest priority. &kdesrc-build; defaults to 10.

`--no-async`

- Disables the asynchronous mode of updating. Instead the update will be performed in its entirety before the build starts. This option will slow down the overall process, but if you encounter IPC errors while running &kdesrc-build; try using this option, and submitting a bug report.

`--no-color`

- Disable colorful output.

`--pretend` (or `-p`)

- &kdesrc-build; will run through the update and build process, but instead of performing any actions to update or build, will instead output what the script would have done (e.g. what commands to run, general steps being taken, etc.).

  Note: Simple read-only commands (such as reading file information) may still be run to make the output more relevant (such as correctly simulating whether source code would be checked out or updated).

`--quiet` (or `-q`)

- Do not be as noisy with the output. With this switch only the basics are output.

`--really-quiet`

- Only output warnings and errors.

`--verbose` (or `-v`)

- Be very descriptive about what is going on, and what &kdesrc-build; is doing.

`--src-only` (or `--svn-only`)

- Only perform the source update. (The `--svn-only` is only supported for compatibility with older scripts).

`--build-only`

- Only perform the build process.

`--ignore-modules`

- Do not include the modules passed on the rest of the command line in the update/build process (this is useful if you want to build most of the modules in your configuration file and just skip a few).

`--no-src` (or `--no-svn`)

- Skip contacting the &subversion; server. (The `--no-svn` parameter is only supported for compatibility with older versions of the script).

`--no-build`

- Skip the build process.

`--no-install`

- Do not automatically install packages after they are built.

`--no-build-when-unchanged`

`--force-build`

- This option explicitly disables skipping the build process (an optimization controlled by the build-when-unchanged option). This is useful for making &kdesrc-build; run the build when you have changed something that &kdesrc-build; cannot check.

  `--force-build` performs the exact same function, and is perhaps easier to remember.

`--debug`

- Enables debug mode for the script. Currently this means that all output will be dumped to the standard output in addition to being logged in the log directory like normal. Also, many functions are much more verbose about what they are doing in debugging mode.

`--no-rebuild-on-fail`

- Do not try to rebuild modules that have failed building from scratch. &kdesrc-build; will never try to do this to a module that already was tried to be built from scratch.

`--refresh-build`

- Recreate the build system and make from scratch.

`--reconfigure`

- Run `cmake` (for &kde; modules) or `configure` (for &Qt;) again, without cleaning the build directory. You should not normally have to specify this, as &kdesrc-build; will detect when you change the relevant options and automatically re-run the build setup. This option is implied if `--refresh-build` is used.

`--resume-from`

- This option is used to resume the build starting from the given module, which should be the next option on the command line. You should not specify other module names on the command line.

  This option formerly added `--no-src`, but does not any longer (since &kdesrc-build; 1.13). If you want to avoid source updates when resuming, simply pass ``--no-src`` in addition to the other options.

  See also: cmdline-resume-after and resuming-failed. You would prefer to use this command line option if you have fixed the build error and want &kdesrc-build; to complete the build.

`--resume-after`

- This option is used to resume the build starting after the given module, which should be the next option on the command line. You should not specify other module names on the command line.

  This option formerly added `--no-src`, but does not any longer (since &kdesrc-build; 1.13). If you want to avoid source updates when resuming, simply pass ``--no-src`` in addition to the other options.

  See also: cmdline-resume-from and resuming-failed. You would prefer to use this command line option if you have fixed the build error and have also built and installed the module yourself, and want &kdesrc-build; to start again with the next module.

`--rc-file`

- This interprets the next command line parameter as the file to read the configuration options from. The default value for this parameter is `kdesrc-buildrc` (checked in the current directory) if it is present, or `~/.kdesrc-buildrc` otherwise. See also kdesrc-buildrc.

`--run`

- This option interprets the next item on the command line as a program to run, and &kdesrc-build; will then finish reading the configuration file, update the environment as normal, and then execute the given program.

  This will not work to start a shell with the &kdesrc-build; environment in most cases however, since interactive shells typically reset at least part of the environment variables (such as `PATH` and `KDEDIRS`) in the startup sequence.

  If you want to see the environment used by &kdesrc-build;, you can run the `printenv` command:

      $ kdesrc-build --run printenv
      KDE_SESSION_VERSION=4
      SDL_AUDIODRIVER=alsa
      LANGUAGE=
      XCURSOR_THEME=Oxygen_Blue
      LESS=-R -M --shift 5
      QMAIL_CONTROLDIR=/var/qmail/control
      ... etc.

`--prefix=</path/to/kde>`

- This allows you to change the directory that &kde; will be installed to from the command line. This option implies `--reconfigure`, but using `--refresh-build` may still be required.

`--revision`

- This option causes &kdesrc-build; to checkout a specific numbered revision for each &subversion; module, overriding any branch, tag, or revision options already set for these modules.

  This option is likely not a good idea, and is only supported for compatibility with older scripts.

`--build-system-only`

- This option causes &kdesrc-build; to abort building a module just before the `make` command would have been run. This is supported for compatibility with older versions only, this effect is not helpful for the current &kde; build system.

`--install`

- If this is the only command-line option, it tries to install all of the modules contained in `log/latest/build-status`. If command-line options are specified after `--install`, they are all assumed to be modules to install (even if they did not successfully build on the last run).

`--no-snapshots`

- Supplying this option causes &kdesrc-build; to always perform a normal initial checkout of a module instead of using a quick-start snapshot (only available for Git modules from the `kde-projects` repository). Note that this option should only be used if there is a failure using snapshots, as the quick-start snapshot reduces load on the KDE source repositories.

  Module snapshots are real checkouts. You should not need to specify this option, it is only a troubleshooting aid.

`--<option-name>=`

- You can use this option to override an option in your configuration file for every module. For instance, to override the log-dir option, you would do: ``--log-dir=``/path/to/dir````.

`--<module-name>,<option-name>=`

- You can use this option to override an option in your configuration file for a specific module.

Any other command-line options are assumed to be modules to update and build. Please, do not mix building with installing.

## Using &kdesrc-build;

### Preface

Normally using &kdesrc-build; after you have gone through getting-started is as easy as doing the following from a terminal prompt:

    % kdesrc-build

&kdesrc-build; will then download the sources for &kde;, try to configure and build them, and then install them.

Read on to discover how &kdesrc-build; does this, and what else you can do with this tool.

### Basic &kdesrc-build; features

#### qt support

&kdesrc-build; supports building the &Qt; toolkit used by &kde; software as a convenience to users. This support is handled by a special module named qt.

&Qt; is developed under a separate repository from &kde; software located at http://qt.gitorious.org/qt.

In order to build &Qt;, you should make sure that the qtdir setting is set to the directory you'd like to install &Qt; to, as described in configure-data.

You should then ensure that the qt module is added to your `.kdesrc-buildrc`, before any other modules in the file. If you are using the sample configuration file, you can simply uncomment the existing qt module entry.

Now you should verify the repository option and branch options are set appropriately:

1. The first option is to build &Qt; using a mirror maintained on the &kde; source repositories (no other changes are applied, it is simply a clone of the official source). This is highly recommended due to occasional issues with cloning the full &Qt; module from its official repository.

   You can set the `repository` option for the qt module to `kde:qt` to use this option.

2. Otherwise, to build the standard &Qt;, set your `repository` option to `git://gitorious.org/qt/qt.git`. Note that you may experience problems performing the initial clone of &Qt; from this repository.

In both cases, the branch option should be set to `master` (unless you'd like to build a different branch).

#### Standard flags added by &kdesrc-build;

To save you time, &kdesrc-build; adds some standard paths to your environment for you:

- The path to the &kde; and &Qt; libraries is added to the `LD_LIBRARY_PATH` variable automatically. This means that you do not need to edit &libpath; to include them.

- The path to the &kde; and &Qt; development support programs are added to the `PATH` variable automatically. This means that you do not need to edit &binpath; to include them.

- The path to the &kde;-provided pkg-config is added automatically to `PKG_CONFIG_PATH`. This means that you do not need to use &set-env; to add these.

- The setting for &kdedir; is automatically propagated to the `KDEDIR` environment variable while building. (`KDEDIRS` is not affected).

- The setting for &qtdir; is automatically propagated to the `QTDIR` environment variable while building.

#### Changing &kdesrc-build;'s build priority

Programs can run with different priority levels on Operating Systems, including &Linux; and &BSD;. This allows the system to allocate time for the different programs in accordance with how important they are.

&kdesrc-build; will normally allocate itself a low priority so that the rest of the programs on your system are unaffected and can run normally. Using this technique, &kdesrc-build; will use extra CPU when it is available.

&kdesrc-build; will still maintain a high enough priority level so that it runs before routine batch processes and before CPU donation programs such as Seti@Home.

To alter &kdesrc-build; so that it uses a higher (or lower) priority level permanently, then you need to adjust the &niceness; setting in the configuration file. The &niceness; setting controls how nice &kdesrc-build; is to other programs. In other words, having a higher &niceness; gives &kdesrc-build; a lower priority. So to give &kdesrc-build; a higher priority, reduce the &niceness; (and vice versa). The &niceness; can go from 0 (not nice at all, highest priority) to 20 (super nice, lowest priority).

You can also temporarily change the priority for &kdesrc-build; by using the &cmd-nice; command line option. The value to the option is used exactly the same as for &niceness;.

It is possible for some programs run by the super user to have a negative nice value, with a correspondingly even higher priority for such programs. Setting a negative (or even 0) &niceness; for &kdesrc-build; is not a great idea, as it will not help run time significantly, but will make your computer seem very sluggish should you still need to use it.

To run &kdesrc-build; with a niceness of 15 (a lower priority than normal):

    % kdesrc-build --nice=15

Or, you can edit the configuration file to make the change permanent:

        &niceness; 15

The niceness option only affects the usage of the computer's processor(s). One other major affect on computer performance relates to how much data input or output (I/O) a program uses. In order to control how much I/O a program can use, modern &Linux; operating systems support a similar tool called ionice. &kdesrc-build; supports ionice, (but only to enable or disable it completely) using the use-idle-io-priority option, since &kdesrc-build; version 1.12.

#### Installation as the superuser

You may wish to have &kdesrc-build; run the installation with super user privileges. This may be for the unrecommended system-wide installation. This is also useful when using a recommended single user &kde; build, however. This is because some modules (especially kdebase) install programs that will briefly need elevated permissions when run. They are not able to achieve these permission levels unless they are installed with the elevated permissions.

You could simply run &kdesrc-build; as the super user directly, but this is not recommended, since the program has not been audited for that kind of use. Although it should be safe to run the program in this fashion, it is better to avoid running as the super user when possible.

To take care of this, &kdesrc-build; provides the &make-install-prefix; option. You can use this option to specify a command to use to perform the installation as another user. The recommended way to use this command is with the &sudo; program, which will run the install command as the super user.

For example, to install all modules using &sudo;, you could do something like this:

    global
      &make-install-prefix; sudo
      # Other options
    end global

To use &make-install-prefix; for only a single module, this would work:

    module svn-module-name
      &make-install-prefix; sudo
    end module

#### Showing the progress of a module build

This feature is always available, and is automatically enabled when possible. What this does is display an estimated build progress while building a module; that way you know about how much longer it will take to build a module.

### 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. &kdesrc-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 &kdesrc-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.

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 KSystemLog from kdeadmin, you could use &checkout-only; like this:

    module kdeadmin
      &checkout-only; kuser ksystemlog
    end module

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. This option depends on support from the build system of the module, so it is only useful for modules that are collections of individual applications.

One final note to make about this option: If you change the value of this option, you should use ``kdesrc-build` `&cmd-refresh-build;` ``module``` in order to ensure that the module is reconfigured properly. In addition, &kdesrc-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.

Also like &checkout-only;, this option requires at least that the build system for the module is reconfigured after changing it. This is done using the ``kdesrc-build` `&cmd-reconfigure;` ``module``` command.

To remove the `python` directory from the kdebindings build process:

    module kdebindings
      &do-not-compile; python
    end module

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

#### Branching and tagging support for &kdesrc-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 &kdesrc-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 &kdesrc-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; 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 &kde; 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!

##### Advanced branch support options

&kdesrc-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 &kdesrc-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 &kdesrc-build; can figure out the appropriate middle part by itself. When it cannot, you can use &module-base-path;, like this:

      module kdesupport
          # kdesupport supports various tags to easily organize the required
          # software for a given KDE Platform release.
          module-base-path tags/kdesupport-for-4.5
      end module

  This would cause &kdesrc-build; to download kdesupport from (in this example), `svn://anonsvn.kde.org/home/kde/`tags/kdesupport-for-4.5``.

  In previous versions of &kdesrc-build;, the &module-base-path; was handled differently. If you encounter trouble using an old module-base-path definition perhaps you should verify that the actual path is as &kdesrc-build; expects by using the --pretend option.

- 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 previous versions of &kdesrc-build; would have no hope of downloading from. Currently, the &module-base-path; option should be sufficient for any Subversion source URL.

  &kdesrc-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 &kdesrc-build; tries to ensure a successful build

##### Automatic rebuilds

&kdesrc-build; 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 &cmake; the build system no longer suffers from these bugs, and so &kdesrc-build; will not try to build a module more than once. There are situations where &kdesrc-build; will automatically take action though:

- If you change configure-flags or cmake-options for a module, then &kdesrc-build; will detect that and automatically re-run configure or cmake for that module.

- If the buildsystem does not exist (even if &kdesrc-build; did not delete it) then &kdesrc-build; 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 &kdesrc-build; 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 &kdesrc-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, &kdesrc-build; 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 `~/kdesrc/build/`module`/`. If you change the setting of the &build-dir; option, then use that instead of `~/kdesrc/build`.

Rebuild using `.refresh-me` for module `kdelibs`:

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

#### Changing environment variable settings

Normally &kdesrc-build; 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 &kdesrc-build; from the command line.

However, you may want to change the setting for environment variables that &kdesrc-build; does not provide an option for directly. (For instance, to setup any required environment variables when running &kdesrc-build; 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 modules:

    global
      set-env DISTRO BSD
    end global

#### Resuming builds

##### Resuming a failed or canceled build

You can tell &kdesrc-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 &cmd-resume-from; option and the &cmd-resume-after; option.

Older versions of &kdesrc-build; 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

##### 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 &cmd-ignore-modules; option. This option tells &kdesrc-build; 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.

&kdesrc-build; allows you to change options named like `option-name` by passing an argument on the command line in the form ``--`option-name`=value``. &kdesrc-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:

    % 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

### Features for &kde; developers

#### &ssh; Agent checks

&kdesrc-build; can ensure that &kde; developers that use &ssh; to access the &kde; source repository do not accidentally forget to leave the &ssh; Agent tool enabled. This can cause &kdesrc-build; to hang indefinitely waiting for the developer to type in their &ssh; password, so by default &kdesrc-build; will check if the Agent is running before performing source updates.

This is only done for &kde; developers using &ssh;. This is because no password is required for the default anonymous checkout. &subversion; will handle passwords for the second possible protocol for &kde; developers, https.

You may wish to disable the &ssh; Agent check, in case of situations where &kdesrc-build; is mis-detecting the presence of an agent. To disable the agent check, set the `disable-agent-check` option to `true`.

Disabling the &ssh; agent check:

    global
      disable-agent-check true
    end global

### Other &kdesrc-build; features

#### Changing the amount of output from &kdesrc-build;

&kdesrc-build; has several options to control the amount of output the script generates. In any case, errors will always be output.

- The `--quiet` option (short form is `-q`) causes &kdesrc-build; to be mostly silent. Only important messages, warnings, or errors will be shown. When available, build progress information is still shown.

- The `--really-quiet` option (no short form) causes &kdesrc-build; to only display important warnings or errors while it is running.

- The `--verbose` option (short form is `-v`) causes &kdesrc-build; to be very detailed in its output.

- The `--debug` option is for debugging purposes only, it causes &kdesrc-build; to act as if `--verbose` was turned on, causes commands to also output to the terminal, and will display debugging information for many functions.

#### Color output

When being run from &konsole; or a different terminal, &kdesrc-build; will normally display with colorized text.

You can disable this by using the `--no-color` on the command line, or by setting the &colorful-output; option in the configuration file to `false`.

Disabling color output in the configuration file:

    global
      colorful-output false
    end global

#### Removing unneeded directories after a build

Are you short on disk space but still want to run a bleeding-edge &kde; checkout? &kdesrc-build; can help reduce your disk usage when building &kde; from &subversion;.

Be aware that building &kde; does take a lot of space. There are several major space-using pieces when using &kdesrc-build;:

1. The actual source checkout can take up a fair amount of space. The default modules take up about 1.6 gigabytes of on-disk space. You can reduce this amount by making sure that you are only building as many modules as you actually want. &kdesrc-build; will not delete source code from disk even if you delete the entry from the configuration file, so make sure that you go and delete unused source checkouts from the source directory. Note that the source files are downloaded from the Internet, you should not delete them if you are actually using them, at least until you are done using &kdesrc-build;.

   Also, if you already have a &Qt; installed by your distribution (and the odds are good that you do), you probably do not need to install the qt module. That will shave about 200 megabytes off of the on-disk source size.

   One thing to note is that due to the way &subversion; works: there are actually two files on disk for every file checked-out from the repository. &kdesrc-build; does not have code at this point to try and minimize the source size when the source is not being used.

2. &kdesrc-build; will create a separate build directory to build the source code in. Sometimes &kdesrc-build; will have to copy a source directory to create a fake build directory. When this happens, space-saving symlinks are used, so this should not be a hassle on disk space. The build directory will typically be much larger than the source directory for a module. For example, the build directory for kdebase is about 1050 megabytes, whereas kdebase's source is only around 550 megabytes.

   Luckily, the build directory is not required after a module has successfully been built and installed. &kdesrc-build; can automatically remove the build directory after installing a module, see the examples below for more information. Note that taking this step will make it impossible for &kdesrc-build; to perform the time-saving incremental builds.

3. Finally, there is disk space required for the actual installation of &kde;, which does not run from the build directory. This typically takes less space than the build directory. It is harder to get exact figures however.

How do you reduce the space requirements of &kde;? One way is to use the proper compiler flags, to optimize for space reduction instead of for speed. Another way, which can have a large effect, is to remove debugging information from your &kde; build.

You should be very sure you know what you are doing before deciding to remove debugging information. Running bleeding-edge software means you are running software which is potentially much more likely to crash than a stable release. If you are running software without debugging information, it can be very hard to create a good bug report to get your bug resolved, and you will likely have to re-enable debugging information for the affected application and rebuild to help a developer fix the crash. So, remove debugging information at your own risk!

Removing the build directory after installation of a module. The source directory is still kept, and debugging is enabled:

    global
      configure-flags      --enable-debug
      remove-after-install builddir        # Remove build directory after install
    end global

Removing the build directory after installation, without debugging information, with size optimization.

    global
      cxxflags             -Os             # Optimize for size
      configure-flags      --disable-debug
      remove-after-install builddir        # Remove build directory after install
    end global

## &cmake;, the &kde; 4 build system

### Introduction to &cmake;

In March 2006, the &cmake; program beat out several competitors and was selected to be the build system for &kde; 4, replacing the autotools-based system that &kde; has used from the beginning.

A introduction to &cmake; page is available on the &kde; TechBase. Basically, instead of running ``make` `-f` `Makefile.cvs``, then `configure`, then &make;, we simply run &cmake; and then &make;.

&kdesrc-build; has support for &cmake;. A few features of &kdesrc-build; were really features of the underlying buildsystem, including configure-flags and do-not-compile. When equivalent features are available, they are provided. For instance, the equivalent to the configure-flags option is cmake-options, and the do-not-compile option is also supported for &cmake; as of &kdesrc-build; version 1.6.3.

## Credits And Licenses

&underFDL;