[sdk/kdesrc-build/docbook_historied_per_file] doc: Add kdesvn-build docs. I tried it as a man page first but it didn't work, so

Michael Pyne null at kde.org
Fri May 10 10:14:25 BST 2024


Git commit 8ca11e65d8c4854cd191bbfc98baf14e079475a4 by Michael Pyne.
Committed on 16/05/2005 at 20:37.
Pushed by ashark into branch 'docbook_historied_per_file'.

Add kdesvn-build docs.  I tried it as a man page first but it didn't work, so
we'll leave it as being converted to HTML for now.

svn path=/trunk/KDE/kdesdk/doc/scripts/kdesvn-build/; revision=414740

Original commit: 05029019
https://invent.kde.org/sdk/kdesrc-build/-/commit/050290192909b67904a5cb82f0845fe4f94ecac7

A  +97   -0    doc/cmdline/index.docbook
A  +6    -0    doc/credits-and-licenses/index.docbook
A  +93   -0    doc/features/index.docbook
A  +10   -0    doc/getting-started/index.docbook
A  +79   -0    doc/index.docbook
A  +8    -0    doc/introduction/index.docbook
A  +528  -0    doc/kdesvn-buildrc/index.docbook

https://invent.kde.org/sdk/kdesrc-build/-/commit/8ca11e65d8c4854cd191bbfc98baf14e079475a4

diff --git a/doc/cmdline/index.docbook b/doc/cmdline/index.docbook
new file mode 100644
index 00000000..19b9e2fd
--- /dev/null
+++ b/doc/cmdline/index.docbook
@@ -0,0 +1,97 @@
+<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=</path/to/kde></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>
diff --git a/doc/credits-and-licenses/index.docbook b/doc/credits-and-licenses/index.docbook
new file mode 100644
index 00000000..b4135a8a
--- /dev/null
+++ b/doc/credits-and-licenses/index.docbook
@@ -0,0 +1,6 @@
+<chapter id="credits-and-licenses">
+<title>Credits And Licenses</title>
+
+&underFDL;
+
+</chapter>
diff --git a/doc/features/index.docbook b/doc/features/index.docbook
new file mode 100644
index 00000000..3c8d3810
--- /dev/null
+++ b/doc/features/index.docbook
@@ -0,0 +1,93 @@
+<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't designed to be built like
+that (unless you'd 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're 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't 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't 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't bug-free. Sorry.</para></listitem>
+</itemizedlist>
+
+</chapter>
diff --git a/doc/getting-started/index.docbook b/doc/getting-started/index.docbook
new file mode 100644
index 00000000..9ee4a92a
--- /dev/null
+++ b/doc/getting-started/index.docbook
@@ -0,0 +1,10 @@
+<chapter id="getting-started">
+<title>Getting Started</title>
+
+<para>
+The first thing to do is to copy the ... bla bla bla.
+</para>
+
+<para>Then you bla, bla, bla.</para>
+
+</chapter>
diff --git a/doc/index.docbook b/doc/index.docbook
new file mode 100644
index 00000000..ac776c4b
--- /dev/null
+++ b/doc/index.docbook
@@ -0,0 +1,79 @@
+<?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>">
+  <!ENTITY introduction SYSTEM "introduction/index.docbook">
+  <!ENTITY getting-started SYSTEM "getting-started/index.docbook">
+  <!ENTITY features SYSTEM "features/index.docbook">
+  <!ENTITY kdesvn-buildrc SYSTEM "kdesvn-buildrc/index.docbook">
+  <!ENTITY cmdline SYSTEM "cmdline/index.docbook">
+  <!ENTITY credits-and-licenses SYSTEM "credits-and-licenses/index.docbook">
+]>
+
+<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 at kdemail.net</email></address></affiliation>
+</author> 
+<author>
+<firstname>Carlos</firstname><surname>Woelz</surname>
+<affiliation><address><email>carloswoelz at 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>
+
+
+&introduction;
+
+&getting-started;
+
+&features;
+
+&kdesvn-buildrc;
+
+&cmdline;
+
+&credits-and-licenses;
+
+</book>
diff --git a/doc/introduction/index.docbook b/doc/introduction/index.docbook
new file mode 100644
index 00000000..2fab33c3
--- /dev/null
+++ b/doc/introduction/index.docbook
@@ -0,0 +1,8 @@
+<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>
diff --git a/doc/kdesvn-buildrc/index.docbook b/doc/kdesvn-buildrc/index.docbook
new file mode 100644
index 00000000..74bdaf95
--- /dev/null
+++ b/doc/kdesvn-buildrc/index.docbook
@@ -0,0 +1,528 @@
+<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'd 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></para></listitem>
+<listitem><para><link linkend="conf-apply-qt-patches">apply-qt-patches</link></para></listitem>
+<listitem><para><link linkend="conf-binpath">binpath</link></para></listitem>
+<listitem><para><link linkend="conf-build-dir">build-dir</link></para></listitem>
+<listitem><para><link linkend="conf-build-system-only">build-system-only</link></para></listitem>
+<listitem><para><link linkend="conf-checkout-only">checkout-only</link></para></listitem>
+<listitem><para><link linkend="conf-colorful-output">colorful-output</link></para></listitem>
+<listitem><para><link linkend="conf-configure-flags">configure-flags</link></para></listitem>
+<listitem><para><link linkend="conf-cxxflags">cxxflags</link></para></listitem>
+<listitem><para><link linkend="conf-debug">debug</link></para></listitem>
+<listitem><para><link linkend="conf-disable-build-list">disable-build-list</link></para></listitem>
+<listitem><para><link linkend="conf-do-not-compile">do-not-compile</link></para></listitem>
+<listitem><para><link linkend="conf-inst-apps">inst-apps</link></para></listitem>
+<listitem><para><link linkend="conf-install-after-build">install-after-build</link></para></listitem>
+<listitem><para><link linkend="conf-kdedir">kdedir</link></para></listitem>
+<listitem><para><link linkend="conf-libpath">libpath</link></para></listitem>
+<listitem><para><link linkend="conf-lockfile">lockfile</link></para></listitem>
+<listitem><para><link linkend="conf-make-install-prefix">make-install-prefix</link></para></listitem>
+<listitem><para><link linkend="conf-make-options">make-options</link></para></listitem>
+<listitem><para><link linkend="conf-manual-build">manual-build</link></para></listitem>
+<listitem><para><link linkend="conf-manual-update">manual-update</link></para></listitem>
+<listitem><para><link linkend="conf-module-base-path">module-base-path</link></para></listitem>
+<listitem><para><link linkend="conf-niceness">niceness</link></para></listitem>
+<listitem><para><link linkend="conf-no-rebuild-on-fail">no-rebuild-on-fail</link></para></listitem>
+<listitem><para><link linkend="conf-no-svn">no-svn</link></para></listitem>
+<listitem><para><link linkend="conf-pretend">pretend</link></para></listitem>
+<listitem><para><link linkend="conf-qtdir">qtdir</link></para></listitem>
+<listitem><para><link linkend="conf-reconfigure">reconfigure</link></para></listitem>
+<listitem><para><link linkend="conf-recreate-configure">recreate-configure</link></para></listitem>
+<listitem><para><link linkend="conf-refresh-build">refresh-build</link></para></listitem>
+<listitem><para><link linkend="conf-set-env">set-env</link></para></listitem>
+<listitem><para><link linkend="conf-source-dir">source-dir</link></para></listitem>
+<listitem><para><link linkend="conf-stop-on-failure">stop-on-failure</link></para></listitem>
+<listitem><para><link linkend="conf-svn-server">svn-server</link></para></listitem>
+<listitem><para><link linkend="conf-use-qt-builddir-hack">use-qt-builddir-hack</link></para></listitem>
+<listitem><para><link linkend="conf-use-unsermake">use-unsermake</link></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 -> 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-build-system-only">
+<entry>build-system-only</entry>
+<entry>Overrides global</entry>
+<entry>Set this option to only create the build system for this module.  What that
+means is that the <command>make <option>-f</option> Makefile.cvs</command> command will be run, and
+the configure script will be created and run, and make will not be run.
+This option is exactly equivalent to the <link
+linkend="cmdline-build-system-only"><option>--build-system-only</option></link> command line option.
+This command is useful for checking what configure-flags each module supports
+so you can change your ~/.kdesvn-buildrc.
+</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-debug">
+<entry>debug</entry>
+<entry>Can't be overridden</entry>
+<entry>This option enables the script's debug mode.  At this point, all this
+switch does is disable logging to files, instead dumping all output to
+stdout.  You should use the <link linkend="cmdline-debug"><option>--debug</option></link> command line
+option instead, this option only exists to implement it internally.
+</entry>
+</row>
+
+<row id="conf-disable-build-list">
+<entry>disable-build-list</entry>
+<entry>Can't be overridden</entry>
+<entry>Normally &kdesvn-build; will write out the list of modules that were
+successfully built to a file under the source directory called
+<filename class="directory">successfully-built</filename>.  If you set this option to 0,
+&kdesvn-build; will skip writing out the file.
+</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-lockfile">
+<entry>lockfile</entry>
+<entry>Can't be overridden</entry>
+<entry>
+<para>The path of a file to use for script locking, to prevent parallel execution.
+If you don't specify this value, the default is <filename class="directory">~/.kdesvn-lock</filename></para>
+
+<para>If the script is unable to create this file, it will abort.</para>
+</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-no-svn">
+<entry>no-svn</entry>
+<entry>Overrides global</entry>
+<entry>Set this option value to <quote>true</quote> to prevent &svn; updates for the module.
+This option is exactly equivalent to the <link linkend="cmdline-no-svn"><option>--no-svn</option></link>
+command line option.
+</entry>
+</row>
+
+<row id="conf-pretend">
+<entry>pretend</entry>
+<entry>Can't be overridden</entry>
+<entry>Set the option value to <quote>true</quote> in order to <quote>fake</quote> the update/build or
+install process.  This setting results in verbose output, and is exactly
+equivalent to the <link linkend="cmdline-pretend"><option>--pretend</option></link> command line option.
+</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-recreate-configure">
+<entry>recreate-configure</entry>
+<entry>Overrides global</entry>
+<entry>Use this option to re-run <command>make <option>-f</option> Makefile.cvs</command> and then reconfigure the
+module before building.  Note that setting this option in the configuration
+file isn't a great idea, use <link
+linkend="cmdline-recreate-configure"><option>--recreate-configure</option></link> on the command line
+instead.
+</entry>
+</row>
+
+<row id="conf-reconfigure">
+<entry>reconfigure</entry>
+<entry>Overrides global</entry>
+<entry>Use this option to reconfigure the module before building.  Note that
+setting this option in the configuration file isn't a great idea, use
+<link linkend="cmdline-reconfigure"><option>--reconfigure</option></link> on the command line instead.
+</entry>
+</row>
+
+<row id="conf-refresh-build">
+<entry>refresh-build</entry>
+<entry>Overrides global</entry>
+<entry>Set this option value to <quote>true</quote> to cause the build system for this module
+to start from scratch every time the script is run.  This option is exactly
+equivalent to the <link linkend="cmdline-refresh-build"><option>--refresh-build</option></link> command
+line option.
+</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>



More information about the kde-doc-english mailing list