[sdk/kdesrc-build/docbook_historied_per_file] doc: Revise and modernize the documentation/help text for kdesvn-build a bit. Unless
Michael Pyne
null at kde.org
Fri May 10 10:14:26 BST 2024
Git commit 1b492e677631307a633f825399c80711da4191c2 by Michael Pyne.
Committed on 02/05/2007 at 02:55.
Pushed by ashark into branch 'docbook_historied_per_file'.
Revise and modernize the documentation/help text for kdesvn-build a bit. Unless
something breaks for someone overnight this will be kdesvn-build 1.4 tomorrow.
svn path=/trunk/KDE/kdesdk/doc/scripts/kdesvn-build/; revision=660238
Original commit: 2da73860
https://invent.kde.org/sdk/kdesrc-build/-/commit/2da73860ea586c164617dacdc319cb8bb658ac41
M +30 -44 doc/features/features-overview.docbook
M +18 -8 doc/getting-started/before-building.docbook
M +7 -3 doc/getting-started/building-and-troubleshooting.docbook
M +14 -1 doc/getting-started/configure-data.docbook
M +3 -2 doc/index.docbook
M +53 -36 doc/kdesvn-buildrc/index.docbook
https://invent.kde.org/sdk/kdesrc-build/-/commit/1b492e677631307a633f825399c80711da4191c2
diff --git a/doc/features/features-overview.docbook b/doc/features/features-overview.docbook
index 469ace2c..29cdf83a 100644
--- a/doc/features/features-overview.docbook
+++ b/doc/features/features-overview.docbook
@@ -9,7 +9,8 @@
<listitem><para>
For developers: Supports <link linkend="building-apidox">building the API
-documentation</link> for a module.
+documentation</link> for a module. Note that this only works for KDE 3
+modules when not using the unsermake script.
</para></listitem>
<listitem><para>
@@ -18,10 +19,12 @@ ranging from being very quiet to a full debug level.
</para></listitem>
<listitem><para>
-&kdesvn-build; can, with the assistance of the <ulink url="http://kdesvn-build.kde.org/">kdesvn-build website</ulink>,
-allow for speedy checkouts of some modules. If the module you are checking out
-has already been packaged at the website, then kdesvn-build will download the
-snapshot and prepare it for use on your computer.
+&kdesvn-build; can, with the assistance of the <ulink
+url="http://kdesvn-build.kde.org/">kdesvn-build website</ulink> and the
+KDE FTP server (FTP since &kdesvn-build; 1.4), allow for speedy checkouts of
+some modules. If the module you are checking out has already been packaged at
+the website, then kdesvn-build will download the snapshot and prepare it for
+use on your computer.
</para>
<para>This is faster for you, and helps to ease the load on the kde.org
@@ -53,6 +56,20 @@ standard flags</link> as appropriate to save you the trouble and possible
errors from typing them yourself.
</para></listitem>
+<listitem><para>
+&kdesvn-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>
+&kdesvn-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-svn-only">--svn-only</link> option to let
+&kdesvn-build; know that it is acceptable to perform the switch.
+</para></listitem>
+
<listitem><para>
&kdesvn-build; can <link linkend="partial-builds">checkout only portions of a
module</link>, for those situations where you only need one program from a
@@ -60,9 +77,9 @@ large module.
</para></listitem>
<listitem><para>
-For developers: 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
+For developers: &kdesvn-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
<application>ssh</application>.
</para></listitem>
@@ -109,16 +126,6 @@ given module. You can even <link linkend="ignoring-modules">ignore some
modules</link> temporarily for a given build.
</para></listitem>
-<listitem><para>
-&kdesvn-build; also supports using the ~/ sequence to stand for your home
-directory in the &rcfile;.
-</para></listitem>
-
-<listitem><para>
-Automatically checks out or updates modules from &svn;, as
-appropriate.
-</para></listitem>
-
<listitem><para>
&kdesvn-build; can quickly perform a <link linkend="partial-builds">partial
build</link> of a module directly from the command line, when you only need
@@ -128,13 +135,14 @@ to update part of a module.
<listitem><para>
&kdesvn-build; will automatically download and create the required <filename>/admin</filename>
directory for a module if it isn't downloaded from &svn; the first time for
-some reason.
+some reason. This only applies to KDE 3 modules, as /admin is not required
+for qt-copy or KDE 4 modules.
</para></listitem>
<listitem><para>
&kdesvn-build; will show the <link linkend="build-progress">progress of your
-build</link> when using &unsermake;, and will always time the build process so
-you know after the fact how long it took.
+build</link> when using &unsermake; and CMake, and will always time the build
+process so you know after the fact how long it took.
</para></listitem>
<listitem><para>
@@ -142,10 +150,6 @@ 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 build 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.
@@ -161,16 +165,10 @@ specify:
<programlisting>qtdir ~/kdesvn/build/qt-copy</programlisting>
</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 is 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>).
+pristine.
</para></listitem>
<listitem><para>
@@ -210,11 +208,6 @@ 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
@@ -230,13 +223,6 @@ 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, but you already select the branch you
-want to build using the <link linkend="conf-module-base-path">module-base-path
-configuration option</link>.
-</para></listitem>
-
</itemizedlist>
</sect1>
diff --git a/doc/getting-started/before-building.docbook b/doc/getting-started/before-building.docbook
index 8e189be7..81c6acb7 100644
--- a/doc/getting-started/before-building.docbook
+++ b/doc/getting-started/before-building.docbook
@@ -40,10 +40,8 @@ Requirements</ulink> page.
<listitem><para>Autoconf version 2.57, or higher. (KDE 3 only)</para></listitem>
<listitem><para><ulink
-url="http://www.cmake.org/"><application>CMake</application></ulink> 2.4.0, or
-higher. Some version 2.3 snapshots may compile KDE 4 as well, please see the
-<ulink url="http://wiki.kde.org/tiki-index.php?page=KDECMakeIntro">CMake Introduction Wiki</ulink> page. (KDE 4
-only)</para></listitem>
+url="http://www.cmake.org/"><application>CMake</application></ulink> 2.4.5, or
+higher.</para></listitem>
<listitem><para>The &svn; client program, including support for Secure
HTTP (https). To ensure needed support, you can run
@@ -51,8 +49,8 @@ HTTP (https). To ensure needed support, you can run
If the ra_dav module says that it handles the https scheme then you should be
set to go.</para></listitem>
-<listitem><para>The gcc compiler, with support for C++. Version 3.3 or 3.4 works
-the best at this point.</para></listitem>
+<listitem><para>The gcc compiler, with support for C++. Versions 3.3 or higher
+are the best supported.</para></listitem>
<listitem><para>Be sure to check the <ulink
url="http://www.kde.org/info/requirements/3.5.php">&kde; Compilation
@@ -81,7 +79,13 @@ to have it. If you don't want to use the &Qt; copy, you need to do these things
<listitem>
<para>If you don't already have &Qt; installed, install it, including any
relevant -dev or -devel packages. You'll need at least &Qt; 3.3 if you're
- building &kde; 3.5, or &Qt; 4.0 if you're building &kde; 4.</para>
+ building &kde; 3.5, or &Qt; 4.3 if you're building &kde; 4.</para>
+
+ <note><para>If you are building &kde; 4 it is highly recommended to use the
+ qt-copy version of &Qt;, making sure to apply recommended patches (this is
+ the default setting, controlled by the <link
+ linkend="conf-apply-qt-patches">apply-qt-patches
+ option</link>).</para></note>
</listitem>
</itemizedlist>
@@ -110,6 +114,12 @@ in your system. However, if you don't, you can download it from
&homepage;, or you can find it from its home in the &kde; source
repository.</para>
+<note><para>&kdesvn-build; is included with the kdesdk module, and the module
+is often installed by distributions already. If you have downloaded
+&kdesvn-build; ensure that you are using the version you downloaded. You can
+use the --version option to be sure you are running the version you think
+you are.</para></note>
+
<orderedlist>
<listitem><para>To download &kdesvn-build; from its &homepage;, simply go to the
&homepage; and download the latest appropriate release. The release is
@@ -131,7 +141,7 @@ if you need to.</para></listitem>
<filename>kdesvn-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.</para>
+was not found, or you may run a previously-installed version by mistake.</para>
</sect3>
<sect3 id="setup-rcfile">
diff --git a/doc/getting-started/building-and-troubleshooting.docbook b/doc/getting-started/building-and-troubleshooting.docbook
index 6472d0bc..a79b34d0 100644
--- a/doc/getting-started/building-and-troubleshooting.docbook
+++ b/doc/getting-started/building-and-troubleshooting.docbook
@@ -23,9 +23,13 @@ the caused an error for a module in the last &kdesvn-build; command, usually
it is sufficient to look at <filename>~/kdesvn/log/latest/<replaceable>module-name</replaceable>/error.log</filename>.</para>
<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're missing some packages,
-try installing the package (including any appropriate -dev packages) before
-trying to build that module. Or, if the error appears to be a build error
+that module. If the file says (at the bottom) that you're missing some
+packages, try installing the package (including any appropriate -dev packages)
+before trying to build that module, and pass the <link
+linkend="cmdline-reconfigure">--reconfigure</link> option after install the
+missing packages.</para>
+
+<para>Or, if the error appears to be a build error
then it is probably an error with the &kde; source, which will hopefully be
resolved within a few days. If it isn't resolved within that time, feel free
to mail the <email>kde-devel at kde.org</email> (subscription may be required first)
diff --git a/doc/getting-started/configure-data.docbook b/doc/getting-started/configure-data.docbook
index 3d3f92bc..5784f6e2 100644
--- a/doc/getting-started/configure-data.docbook
+++ b/doc/getting-started/configure-data.docbook
@@ -27,12 +27,25 @@ The default settings should actually already be appropriate to perform a
<listitem><para><link linkend="conf-binpath">binpath</link>, to change the list of
directories that will be searched for commands. This is exactly the same as
the <envar>PATH</envar> variable in the shell.</para></listitem>
+
+<listitem><para><link linkend="conf-use-stable-kde">use-stable-kde</link> to
+change the default version to build of KDE modules. By default &kdesvn-build;
+will build the trunk version of KDE (currently KDE 4). If you want to build
+the latest stable release of KDE instead of using your distribution packages
+(right now the KDE 3.5 branch is stable) you would set this option to true.
+</para></listitem>
+
<listitem><para><link linkend="conf-kdedir">kdedir</link>, which changes the
destination directory that &kde; is installed to. This defaults to
<filename>~/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 defaults to using the qt-copy
-module from the &kde; &svn; repository. (<filename>~/kdesvn/build/qt-copy</filename>)</para></listitem>
+module from the &kde; &svn; repository. (<filename>~/kdesvn/build/qt-copy</filename>)</para>
+
+<para>For Qt versions that support installation, this also controls where to
+install qt-copy.</para></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://developer.kde.org/documentation/misc/firststepsaccount.php">&kde;
diff --git a/doc/index.docbook b/doc/index.docbook
index 55c30164..87877841 100644
--- a/doc/index.docbook
+++ b/doc/index.docbook
@@ -98,6 +98,7 @@
<copyright>
<year>2006</year>
+<year>2007</year>
<holder>Michael Pyne</holder>
</copyright>
@@ -109,8 +110,8 @@
<legalnotice>&FDLNotice;</legalnotice>
-<date>2006-03-28</date>
-<releaseinfo>1.1</releaseinfo>
+<date>2007-05-01</date>
+<releaseinfo>1.4</releaseinfo>
<abstract>
<para>&kdesvn-build; is a script which builds and installs &kde; directly from the sources found in the &kde; &svn; repository.</para>
diff --git a/doc/kdesvn-buildrc/index.docbook b/doc/kdesvn-buildrc/index.docbook
index 496e1774..72b354c0 100644
--- a/doc/kdesvn-buildrc/index.docbook
+++ b/doc/kdesvn-buildrc/index.docbook
@@ -107,7 +107,9 @@ process. This only works for modules where <command>make apidox</command> does
including kdelibs, kdebase, and koffice, among others.
</para>
<para>This option does not work for modules using &unsermake; support, due to
-deficiencies in the unsermake build system.
+deficiencies in the &unsermake; build system. This option does not work for
+KDE 4 modules because the required build system support has been migrated to
+a different program which &kdesvn-build; has not been corrected to use yet.
</para>
</entry>
</row>
@@ -144,7 +146,7 @@ default of "trunk", where &kde; development occurs. For instance, to checkout
<para>Note that some modules use a different branch name. Notably, the
required arts module doesn't go by &kde; version numbers. The arts that
accompanied &kde; 3.4 was version 1.4.</para>
-<para>If kdesvn-build fails to properly download a branch with this option, you
+<para>If &kdesvn-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-override-url">override-url</link> option.</para>
</entry>
@@ -265,7 +267,7 @@ extragear-network using this option.
<entry>disable-agent-check</entry>
<entry>Can't be overridden</entry>
<entry>Normally if you're using SSH to download the Subversion sources (such as
-if you're using the svn+ssh protocol), kdesvn-build will try and make sure that
+if you're using the svn+ssh protocol), &kdesvn-build; will try and make sure that
if you're using ssh-agent, it is actually managing some SSH identities. This is
to try and prevent SSH from asking for your pass phrase for every module. You can
disable this check by setting disable-agent-check to true.
@@ -286,7 +288,7 @@ the <link linkend="conf-checkout-only">checkout-only</link>
directive to choose directories that you want to check out.</para>
<important><para>This option does not yet work with modules built using
-&cmake;</para></important>
+&cmake;.</para></important>
</entry>
</row>
@@ -294,7 +296,7 @@ directive to choose directories that you want to check out.</para>
<entry>email-address</entry>
<entry>Can't be overridden</entry>
<entry>
-<para>Set this option to the e-mail address kdesvn-build should send from should
+<para>Set this option to the e-mail address &kdesvn-build; should send from should
it ever need to send e-mail. You do not need to worry about this if you don't
use any feature which send e-mail. (They are all disabled by default).
</para>
@@ -310,13 +312,13 @@ needs this option.
<entry>Can't be overridden</entry>
<entry>
<para>You can set this option to the email address to send a report to when a
-module fails to build. kdesvn-build will wait until all the modules are done
+module fails to build. &kdesvn-build; will wait until all the modules are done
and collate all of the results in the report. The report is only sent if a
module fails to build.
</para>
<para>Please see the <link linkend="conf-email-address">email-address</link>
-option to set the address kdesvn-build should send from, since the default
+option to set the address &kdesvn-build; should send from, since the default
is usually not what you want.
</para>
</entry>
@@ -422,12 +424,9 @@ please be careful while dealing with root privileges.</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>
+url="http://distcc.samba.org/"><application>distcc</application></ulink> or
+systems with more than one processor core.
+</entry>
</row>
<row id="conf-manual-build">
@@ -462,6 +461,9 @@ following template:
</para>
<para>The default value is either <quote>trunk</quote> or
<quote>trunk/KDE</quote>, 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>
@@ -485,9 +487,9 @@ effect of a stray &svn; update messing up the build system.</entry>
<row id="conf-override-url">
<entry>override-url</entry>
<entry>Overrides global</entry>
-<entry>If you set this option, kdesvn-build will use its value as the URL
+<entry>If you set this option, &kdesvn-build; will use its value as the URL
to pass to &svn; <emphasis>completely unchanged</emphasis>. You should
-generally use this if you want to download a specific release but kdesvn-build
+generally use this if you want to download a specific release but &kdesvn-build;
can't figure out what you mean using <link linkend="conf-branch">branch</link>.
</entry>
</row>
@@ -522,10 +524,21 @@ installed.
<para>Note that using this option can have a significant detrimental impact on
both your bandwidth usage (if you use 'all') and the time taken to compile &kde;,
-since kdesvn-build will be unable to perform incremental builds.</para>
+since &kdesvn-build; will be unable to perform incremental builds.</para>
</entry>
</row>
+<row id="conf-revision">
+<entry>revision</entry>
+<entry>Overrides global</entry>
+<entry>If this option is set to a value other than 0 (zero), &kdesvn-build;
+will force the Subversion 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.</entry>
+</row>
+
<row id="conf-set-env">
<entry>set-env</entry>
<entry>Overrides global</entry>
@@ -551,13 +564,6 @@ you do specify this value, use an absolute path name.
</entry>
</row>
-<row id="conf-svn-server">
-<entry>svn-server</entry>
-<entry>Overrides global</entry>
-<entry>This option is used to set the server used to check out from &svn;.
-The default is the anonymous &svn; repository, <emphasis>svn://anonsvn.kde.org/</emphasis></entry>
-</row>
-
<row id="conf-stop-on-failure">
<entry>stop-on-failure</entry>
<entry>Overrides global</entry>
@@ -567,6 +573,13 @@ by default.
</entry>
</row>
+<row id="conf-svn-server">
+<entry>svn-server</entry>
+<entry>Overrides global</entry>
+<entry>This option is used to set the server used to check out from &svn;.
+The default is the anonymous &svn; repository, <emphasis>svn://anonsvn.kde.org/</emphasis></entry>
+</row>
+
<row id="conf-tag">
<entry>tag</entry>
<entry>Overrides global</entry>
@@ -575,23 +588,27 @@ by default.
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>
-<para>If you are using kdesvn-build because you have having trouble getting
+<para>If you are using &kdesvn-build; because you have having trouble getting
a &kde; release to build on your distribution, consider using the <ulink
url="http://developer.kde.org/build/konstruct/">Konstruct build tool</ulink>
instead, which works from the release tarballs.</para>
</entry>
</row>
+<row id="conf-unsermake-options">
+<entry>unsermake-options</entry>
+<entry>Overrides global</entry>
+<entry>This option is just like <link linkend="conf-make-options">make-options</link>
+but for &unsermake;, which accepts some options that <command>make</command>
+cannot understand.
+</entry>
+</row>
+
<row id="conf-use-cmake">
<entry>use-cmake</entry>
<entry>Overrides global</entry>
-<entry>
-<para>This option allows you to force &kdesvn-build; to try (or not try) to use
-CMake with a given module. Normally &kdesvn-build; will always try to use CMake
-if it is present in the module, as this will be required to build KDE 4. This
-option is available to ease the transition from unsermake to CMake. This option
-will be removed once all KDE 4 modules require CMake.
-</para>
+<entry>This option was removed in &kdesvn-build; 1.4 as all KDE 4 modules
+require CMake, and CMake use is not permitted on any other modules.
</entry>
</row>
@@ -600,7 +617,7 @@ will be removed once all KDE 4 modules require CMake.
<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,
+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
@@ -641,16 +658,16 @@ instead of the pre-release &kde; 4.</para>
<entry>use-unsermake</entry>
<entry>Overrides global</entry>
<entry><para>Set this option to <quote>true</quote> in order to use the
-experimental unsermake program instead of automake when running the configure
+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).
</para>
-<para>Normally if you use this option kdesvn-build will automatically keep
+<para>Normally if you use this option &kdesvn-build; will automatically keep
unsermake up-to-date. This may start to get annoying, especially if you are
-managing unsermake yourself. If this is the case, you can set this option to
-<quote>self</quote>, and kdesvn-build will still use unsermake, but will not
+managing &unsermake; yourself. If this is the case, you can set this option to
+<quote>self</quote>, and &kdesvn-build; will still use &unsermake;, but will not
do anything special to keep it updated.
</para>
</entry>
More information about the kde-doc-english
mailing list