kdesrc-build/doc/index.docbook

<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!--
    Documentation for kdesrc-build.
    Copyright (c) 2005-2008, 2010-2013 Michael Pyne <mpyne@kde.org>

    Copyright (c) 2005 Carlos Leonhard Woelz <carloswoelz@imap-mail.com>
    Copyright (c) 2009 Burkhard Lück <lueck@hube-lueck.de>
    Copyright (c) 2007, 2011 Federico Zenith <federico.zenith@members.fsf.org>
    Copyright (c) 2009-2011 Yuri Chornoivan <yurchor@ukr.net>
    ... and possibly others. Check the git source repository for specifics.

    Permission is granted to copy, distribute and/or modify this document under
    the terms of the GNU Free Documentation License, Version 1.2 or any later
    version published by the Free Software Foundation; with no Invariant
    Sections, no Front-Cover Texts, and no Back-Cover Texts.

    A copy of the license is included in COPYING.DOC. The license will be
    included in the generated documentation as well.
   -->
  <!ENTITY kappname "kdesrc-build">
  <!ENTITY package "kdesdk">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE"> <!-- Change language only here -->
  <!ENTITY kdesrc-build "<application>kdesrc-build</application>">
  <!ENTITY BSD '<acronym>BSD</acronym>'>
  <!ENTITY git '<application>Git</application>'>
  <!ENTITY cmake '<application>CMake</application>'>
  <!ENTITY make '<application>Make</application>'>
  <!ENTITY ssh '<application>SSH</application>'>
  <!ENTITY cron '<application>Cron</application>'>
  <!ENTITY subversion '<application>Subversion</application>'>
  <!ENTITY sudo '<application>Sudo</application>'>
  <!ENTITY url '<acronym>URL</acronym>'>

  <!-- These define shortcut entities for some of the configuration options.
       Just add them as necessary.
  -->

  <!ENTITY configure-flags '<link linkend="conf-configure-flags">configure-flags</link>'>
  <!ENTITY kdedir '<link linkend="conf-kdedir">kdedir</link>'>
  <!ENTITY qtdir '<link linkend="conf-qtdir">qtdir</link>'>
  <!ENTITY build-dir '<link linkend="conf-build-dir">build-dir</link>'>
  <!ENTITY module-base-path '<link linkend="conf-module-base-path">module-base-path</link>'>
  <!ENTITY override-url '<link linkend="conf-override-url">override-url</link>'>
  <!ENTITY source-dir '<link linkend="conf-source-dir">source-dir</link>'>
  <!ENTITY email-address '<link linkend="conf-email-address">email-address</link>'>
  <!ENTITY email-on-compile-error '<link linkend="conf-email-on-compile-error">email-on-compile-error</link>'>
  <!ENTITY colorful-output '<link linkend="conf-colorful-output">colorful-output</link>'>
  <!ENTITY tag '<link linkend="conf-tag">tag</link>'>
  <!ENTITY branch '<link linkend="conf-branch">branch</link>'>
  <!ENTITY do-not-compile '<link linkend="conf-do-not-compile">do-not-compile</link>'>
  <!ENTITY checkout-only '<link linkend="conf-checkout-only">checkout-only</link>'>
  <!ENTITY svn-server '<link linkend="conf-svn-server">svn-server</link>'>
  <!ENTITY make-install-prefix '<link linkend="conf-make-install-prefix">make-install-prefix</link>'>
  <!ENTITY niceness '<link linkend="conf-niceness">niceness</link>'>
  <!ENTITY set-env '<link linkend="conf-set-env">set-env</link>'>
  <!ENTITY libpath '<link linkend="conf-libpath">libpath</link>'>
  <!ENTITY binpath '<link linkend="conf-binpath">binpath</link>'>

  <!-- These define shortcut entities for some of the command line options.
       Just add them as necessary.
  -->
  <!ENTITY cmd-nice '<link linkend="cmdline-nice">--nice</link>'>
  <!ENTITY cmd-ignore-modules '<link linkend="cmdline-ignore-modules">--ignore-modules</link>'>
  <!ENTITY cmd-resume-from '<link linkend="cmdline-resume-from">--resume-from</link>'>
  <!ENTITY cmd-resume-after '<link linkend="cmdline-resume-after">--resume-after</link>'>
  <!ENTITY cmd-reconfigure '<link linkend="cmdline-reconfigure">--reconfigure</link>'>
  <!ENTITY cmd-refresh-build '<link linkend="cmdline-refresh-build">--refresh-build</link>'>
]>

<book id="kdesrc-build" lang="&language;">

<bookinfo>
<title>&kdesrc-build; Script Manual</title>

<authorgroup id="authors">
<author>
<firstname>Michael</firstname><surname>Pyne</surname>
<affiliation><address><email>mpyne@kde.org</email></address></affiliation>
</author>
<author>
<firstname>Carlos</firstname><surname>Woelz</surname>
<affiliation><address><email>carloswoelz@imap-mail.com</email></address></affiliation>
</author>


<!-- TRANS:ROLES_OF_TRANSLATORS -->

</authorgroup>

<copyright>
<year>2006</year>
<year>2007</year>
<year>2008</year>
<year>2009</year>
<year>2010</year>
<year>2011</year>
<year>2012</year>
<year>2013</year>
<holder>Michael Pyne</holder>
</copyright>

<copyright>
<year>2005</year>
<holder>Carlos Woelz</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>

<date>2013-02-19</date>
<releaseinfo>1.16</releaseinfo>

<abstract>
<para>&kdesrc-build; is a script which builds and installs &kde; software
directly from the &kde; project's source code repositories.</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>kdesdk</keyword>
<keyword>SVN</keyword>
<keyword>Subversion</keyword>
<keyword>git</keyword>
<keyword>gitorious</keyword>
<keyword>KDE development</keyword>
<!-- Older names for the software -->
<keyword>kdesvn-build</keyword>
<keyword>kdecvs-build</keyword>
</keywordset>

</bookinfo>

<chapter id="introduction">
<title>Introduction</title>

<sect1 id="brief-intro">
<title>A brief introduction to &kdesrc-build;</title>

<sect2 id="whatis-kdesrc-build">
<title>What is &kdesrc-build;?</title>

<para>
&kdesrc-build; is a script to help users install <ulink
url="http://www.kde.org/">&kde;</ulink> software from its <ulink
url="http://subversion.tigris.org/">&subversion;</ulink> and <ulink
url="http://gitscm.org/">&git;</ulink> source repositories.
<!-- Deliberately not KDE SC, we can also install Extragear, amarok, etc. -->
</para>

<para>In addition to simply installing &kde; software, the script can also be
used to update the installed &kde; software after it is installed. This allows
you to keep up-to-date with &kde; development.
</para>

<para>The &kdesrc-build; script can be used to maintain a single individual
module or an entire &kde; desktop depending on how it is configured.
</para>
</sect2>

<sect2 id="operation-in-a-nutshell">
<title>&kdesrc-build; operation <quote>in a nutshell</quote></title>

<para>&kdesrc-build; intentionally works by using the same tools available to
the user at the command-line. When &kdesrc-build; is run, the following
sequence is followed:
</para>

<orderedlist>
<listitem><para>&kdesrc-build; reads in the <link linkend="cmdline">command
line</link> and <link linkend="configure-data">configuration file</link>, to
determine what to build, compile options to use, where to install,
&etc;</para></listitem>

<listitem><para>&kdesrc-build; performs a source update for each <link
linkend="module-concept">module</link>. The update continues until all modules
have been updated. Modules that fail to update normally do not stop the build
&ndash; you will be notified at the end which modules did not
update.</para></listitem>
</orderedlist>

</sect2>
</sect1>

<sect1 id="intro-toc">
<title>Documentation Overview</title>

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

<itemizedlist>
<listitem><para>An <link linkend="getting-started">overview</link> of the steps
required to get started.</para></listitem>
<listitem><para>Notable <link linkend="features">features</link>.</para></listitem>
<listitem><para>The <link linkend="configure-data">configuration file</link> syntax
and options.</para></listitem>
<listitem><para>The <link linkend="cmdline">command line options</link>.</para></listitem>
</itemizedlist>

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

</sect1>
</chapter>

<chapter id="getting-started">
<title>Getting Started</title>

<para>
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; source code structure and the steps you have to perform before running
the script.
</para>

<para>
All topics present in this chapter are covered with even more detail in the
<ulink url="http://techbase.kde.org/Getting_Started/Build/KDE4">
Building &kde; 4 from Source</ulink> article, at the
<ulink url="http://techbase.kde.org/">&kde; TechBase site</ulink>.
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.
</para>

<sect1 id="before-building">
<title>Preparing the System to Build &kde;</title>

<sect2 id="before-building-users">
<title>Setup a new user account</title>

<para>
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;.
</para>

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

<para>
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.
</para>

</sect2>
<sect2 id="before-building-preparation">
<title>Ensure your system is ready to build &kde; source</title>

<para>Before using the &kdesrc-build; script (or any other building
strategy) you must install the development tools and libraries needed for &kde;.
The nearly complete list of required tools can be found from
the <ulink url="http://techbase.kde.org/Getting_Started/Build/Requirements">KDE
TechBase Build Requirements</ulink> page.
</para>

<para>Here is a list of some of the things you will need:</para>
<itemizedlist>

<listitem><para>You will need &cmake;.  The required version will vary
depending on what version of &kde; 4 you are building, see TechBase for
specifics, however a good bet is to have the most recent available version.
&cmake; is the program used by &kdesrc-build; to handle the actual
configuration and build steps for the vast majority of &kde; software.
</para></listitem>

<listitem><para>You must also install the client software used to checkout
the &kde; source code. This means you need at least the following:</para>

<itemizedlist>
<listitem><para>&subversion;, which used to be the only source code manager in use, and is still
used for some modules with large data files.  You can check
if you have it by running <userinput><command>svn
<option>--version</option></command></userinput>.</para></listitem>

<listitem><para>You will need the <ulink url="http://gitscm.org/">Git
source control manager</ulink> installed as well, for &kde;'s <ulink
url="http://projects.kde.org/">git-based projects.</ulink>
.</para></listitem>

<listitem><para>Although it is not required, the <ulink
url="http://bazaar.canonical.com/">Bazaar</ulink> source control manager is
used for a single module (libdbusmenu-qt) that is required for the &kde;
libraries. Most users can install this library through their distribution
packages but &kdesrc-build; supports building it as well if you desire. But to
build libdbusmenu-qt, you must have Bazaar installed.</para></listitem>

</itemizedlist></listitem>

<listitem><para>You will need a full C++ development environment. GCC 4.6 or
later is recommended.</para></listitem>

<listitem><para>Finally, you will need a <quote>make</quote> tool. GNU Make is
recommended and should be available through your package manager. After
<command>cmake</command> has been run by &kdesrc-build;,
<command>make</command> handles actually running the build process, which is
why it is required.</para></listitem>

</itemizedlist>

<note><para>Most operating system distributions include a method of easily
installing required development tools. Consult the TechBase <ulink
url="http://techbase.kde.org/Getting_Started/Build/KDE4">Getting Started</ulink>
page's <quote>Required Packages from your Distribution</quote> section to see
if these instructions are already available.</para></note>

<para>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:</para>

<itemizedlist>
<listitem>
  <para>Make sure to remove the qt module from your <link
  linkend="configure-data">configuration file</link>, as you will not need it,
  and having it would add extra time to your build.</para>
</listitem>

<listitem>
  <para>Change the setting of the <link linkend="conf-qtdir">qtdir</link>
  option in your <link linkend="configure-data">configuration file</link> to
  point to your system &Qt;. The location of your system &Qt; can be found
  by running <userinput><command>qmake</command> <option>-query</option>
  <option>QT_INSTALL_PREFIX</option></userinput>.</para>

  <note><para>The <command>qmake</command> command might be called
  <command>qmake4</command> or <command>qmake-qt4</command> on your
  distribution.</para></note>
</listitem>

<listitem>
  <para>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.</para>
</listitem>
</itemizedlist>

<important><para>
Some of these packages are divided into libraries (or programs or utilities),
and development packages. You will need at least the program or library
<emphasis>and</emphasis> its development package. The libraries you need will
change depending on the modules you intend to build, as each module has its own
requirements. The <ulink
url="http://techbase.kde.org/Getting_Started/Build/KDE4#Required_packages_from_your_distribution">&kde;
TechBase</ulink> has more details about the specific tools and techniques used
to install and find the required software.
</para></important>

</sect2>

<sect2 id="before-building-prepare-script">
<title>Setup &kdesrc-build;</title>

<sect3 id="get-kdesrc-build">
<title>Install &kdesrc-build;</title>
<para>
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
<ulink url="http://kdesrc-build.kde.org/">&kdesrc-build; home page</ulink>,
or you can find it from its home in the &kde; source repository.</para>

<tip><para>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 <option>--version</option> option to &kdesrc-build; as a quick
way to verify this.</para></tip>

<orderedlist>
<listitem><para>To download &kdesrc-build; from its home page, simply go to the
<ulink url="http://kdesrc-build.kde.org/">&kdesrc-build; home page</ulink> and download the latest appropriate release. The release is
packaged as a compressed tarball archive, which you can extract using &ark; or
<command>tar</command>. The contents of the archive include the actual
&kdesrc-build; script, a sample configuration file
(<filename>kdesrc-buildrc-sample</filename>), and a quick-setup
program.</para></listitem>

<listitem><para>Or, you can obtain &kdesrc-build; from its source repository,
by running:</para>
<programlisting>
<prompt>$ </prompt><userinput><command>git <option>clone</option> <option>git://anongit.kde.org/kdesrc-build</option> <option><filename class="directory"><replaceable>~/kdesrc-build</replaceable></filename></option></command></userinput>
</programlisting>

<para>Replace <option><replaceable>~/kdesrc-build</replaceable></option> with
the directory you would like to install to.
</para></listitem>
</orderedlist>

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

<sect3 id="setup-rcfile">
<title>Prepare the configuration file</title>

<para>&kdesrc-build; uses a <link linkend="configure-data">configuration
file</link> (located at <filename>~/.kdesrc-buildrc</filename>) to control
which modules are built, where they are installed to, etc.</para>

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

<para><application>kdesrc-build-setup</application> 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.</para>

<tip><para>You can use the included <filename>kdesrc-buildrc-sample</filename>
sample configuration to get explanations as to the various options available.
</para></tip>

<para>You can find more information about the syntax of the <link linkend="configure-data">configuration file</link>
in <xref linkend="configure-data" /> and in <xref linkend="kdesrc-buildrc" />.
</para>

</sect3>
</sect2>
</sect1>

<sect1 id="configure-data">
<title>Setting the Configuration Data</title>

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

<note><para>It is possible to use different configuration files for &kdesrc-build;,
which is described in <xref linkend="kdesrc-buildrc" />. If you need to use
multiple configurations, please see that section. Here, we will assume the
configuration is stored in <filename>~/.kdesrc-buildrc</filename>.</para></note>

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

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

<itemizedlist>
<listitem><para><link linkend="conf-use-stable-kde">use-stable-kde</link> 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 <replaceable>true</replaceable>.
</para>

<tip><para>Note that this option relies on information available from the
&kde; project database, so this feature only works for these modules.
See also <xref linkend="kde-projects-module-sets"/>.
</para></tip>
</listitem>

<listitem><para><link linkend="conf-kdedir">kdedir</link>, which changes the
destination directory that &kde; is installed to. This defaults to
<filename class="directory">~/kde</filename>, which is a single-user installation.</para></listitem>

<listitem><para><link linkend="conf-qtdir">qtdir</link>, 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.
(<filename class="directory">~/kdesrc/build/qt</filename>).</para>

<note><para>This also controls where to install qt.</para></note>
</listitem>

<listitem><para><link linkend="conf-svn-server">svn-server</link>, which
selects what &url; to download the sources from. This is useful if you are a
developer with a <ulink url="http://techbase.kde.org/Contribute/First_Steps_with_your_KDE_SVN_Account">&kde;
&subversion; account</ulink>.</para></listitem>

<listitem><para>You will probably want to select different modules to build, which
is described in <xref linkend="selecting-modules"/>.</para></listitem>
</itemizedlist>
</para>
</sect1>

<sect1 id="kde-modules-and-selection">
<title>Module Organization and selection</title>

<sect2 id="kde-layers">
<title>KDE Software Organization</title>

<para>
&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.
</para>

<orderedlist>
<listitem><para>At the lowest level comes Digia's &Qt; library, which is a
very powerful, cross-platform <quote>toolkit</quote> 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.</para></listitem>

<listitem><para>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
<literal>kdesupport</literal> module.</para>

<note><para>As of &kde; Platform 4.6, many of the libraries in the kdesupport
module are being migrated over to <ulink
url="http://projects.kde.org/">git.kde.org</ulink>, although they are still not
considered part of the Platform.</para></note>
</listitem>

<listitem><para>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.
</para>

<para>For &kdesrc-build;, the Platform layer consists of the <literal>kdelibs</literal>,
<literal>kdepimlibs</literal>, and <literal>kde-runtime</literal> modules.</para>
</listitem>

<listitem><para>On top of the Platform, come several different things:</para>
    <itemizedlist>
        <listitem><para><quote>Third-party</quote> applications. These are
        applications that use the &kde; Platform but are not authored by or in
        association with the &kde; project.</para></listitem>

        <listitem><para>A full <quote>workspace</quote> desktop environment.
        This is what users normally see when they <quote>log-in to
        &kde;</quote>.  This is provided by the &plasma; Desktop, mostly in
        <literal>kde-workspace</literal>.  </para></listitem>

        <listitem><para>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 <literal>kde</literal>. For example,
        <literal>kdepim</literal> is a component of the Software Compilation
        that contains email, news-reading, calendar/organizational software,
        &etc;, while <literal>kdegames</literal> contains a collection of
        high-quality games to while away the time.</para></listitem>

        <listitem><para>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 <quote>Extragear</quote>, and have module names
        such as <literal>extragear/network</literal>. As with
        <literal>kdesupport</literal>, some of these Extragear applications are
        migrating to <ulink
        url="http://projects.kde.org/">git.kde.org</ulink>.</para></listitem>
    </itemizedlist>
</listitem>
</orderedlist>
</sect2>

<sect2 id="selecting-modules">
<title>Selecting modules to build</title>

<para>Selecting which of the possible modules to build is controlled by
<link linkend="kdesrc-buildrc">the configuration file</link>.
After the <literal>global</literal> section is a list of modules to build,
bracketed by module ... end module lines. An example entry for a module is
shown in <xref linkend="conf-module-example"/>.</para>

<example id="conf-module-example">
<title>Example module entry in the configuration file</title>
<programlisting>
module <replaceable>module-name</replaceable>
    # Options for this module go here, example:
    <link linkend="conf-make-options">make-options</link> -j4 # Run 4 compiles at a time
end module
</programlisting>
</example>

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

<para>&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
<xref linkend="kde-layers"/>.</para>

<para>There is a sample file that comes with &kdesrc-build; called
<filename>kdesrc-buildrc-sample</filename>. It is recommended to copy this file
to a file called <filename>~/.kdesrc-buildrc</filename> (<emphasis>Note the
leading period in front of kdesrc-buildrc!</emphasis>). Afterwards, edit the
new file to adjust the default options to your liking. (Each option is described
in more detail in <xref linkend="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 <literal>kdebase</literal>
if you'd like to save disk space or build time.</para>

</sect2>

<sect2 id="module-sets">
<title>Module Sets</title>

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

<para>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
<quote>module sets</quote> was developed for &kdesrc-build; 1.12.1.</para>

<para>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 <link linkend="conf-repository">repository</link> 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.</para>

<example id="example-using-module-sets">
<title>Using module sets</title>
<programlisting>
global
    <option><link linkend="conf-git-repository-base">git-repository-base</link></option> <replaceable>kde-git</replaceable> <replaceable>kde:</replaceable>
end global

module <replaceable>qt</replaceable>
    # Options removed for brevity
end module

module-set <replaceable>kde-support-libs</replaceable>
    <option><link linkend="conf-repository">repository</link></option> <replaceable>kde-git</replaceable>
    <option><link linkend="conf-use-modules">use-modules</link></option> <replaceable>automoc</replaceable> <replaceable>attica</replaceable> <replaceable>akonadi</replaceable>
end module-set

# Other modules as necessary...
module <replaceable>kdesupport</replaceable>
end module
</programlisting>
</example>

<para>In <xref linkend="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 <option>use-modules</option>, that an individual module
has been declared, with its <option>repository</option> equal to the
module-set's <option>repository</option> followed immediately by the given
module name.</para>

<para>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.</para>

<note><para>Module sets are used in supporting module downloads from
the &kde; <ulink url="https://projects.kde.org/">projects.kde.org</ulink>
module database. See also <xref linkend="kde-projects-module-sets"/>.
</para></note>

<para>Module sets use the options <simplelist><member><link
linkend="conf-git-repository-base">git-repository-base</link></member>
<member><link
linkend="conf-use-modules">use-modules</link></member></simplelist></para>
</sect2>

<sect2 id="kde-projects-module-sets">
<title>Automatically finding modules from the official &kde; module
database</title>

<para>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 <literal>kdegraphics</literal> becomes
16 different Git modules).</para>

<para>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).</para>

<para>&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.</para>

<para>The way this is done is by using <link linkend="module-sets">module
sets</link>. Instead of using a specific <literal>git://</literal> repository,
or a repository name created by <link
linkend="conf-git-repository-base">git-repository-base</link>, a special
repository name, <quote><literal>kde-projects</literal></quote> is used.</para>

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

<itemizedlist>

<listitem><para>Download the latest module database from <ulink
url="https://projects.kde.org/">projects.kde.org</ulink>.</para></listitem>

<listitem><para>Try to find a module with the name given in the module set's
<option>use-modules</option> setting.</para></listitem>

<listitem><para>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.</para></listitem>

</itemizedlist>

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

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

<informalexample>
<programlisting>
module-set <replaceable>media-support</replaceable>
    # This option must be kde-projects to use the module database.
    <option><link linkend="conf-repository">repository</link></option> <literal>kde-projects</literal>

    # This option chooses what modules to look for in the database.
    <option><link linkend="conf-use-modules">use-modules</link></option> <replaceable>phonon/phonon</replaceable> <replaceable>phonon-gstreamer</replaceable> <replaceable>phonon-vlc</replaceable>
end module-set
</programlisting>
</informalexample>

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

<para>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.</para>

<informalexample>
<programlisting>
module-set <replaceable>kdegraphics</replaceable>
    # This option must be kde-projects to use the module database.
    <option><link linkend="conf-repository">repository</link></option> <literal>kde-projects</literal>

    # This option chooses what modules to look for in the database.
    <option><link linkend="conf-use-modules">use-modules</link></option> <literal>kdegraphics/libs</literal> <literal>kdegraphics/*</literal>
end module-set
</programlisting>
</informalexample>

<para>There are two important abilities demonstrated here:</para>

<orderedlist>

<listitem><para>&kdesrc-build; allows you to specify modules that are
descendents of a given module, without building the parent module, by using the
syntax <userinput><replaceable>module-name</replaceable>/*</userinput>. 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.
</para></listitem>

<listitem><para>&kdesrc-build; will also not add a given module to the build
list more than once. This allows us to manually set
<literal>kdegraphics/libs</literal> to build first, before the rest of
<literal>kdegraphics</literal>, without trying to build
<literal>kdegraphics/libs</literal> twice.
</para></listitem>
</orderedlist>

<note><para>It is worth noting that &kdesrc-build; will try to build modules
in the right order, such as if only <literal>kdegraphics/*</literal> had been
listed above, but this depends on other databases being kept up-to-date.  You
can manually list modules in the proper order if necessary by using the
technique described above.
</para></note>
</sect2>

<sect2 id="ignoring-project-modules">
<title>Filtering out &kde; project modules</title>

<para>You might decide that you'd like to build all programs within a &kde;
module grouping <emphasis>except</emphasis> for a given program.</para>

<para>For instance, the <literal>kdeutils</literal> group includes a program
named <application>kremotecontrol</application>. If your computer does not have
the proper hardware to receive the signals sent by remote controls then you may
decide that you'd rather not download, build, and install
<application>kremotecontrol</application> every time you update
<literal>kdeutils</literal>.</para>

<para>As of &kdesrc-build; 1.16, you can achieve this by using the <link
linkend="conf-ignore-modules">ignore-modules</link> configuration option.</para>

<example id="example-ignoring-a-module">
<title>Example for ignoring a kde-project module in a group</title>
<programlisting>
module-set <replaceable>utils</replaceable>
    <option><link linkend="conf-repository">repository</link></option> <literal>kde-projects</literal>

    # This option chooses what modules to look for in the database.
    <option><link linkend="conf-use-modules">use-modules</link></option> <replaceable>kdeutils</replaceable>

    # This option "subtracts out" modules from the modules chosen by use-modules, above.
    <option><link linkend="conf-ignore-modules">ignore-modules</link></option> <replaceable>kremotecontrol</replaceable>
end module-set

module-set <replaceable>graphics</replaceable>
    <option><link linkend="conf-repository">repository</link></option> <literal>kde-projects</literal>

    # This option chooses what modules to look for in the database.
    <option><link linkend="conf-use-modules">use-modules</link></option> <replaceable>extragear/graphics</replaceable>

    # This option "subtracts out" modules from the modules chosen by use-modules, above.
    # In this case, *both* extragear/graphics/kipi-plugins and
    # extragear/graphics/kipi-plugins/kipi-plugins-docs are ignored
    <option><link linkend="conf-ignore-modules">ignore-modules</link></option> <replaceable>extragear/graphics/kipi-plugins</replaceable>
end module-set
</programlisting>
</example>

</sect2>

</sect1>

<sect1 id="building-and-troubleshooting">
<title>Using the &kdesrc-build; script</title>

<para>
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:
<screen>
<prompt>&percnt;</prompt> <userinput><command>kdesrc-build</command></userinput>
</screen>
</para>

<para>Afterwards, you should see output similar to that in <xref
linkend="example-single-module"/>:</para>

<example id="example-single-module">
<title>Example output of building a single module</title>
<screen>
<prompt>&percnt;</prompt> <userinput><command>kdesrc-build</command> <option>kdelibs</option></userinput>
Script started processing at Wed Dec 22 13:21:45 2010
&lt;&lt;&lt;  Build Process  &gt;&gt;&gt;
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.

&lt;&lt;&lt;  Build Done  &gt;&gt;&gt;

&lt;&lt;&lt;  PACKAGES SUCCESSFULLY BUILT  &gt;&gt;&gt;
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
</screen>
</example>

<para>
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!
</para>

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

<tip><para>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 <literal>error</literal>.  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.</para></tip>

<para>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 <link
linkend="cmdline-reconfigure">--reconfigure</link> option so that
&kdesrc-build; forces the module to check for the missing packages
again.</para>

<para>Or, if the error appears to be a build error (such as a syntax error,
<quote>incorrect prototype</quote>, <quote>unknown type</quote>, 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 <email>kde-devel@kde.org</email> mailing list (subscription may be
required first) in order to report the build failure.</para>

<para>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
<ulink url="http://techbase.kde.org/Getting_Started/Build/KDE4">
Building &kde; 4 from Source</ulink>.
</para>

<para>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 <xref linkend="environment"/>.</para>

<note><para>For more information about &kdesrc-build;'s logging features,
please see <xref linkend="kdesrc-build-logging"/>.</para></note>

</sect1>

<sect1 id="environment">
<title>Setting the Environment to Run Your &kde; &plasma; Desktop</title>

<para>
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. You must change the environment
variables of your login scripts to make sure the newly-built desktop is used.
</para>

<sect2 id="session-driver">
<title>Automatically installing a login driver</title>

<para>Starting from version 1.16, &kdesrc-build; will try to install an
appropriate login driver, that will allow you to login to your
&kdesrc-build;-built &kde; desktop from your login manager. This can be
disabled by using the <option><link
linkend="conf-install-session-driver">install-session-driver</link></option>
configuration file option.</para>

<note><para>Session setup does not occur while &kdesrc-build; is running
in pretend mode.</para></note>

<para>This driver works by setting up a custom <quote><literal>xsession</literal></quote>
session type. This type of session should work by default with the &kdm; login
manager (where it appears as a <quote>Custom</quote> session), but other login
managers (such as <application>LightDM</application> and
<application>gdm</application>) may require additional files installed to
enable <literal>xsession</literal> support.</para>

<sect3 id="xsession-distribution-setup">
<title>Adding xsession support for distributions</title>

<para>The default login managers for some distributions may require additional
packages to be installed in order to support <literal>xsession</literal> logins.</para>

<itemizedlist>
<listitem><para>The <ulink url="http://fedoraproject.org/">Fedora</ulink>
&Linux; distribution requires the <literal>xorg-x11-xinit-session</literal>
package to be installed for custom <literal>xsession</literal> login
support.</para></listitem>

<listitem><para><ulink url="http://debian.org/">Debian</ulink> and
Debian-derived &Linux; distributions should support custom
<literal>xsession</literal> logins, but require the
<option><userinput>allow-user-xsession</userinput></option> option to be set in
<filename>/etc/X11/Xsession.options</filename>. See also the Debian <ulink
url="http://www.debian.org/doc/manuals/debian-reference/ch07.en.html#_customizing_the_x_session_classic_method">documentation
on customizing the X session.</ulink></para></listitem>

<listitem><para>For other distributions, go to <xref
linkend="xsession-manual-setup"/>.</para></listitem>
</itemizedlist>

</sect3>

<sect3 id="xsession-manual-setup">
<title>Manually adding support for xsession</title>

<para>If there were no distribution-specific directions for your distribution
in <xref linkend="xsession-distribution-setup"/>, you can manually add a
<quote>Custom xsession login</quote> entry to your distribution's list of
session types as follows:</para>

<procedure id="proc-adding-xsession-type">
<title>Adding an .xsession login session type.</title>

<note><para>This procedure will likely require administrative privileges to
complete.
</para></note>

<step performance="required">
<para>Create the file
<filename>/usr/share/xsessions/kdesrc-build.desktop</filename>.</para>
</step>

<step performance="required">
<para>Ensure the file just created has the following text:</para>
<literallayout><userinput>
Type=XSession
Exec=<co id="session-homedir"/><replaceable>$HOME</replaceable>/.xsession
Name=KDE Plasma Desktop (unstable; kdesrc-build)
</userinput></literallayout>

<calloutlist>
<callout arearefs="session-homedir"><para>
The <replaceable>$HOME</replaceable> entry must be replaced by the full path to
your home directory (example, <filename
class="directory">/home/<replaceable>user</replaceable></filename>).  The
desktop entry specification does not allow for user-generic files.
</para></callout>

</calloutlist>
</step>

<step performance="optional"><para>When the login manager is restarted, it
should show a new session type, <quote>KDE Plasma Desktop (unstable;
kdesrc-build)</quote> in its list of sessions, which should try to run the
<filename>.xsession</filename> file installed by &kdesrc-build; if it is
selected when you login.</para>

<note><para>It may be easiest to restart the computer to restart the login
manager, if the login manager does not track updates to the <filename
class="directory">/usr/share/xsessions</filename> directory.</para></note>

</step>

</procedure>

</sect3>

</sect2>

<sect2 id="old-profile-instructions">
<title>Setting up the environment manually</title>
<para>This documentation used to include instruction on which environment
variables to set in order to load up the newly-built desktop. These
instructions have been moved to an appendix (<xref
linkend="old-profile-setup"/>).</para>

<para>If you intend to setup your own login support you can consult that
appendix or view the <filename>sample-kde-env-master.sh</filename> file
included with the &kdesrc-build; source.</para>

</sect2>

</sect1>

</chapter>

<chapter id="features">
<title>Script Features</title>

<sect1 id="features-overview">
<title>Feature Overview</title>

<para>
&kdesrc-build; features include:
</para>

<itemizedlist>

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

<tip><para>For an even more verbose description of what &kdesrc-build; is
doing, try using the <option>--debug</option> option.
</para></tip>

</para></listitem>

<listitem><para>
&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.
</para>

<tip><para>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.</para></tip>

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

<listitem><para>
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)
</para></listitem>

<listitem><para>
Excellent support for building the &Qt; library (in case the &kde; software you
are trying to build depends on a recent &Qt; not available in your
distribution).
</para></listitem>

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

<listitem><para>
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.</para>

<para>Also, &kdesrc-build; will <link linkend="kdesrc-build-std-flags">add
standard flags</link> as appropriate to save you the trouble and possible
errors from typing them yourself.
</para></listitem>

<listitem><para>
&kdesrc-build; can checkout a specific <link linkend="using-branches">branch
or tag</link> of a module. You can also ensure that a specific <link
linkend="conf-revision">revision</link> is checked out of a module.
</para></listitem>

<listitem><para>
&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 <link linkend="cmdline-src-only">--src-only</link> option to let
&kdesrc-build; know that it is acceptable to perform the switch.
</para></listitem>

<listitem><para>
&kdesrc-build; can <link linkend="partial-builds">checkout only portions of a
module</link>, for those situations where you only need one program from a
large module.
</para></listitem>

<listitem><para>
For developers: &kdesrc-build; will <link linkend="ssh-agent-reminder">remind
you</link> if you use svn+ssh:// but <application>ssh-agent</application> is
not running, as this will lead to repeated password requests from
&ssh;.
</para></listitem>

<listitem><para>
Can <link linkend="deleting-build-dir">delete the build directory</link> of a
module after its installation to save space at the expense of future compilation
time.
</para></listitem>

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

<listitem><para>
Can use &sudo;, or a different user-specified command
to <link linkend="root-installation">install modules</link> so that
&kdesrc-build; does not need to be run as the super user.
</para></listitem>

<listitem><para>
&kdesrc-build; runs <link linkend="build-priority">with reduced priority</link>
by default to allow you to still use your computer while &kdesrc-build; is
working.
</para></listitem>

<listitem><para>
Has support for using &kde;'s <link linkend="using-branches">tags and
branches</link>.
</para></listitem>

<listitem><para>
There is support for <link linkend="resuming">resuming a build</link> from a
given module. You can even <link linkend="ignoring-modules">ignore some
modules</link> temporarily for a given build.
</para></listitem>

<listitem><para>
&kdesrc-build; will show the <link linkend="build-progress">progress of your
build</link> when using &cmake;, and will always time the build
process so you know after the fact how long it took.
</para></listitem>

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

<listitem><para>
Tilde-expansion for your configuration options. For example, you can
specify:
<programlisting>qtdir ~/kdesrc/build/qt</programlisting>
</para></listitem>

<listitem><para>
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.
</para></listitem>

<listitem><para>
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.
</para></listitem>

<listitem><para>
Forced full rebuilds, by running
&kdesrc-build; with the <option>--refresh-build</option> option.
</para></listitem>

<listitem><para>
You can specify various environment values to be used during the build,
including <envar>KDEDIR</envar>, <envar>QTDIR</envar>, <envar>DO_NOT_COMPILE</envar>,
and <envar>CXXFLAGS</envar>.
</para></listitem>

<listitem><para>
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.
</para></listitem>

<listitem><para>
You can check out only a portion of a &kde; &subversion; module. For example,
you could check out only the <application>taglib</application> from
<application>kdesupport</application>.
</para></listitem>

</itemizedlist>

</sect1>

<sect1 id="kdesrc-build-logging">
<title>&kdesrc-build;'s build logging</title>

<sect2 id="logging-overview">
<title>Logging overview</title>

<para>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.</para>

<sect3 id="log-directory-layout">
<title>Logging directory layout</title>

<para>The logs are always stored under the log directory. The destination of
the log directory is controlled by the <link linkend="conf-log-dir">log-dir</link>
option, which defaults to <filename class="directory"><symbol>${source-dir}</symbol>/log</filename> (where
<symbol>${source-dir}</symbol> is the value of the <link linkend="conf-source-dir">source-dir</link>
option. The in rest of this section, this value will be referred to as
<symbol>${log-dir}</symbol>).</para>

<para>Under <symbol>${log-dir}</symbol>, 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 <filename>2004-05-26-02</filename>,
where the 2004-05-26 is for the date, and the -02 is the run number.</para>

<para>For your convenience, &kdesrc-build; will also create a link to the
logs for your latest run, called <filename class="directory">latest</filename>. So the logs for
the most recent &kdesrc-build; run should always be under <filename class="directory"><symbol>${log-dir}</symbol>/latest</filename>.
</para>

<para>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 <filename>build-status</filename> will be contained in the directory,
which will allow you to determine which modules built and which failed.</para>

<note><para>
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 <filename class="directory"><symbol>${log-dir}</symbol>/latest/KDE/kdelibs</filename>,
and not under <filename class="directory"><symbol>${log-dir}</symbol>/latest/kdelibs</filename>.
</para></note>

<para>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 <filename>svn-co.log</filename> (for a
module checkout) or <filename>svn-up.log</filename> (when updating a module
that has already been checked out). If the <command>configure</command>
command was run, then you would expect to see a <filename>configure.log</filename>
in that directory.</para>

<para>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
<filename>build-1.log</filename> to a file called <filename>error.log</filename>).</para>

<para>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
<filename><symbol>${log-dir}</symbol>/latest/<replaceable>module-name</replaceable>/error.log</filename>.
</para>

<tip><para>If the file <filename>error.log</filename> 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.</para>

<para>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;.</para>
</tip>

</sect3>
</sect2>
</sect1>

</chapter>

<chapter id="kdesrc-buildrc">
<title>Configuring &kdesrc-build;</title>

<sect1 id="kdesrc-buildrc-overview">
<title>Overview of &kdesrc-build; configuration</title>

<para>
To use the script, you must have a file in your home directory called
<filename>.kdesrc-buildrc</filename>, which describes the modules you would
like to download and build, and any options or configuration parameters to
use for these modules.
</para>

<sect2 id="kdesrc-buildrc-layout">
<title>Layout of the configuration file</title>

<sect3 id="kdesrc-buildrc-layout-global">
<title>Global configuration</title>

<para>
The configuration file starts with the global options, specified like the
following:
</para>

<programlisting>
global
<replaceable>option-name option-value</replaceable>
<replaceable>[...]</replaceable>
end global
</programlisting>

</sect3>
<sect3 id="kdesrc-buildrc-layout-modules">
<title>Module configuration</title>

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

<itemizedlist>
<listitem>
<programlisting>
module <replaceable>module-name</replaceable>
<replaceable>option-name option-value</replaceable>
<replaceable>[...]</replaceable>
end module
</programlisting>
</listitem>

<listitem>
<programlisting>
module-set <replaceable>module-set-name</replaceable>
  repository <userinput>kde-projects</userinput> or <userinput><replaceable>git://host.org/path/to/repo.git</replaceable></userinput>
  use-modules <replaceable>module-names</replaceable>

# Other options may also be set
<replaceable>option-name option-value</replaceable>
<replaceable>[...]</replaceable>
end module-set
</programlisting>
</listitem>
</itemizedlist>

<important><para>Note that the second form, module sets, <emphasis>only works
for Git-based modules</emphasis>.</para></important>

<para>
For Subversion modules, <replaceable>module-name</replaceable> 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
<link linkend="conf-override-url">manually specify the &subversion; URL</link>.
</para>

<para>
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 <link linkend="conf-dest-dir">dest-dir</link> option.
</para>

<para>However, for Git <emphasis>module sets</emphasis> the
<replaceable>module-names</replaceable> must correspond with actual git modules
in the chosen <option>repository</option>. See <link
linkend="conf-git-repository-base">git-repository-base</link> or <link
linkend="conf-use-modules">use-modules</link> for more information.
</para>

</sect3>

<sect3 id="kdesrc-buildrc-options-groups">
<title><quote>options</quote> modules</title>

<para>There is a final type of configuration file entry,
<literal>options</literal> groups, which may be given wherever a
<literal>module</literal> or <literal>module-set</literal> may be used.</para>

<programlisting>
options <replaceable>module-name</replaceable>
<replaceable>option-name option-value</replaceable>
<replaceable>[...]</replaceable>
end options
</programlisting>

<para>An <literal>options</literal> group may have options set for it just like
a module declaration, and is associated with an existing module. Any options
set these way will be used to <emphasis>override</emphasis> options set for the
associated module.</para>

<important><para>The associated module name <emphasis>must</emphasis> match the
name given in the <literal>options</literal> declaration. Be careful of
mis-typing the name.</para></important>

<para>This is useful to allow for declaring an entire
<literal>module-set</literal> worth of modules, all using the same options, and
then using <literal>options</literal> groups to make individual changes.</para>

<example id="ex-options-group">
<title>Example of using options</title>

<para>In this example we choose to build all modules from the &kde; multimedia
software grouping. However we want to use a different version of the &kmix;
application (perhaps for testing a bug fix). It works as follows:</para>

<programlisting>
module-set <replaceable>kde-multimedia-set</replaceable>
  repository <userinput>kde-projects</userinput>
  use-modules <replaceable>kde/kdemultimedia</replaceable>
  branch <replaceable>master</replaceable>
end module-set

# kmix is a part of kde/kdemultimedia group, even though we never named
# kmix earlier in this file, &kdesrc-build; will figure out the change.
options <replaceable>kmix</replaceable>
  branch <replaceable>KDE/4.12</replaceable>
end options
</programlisting>

<para>Now when you run &kdesrc-build;, all of the &kde; multimedia programs will
be built from the <quote>master</quote> branch of the source repository, but
&kmix; will be built from the older <quote>KDE/4.12</quote> branch. By using
<literal>options</literal> you didn't have to individually list all the
<emphasis>other</emphasis> &kde; multimedia programs to give them the right
branch option.</para>

</example>

<note>
<para>Note that this feature is only available in &kdesrc-build; from version
1.16, or using the development version of &kdesrc-build; after
2014-01-12.</para></note>

</sect3>

</sect2>

<sect2 id="kdesrc-buildrc-including">
<title>Including other configuration files</title>

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

<informalexample><para>For example, you could have something like this:</para>
<programlisting>
global
    include <replaceable>~/common-kdesrc-build-options</replaceable>

    # Insert specific options here.

end global
</programlisting>
</informalexample>

<note><para>If you don't specify the full path to the file to include, then
the file will be searched for starting from the directory containing the source
file. This works recursively as well.</para></note>

</sect2>

<sect2 id="kdesrc-buildrc-common">
<title>Commonly used configuration options</title>

<para>
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
<xref linkend="conf-options-table"/>.
</para>

<itemizedlist>
<listitem><para><link linkend="conf-cmake-options">cmake-options</link> to define what flags to configure a module with using &cmake;.</para></listitem>
<listitem><para><link linkend="conf-branch">branch</link>, to checkout from a branch instead of /trunk (for &subversion;) or <literal>master</literal> (for Git).</para></listitem>
<listitem><para><link linkend="conf-configure-flags">configure-flags</link> to define what flags to configure &Qt; with.</para></listitem>
<listitem><para><link linkend="conf-kdedir">kdedir</link>, to set the directory to install &kde; to.</para></listitem>
<listitem><para><link linkend="conf-make-options">make-options</link>, to pass options to the &make; program (such as number of CPUs to use).</para></listitem>
<listitem><para><link linkend="conf-qtdir">qtdir</link>, to set the path to &Qt;.</para></listitem>
<listitem><para><link linkend="conf-source-dir">source-dir</link>, to change where to download the source code to.</para></listitem>
</itemizedlist>

</sect2>
</sect1>
<sect1 id="conf-options-table">
<title>Table of available configuration options</title>

<para>Here is a table of the various options, containing the following
information:</para>

<itemizedlist>

<listitem><para>The option name</para></listitem>

<listitem><para>A description of how &kdesrc-build; responds if the option is
set in both the global section, and the module section of the <link
linkend="configure-data">configuration file</link> while building a
module.</para></listitem>

<listitem><para>Special comments on the purpose and usage of the
option.</para></listitem>

</itemizedlist>

<table id="option-table">
<title>Table of Options</title>
<tgroup cols="3">

<thead>
<row>
<entry>Option-name</entry>
<entry>Module -&gt; Global Behavior</entry>
<entry>Notes</entry>
</row>
</thead>

<tbody>

<row>
<entry>apidox</entry>
<entry></entry>
<entry><para>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 <ulink url="http://api.kde.org/">kde.org</ulink>.
In addition it is possible to build KDE 4's API documentation using a script included in
the kdesdk module (/scripts directory).  See <ulink url="http://techbase.kde.org/Development/Tools/apidox">KDE
TechBase</ulink> for more details.  It is still possible to manually build API documentation
for older modules of course.</para>
</entry>
</row>

<row>
<entry>apply-qt-patches</entry>
<entry></entry>
<entry>This option was removed in kdesrc-build 1.10. To get the same effect,
see <xref linkend="using-qt" /> and the <link
linkend="conf-repository">repository</link> option.</entry>
</row>

<row id="conf-async">
<entry>async</entry>
<entry>Cannot be overridden</entry>
<entry><para>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 <userinput>false</userinput></para>
<para>This option is available since the 1.6 release.</para></entry>
</row>

<row id="conf-binpath">
<entry>binpath</entry>
<entry>Module setting overrides global</entry>
<entry><para>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 $<envar>PATH</envar> that is set when the script starts. This environment
variable should include the colon-separated paths of your development
toolchain. The paths <filename class="directory">$<envar>KDEDIR</envar>/bin</filename> and
<filename class="directory">$<envar>QTDIR</envar>/bin</filename> are automatically added. You
may use the tilde (~) for any paths you add using this option.</para>
</entry>
</row>

<row id="conf-branch">
<entry>branch</entry>
<entry>Module setting overrides global</entry>
<entry><para>Set this option to checkout from a branch of &kde; instead of the
default of <replaceable>master</replaceable> (for &git; modules) or
<replaceable>trunk</replaceable> (for &subversion;), where &kde; development
occurs.</para>

<para>
For instance, to checkout &kde; 4.6 branch, you would set this option to
<replaceable>4.6</replaceable>.</para>

<para>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 <link
linkend="conf-module-base-path">module-base-path</link> or <link
linkend="conf-override-url">override-url</link> options.</para>

<note><para>For most &kde; modules you probably wish to use the <link
linkend="conf-branch-group">branch-group</link> option instead and use this
option for case-by-case exceptions.</para></note>

</entry>
</row>

<row id="conf-branch-group">
<entry>branch-group</entry>
<entry>Module setting overrides global</entry>
<entry>

<para>Set this option to a general group from which you want modules to be
chosen.</para>

<para>For supported &git; module types, &kdesrc-build; will determine the
actual branch to use automatically based on rules encoded by the &kde;
developers (these rules may be viewed in the
<literal>kde-build-metadata</literal> source repository in your source
directory). After a branch is determined that branch is used as if you had
specified it yourself using the <link linkend="conf-branch">branch</link>
option.
</para>

<para>This is useful if you're just trying to maintain up-to-date on some
normal development track without having to pay attention to all the branch name
changes.</para>

<para>The current branch groups (as of 2013-08-11) are:</para>

<itemizedlist>

<listitem><para><literal>stable-qt4</literal>, for tracking bugfixes to the
&Qt; 4-based &kde; libraries and applications.</para></listitem>

<listitem><para><literal>latest-qt4</literal>, for tracking development and new
features for the &Qt; 4-based &kde; libraries and
applications.</para></listitem>

<listitem><para><literal>kf5-qt5</literal>, for tracking
<quote>bleeding-edge</quote> development for the upcoming &Qt; 5-based &kde;
Frameworks 5, &plasma; Workspace 2, &etc;</para></listitem>

</itemizedlist>

<para>Note that if you <emphasis>do</emphasis> choose a
<literal>branch</literal> yourself, that it will override this setting. The
same is true of other specific branch selection options such as <link
linkend="conf-tag">tag</link>.</para>

<para>This option was added in &kdesrc-build; 1.16-pre2.</para>

<note><para>This option only applies to <literal>kde-projects</literal> &git;
modules (the common case).  See also <xref
linkend="kde-projects-module-sets"/>.
</para></note>

</entry>
</row>

<row id="conf-build-dir">
<entry>build-dir</entry>
<entry>Module setting overrides global</entry>
<entry>Use this option to change the directory to contain the built sources. There
are three different ways to use it:

<orderedlist>

<listitem><para>Relative to the &kde; &subversion; source directory (see <link
linkend="conf-source-dir">the source-dir option</link>). This is the default,
and is selected if you type a directory name that does not start with a tilde
(~) or a slash (/).</para> <para>The default value is <filename
class="directory">build</filename>.</para></listitem>

<listitem><para>Absolute path. If you specify a path that begins with a /, then
that path is used directly. For example, <filename
class="directory">/tmp/kde-obj-dir/</filename>.</para></listitem>

<listitem><para>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, <filename
class="directory">~/builddir</filename> would set the build directory to
<filename
class="directory">/home/user-name/builddir</filename>.</para></listitem>

</orderedlist>

Perhaps surprisingly, this option can be changed per module.

</entry>
</row>

<row id="conf-build-when-unchanged">
<entry>build-when-unchanged</entry>
<entry>Module setting overrides global</entry>
<entry><para>Use this option in order to control whether &kdesrc-build; always
tries to build a module that has not had any source code updates.</para>

<para>By setting <option>build-when-unchanged</option> to
<userinput>true</userinput>, &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.</para>

<para>By setting <option>build-when-unchanged</option> to
<userinput>false</userinput>, &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.</para>

<important><para>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.</para></important>
</entry>
</row>

<row id="conf-checkout-only">
<entry>checkout-only</entry>
<entry>Module setting overrides global</entry>
<entry><para>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.
</para>

<para>Note that this setting has no effect on &git; modules due to the
operation of the &git; source control system.</para>

<para>See <xref linkend="checking-out-parts"/> for an example.</para></entry>
</row>

<row id="conf-cmake-options">
<entry>cmake-options</entry>
<entry>Appends to global options (not applicable to qt)</entry>
<entry><para>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.</para>

<para>This option does not apply to qt (which does not use &cmake;). Use
<link linkend="conf-configure-flags">configure-flags</link> instead.</para>

<para>Since these options are passed directly to the &cmake; command line, they
should be given as they would be typed into &cmake;. For example:</para>

<screen>  cmake-options -DCMAKE_BUILD_TYPE=RelWithDebInfo
</screen>

<para>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, <emphasis>required</emphasis> &cmake; parameters
are set for you automatically)</para></entry>
</row>

<row id="conf-colorful-output">
<entry>colorful-output</entry>
<entry>Cannot be overridden</entry>
<entry>Set this option to <userinput>false</userinput> to disable the colorful output of &kdesrc-build;.
This option defaults to <replaceable>true</replaceable>. Note that &kdesrc-build; will not output the
color codes to anything but a terminal (such as xterm, &konsole;, or the normal
&Linux; console).
</entry>
</row>

<row id="conf-configure-flags">
<entry>configure-flags</entry>
<entry>Module setting overrides global</entry>
<entry><para>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. <emphasis>This option
only works for qt.</emphasis></para>

<para>To change configuration settings for KDE 4 modules, see
<link linkend="conf-cmake-options">cmake-options</link>.
</para>
</entry>
</row>

<row id="conf-custom-build-command">
<entry>custom-build-command</entry>
<entry>Module setting overrides global</entry>
<entry>
    <para>This option can be set to run a different command (other than
    <command>make</command>, for example) in order to perform the build
    process.  &kdesrc-build; should in general do the right thing, so you
    should not need to set this option. However it can be useful to use
    alternate build systems.
    </para>

    <para>The value of this option is used as the command line to run, modified
    by the <link linkend="conf-make-options">make-options</link> option as
    normal.
    </para>
</entry>
</row>

<row id="conf-cxxflags">
<entry>cxxflags</entry>
<entry>Appends to global option</entry>
<entry><para>Use this option to specify what flags to use for building the
module. This option is
specified here instead of with <link
linkend="conf-configure-flags">configure-flags</link> or <link
linkend="conf-cmake-options">cmake-options</link> because this option will also
set the environment variable <envar>CXXFLAGS</envar> during the build process.</para>

<para>Note that for &kde; 4 and any other modules that use &cmake;, it is
necessary to set the CMAKE_BUILD_TYPE option to <userinput>none</userinput>
when configuring the module.  This can be done using the <link
linkend="conf-cmake-options">cmake-options</link> option.
</para>
</entry>
</row>

<row id="conf-dest-dir">
<entry>dest-dir</entry>
<entry>Module setting overrides global</entry>
<entry>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
<link linkend="conf-build-dir">build-dir</link> or
<link linkend="conf-source-dir">source-dir</link> options.
</entry>
</row>

<row id="conf-disable-agent-check">
<entry>disable-agent-check</entry>
<entry>Cannot be overridden</entry>
<entry>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
<option>disable-agent-check</option> to <userinput>true</userinput>.
</entry>
</row>

<row id="conf-do-not-compile">
<entry>do-not-compile</entry>
<entry>Module setting overrides global</entry>
<entry><para>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.</para>

<para>Note that the sources to the programs will still be downloaded. You can use
the <link linkend="conf-checkout-only">checkout-only</link>
directive to choose directories that you want to check out.</para>

<para>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.</para>

<para>See <xref linkend="not-compiling"/> for an example.</para>
</entry>
</row>

<row id="conf-email-address">
<entry>email-address</entry>
<entry>Cannot be overridden</entry>
<entry>
<para>This option was removed in &kdesrc-build; 1.14.
</para>
</entry>
</row>

<row id="conf-email-on-compile-error">
<entry>email-on-compile-error</entry>
<entry>Cannot be overridden</entry>
<entry>
<para>This option was removed in &kdesrc-build; 1.14.
</para>
</entry>
</row>

<row>
<entry>inst-apps</entry>
<entry></entry>
<entry>
This option was removed in version 1.10
</entry>
</row>

<row id="conf-git-desired-protocol">
<entry>git-desired-protocol</entry>
<entry>Cannot be overridden</entry>
<entry><para>This option only applies to modules from a <link
linkend="kde-projects-module-sets">&kde; project</link> repository.</para>

<para>What this option actually does is configure which network protocol to
prefer when updating source code for these modules. Normally the very-efficient
<literal>git</literal> protocol is used, but this may be blocked in some
networks (e.g. corporate intranets, public Wi-Fi). An alternative protocol
which is much better supported is the <literal>HTTP</literal> protocol used for
Internet web sites.</para>

<para>If you are using one of these constrained networks you can set this
option to <userinput>http</userinput> to prefer <literal>HTTP</literal>
communications instead.</para>

<tip><para>You may also need the <link
linkend="conf-http-proxy">http-proxy</link> option if an HTTP proxy is also
needed for network traffic.</para></tip>

<para>In any other situation you should not set this option as the default
protocol is most efficient.</para>

<para>This option was added in &kdesrc-build; 1.16.</para>
</entry>
</row>

<row id="conf-git-repository-base">
<entry>git-repository-base</entry>
<entry>Cannot be overridden</entry>
<entry><para>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 <link
linkend="module-sets">module set</link> declarations, which is useful for
quickly declaring many Git modules to build.</para>

<para>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:</para>

<para>
<informalexample>
<programlisting>
global
   # other options

   # This is the common path to all anonymous Git server modules.
   git-repository-base <replaceable>kde-git</replaceable> <replaceable>kde:</replaceable>
end global

# Module declarations

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

   <link linkend="conf-use-modules">use-modules</link> <replaceable>module1.git</replaceable> <replaceable>module2.git</replaceable>
end module-set
</programlisting>
</informalexample>
</para>

<para>The module-set's <literal>use-modules</literal> option created two modules
internally, with &kdesrc-build; behaving as if it had read:</para>

<programlisting>
module module1
    repository kde:<replaceable>module1.git</replaceable>
end module

module module2
    repository kde:<replaceable>module2.git</replaceable>
end module
</programlisting>

<para>The <literal>kde:</literal> &git; repository prefix used above is a
shortcut which will be setup by &kdesrc-build; automatically. See the TechBase
<ulink
url="http://techbase.kde.org/Development/Git/Configuration#URL_Renaming">URL
Renaming</ulink> 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.</para>

<tip><para>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.</para></tip>
</entry>
</row>

<row id="conf-http-proxy">
<entry>http-proxy</entry>
<entry>Module setting overrides global</entry>

<entry><para>This option, if set, uses the specified URL as a proxy server to use for
any HTTP network communications (for example, when downloading snapshots for
new modules, or the <link linkend="kde-projects-module-sets">KDE project
database</link>).</para>

<para>In addition, &kdesrc-build; will try to ensure that the tools it depends
on also use that proxy server, if possible, by setting the
<envar>http_proxy</envar> environment variable to the indicated server,
<emphasis>if that environment variable is not already set</emphasis>.</para>

<para>This option was introduced with &kdesrc-build; 1.16.</para>
</entry>
</row>

<row id="ignore-kde-structure">
<entry>ignore-kde-structure</entry>
<entry>Module setting overrides global</entry>
<entry><para>This option is used to store the source and the build files directly
in the name of the module. For example,
<literal>source/extragear/network/telepathy/ktp-text-ui</literal>
becomes
<literal>source/ktp-text-ui</literal>.
This option is disabled by default. If you want to enable this option you need to set it
to <userinput>true</userinput>.</para>

<para>This option was introduced with &kdesrc-build; 1.16.</para>
</entry>
</row>

<row id="conf-ignore-modules">
<entry>ignore-modules</entry>
<entry>Can't be overridden</entry>
<entry><para>Modules named by this option, which would be chosen by &kdesrc-build;
due to a <link linkend="conf-use-modules">use-modules</link> option, are
instead skipped entirely. Use this option when you want to build an entire
<link linkend="kde-projects-module-sets">kde-projects</link> project grouping
<emphasis>except for</emphasis> some specific modules.</para>

<para>The option value does not necessarily have to name the module directly.
Any module that has full consecutive parts of its <link
linkend="kde-projects-module-sets">&kde; projects module path</link> match one
of the option values will be ignored, so you can ignore multiple modules this
way.</para>

<para>For example, an option value of <replaceable>libs</replaceable> would
result in both <symbol>kde/kdegraphics/libs</symbol> and
<symbol>playground/libs</symbol> being excluded (though not
<symbol>kde/kdelibs</symbol> since the full part <quote>kdelibs</quote> is what
is compared).</para>

<tip><para>See also <xref linkend="example-ignoring-a-module"/>.</para></tip>

<para>This option was introduced with &kdesrc-build; 1.16.</para>
</entry>
</row>

<row id="conf-install-after-build">
<entry>install-after-build</entry>
<entry>Module setting overrides global</entry>
<entry>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 <userinput>false</userinput> in the <link
linkend="configure-data">configuration file</link>. You can also use the <link
linkend="cmdline-no-install"><option>--no-install</option></link> command line
flag.
</entry>
</row>

<row id="conf-install-session-driver">
<entry>install-session-driver</entry>
<entry>Cannot be overridden</entry>
<entry><para>By default, &kdesrc-build; will try to install a driver for the graphical
login manager that allows you to login to your &kdesrc-build;-built &kde; desktop.</para>

<para>This driver will alter the following files:</para>

<itemizedlist>
<listitem><para><filename>~/.xsession</filename> (normally found at <filename>~/.config/kde-env-master.sh</filename>).</para></listitem>
<listitem><para><filename>$XDG_CONFIG_HOME/kde-env-master.sh</filename> (normally found at <filename>~/.config/kde-env-master.sh</filename>).</para></listitem>
<listitem><para><filename>$XDG_CONFIG_HOME/kde-env-user.sh</filename> (normally found at <filename>~/.config/kde-env-user.sh</filename>).</para></listitem>
</itemizedlist>

<para>If you maintain your own login driver then you can disable this feature by setting this
option to <replaceable>false</replaceable>.</para>

<para>This option was introduced with &kdesrc-build; 1.16.</para>

<tip><para>&kdesrc-build; will not overwrite your existing files (if present)
unless you also pass the <option><link
linkend="cmdline-delete-my-settings">--delete-my-settings</link></option>
command-line option.</para></tip>
</entry>
</row>

<row id="conf-kdedir">
<entry>kdedir</entry>
<entry>Module setting overrides global</entry>
<entry>This option sets the directory that &kde; will be installed to after it
is built. It defaults to <filename class="directory">~/kde</filename>. If you
change this to a directory needing root access, you may want to read about the
<link linkend="conf-make-install-prefix">make-install-prefix</link> option as
well.</entry>
</row>

<row id="conf-kde-languages">
<entry>kde-languages</entry>
<entry>Cannot be overridden</entry>
<entry><para>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.</para>

<para>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: <ulink
url="http://i18n.kde.org/teams/">http://i18n.kde.org/teams/</ulink>.
</para>

<para>It is alright to choose only one language. By default, none are
downloaded, which means &kde; will display in American English.</para>

<para>For instance, to choose to install French, you would set the option to
something like: <userinput><option>kde-languages</option>
<replaceable>fr</replaceable></userinput>.  You would still need to use
&systemsettings; in order to choose the French language, however.</para>
</entry>
</row>

<row id="conf-libpath">
<entry>libpath</entry>
<entry>Module setting overrides global</entry>
<entry>Set this option to set the environment variable
<envar>LD_LIBRARY_PATH</envar> while building. You cannot override this setting
in a module option. The default value is blank, but the paths <filename
class="directory">$<envar>KDEDIR</envar>/lib</filename> and <filename
class="directory">$<envar>QTDIR</envar>/lib</filename> are automatically added.
You may use the tilde (~) for any paths you add using this option.
</entry>
</row>

<row id="conf-log-dir">
<entry>log-dir</entry>
<entry>Module setting overrides global</entry>
<entry>Use this option to change the directory used to hold the log files
generated by the script.
</entry>
</row>

<row id="conf-make-install-prefix">
<entry>make-install-prefix</entry>
<entry>Module setting overrides global</entry>
<entry>Set this variable to a space-separated list, which is interpreted as a
command and its options to precede the <userinput><command>make</command> <option>install</option></userinput> command used to install
modules. This is useful for installing packages with &sudo; for example, but
please be careful while dealing with root privileges.</entry>
</row>

<row id="conf-make-options">
<entry>make-options</entry>
<entry>Module setting overrides global</entry>
<entry>Set this variable in order to pass command line options to the
<command>make</command> command. This is useful for programs such as <ulink
url="http://distcc.samba.org/"><application>distcc</application></ulink> or
systems with more than one processor core.
</entry>
</row>

<row id="conf-manual-build">
<entry>manual-build</entry>
<entry>Module setting overrides global</entry>
<entry>Set the option value to <userinput>true</userinput> 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 <link linkend="cmdline-no-build"><option>--no-build</option></link>
command line option.
</entry>
</row>

<row id="conf-manual-update">
<entry>manual-update</entry>
<entry>Module setting overrides global</entry>
<entry>Set the option value to <userinput>true</userinput> 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.
</entry>
</row>

<row id="conf-module-base-path">
<entry>module-base-path</entry>
<entry>Module setting overrides global</entry>
<entry><para>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. <ulink url="http://websvn.kde.org/">The &kde;
Source Viewer</ulink> is invaluable in helping to pick the right path.</para>

<para>Note that &kdesrc-build; constructs the final path according to the
following template:
<filename class="directory"><varname>$svn-server</varname>/home/kde/<varname>$module-base-path</varname></filename>.
</para>

<para>The default value is either <filename
class="directory">trunk/<varname>$module</varname></filename> or <filename
class="directory">trunk/KDE/<varname>$module</varname></filename>, depending on
the module name.</para>

<tip><para>Use the <link linkend="conf-branch">branch</link> or <link
linkend="conf-tag">tag</link> options instead whenever they are applicable.
</para></tip>
</entry>
</row>

<row id="conf-niceness">
<entry>niceness</entry>
<entry>Cannot be overridden</entry>
<entry>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.
</entry>
</row>

<row id="conf-no-svn">
<entry>no-svn</entry>
<entry>Module setting overrides global</entry>
<entry>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.</entry>
</row>

<row>
<entry>no-rebuild-on-fail</entry>
<entry></entry>
<entry>This option was removed in version 1.10, since this behavior no longer helps
due to fixes in the underlying build system.</entry>
</row>

<row id="conf-override-build-system">
<entry>override-build-system</entry>
<entry>Module setting overrides global</entry>
<entry><para>This is an advanced option, added in &kdesrc-build; 1.16.</para>

<para>Normally &kdesrc-build; will detect the appropriate build system to use
for a module after it is downloaded. This is done by checking for the existence
of specific files in the module's source directory.</para>

<para>Some modules may include more than one required set of files, which could confuse
the auto-detection. In this case you can manually specify the correct build type.</para>

<para>Currently supported build types that can be set are:</para>

<variablelist>
    <varlistentry>
        <term>KDE</term>
        <listitem><para>Used to build &kde; modules. In reality it can be used to build
            almost any module that uses &cmake; but it is best not to rely on this.</para></listitem>
    </varlistentry>
    <varlistentry>
        <term>Qt</term>
        <listitem><para>Used to build the &Qt; library itself.</para></listitem>
    </varlistentry>
    <varlistentry>
        <term>qmake</term>
        <listitem><para>Used to build &Qt; modules that use
            <application>qmake</application>-style <literal>.pro</literal>
            files.</para></listitem>
    </varlistentry>
    <varlistentry>
        <term>generic</term>
        <listitem><para>Used to build modules that use plain Makefiles and that do not
            require any special configuration.</para></listitem>
    </varlistentry>
    <varlistentry>
        <term>autotools</term>
        <listitem><para>This is the standard configuration tool used for most Free and
            open-source software not in any of the other categories.</para></listitem>
    </varlistentry>
</variablelist>

</entry>
</row>

<row id="conf-override-url">
<entry>override-url</entry>
<entry>Module setting overrides global</entry>
<entry>If you set this option, &kdesrc-build; will use its value as the &url;
to pass to &subversion; <emphasis>completely unchanged</emphasis>. You should
generally use this if you want to download a specific release but &kdesrc-build;
cannot figure out what you mean using <link linkend="conf-branch">branch</link>.
</entry>
</row>

<row id="conf-persistent-data-file">
<entry>persistent-data-file</entry>
<entry>Cannot be overridden</entry>
<entry><para>Use this option to change where &kdesrc-build; stores its persistent
data. The default is to store this data in a file called
<filename>.kdesrc-build-data</filename> 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.</para>

<para>This option was added with &kdesrc-build; 1.15.</para>
</entry>
</row>

<row id="conf-prefix">
<entry>prefix</entry>
<entry>Module setting overrides global</entry>
<entry><para>This option controls where to install the module (normally the
<option><link linkend="conf-kdedir">kdedir</link></option> 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.</para>
<para>You can use <varname>${MODULE}</varname> or <varname>$MODULE</varname>
in the path to have them expanded to the module's name.</para>
</entry>
</row>

<row id="conf-purge-old-logs">
<entry>purge-old-logs</entry>
<entry>Module setting overrides global</entry>
<entry><para>This option controls whether old log directories are automatically
deleted or not. The default value is <replaceable>true</replaceable>.</para>
</entry>
</row>

<row id="conf-qtdir">
<entry>qtdir</entry>
<entry>Module setting overrides global</entry>
<entry>Set this option to set the environment variable <envar>QTDIR</envar> while building.
You cannot override this setting in a module option. If you do not specify
this option, it defaults to
<filename class="directory"><symbol>${source-dir}</symbol>/build/qt</filename>,
which uses the qt module included in the &kde; source repository.
You may use a tilde (~) to represent your home directory.
</entry>
</row>

<row id="conf-remove-after-install">
<entry>remove-after-install</entry>
<entry>Module setting overrides global</entry>
<entry><para>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.
</para>
<para>Possible values for this option are:
<itemizedlist>
<listitem><para>none - Do not delete anything (This is the default).</para></listitem>
<listitem><para>builddir - Delete the build directory, but not the source.</para></listitem>
<listitem><para>all - Delete both the source code and build directory.</para></listitem>
</itemizedlist>
</para>

<para>Note that using this option can have a significant detrimental impact on
both your bandwidth usage (if you use <replaceable>all</replaceable>) and the time taken to compile &kde;,
since &kdesrc-build; will be unable to perform incremental builds.</para>
</entry>
</row>

<row id="conf-repository">
<entry>repository</entry>
<entry>Module setting overrides global</entry>
<entry><para>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;.</para></entry>
</row>

<row id="conf-revision">
<entry>revision</entry>
<entry>Module setting overrides global</entry>
<entry><para>If this option is set to a value other than 0 (zero), &kdesrc-build;
will force the source update to bring the module to the exact revision
given, even if options like <link linkend="conf-branch">branch</link> 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.</para>

<note><para>This option did not work for git-based modules (including <link
linkend="kde-projects-module-sets">kde-projects</link> modules) until
&kdesrc-build; version 1.16.</para></note>

</entry>
</row>

<row id="conf-run-tests">
<entry>run-tests</entry>
<entry>Module setting overrides global</entry>
<entry>If set to <userinput>true</userinput>, 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.</entry>
</row>

<row id="conf-set-env">
<entry>set-env</entry>
<entry>Module setting overrides global</entry>
<entry><para>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 <envar>RONALD</envar> to
McDonald, you would put in the appropriate section this command:</para>
<screen><command>set-env</command> <envar>RONALD</envar> <userinput>McDonald</userinput></screen>
<para>This option is special in that it can be repeated without overriding
earlier set-env settings in the same section of the <link linkend="configure-data">configuration file</link>. This
way you can set more than one environment variable per module (or
globally).</para>
</entry>
</row>

<row id="conf-source-dir">
<entry>source-dir</entry>
<entry>Module setting overrides global</entry>
<entry>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
<filename class="directory">~/kdesrc</filename>. You may use the tilde (~)
to represent the home directory if using this option.
</entry>
</row>

<row id="conf-ssh-identity-file">
<entry>ssh-identity-file</entry>
<entry>Cannot be overridden</entry>
<entry>
<para>Set this option to control which private SSH key file is passed to the
<command>ssh-add</command> command when &kdesrc-build; is downloading source
code from repositories that require authentication. See also: <xref
linkend="ssh-agent-reminder"/>.</para>

<para>This option was added in version 1.14.2.</para>
</entry>
</row>

<row id="conf-stop-on-failure">
<entry>stop-on-failure</entry>
<entry>Module setting overrides global</entry>
<entry>Set this option value to <userinput>true</userinput> to cause the script to stop execution
after an error occurs during the build or install process. This option is off
by default.
</entry>
</row>

<row id="conf-svn-server">
<entry>svn-server</entry>
<entry>Module setting overrides global</entry>
<entry><para>This option is used to set the server used to check out from &subversion;.
The default is the anonymous &subversion; repository, <filename>svn://anonsvn.kde.org/</filename></para>
<note><para>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.</para></note>
</entry>
</row>

<row id="conf-tag">
<entry>tag</entry>
<entry>Module setting overrides global</entry>
<entry><para>Use this option to download a specific release of a module.</para>
<para><emphasis>Note:</emphasis> The odds are very good that you <emphasis>do not
want</emphasis> to use this option. &kde; releases are available in tarball form
from <ulink url="ftp://ftp.kde.org/">The &kde; FTP site</ulink> or one of <ulink
url="http://download.kde.org/download.php">its mirrors</ulink>.</para>

<note><para>This option has only been supported for git-based modules since
&kdesrc-build; 1.16.</para></note>
</entry>
</row>

<row id="conf-use-clean-install">
<entry>use-clean-install</entry>
<entry>Module setting overrides global</entry>
<entry><para>Set this option to <userinput>true</userinput> in order to
have &kdesrc-build; run <command>make uninstall</command> directly before
running <command>make install</command>.</para>

<para>This can be useful in ensuring that there are not stray old library
files, &cmake; metadata, etc. that can cause issues in long-lived &kde;
installations. However this only works on build systems that support
<command>make uninstall</command>.</para>

<para>This option was added with &kdesrc-build; 1.12, but was not documented
until &kdesrc-build; 1.16.</para>
</entry>
</row>

<row>
<entry>use-cmake</entry>
<entry></entry>
<entry>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.
</entry>
</row>

<row id="conf-use-idle-io-priority">
<entry>use-idle-io-priority</entry>
<entry>Cannot be overridden</entry>
<entry>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 <userinput>true</userinput>.
</entry>
</row>

<row id="conf-use-modules">
<entry>use-modules</entry>
<entry>Can only use in <link linkend="module-sets">module-set</link></entry>
<entry><para>This option, added in &kdesrc-build; 1.12.1, allows you to easily
specify many different modules to build at the same point in <link
linkend="kdesrc-buildrc">the configuration file</link>.</para>

<para>This option <emphasis>must</emphasis> be used within a
<literal>module-set</literal>. Every identifier passed to this option is
internally converted to a &kdesrc-build; module, with a <link
linkend="conf-repository"><option>repository</option></link> 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.</para>

<para>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.</para>

<para>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).</para>

<important><para>The name to use for the module if you do this is simply the
name that you passed to <option>use-modules</option>, with the exception that
any <literal>.git</literal> is removed.</para></important>

<para>See <xref linkend="module-sets"/> and <link
linkend="conf-git-repository-base">git-repository-base</link> for a description
of its use and an example.</para>
</entry>
</row>

<row id="conf-use-qt-builddir-hack">
<entry>use-qt-builddir-hack</entry>
<entry>Module setting overrides global</entry>
<entry>This option has been removed due to improvements in the &Qt; build
system.
</entry>
</row>

<row id="conf-use-stable-kde">
<entry>use-stable-kde</entry>
<entry>Can't be overridden</entry>
<entry><para>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.</para>

<para>So, if you set this option to <replaceable>true</replaceable>,
&kdesrc-build; will (for a given module) automatically download the version of
that module which is marked as stable in kde_projects.xml.</para>

<para>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.
</para>

</entry>
</row>

</tbody>

</tgroup>
</table>

</sect1>
</chapter>

<chapter id="cmdline">
<title>Command Line Options and Environment Variables</title>

<sect1 id="cmdline-usage">
<title>Command Line Usage</title>

<para>&kdesrc-build; is designed to be run as follows:</para>

<cmdsynopsis>
<command>kdesrc-build</command>
<arg rep="repeat"><replaceable>--options</replaceable></arg>
<arg rep="repeat"><replaceable>modules to build</replaceable></arg>
</cmdsynopsis>

<para>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).</para>

<sect2 id="cmdline-usage-options">
<title>Commonly used command line options</title>

<para>The full list of command line options is given in <xref
linkend="supported-cmdline-params"/>. The most-commonly used options
include:</para>

<variablelist>
  <varlistentry>
    <term><option>--pretend</option> (or <option>-p</option>)</term>
    <listitem><para>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.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><option>--refresh-build</option></term>
    <listitem><para>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.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><option>--no-src</option></term>
    <listitem><para>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.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><option>--no-build</option></term>
    <listitem><para>This option is similar to <option>--no-src</option> above,
    but this time the build process is skipped.</para></listitem>
  </varlistentry>
</variablelist>

</sect2>

<sect2 id="cmdline-usage-modules">
<title>Specifying modules to build</title>

<para>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 <link
linkend="conf-use-modules">use-modules</link>, or the name of the entire module
set itself, if you have given it a name.</para>

<para>In the specific case of module sets based against the <link
linkend="kde-projects-module-sets">KDE project database</link>, &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
<literal>extragear/utils/kdesrc-build</literal>. You could specify any
of the following to build &kdesrc-build;:</para>

<informalexample>
<screen>
<prompt>&percnt;</prompt> <command>kdesrc-build</command> <option><replaceable>+extragear/utils/kdesrc-build</replaceable></option>
<prompt>&percnt;</prompt> <command>kdesrc-build</command> <option><replaceable>+utils/kdesrc-build</replaceable></option>
<prompt>&percnt;</prompt> <command>kdesrc-build</command> <option><replaceable>+kdesrc-build</replaceable></option>
</screen>
</informalexample>

<note><para>The commands in the previous example preceded the module-name with
a <symbol>+</symbol>. 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.
</para></note>

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

</sect2>
</sect1>

<sect1 id="supported-envvars">
<title>Supported Environment Variables</title>

<para>
&kdesrc-build; does not use environment variables. If you need to set environment
variables for the build or install process, please see the <link
linkend="conf-set-env">set-env</link> option.
</para>

</sect1>

<sect1 id="supported-cmdline-params">
<title>Supported command-line parameters</title>

<para>
The script accepts the following command-line options:
</para>

<variablelist>

<varlistentry id="cmdline-async">
<term><parameter>--async</parameter></term>
<listitem><para>
Enables the <link linkend="conf-async">asynchronous mode</link>, 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.
</para></listitem>
</varlistentry>

<varlistentry id="cmdline-help">
<term><parameter>--help</parameter></term>
<listitem><para>
Only display simple help on this script.
</para></listitem>
</varlistentry>

<varlistentry id="cmdline-version">
<term><parameter>--version</parameter></term>
<listitem><para>
Display the program version.
</para></listitem>
</varlistentry>

<varlistentry id="cmdline-author">
<term><parameter>--author</parameter></term>
<listitem><para>
Display contact information for the
author.
</para></listitem>
</varlistentry>

<varlistentry id="cmdline-color">
<term><parameter>--color</parameter></term>
<listitem><para>
Enable colorful output. (This is the default for interactive terminals).
</para></listitem>
</varlistentry>

<varlistentry id="cmdline-nice">
<term><parameter>--nice=<replaceable>value</replaceable></parameter></term>
<listitem><para>
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 <quote>nice</quote>), 20 is lowest priority. &kdesrc-build; defaults
to 10.
</para></listitem>
</varlistentry>

<varlistentry id="cmdline-no-async">
<term><parameter>--no-async</parameter></term>
<listitem><para>
Disables the <link linkend="conf-async">asynchronous mode</link> 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
<ulink url="http://bugs.kde.org/">bug report</ulink>.
</para></listitem>
</varlistentry>

<varlistentry id="cmdline-no-color">
<term><parameter>--no-color</parameter></term>
<listitem><para>
Disable colorful output.
</para></listitem>
</varlistentry>

<varlistentry id="cmdline-pretend">
<term><parameter>--pretend</parameter> (or <parameter>-p</parameter>)</term>
<listitem><para>
&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.).</para>

<para>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).
</para></listitem>
</varlistentry>

<varlistentry id="cmdline-quiet">
<term><parameter>--quiet</parameter> (or <parameter>-q</parameter>)</term>
<listitem><para>
Do not be as noisy with the output. With this switch only the basics are
output.
</para></listitem>
</varlistentry>

<varlistentry id="cmdline-really-quiet">
<term><parameter>--really-quiet</parameter></term>
<listitem><para>
Only output warnings and errors.
</para></listitem>
</varlistentry>

<varlistentry id="cmdline-verbose">
<term><parameter>--verbose</parameter> (or <parameter>-v</parameter>)</term>
<listitem><para>
Be very descriptive about what is going on, and what &kdesrc-build; is doing.
</para></listitem>
</varlistentry>

<varlistentry id="cmdline-src-only">
<term><parameter>--src-only</parameter> (or <parameter>--svn-only</parameter>)</term>
<listitem><para>
Only perform the source update. (The <parameter>--svn-only</parameter> is
only supported for compatibility with older scripts).
</para></listitem>
</varlistentry>

<varlistentry id="cmdline-build-only">
<term><parameter>--build-only</parameter></term>
<listitem><para>
Only perform the build process.
</para></listitem>
</varlistentry>

<varlistentry id="cmdline-ignore-modules">
<term><parameter>--ignore-modules</parameter></term>
<listitem><para>
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 <link linkend="configure-data">configuration file</link> and just skip
a few).
</para></listitem>
</varlistentry>

<varlistentry id="cmdline-no-src">
<term><parameter>--no-src</parameter> (or <parameter>--no-svn</parameter>)</term>
<listitem><para>
Skip contacting the &subversion; server. (The <parameter>--no-svn</parameter>
parameter is only supported for compatibility with older versions of the
script).
</para></listitem>
</varlistentry>

<varlistentry id="cmdline-no-build">
<term><parameter>--no-build</parameter></term>
<listitem><para>
Skip the build process.
</para></listitem>
</varlistentry>

<varlistentry id="cmdline-no-install">
<term><parameter>--no-install</parameter></term>
<listitem><para>
Do not automatically install packages after they are built.
</para></listitem>
</varlistentry>

<varlistentry id="cmdline-no-build-when-unchanged">
<term><parameter>--no-build-when-unchanged</parameter></term>
<term><parameter>--force-build</parameter></term>
<listitem><para>
This option explicitly disables skipping the build process (an optimization
controlled by the <link
linkend="conf-build-when-unchanged">build-when-unchanged</link> option). This is
useful for making &kdesrc-build; run the build when you have changed something
that &kdesrc-build; cannot check.</para>

<para><parameter>--force-build</parameter> performs the exact same function, and
is perhaps easier to remember.</para>
</listitem>
</varlistentry>

<varlistentry id="cmdline-debug">
<term><parameter>--debug</parameter></term>
<listitem><para>
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.
</para></listitem>
</varlistentry>

<varlistentry id="cmdline-no-rebuild-on-fail">
<term><parameter>--no-rebuild-on-fail</parameter></term>
<listitem><para>
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.
</para></listitem>
</varlistentry>

<varlistentry id="cmdline-refresh-build">
<term><parameter>--refresh-build</parameter></term>
<listitem><para>
Recreate the build system and make from scratch.
</para></listitem>
</varlistentry>

<varlistentry id="cmdline-reconfigure">
<term><parameter>--reconfigure</parameter></term>
<listitem><para>
Run <command>cmake</command> (for &kde; modules) or
<command>configure</command> (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 <parameter><link
linkend="cmdline-refresh-build">--refresh-build</link></parameter> is used.
</para></listitem>
</varlistentry>

<varlistentry id="cmdline-resume-from">
<term><parameter>--resume-from</parameter></term>
<listitem><para>
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.
</para>

<note><para>This option formerly added <link
    linkend="cmdline-no-src"><parameter>--no-src</parameter></link>, but does
not any longer (since &kdesrc-build; 1.13). If you want to avoid source updates
when resuming, simply pass <option><userinput>--no-src</userinput></option>
in addition to the other options.
</para></note>

<para>See also: <xref linkend="cmdline-resume-after"/> and <xref
linkend="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.</para></listitem>
</varlistentry>

<varlistentry id="cmdline-resume-after">
<term><parameter>--resume-after</parameter></term>
<listitem><para>
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.
</para>

<note><para>This option formerly added <link
    linkend="cmdline-no-src"><parameter>--no-src</parameter></link>, but does
not any longer (since &kdesrc-build; 1.13). If you want to avoid source updates
when resuming, simply pass <option><userinput>--no-src</userinput></option>
in addition to the other options.
</para></note>

<para>See also: <xref linkend="cmdline-resume-from"/> and <xref
linkend="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.</para></listitem>
</varlistentry>

<varlistentry id="cmdline-stop-before">
<term><parameter>--stop-before</parameter></term>
<listitem><para>
This command line option is used to stop the normal build process just
<emphasis>before</emphasis> a module would ordinarily be built.
</para><para>
For example, if the normal build list was <simplelist type="inline">
<member>moduleA</member><member>moduleB</member><member>moduleC</member></simplelist>,
then <option>--stop-before=<replaceable>moduleB</replaceable></option> would cause
&kdesrc-build; to only build <literal>moduleA</literal>.
</para><para>
This command line option was added with &kdesrc-build; 1.16.
</para></listitem>
</varlistentry>

<varlistentry id="cmdline-stop-after">
<term><parameter>--stop-after</parameter></term>
<listitem><para>
This command line option is used to stop the normal build process just
<emphasis>after</emphasis> a module would ordinarily be built.
</para><para>
For example, if the normal build list was <simplelist type="inline">
<member>moduleA</member><member>moduleB</member><member>moduleC</member></simplelist>,
then <option>--stop-after=<replaceable>moduleB</replaceable></option> would cause
&kdesrc-build; to build <literal>moduleA</literal> and <literal>moduleB</literal>.
</para><para>
This command line option was added with &kdesrc-build; 1.16.
</para></listitem>
</varlistentry>

<varlistentry id="cmdline-rc-file">
<term><parameter>--rc-file</parameter></term>
<listitem><para>
This interprets the next command line parameter as the file to read the
configuration options from. The default value for this parameter is
<filename>kdesrc-buildrc</filename> (checked in the current directory) if
it is present, or <filename>~/.kdesrc-buildrc</filename> otherwise. See
also <xref linkend="kdesrc-buildrc" />.
</para></listitem>
</varlistentry>

<varlistentry id="cmdline-run">
<term><parameter>--run</parameter></term>
<listitem><para>
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.</para>

<para>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 <envar>PATH</envar> and
<envar>KDEDIRS</envar>) in the startup sequence.
</para>

<tip><para>If you want to see the environment used by &kdesrc-build;, you
can run the <command>printenv</command> command:</para>
<informalexample>
<screen>$ <command>kdesrc-build</command> <parameter>--run</parameter> <parameter>printenv</parameter>
KDE_SESSION_VERSION=4
SDL_AUDIODRIVER=alsa
LANGUAGE=
XCURSOR_THEME=Oxygen_Blue
LESS=-R -M --shift 5
QMAIL_CONTROLDIR=/var/qmail/control
... etc.
</screen>
</informalexample></tip>
</listitem>
</varlistentry>

<varlistentry id="cmdline-prefix">
<term><parameter>--prefix=&lt;/path/to/kde&gt;</parameter></term>
<listitem><para>
This allows you to change the directory that &kde; will be installed to from
the command line.  This option implies <link
linkend="cmdline-reconfigure"><parameter>--reconfigure</parameter></link>,
but using <link linkend="cmdline-refresh-build"><parameter>--refresh-build</parameter></link>
may still be required.
</para></listitem>
</varlistentry>

<varlistentry id="cmdline-revision">
<term><parameter>--revision</parameter></term>
<listitem><para>
This option causes &kdesrc-build; to checkout a specific numbered revision
for each &subversion; module, overriding any <link linkend="conf-branch">branch</link>,
<link linkend="conf-tag">tag</link>, or <link linkend="conf-revision">revision</link>
options already set for these modules.</para>

<para>This option is likely not a good idea, and is only supported for
compatibility with older scripts.
</para></listitem>
</varlistentry>

<varlistentry id="cmdline-build-system-only">
<term><parameter>--build-system-only</parameter></term>
<listitem><para>
This option causes &kdesrc-build; to abort building a module just before
the <command>make</command> 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.
</para></listitem>
</varlistentry>

<varlistentry id="cmdline-install"><term><parameter>--install</parameter></term>
<listitem><para>
If this is the only command-line option, it tries to install all of the modules
contained in <filename>log/latest/build-status</filename>. If command-line
options are specified after <parameter>--install</parameter>, they are all
assumed to be modules to install (even if they did not successfully build on
the last run).
</para></listitem>
</varlistentry>

<varlistentry id="cmdline-no-snapshots"><term><parameter>--no-snapshots</parameter></term>
<listitem><para>
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 <literal>kde-projects</literal> 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.
</para>

<note><para>Module snapshots <emphasis>are</emphasis> real checkouts. You
should not need to specify this option, it is only a troubleshooting
aid.</para></note>
</listitem>
</varlistentry>

<varlistentry id="cmdline-delete-my-patches">
<term><parameter>--delete-my-patches</parameter></term>
<listitem><para>
This option is used to let &kdesrc-build; delete source directories that may
contain user data, so that the module can be re-downloaded. This would normally
only be useful for &kde; developers (who might have local changes that would be
deleted).</para>

<para>This is currently only used to checkout modules that have been converted
from &subversion; to &git;. You should not use this option normally,
&kdesrc-build; will prompt to be re-run with it if it is needed.</para>
</listitem>
</varlistentry>

<varlistentry id="cmdline-delete-my-settings">
<term><parameter>--delete-my-settings</parameter></term>
<listitem><para>
This option is used to let &kdesrc-build; overwrite existing files which may contain
user data.</para>

<para>This is currently only used for xsession setup for the login manager. You
should not use this option normally, &kdesrc-build; will prompt to be re-run
with it if it is needed.</para>
</listitem>
</varlistentry>

<varlistentry id="cmdline-global-option">
<term><parameter>--&lt;option-name&gt;=</parameter></term>
<listitem><para>
You can use this option to override an option in your <link linkend="configure-data">configuration file</link> for
every module. For instance, to override the <link
linkend="conf-log-dir">log-dir</link> option, you would do:
<userinput><parameter>--log-dir=<filename class="directory"><replaceable>/path/to/dir</replaceable></filename></parameter></userinput>.
</para></listitem>
</varlistentry>

<varlistentry id="cmdline-module-option">
<term><parameter>--&lt;module-name&gt;,&lt;option-name&gt;=</parameter></term>
<listitem><para>
You can use this option to override an option in your <link linkend="configure-data">configuration file</link> for
a specific module.
</para></listitem>
</varlistentry>

</variablelist>

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

</sect1>

</chapter>

<chapter id="using-kdesrc-build">
<title>Using &kdesrc-build;</title>

<sect1 id="using-kdesrc-build-preface">
<title>Preface</title>

<para>Normally using &kdesrc-build; after you have gone through <xref linkend="getting-started" />
is as easy as doing the following from a terminal prompt:</para>

<screen>
<prompt>&percnt;</prompt> <command><userinput>kdesrc-build</userinput></command>
</screen>

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

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

</sect1>

<sect1 id="basic-features">
<title>Basic &kdesrc-build; features</title>

<sect2 id="using-qt">
<title>qt support</title>
<para>&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.</para>

<note><para>&Qt; is developed under a separate repository from &kde; software
located at <ulink
url="http://qt.gitorious.org/qt">http://qt.gitorious.org/qt</ulink>.</para></note>

<para>In order to build &Qt;, you should make sure that the
<link linkend="conf-qtdir">qtdir</link> setting is set to the directory you'd
like to install &Qt; to, as described in <xref linkend="configure-data"/>.</para>

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

<para>Now you should verify the <link
linkend="conf-repository">repository</link> option and <link
linkend="conf-branch">branch</link> options are set appropriately:</para>

<orderedlist>
<listitem><para>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.</para>

<para>You can set the <option>repository</option> option for the qt
module to <userinput>kde:qt</userinput> to use this option.</para>
</listitem>

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

<para>In both cases, the branch option should be set to <userinput>master</userinput> (unless you'd
like to build a different branch).</para>

</sect2>

<sect2 id="kdesrc-build-std-flags">
<title>Standard flags added by &kdesrc-build;</title>
<para>To save you time, &kdesrc-build; adds some standard paths to your
environment for you:
</para>

<itemizedlist>
<listitem><para>
The path to the &kde; and &Qt; libraries is added to the
<envar>LD_LIBRARY_PATH</envar> variable automatically. This means that you
do not need to edit &libpath; to include them.
</para></listitem>

<listitem><para>
The path to the &kde; and &Qt; development support programs are added to the
<envar>PATH</envar> variable automatically. This means that you do not need to
edit &binpath; to include them.
</para></listitem>

<listitem><para>
The path to the &kde;-provided <application>pkg-config</application> is added
automatically to <envar>PKG_CONFIG_PATH</envar>. This means that you do not
need to use &set-env; to add these.
</para></listitem>

<listitem><para>
The setting for &kdedir; is automatically propagated to the <envar>KDEDIR</envar>
environment variable while building. (<envar>KDEDIRS</envar> is not affected).
</para></listitem>

<listitem><para>
The setting for &qtdir; is automatically propagated to the <envar>QTDIR</envar>
environment variable while building.
</para></listitem>

</itemizedlist>

</sect2>

<sect2 id="build-priority">
<title>Changing &kdesrc-build;'s build priority</title>
<para>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.
</para>

<para>&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.
</para>

<para>&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 <ulink url="http://setiathome.ssl.berkeley.edu/">Seti@Home</ulink>.
</para>

<para>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 <link
linkend="configure-data">configuration file</link>. The &niceness; setting
controls how <quote>nice</quote> &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).</para>

<para>You can also temporarily change the priority for &kdesrc-build; by using
the &cmd-nice; <link linkend="cmdline">command line option</link>. The value to
the option is used exactly the same as for &niceness;.</para>

<note><para>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.
</para></note>

<informalexample>
<para>To run &kdesrc-build; with a niceness of 15 (a lower priority than
normal):</para>

<screen>
<prompt>&percnt;</prompt> <userinput><command>kdesrc-build</command> <option>--nice=<replaceable>15</replaceable></option></userinput>
</screen>

<para>Or, you can edit the <link linkend="configure-data">configuration file</link> to make the change permanent:</para>

<screen>
    &niceness; <replaceable>15</replaceable>
</screen>
</informalexample>

<tip>
<para>The <link linkend="conf-niceness">niceness</link> 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 (<acronym>I/O</acronym>) a
program uses. In order to control how much <acronym>I/O</acronym> a program can
use, modern &Linux; operating systems support a similar tool called
<application>ionice</application>. &kdesrc-build; supports
<application>ionice</application>, (but only to enable or disable it
completely) using the <link
linkend="conf-use-idle-io-priority">use-idle-io-priority</link> option,
since &kdesrc-build; version 1.12.
</para>
</tip>

</sect2>

<sect2 id="root-installation">
<title>Installation as the superuser</title>
<para>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.
</para>

<para>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.</para>

<para>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.
</para>

<informalexample>
<para>For example, to install all modules using &sudo;,
you could do something like this:</para>

<screen>
global
  &make-install-prefix; <replaceable>sudo</replaceable>
  # Other options
end global
</screen>

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

<screen>
module <replaceable>svn-module-name</replaceable>
  &make-install-prefix; <replaceable>sudo</replaceable>
end module
</screen>
</informalexample>

</sect2>

<sect2 id="build-progress">
<title>Showing the progress of a module build</title>
<para>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.
</para>

</sect2>

</sect1>

<sect1 id="advanced-features">
<title>Advanced features</title>

<sect2 id="partial-builds">
<title>Partially building a module</title>
<para>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.
</para>

<sect3 id="checking-out-parts">
<title>Checking out portions of a module</title>

<para>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.
</para>

<tip><para>
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
<ulink url="http://websvn.kde.org/branches/KDE/4.6/">WebSVN</ulink>.
</para></tip>

<informalexample>
<para>To only grab &kuser; and <application>KSystemLog</application> from
kdeadmin, you could use &checkout-only; like this:</para>

<screen>
module <replaceable>kdeadmin</replaceable>
  &checkout-only; <replaceable>kuser ksystemlog</replaceable>
end module
</screen>

</informalexample>

<important><para>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.</para>

<para>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.</para>
</important>

<para>One final note to make about this option: If you change the value of this
option, you should use <userinput><command>kdesrc-build</command>
<option>&cmd-refresh-build;</option> <option><replaceable>module</replaceable></option></userinput>
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.</para>

</sect3>

<sect3 id="not-compiling">
<title>Removing directories from a build</title>
<para>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.
</para>

<para>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.</para>

<important><para>
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 <userinput><command>kdesrc-build</command>
<option>&cmd-reconfigure;</option>
<option><replaceable>module</replaceable></option></userinput> command.
</para></important>

<informalexample>
<para>To remove the <filename class="directory">python</filename> directory
from the kdebindings build process:</para>

<screen>
module <replaceable>kdebindings</replaceable>
  &do-not-compile; <replaceable>python</replaceable>
end module
</screen>

</informalexample>

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

</sect3>

</sect2>

<sect2 id="using-branches">
<title>Branching and tagging support for &kdesrc-build;</title>

<sect3 id="branches-and-tags">
<title>What are branches and tags?</title>

<para>&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.
</para>

<para>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.
</para>

<para>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.
</para>

<para>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.
</para>

</sect3>

<sect3 id="branch-support">
<title>How to use branches and tags</title>

<para>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.
</para>

<para>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.</para>

<informalexample>
<para>To download kdelibs from &kde; 4.6 (which is simply known as the 4.6 branch):
</para>

<screen>
module kdelibs
  branch <replaceable>4.6</replaceable>
  # other options...
end module
</screen>

<para>Or, to download kdemultimedia as it was released with &kde; 4.6.1:</para>

<screen>
module kdemultimedia
  tag <replaceable>4.6.1</replaceable>
  # other options...
end module
</screen>

</informalexample>

<tip><para>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!
</para></tip>
</sect3>

<sect3 id="advanced-branches">
<title>Advanced branch support options</title>

<para>&kdesrc-build; supports two options for situations where &branch; and &tag;
guess the correct path improperly: &module-base-path; and &override-url;.
</para>

<itemizedlist>
<listitem><para>
&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
<filename class="directory">svnRoot/module-base-path/<replaceable>module-name</replaceable></filename>. Normally &kdesrc-build;
can figure out the appropriate middle part by itself. When it cannot, you can use
&module-base-path;, like this:
</para>

<informalexample>
<screen>
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
</screen>

<para>This would cause &kdesrc-build; to download kdesupport from (in this example),
<filename>svn://anonsvn.kde.org/home/kde/<replaceable>tags/kdesupport-for-4.5</replaceable></filename>.
</para>
</informalexample>
<tip><para>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 <link linkend="cmdline-pretend">--pretend</link> option.
</para></tip>
</listitem>

<listitem><para>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.
</para>

<important><para>
&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.
</para></important>

</listitem>
</itemizedlist>

</sect3>

</sect2>

<sect2 id="building-successfully">
<title>How &kdesrc-build; tries to ensure a successful build</title>

<sect3 id="automatic-rebuilds">
<title>Automatic rebuilds</title>

<para>&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:</para>

<itemizedlist>

<listitem><para>If you change <link linkend="conf-configure-flags">configure-flags</link>
or <link linkend="conf-cmake-options">cmake-options</link> for a module, then
&kdesrc-build; will detect that and automatically re-run configure or cmake
for that module.</para></listitem>

<listitem><para>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 <link
linkend="cmdline-refresh-build">--refresh-build</link> for a specific module
without having that performed on other modules.</para></listitem>

</itemizedlist>

</sect3>

<sect3 id="manual-rebuilds">
<title>Manually rebuilding a module</title>
<para>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.</para>

<para>You can do this by simply running <userinput><command>kdesrc-build</command>
 <option>--refresh-build</option> <option><replaceable>module</replaceable></option></userinput>.
</para>

<para>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 <filename>.refresh-me</filename>
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.</para>

<tip>
<para>By default, the build directory is <filename class="directory">~/kdesrc/build/<replaceable>module</replaceable>/</filename>.
If you change the setting of the &build-dir; option, then use that instead of
<filename class="directory">~/kdesrc/build</filename>.</para>
</tip>

<informalexample>
<para>Rebuild using <filename>.refresh-me</filename> for module <replaceable>kdelibs</replaceable>:</para>
<screen>
<prompt>&percnt;</prompt> <userinput><command>touch</command> <filename>~/kdesrc/build/<replaceable>kdelibs</replaceable>/.refresh-me</filename></userinput>
<prompt>&percnt;</prompt> <userinput><command>kdesrc-build</command></userinput>
</screen>
</informalexample>
</sect3>

</sect2>

<sect2 id="changing-environment">
<title>Changing environment variable settings</title>
<para>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.</para>

<para>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.</para>

<para>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.</para>

<informalexample>
<para>Set <userinput><envar>DISTRO</envar>=<replaceable>BSD</replaceable></userinput>
for all modules:</para>
<screen>
global
  set-env <replaceable>DISTRO</replaceable> <replaceable>BSD</replaceable>
end global
</screen>
</informalexample>

</sect2>

<sect2 id="resuming">
<title>Resuming builds</title>

<sect3 id="resuming-failed">
<title>Resuming a failed or canceled build</title>

<para>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.</para>

<note><para>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 <option>--no-src</option> command line option
to skip the source update.</para></note>

<informalexample>
<para>Resuming the build starting from kdebase:</para>

<screen>
<prompt>&percnt;</prompt> <userinput><command>kdesrc-build</command> <option>--resume-from=<replaceable>kdebase</replaceable></option></userinput>
</screen>
</informalexample>

<informalexample>
<para>Resuming the build starting after kdebase (in case you manually fixed
the issue and installed the module yourself):</para>

<screen>
<prompt>&percnt;</prompt> <userinput><command>kdesrc-build</command> <option>--resume-after=<replaceable>kdebase</replaceable></option></userinput>
</screen>
</informalexample>

</sect3>

<sect3 id="ignoring-modules">
<title>Ignoring modules in a build</title>

<para>Similar to the way you can <link linkend="resuming-failed">resume the
build from a module</link>, you can instead choose to update and build everything
normally, but ignore a set of modules.</para>

<para>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.</para>

<informalexample>
<para>Ignoring extragear/multimedia and kdereview during a full run:</para>
<screen>
<prompt>&percnt;</prompt> <userinput><command>kdesrc-build</command> <option>--ignore-modules</option> <replaceable>extragear/multimedia kdereview</replaceable></userinput>
</screen>
</informalexample>

</sect3>
</sect2>

<sect2 id="changing-env-from-cmd-line">
<title>Changing options from the command line</title>

<sect3 id="changing-global-opts">
<title>Changing global options</title>
<para>You can change the setting of options read from the <link linkend="configure-data">configuration file</link> 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.</para>

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

<informalexample>
<para>Setting the &source-dir; option to <filename>/dev/null</filename> for
testing:</para>

<screen>
<prompt>&percnt;</prompt> <userinput><command>kdesrc-build</command> <option>--pretend</option> <option>--<replaceable>source-dir</replaceable>=<replaceable>/dev/null</replaceable></option></userinput>
</screen>

</informalexample>

</sect3>

<sect3 id="changing-module-opts">
<title>Changing module options</title>
<para>It is also possible to change options only for a specific module. The
syntax is similar: --<replaceable>module</replaceable>,<replaceable>option-name</replaceable>=<replaceable>value</replaceable>.
</para>

<para>This change overrides any duplicate setting for the module found in the
<link linkend="configure-data">configuration file</link>, and applies only while the option is passed on the command line.</para>

<informalexample>
<para>Using a different build directory for the kdeedu module:</para>

<screen>
<prompt>&percnt;</prompt> <userinput><command>kdesrc-build</command> <option>--<replaceable>kdeedu</replaceable>,<replaceable>build-dir</replaceable>=<replaceable>temp-build</replaceable></option></userinput>
</screen>

</informalexample>

</sect3>

</sect2>

</sect1>

<sect1 id="developer-features">
<title>Features for &kde; developers</title>

<sect2 id="ssh-agent-reminder">
<title>&ssh; Agent checks</title>
<para>&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.
</para>

<note><para>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.
</para></note>

<para>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 <option>disable-agent-check</option> option to
<userinput>true</userinput>.</para>

<informalexample>
<para>Disabling the &ssh; agent check:</para>
<screen>
global
  disable-agent-check true
end global
</screen>
</informalexample>

</sect2>

</sect1>

<sect1 id="other-features">
<title>Other &kdesrc-build; features</title>

<sect2 id="changing-verbosity">
<title>Changing the amount of output from &kdesrc-build;</title>
<para>&kdesrc-build; has several options to control the amount of output the
script generates. In any case, errors will always be output.</para>

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

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

<listitem><para>The <option>--verbose</option> option (short form is
<option>-v</option>) causes &kdesrc-build; to be very detailed in its
output.</para></listitem>

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

</sect2>

<sect2 id="kdesrc-build-color">
<title>Color output</title>
<para>When being run from &konsole; or a different terminal, &kdesrc-build;
will normally display with colorized text.</para>

<para>You can disable this by using the <option>--no-color</option> on the
command line, or by setting the &colorful-output; option in the <link linkend="configure-data">configuration file</link> to
<userinput>false</userinput>.
</para>

<informalexample>
<para>Disabling color output in the configuration file:</para>
<screen>
global
  colorful-output false
end global
</screen>
</informalexample>

</sect2>

<sect2 id="deleting-build-dir">
<title>Removing unneeded directories after a build</title>
<para>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;.</para>

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

<orderedlist>
<listitem><para>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 <link linkend="configure-data">configuration file</link>, 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 <emphasis>should not</emphasis> delete them
if you are actually using them, at least until you are done using
&kdesrc-build;.</para>

<para>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.</para>

<para>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.
</para>
</listitem>

<listitem>
<para>&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.</para>

<para>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.</para>
</listitem>

<listitem><para>
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.
</para></listitem>
</orderedlist>

<para>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.
</para>

<warning><para>
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!
</para></warning>

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

<screen>
global
  configure-flags      --enable-debug
  remove-after-install builddir        # Remove build directory after install
end global
</screen>

<para>Removing the build directory after installation, without debugging
information, with size optimization.</para>

<screen>
global
  cxxflags             -Os             # Optimize for size
  configure-flags      --disable-debug
  remove-after-install builddir        # Remove build directory after install
end global
</screen>
</informalexample>
</sect2>

</sect1>

</chapter>

<chapter id="kde-cmake">
<title>&cmake;, the &kde; 4 build system</title>

<sect1 id="kde-cmake-intro">
<title>Introduction to &cmake;</title>

<para>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.</para>

<para>A introduction to &cmake; page is available on the <ulink
url="http://techbase.kde.org/Development/Tutorials/CMake">&kde; TechBase</ulink>.
Basically, instead of running <userinput><command>make</command> <option>-f</option>
<filename>Makefile.cvs</filename></userinput>, then <command>configure</command>,
then &make;, we simply run &cmake; and then &make;.
</para>

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

</sect1>
</chapter>

<chapter id="credits-and-license">
<title>Credits And License</title>

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
&underFDL;

</chapter>

<appendix id="appendix-modules">
<title>&kde; modules and source code organization</title>
<sect1 id="module-concept">
<title>The <quote>Module</quote></title>

<para>&kde; groups its software into <quote>modules</quote> of various size.
This was initially a loose grouping of a few large modules, but with the
introduction of the <ulink url="http://git-scm.com/">Git</ulink>-based <ulink
url="https://projects.kde.org/">source code repositories</ulink>, these large
modules were further split into many smaller modules.
</para>

<para>&kdesrc-build; uses this module concept as well. In essence, a
<quote>module</quote> is a grouping of code that can be downloaded, built,
tested, and installed.
</para>

<sect2 id="single-modules">
<title>Individual modules</title>

<para>It is easy to set &kdesrc-build; to build a single module. The following
listing is an example of what a declaration for a Subversion-based module would
look like in <link linkend="kdesrc-buildrc">the configuration
file</link>.</para>

<programlisting>
module <replaceable>kdefoo</replaceable>
    <option><replaceable>cmake-options -DCMAKE_BUILD_TYPE=Debug</replaceable></option>
end module
</programlisting>

<tip><para>This is a Subversion-based module since it doesn't use a <link
linkend="conf-repository">repository</link> option. Also, the
<option>cmake-options</option> option is listed as an example only, it is not
required.</para></tip>

</sect2>
<sect2 id="module-groups">
<title>Groups of related modules</title>

<para>Now most &kde; source modules are Git-based &kde;, and are normally
combined into groups of modules.</para>

<para>&kdesrc-build; therefore supports groups of modules as well, using
<link linkend="module-sets">module sets</link>. An example:</para>

<programlisting>
module-set <replaceable>base-modules</replaceable>
    <option>repository</option> kde-projects
    <option>use-modules</option> <replaceable>kde-runtime kde-workspace kde-baseapps</replaceable>
end module-set
</programlisting>

<tip><para>You can leave the module set name (<replaceable>base-modules</replaceable>
in this case) empty if you like. This <option>repository</option> setting tells
&kdesrc-build; where to download the source from, but you can also use a
<symbol>git://</symbol> URL.</para></tip>

<para>One special feature of the <quote><option>repository</option>
<literal>kde-projects</literal></quote> is that &kdesrc-build; will
automatically include any Git modules that are grouped under the modules you
list (in the KDE Project database).</para>
</sect2>

<sect2 id="module-branch-groups">
<title>Module <quote>branch groups</quote></title>

<para>Taking the concept of a <link linkend="module-groups">group of
modules</link> further, the &kde; developers eventually found that
synchronizing the names of the Git branches across a large number of
repositories was getting difficult, especially during the development push for
the new &kde; Frameworks for &Qt; 5.
</para>

<para>So the concept of <quote>branch groups</quote> was developed, to allow
users and developers to select one of only a few groups, and allow the script
to automatically select the appropriate Git branch.
</para>

<para>&kdesrc-build; supports this feature as of version 1.16-pre2, via the
<link linkend="conf-branch-group">branch-group</link> option.
</para>

<example id="ex-branch-group">
<title>Example of using branch-group</title>

<para>branch-group can be used in the configuration file as follows:
</para>

<programlisting>
global
    # Select KDE Frameworks 5 and other Qt5-based apps
    <option>branch-group</option> <replaceable>kf5-qt5</replaceable>

    # Other global options here ...
end global

module-set
    # branch-group only works for kde-projects
    <option>repository</option> kde-projects

    # branch-group is inherited from the one set globally, but could
    # specified here.

    <option>use-modules</option> <replaceable>kdelibs kde-workspace</replaceable>
end module-set

# kdelibs's branch will be "frameworks"
# kde-workspace's branch will be "master" (as of August 2013)
</programlisting>

<para>In this case the same <literal>branch-group</literal> gives different
branch names for each Git module.
</para>
</example>

<para>This feature requires some data maintained by the &kde; developers in a Git
repository named <literal>kde-build-metadata</literal>, however this module
will be included automatically by &kdesrc-build; (though you may see it appear
in the script output).
</para>

<tip><para>&kde; modules that do not have a set branch name for the branch
group you choose will default to an appropriate branch name, as if you had not
specified <literal>branch-group</literal> at all.
</para></tip>

</sect2>

</sect1>
</appendix>

<appendix id="appendix-profile">
<title>Superseded profile setup procedures</title>

<sect1 id="old-profile-setup">
<title>Setting up a &kde; login profile</title>

<para>These instructions cover how to setup the profile required to ensure your
computer can login to your newly-built &kde; &plasma; desktop. &kdesrc-build;
will normally try to do this automatically (see <xref
linkend="session-driver"/>). This appendix section can be useful for those who
cannot use &kdesrc-build;'s support for login profile setup. However the
instructions may not always be up-to-date, it can also be useful to consult the
<filename>kde-env-master.sh</filename> file included with the &kdesrc-build;
source.</para>

<sect2 id="changing-profile">
<title>Changing your startup profile settings</title>

<important><para>The <filename>.bash_profile</filename> is the login settings
file for the popular <application>bash</application> 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.</para></important>

<para>
Open or create the <filename>.bash_profile</filename> 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:

<programlisting>
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
</programlisting>

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

<programlisting>
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
</programlisting>
</para>

<para>
If you are not using a dedicated user, set a different $<envar>KDEHOME</envar>
for your new environment in your <filename>.bash_profile</filename>:

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

# Create it if needed
[ ! -e ~/.kde-svn ] &amp;&amp; mkdir ~/.kde-svn
</programlisting>
</para>

<note>
<para>
If later your K Menu is empty or too crowded with applications from your
distribution, you may have to set the <acronym>XDG</acronym> environment
variables in your <filename>.bash_profile</filename>:

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

</para>
</note>

</sect2>
<sect2 id="starting-kde">
<title>Starting &kde;</title>

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

<para>
Open the <filename>.xinitrc</filename> text file from the home directory, or
create it if necessary. Add the line:

<programlisting>
<command>exec</command> <option>${KDEDIR}/bin/startkde</option>
</programlisting>
</para>

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

<para>
Now start your fresh &kde;: in &BSD; and &Linux; systems with virtual terminal support,
<keycombo action="simul">&Ctrl;&Alt;<keycap>F1</keycap></keycombo> ... <keycombo action="simul">&Ctrl;&Alt;<keycap>F12</keycap></keycombo> 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.
</para>

<para>
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 <quote>Custom Session</quote> when you login. With this option, your session settings are
loaded from the <filename>.xsession</filename> 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.
</para>

<para>If it does not, there is something else you can try that should normally
work: Press <keycombo action="simul">&Ctrl;&Alt;<keycap>F2</keycap></keycombo>,
and you will be presented to a text terminal. Log in using the dedicated user
and type:
</para>

<screen>
<command>startx</command> <option>--</option> <option>:1</option>
</screen>

<tip>
<para>
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 <keycombo
action="simul">&Ctrl;&Alt;<keycap>F2</keycap></keycombo> (or
<keycap>F1</keycap>, <keycap>F3</keycap>, etc..), and you will be presented
with a text terminal. Log in using the dedicated &kde; &subversion; user and
type:</para>

<screen>
<command>startx</command> <option>--</option> <option>:1</option>
</screen>

<para>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
<keycombo action="simul">&Ctrl;&Alt;<keycap>F7</keycap></keycombo>, you may need
to use <keycap>F6</keycap> or <keycap>F8</keycap> 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 <keycombo action="simul">&Ctrl;&Alt;<keycap>F7</keycap></keycombo>
to switch to your regular &kde;, you would need to enter
<keycombo action="simul">&Ctrl;&Alt;<keycap>F8</keycap></keycombo> to go back
to your &kdesrc-build; &kde;.</para>
</tip>

</sect2>
</sect1>

</appendix>
</book>