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" [
  <!ENTITY kappname "kdesvn-build">
  <!ENTITY package "kdesdk">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE"> <!-- Change language only here -->
  <!ENTITY svn "<application>Subversion</application>">
  <!ENTITY kdesvn-build "<application>kdesvn-build</application>">
]>

<book lang="&language;">

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

<authorgroup id="authors">
<author>
<firstname>Michael</firstname><surname>Pyne</surname>
<affiliation><address><email>michael.pyne@kdemail.net</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>2005</year>
<holder>Michael Pyne</holder>
</copyright>

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


<legalnotice>&FDLNotice;</legalnotice>

<date>2005-05-15</date>
<releaseinfo>0.94</releaseinfo>

<abstract>
<para>The &kdesvn-build; is a Perl script that provides automated &kde; building and installing, directly from the sources found in the &kde; &svn; repository.</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>kdesdk</keyword>
<keyword>SVN</keyword>
<keyword>KDE development</keyword>
</keywordset>

</bookinfo>


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

<para>
&kdesvn-build; is a Perl script to help users install  <ulink
url="http://www.kde.org/">&kde;</ulink> from <ulink
url="http://subversion.tigris.org/">&svn;</ulink>.  You may also want to
consider the kde-build script include with &kde;'s kdesdk module.
</para>

</chapter>

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

<para>
In this chapter, we show how to use the &kdesvn-build; to checkout modules from the
&kde; repository and build them. We also provide a basic explanation of the &kde;
&svn; 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://quality.kde.org/develop/cvsguide/buildstep.php">
Building &kde; from Source Step by Step Guide</ulink>, at the
<ulink url="http://quality.kde.org">&kde; Quality Team Website</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>

<para>It is recommended that you download and build &kde; using a user
account. If you already have &kde; packages installed, the best choice
would be to create a different user to build and run the new &kde;. The
advantage of building &kde; as a user is you can not break the base
system, and you will always have a way to comfortably work when
things go wrong.</para>

<para>Later, you can install it system wide as root. This document
does not cover a root installation, because if you are performing a system
wide install, you probably already know what you are doing.
</para>

<para>Before using the &kdesvn-build; script (or any other building
strategy) you must install the development tools and libraries needed for &kde;.
You need the Qt library, version 3.3.0 or greater, Automake 1.8,
Autoconf 2.5X (better if >=2.57 as a bug was reported with lower versions),
the subversion (svn) client, the gcc compiler with C++ support, libxml2,
openssl, libbz2, and many more (for a complete list, visit the
<ulink url="http://www.kde.org/info/requirements/3.4.php">KDE 3.4 Compilation
Requirements</ulink>). You can usually get those tools packaged for your system
from your distribution or vendor.
</para>

<para>
Some of these packages are divided into libs, programs or utilities and
development packages. You will need at least the program or library and
its development package. If in doubt, install all. The libraries you need
will change depending on the modules you intend to build, as each module
has its own requirements. The
<ulink url="http://quality.kde.org/develop/cvsguide/buildstep.php#step1">
Building &kde; from Source Step by Step Guide</ulink> has more details
about the specific tools and techniques used to install and find the
required software.
</para>

<para>
You probably already have a version of the &kdesvn-build; script installed
in your system. &kdesvn-build;requires you to create a configuration file, named
<filename>.kdesvn-build</filename>. This file should be installed on
the home folder (~/), and contain all configuration data
required for the script to run, like configuration options,
compiling options, location of the sources, the destination of the installation
(prefix), the modules that should be built, &etc;. The default configuration
data is provided by the <filename>kdesvn-buildrc-sample</filename> file.
You can find more information about the sintax of the configuration file
in <xref linkend="configure-data" /> and in <xref linkend="kdesvn-buildrc" />.
</para>

<para>
A good way to get the latest version is to browse the kdesdk/scripts page
at the <ulink url="http://websvn.kde.org/trunk/KDE">websvn.kde.org</ulink> website.
You will see a list of the files available in the kdesdk/scripts directory in
the &kde; &svn; repository. Click the &kdesvn-build; link and download
the latest version of the script. Do the same for the
<filename>kdesvn-buildrc-sample</filename> file.

</para>


</sect1>

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

<para>Bla Bla.</para>


</sect1>

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

<para>Bla Bla.</para>

</sect1>

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

<para>Bla Bla.</para>

</sect1>

</chapter>

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

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


<itemizedlist>

<listitem><para>Automatically checks out or updates modules from &svn;, as
appropriate.</para></listitem>

<listitem><para>Times the build process for modules.</para></listitem>

<listitem><para>Automatically tries to rebuild modules that were using incremental
make, which is prone to failure after certain kinds of commits.</para></listitem>

<listitem><para>Can resume a previous script, or start the build process from a particular
module.</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 &svn; repository.
</para></listitem>

<listitem><para>Comes with <ulink url="http://www.kde.me.uk/index.php?page=unsermake">Unsermake</ulink>
support.</para></listitem>

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

<listitem><para>Configurable build, source, and logging directories</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. The exception is <application>qt-copy</application>, which isn not designed to be built like
that (unless you would like to test the
<link linkend="conf-use-qt-builddir-hack"><quote>qt with a separate build directory hack</quote></link>).</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>Since the autotools sometimes get out of sync with changes to the
source tree, you can force a rebuild of a module by creating a file called
.refresh-me in the build directory of the module in question, or by running
&kdesvn-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>If you are using a user build of &kde; instead of a system build (for which
you must be root to install), you can use the script to install for you.  I
haven not audited this code, and it makes ample use of the <function>system()</function>
call, so I would not recommend running it as root at this point.</para></listitem>

<listitem><para>You can use <link linkend="conf-make-install-prefix">make-install-prefix</link> to
prefix the make install command line with a separate command, which is useful
for sudo.</para></listitem>

<listitem><para>You can use the <link linkend="conf-apidox">apidox</link> option to automatically
build and install the API documentation for some modules.</para></listitem>

<listitem><para>You can check out only a portion of a &kde; &svn; module.  For example,
you could check out only the <application>taglib</application> from
<application>kdesupport</application>, or only <application>K3B</application> from
<application>extragear/multimedia</application>.  The script will automatically pull in
<application>kde-common</application> if necessary to make the build work.</para></listitem>

<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 very verbose description of the commands
it is about to execute, without actually executing it.</para></listitem>

<listitem><para>Support for checking out specific branches of &svn;
modules. This work still needs to be completed.</para></listitem>

</itemizedlist>

<para>Things that &kdesvn-build; does NOT do:</para>

<itemizedlist>
<listitem><para>Find the fastest &kde; &svn; mirror.  There isn not even a list shipped
with the script at this point, although the default server should work
fine.</para></listitem>
<listitem><para>Brush your teeth. You should remember to do that yourself.</para></listitem>
<listitem><para>The script probably isn not bug-free. Sorry.</para></listitem>
</itemizedlist>

</chapter>

<chapter id="kdesvn-buildrc">
<title>The Format of .kdesvn-buildrc</title>

<para>To use the script, you must have a file in your home directory called
.kdesvn-buildrc, which describes the modules you would like to download and
build.</para>



<para>It starts with the global options, specified like the following:</para>
<programlisting>
global
<replaceable>option-name option-value</replaceable>
<replaceable>[...]</replaceable>
end global
</programlisting>
<para>It is then followed by one or more module sections, specified like the
following:</para>
<programlisting>module <replaceable>module-name</replaceable>
<replaceable>option-name option-value</replaceable>
<replaceable>[...]</replaceable>
end module
</programlisting>

<para><replaceable>module-name</replaceable> must be a module from the &kde; &svn; repository (for
example, kdelibs or kdebase).  Some options override global options, some
add to global options, and some global options simply can't be overridden.
</para>

<para>The following is an alphabetized list of options you can use.  Click on the
option to find out more about it.  If one is not documented, please e-mail the
authors using the address you can find <link linkend="authors">above</link>.

<itemizedlist>
<listitem><para><link linkend="conf-apidox">apidox</link>, to build API Documentation</para></listitem>
<listitem><para><link linkend="conf-apply-qt-patches">apply-qt-patches</link>, to enhance qt-copy</para></listitem>
<listitem><para><link linkend="conf-binpath">binpath</link>, to set the <envar>PATH</envar> variable.</para></listitem>
<listitem><para><link linkend="conf-build-dir">build-dir</link>, to set the directory to build in.</para></listitem>
<listitem><para><link linkend="conf-checkout-only">checkout-only</link>, to checkout only parts of a module.</para></listitem>
<listitem><para><link linkend="conf-colorful-output">colorful-output</link> to add color to the script output.</para></listitem>
<listitem><para><link linkend="conf-configure-flags">configure-flags</link> to define what flags to configure a module with.</para></listitem>
<listitem><para><link linkend="conf-cxxflags">cxxflags</link> to define the <envar>CXXFLAGS</envar> variable.</para></listitem>
<listitem><para><link linkend="conf-dest-dir">dest-dir</link> to change the directory name for a module.</para></listitem>
<listitem><para><link linkend="conf-do-not-compile">do-not-compile</link>, to mark directories to skip building.</para></listitem>
<listitem><para><link linkend="conf-inst-apps">inst-apps</link>, to only build and install some directories.</para></listitem>
<listitem><para><link linkend="conf-install-after-build">install-after-build</link>, to avoid installing after the build process.</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-libpath">libpath</link>, to set the <envar>LD_LIBRARY_PATH</envar> variable.</para></listitem>
<listitem><para><link linkend="conf-make-install-prefix">make-install-prefix</link>, to run a helper program (like sudo) during make install.</para></listitem>
<listitem><para><link linkend="conf-make-options">make-options</link>, to pass options to the make program.</para></listitem>
<listitem><para><link linkend="conf-manual-build">manual-build</link>, to avoid building the module automatically.</para></listitem>
<listitem><para><link linkend="conf-manual-update">manual-update</link>, to avoid doing anything to the module automatically.</para></listitem>
<listitem><para><link linkend="conf-module-base-path">module-base-path</link>, to change where to download the module from (useful for branches and tags).</para></listitem>
<listitem><para><link linkend="conf-niceness">niceness</link>, to change the CPU priority.</para></listitem>
<listitem><para><link linkend="conf-no-rebuild-on-fail">no-rebuild-on-fail</link>, to avoid running make again if it fails.</para></listitem>
<listitem><para><link linkend="conf-qtdir">qtdir</link>, to set the path to Qt.</para></listitem>
<listitem><para><link linkend="conf-set-env">set-env</link>, to set an environment variable.</para></listitem>
<listitem><para><link linkend="conf-source-dir">source-dir</link>, to change where to download the source code to.</para></listitem>
<listitem><para><link linkend="conf-stop-on-failure">stop-on-failure</link>, to make kdesvn-build stop as soon as a failure is encountered.</para></listitem>
<listitem><para><link linkend="conf-svn-server">svn-server</link>, to change the server the sources are downloaded from.</para></listitem>
<listitem><para><link linkend="conf-use-qt-builddir-hack">use-qt-builddir-hack</link>, to give Qt a separate build directory from its source like KDE.</para></listitem>
<listitem><para><link linkend="conf-use-unsermake">use-unsermake</link>, to use the advanced unsermake build system.</para></listitem>
</itemizedlist>

</para>

<para>Here is a table of the various options, and some comments on them.  Any
option which overrides the global option will override a command line setting
as well.</para>

<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 id="conf-apidox">
<entry>apidox</entry>
<entry>Overrides global</entry>
<entry>Set this option to <quote>true</quote> in order to have &kdesvn-build; automatically
build and install the API documentation for the module after the normal build/install
process.  This only works for modules where <command>make apidox</command> does something,
including kdelibs, kdebase, and koffice, among others.
</entry>
</row>

<row id="conf-apply-qt-patches">
<entry>apply-qt-patches</entry>
<entry>Overrides global</entry>
<entry>This option is only useful for qt-copy.  If it is set to a non-zero value,
then the apply-patches script in qt-copy will be run prior to building, in
order to apply the non-official patches to the qt-copy.  Since these patches
are normally the reason for using qt-copy instead of a stock Qt, it shouldn't
do any harm to enable it.  The default is to enable the patches.</entry>
</row>

<row id="conf-binpath">
<entry>binpath</entry>
<entry>Can't be overridden</entry>
<entry><para>Set this option to set the environment variable PATH while building.
You can't override this setting in a module option.  The default value is
<filename class="directory">/bin:/usr/bin:/usr/local/bin:/usr/X11R6/bin</filename>.  This environment
variable should include the colon-separated paths of your development
toolchain.  The paths <filename class="directory">$KDEDIR/bin</filename> and
<filename class="directory">$QTDIR/bin</filename> are automatically added.  You
may use the tilde (~) for any paths you add using this option.</para>
</entry>
</row>

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

<listitem><para>Relative to the &kde; &svn; source directory (see <link
linkend="conf-source-dir">the source-dir option</link>).  This is the default, and
the way the script worked up to version v0.61.  This mode is selected if you
type a directory name that doesn't 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>

</itemizedlist>

Perhaps surprisingly, this option can be changed per module.

</entry>
</row>

<row id="conf-checkout-only">
<entry>checkout-only</entry>
<entry>Overrides global</entry>
<entry>Set this option to checkout &svn; sources piece by piece.  The value
for this option should be a space separated list of directories to checkout.
If you don't include the admin directory, it will automatically be included (if
necessary).  When checking out piece by piece, the admin directory will be
pulled in from kde-common, which is where it exists on the &svn; server.
Although this option overrides the global option, be aware that setting this as
a global option makes no sense.
</entry>
</row>

<row id="conf-configure-flags">
<entry>configure-flags</entry>
<entry>Appends to global option(except for qt-copy)</entry>
<entry>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.  qt-copy uses a much different
set of configure options than the rest of &kde;, so this option
<emphasis>overrides</emphasis> the global settings when applied to qt-copy.</entry>
</row>

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

<row id="conf-cxxflags">
<entry>cxxflags</entry>
<entry>Appends to global option</entry>
<entry>Use this option to specify what flags to pass to <command>./configure</command> as the
<envar>CXXFLAGS</envar> when creating the build system for the module.  This option is
specified here instead of with <link
linkend="conf-configure-flags">configure-flags</link> because this option will also
set the environment variable <envar>CXXFLAGS</envar> during the build process.
</entry>
</row>

<row id="conf-dest-dir">
<entry>dest-dir</entry>
<entry>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.
</entry>
</row>

<row id="conf-do-not-compile">
<entry>do-not-compile</entry>
<entry>Overrides global</entry>
<entry><para>Use this option to set the <envar>DO_NOT_COMPILE</envar> environment variable prior to
running the configure script.  According to the <ulink
url="http://developer.kde.org/documentation/other/developer-faq.html">&kde;
Developer FAQ</ulink>, this should cause any toplevel directory you pass to not be
built.  The directories 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>
</entry>
</row>

<row id="conf-inst-apps">
<entry>inst-apps</entry>
<entry>Overrides global</entry>
<entry><para>This is the opposite of the <link
linkend="conf-do-not-compile">do-not-compile</link> option.  This option makes it
so that only the given toplevel directories are built.  The directories should
be space-separated.</para>

<para>Any changes don't take effect until the next time
<command>make <option>-f</option> Makefile.cvs</command> is
run, either automatically by the script, or manually by the <link
linkend="cmdline-refresh-build"><option>--refresh-build</option></link> or <link
linkend="cmdline-recreate-configure"><option>--recreate-configure</option></link> options.
</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>
</entry>
</row>

<row id="conf-install-after-build">
<entry>install-after-build</entry>
<entry>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 0 in the configuration file.  You can also use the
<link linkend="cmdline-no-install"><option>--no-install</option></link> command line flag.
</entry>
</row>

<row id="conf-kdedir">
<entry>kdedir</entry>
<entry>Can't be overridden</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-libpath">
<entry>libpath</entry>
<entry>Can't be overridden</entry>
<entry>Set this option to set the environment variable LD_LIBRARY_PATH while
building.  You can't override this setting in a module option.  The default
value is blank, but the paths <filename class="directory">$KDEDIR/lib</filename> and
<filename class="directory">$QTDIR/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>Overrides global</entry>
<entry>Use this option to change the directory used to hold the log files
generated by the script.  This setting can be set on a per-module basis as of
version 0.64 or later.
</entry>
</row>

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

<row id="conf-make-options">
<entry>make-options</entry>
<entry>Overrides global</entry>
<entry>Set this variable in order to pass command line options to the make
command.  This is useful for programs such as <ulink
url="http://distcc.samba.org/"><application>distcc</application></ulink>.
<application>distcc</application> allows you to share your
compilation work among more than one computer.  To use it, you must use the
<option>-j</option> option to make.  Now you can.  According to the docs, 2 *
number_of_network_cpus is recommended.  I have 1 CPU total, so it would be
<option>-j2</option> in my case.</entry>
</row>

<row id="conf-manual-build">
<entry>manual-build</entry>
<entry>Overrides global</entry>
<entry>Set the option value to <quote>true</quote> to keep the build process from attempting to
build this module.  It will still be kept up-to-date when updating from &svn;.
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>Overrides global</entry>
<entry>Set the option value to <quote>true</quote> 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 pretty much commented it out.
</entry>
</row>

<row id="conf-module-base-path">
<entry>module-base-path</entry>
<entry>Overrides global</entry>
<entry><para>Set this option to override &kdesvn-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 &kdesvn-build; constructs the final path according to the
following template:
<varname>$svn-server</varname>/home/kde/<varname>$module-base-path</varname>/<varname>$module-name</varname>.
</para>
<para>The default value is either <quote>trunk</quote> or
<quote>trunk/KDE</quote>, depending on the modulename.</para>
</entry>
</row>

<row id="conf-niceness">
<entry>niceness</entry>
<entry>Can't be overridden</entry>
<entry>Set this option to a number between 20 and 0.  The higher the number, the
lower a priority &kdesvn-build; will set for itself.  The default is 10.
</entry>
</row>

<row id="conf-no-rebuild-on-fail">
<entry>no-rebuild-on-fail</entry>
<entry>Overrides global</entry>
<entry>Set this option value to <quote>true</quote> to always prevent &kdesvn-build; from trying
to rebuild this module if it should fail an incremental build.  Normally
&kdesvn-build; will try to rebuild the module from scratch to counteract the
effect of a stray &svn; update messing up the build system.</entry>
</row>

<row id="conf-qtdir">
<entry>qtdir</entry>
<entry>Can't be overridden</entry>
<entry>Set this option to set the environment variable QTDIR while building.
You can't override this setting in a module option.  If you don't specify
this option, it defaults to
<filename class="directory"><varname>$(source-dir)</varname>/build/qt-copy</filename>,
which uses the qt-copy module included in the &kde; source repository.
You may use a tilde (~) to represent your home directory.
</entry>
</row>

<row id="conf-set-env">
<entry>set-env</entry>
<entry>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 RONALD 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 configuration file.  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>Can't be overridden</entry>
<entry>This option is used to set the directory on your computer to store the &kde;
&svn; sources at.  If you don't specify this value, the default is
<filename class="directory">~/kdesvn</filename>.  If
you do specify this value, use an absolute path name.
</entry>
</row>

<row id="conf-svn-server">
<entry>svn-server</entry>
<entry>Can't be overridden</entry>
<entry>This option is used to set the server used to check out from &svn;.
The default is the anonymous &svn; repository, <ulink
url="svn://anonsvn.kde.org/">svn://anonsvn.kde.org/</ulink></entry>
</row>

<row id="conf-stop-on-failure">
<entry>stop-on-failure</entry>
<entry>Overrides global</entry>
<entry>Set this option value to <quote>true</quote> 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-use-qt-builddir-hack">
<entry>use-qt-builddir-hack</entry>
<entry>Overrides global</entry>
<entry>Although this option overrides the global option, it only makes sense for
qt-copy.  Set this option to <quote>true</quote> to enable the script's
<emphasis>experimental</emphasis> srcdir != builddir mode.  When enabled,
&kdesvn-build; will copy the qt-copy source module to the build directory,
and perform builds from there.  That means your QTDIR environment variable
should be set to
<filename class="directory">$(qt-copy-build-dir)/qt-copy/lib</filename>
instead.  You should also change your <link linkend="conf-qtdir">qtdir</link>
option accordingly. Incremental make should still work in this mode, as the
timestamps will be preserved after the copy.  If you use the
<link linkend="conf-apply-qt-patches">apply-qt-patches</link> option, the patches
will be applied in the build directory, not the source directory.
This option defaults to <quote>true</quote>.
</entry>
</row>

<row id="conf-use-unsermake">
<entry>use-unsermake</entry>
<entry>Overrides global</entry>
<entry>Set this option to a non-zero value in order to use the experimental
unsermake program instead of automake when running the configure script.  This
can lead to some serious decreases in build time, especially for
<ulink url="http://www.csh.rit.edu/slashdot/distcc.html">distributed building
systems</ulink>.  This option defaults to <quote>true</quote> (for most modules).
</entry>
</row>

</tbody>

</tgroup>
</table>

</chapter>

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

<para>This script doesn't 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>

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

<itemizedlist>

<listitem id="cmdline-help"><para><option>--help</option>,= only display simple help on this script.</para></listitem>

<listitem id="cmdline-version"><para><option>--version</option>, display the program version.</para></listitem>

<listitem id="cmdline-author"><para><option>--author</option>, display contact information for the
author.</para></listitem>

<listitem id="cmdline-color"><para><option>--color</option>, enable colorful output.</para></listitem>

<listitem id="cmdline-no-color"><para><option>--no-color</option>, disable colorful output.</para></listitem>

<listitem id="cmdline-pretend"><para><option>--pretend</option> (or <option>-p</option>), don't actually DO anything, but
act like you did.</para></listitem>

<listitem id="cmdline-svn-only"><para><option>--svn-only</option>, Only perform the source update.</para></listitem>

<listitem id="cmdline-build-only"><para><option>--build-only</option>, Only perform the build process.</para></listitem>

<listitem id="cmdline-ignore-modules"><para><option>--ignore-modules</option>, Don't including the modules
passed on the rest of the command line in the update/build process.</para></listitem>

<listitem id="cmdline-no-svn"><para><option>--no-svn</option>, Skip contacting the &svn; server.</para></listitem>

<listitem id="cmdline-no-build"><para><option>--no-build</option>, Skip the build process.</para></listitem>

<listitem id="cmdline-no-install"><para><option>--no-install</option>, Don't automatically install packages
after they're built.</para></listitem>

<listitem id="cmdline-debug"><para><option>--debug</option>, Enables debug mode for the script.  Currently
this means that all output will be dumped to STDOUT in addition to being
logged in the log directory like normal.  Also, many functions are much more
verbose about what they're doing in debugging mode.</para></listitem>

<listitem id="cmdline-no-rebuild-on-fail"><para><option>--no-rebuild-on-fail</option>, Don't try and
rebuild modules that have failed building from scratch.  &kdesvn-build; will
never try to do this to a module that already was tried to be built from
scratch.</para></listitem>

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

<listitem id="cmdline-reconfigure"><para><option>--reconfigure</option>, Run the configure script again
without cleaning the build directory.</para></listitem>

<listitem id="cmdline-recreate-configure"><para><option>--recreate-configure</option>, Run <command>make <option>-f</option>
Makefile.cvs</command> again to create the configure script, and continue
building as normal.  This option implies <option>--reconfigure</option>.</para></listitem>

<listitem id="cmdline-resume"><para><option>--resume</option>, which tries to continue building from where
the script stopped last time.  The script starts building the module after the
last module to be compiled last time the script was run, whether or not it
succeeded.  This option implies <link linkend="cmdline-no-svn"><option>--no-svn</option></link>.  You
should not specify other module names on the command line.</para></listitem>

<listitem id="cmdline-resume-from"><para><option>--resume-from</option>, which is like <link
linkend="cmdline-resume"><option>--resume</option></link>, except that you supply the module to
start building from as the next parameter on the command line.  This option
implies <link linkend="cmdline-no-svn"><option>--no-svn</option></link>.  You should not specify
other module names on the command line.</para></listitem>

<listitem id="cmdline-rc-file"><para><option>--rc-file</option>, which interprets the next command line
parameter as the file to read the configuration options from.  The default
value for this parameter is ~/.kdesvn-buildrc.</para></listitem>

<listitem id="cmdline-prefix"><para><option>--prefix=&lt;/path/to/kde&gt;</option>, which allows you to
change the directory that &kde; will be installed to from the command line.
This option implies <link linkend="cmdline-reconfigure"><option>--reconfigure</option></link>.</para></listitem>

<listitem id="cmdline-build-system-only"><para><option>--build-system-only</option>, Stop after runnning
<command>make <option>-f</option> Makefile.cvs</command>.  The configure script will still need to be run, which
&kdesvn-build; will do next time.  This lets you prepare all the configure
scripts at once so you can view the <command>./configure <option>--help</option></command> for each module, and
edit your configure-flags accordingly.</para></listitem>

<listitem id="cmdline-install"><para><option>--install</option>, If this is the only command-line option,
it tries to install all of the modules contained in successfully-built, except
for qt-copy, which doesn't need installation.  If command-line options are
specified after <option>--install</option>, they are all assumed to be modules to install.
</para></listitem>

</itemizedlist>

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

</chapter>

<chapter id="credits-and-licenses">
<title>Credits And Licenses</title>

&underFDL;

</chapter>

</book>