[sdk/kdesrc-build] doc: doc: features - separate docbook

[Andrew Shark]

Git commit 17357b81a15786f0066759f9433819912678f87b by Andrew Shark.
Committed on 05/01/2024 at 19:59.
Pushed by ashark into branch 'master'.

doc: features - separate docbook

A  +262  -0    doc/features.docbook
M  +2    -262  doc/index.docbook

https://invent.kde.org/sdk/kdesrc-build/-/commit/17357b81a15786f0066759f9433819912678f87b

diff --git a/doc/features.docbook b/doc/features.docbook
new file mode 100644
index 00000000..2a911dc3
--- /dev/null
+++ b/doc/features.docbook
@@ -0,0 +1,262 @@
+<chapter id="features">
+<title>Script Features</title>
+
+<sect1 id="features-overview">
+<title>Feature Overview</title>
+
+<para>
+&kdesrc-build; features include:
+</para>
+
+<itemizedlist>
+
+<listitem><para>
+You can <quote>pretend</quote> to do the operations. If you pass
+<option>--pretend</option> or <option>-p</option> on the
+command line, the script will give a verbose description of the commands
+it is about to execute, without actually executing it. However if you've never
+run &kdesrc-build;, you would want to run the <command>kdesrc-build
+<option><link
+linkend="cmdline-metadata-only">--metadata-only</link></option></command>
+command first in order for <option>--pretend</option> to work.
+
+<tip><para>For an even more verbose description of what &kdesrc-build; is
+doing, try using the <option>--debug</option> option.
+</para></tip>
+
+</para></listitem>
+
+<listitem><para>
+&kdesrc-build; allows you to checkout modules quickly. If the module you are checking out
+has already been checked out previously, then &kdesrc-build; will download only commits
+that are not yet on your computer.
+</para>
+
+<tip><para>There is generally no need for any special preparation to perform
+the initial checkout of a Git module, as the entire Git repository must be
+downloaded anyways, so it is easy for the server to determine what to
+send.</para></tip>
+
+<para>This is faster for you, and helps to ease the load on the kde.org
+anonymous &git; servers.</para>
+</listitem>
+
+<listitem><para>
+Another speedup is provided by starting the build process for a module as soon
+as the source code for that module has been downloaded.  (Available since
+version 1.6)
+</para></listitem>
+
+<listitem><para>
+Excellent support for building the &Qt; library (in case the &kde; software you
+are trying to build depends on a recent &Qt; not available in your
+distribution).
+</para></listitem>
+
+<listitem><para>
+&kdesrc-build; does not require a <acronym>GUI</acronym> present to operate. So,
+you can build &kde; software without needing a graphical environment.
+</para></listitem>
+
+<listitem><para>
+Supports setting default options for all modules (such as the compilation
+settings or the configuration options). Such options can normally be changed
+for specific modules as well.</para>
+
+<para>Also, &kdesrc-build; will <link linkend="kdesrc-build-std-flags">add
+standard flags</link> as appropriate to save you the trouble and possible
+errors from typing them yourself. Nota Bene: this does not apply when a (custom)
+toolchain is configured through e.g.:
+<link linkend="conf-cmake-toolchain">cmake-toolchain</link>
+</para></listitem>
+
+<listitem><para>
+&kdesrc-build; can checkout a specific <link linkend="using-branches">branch
+or tag</link> of a module. You can also ensure that a specific <link
+linkend="conf-revision">revision</link> is checked out of a module.
+</para></listitem>
+
+<listitem><para>
+&kdesrc-build; can automatically switch a source directory to checkout from
+a different repository, branch, or tag. This happens automatically when you
+change an option that changes what the repository &url; should be, but you must
+use the <link linkend="cmdline-src-only">--src-only</link> option to let
+&kdesrc-build; know that it is acceptable to perform the switch.
+</para></listitem>
+
+<listitem><para>
+&kdesrc-build; can <link linkend="partial-builds">checkout only portions of a
+module</link>, for those situations where you only need one program from a
+large module.
+</para></listitem>
+
+<listitem><para>
+For developers: &kdesrc-build; will <link linkend="ssh-agent-reminder">remind
+you</link> if you use git+ssh:// but <application>ssh-agent</application> is
+not running, as this will lead to repeated password requests from
+&ssh;.
+</para></listitem>
+
+<listitem><para>
+Can <link linkend="deleting-build-dir">delete the build directory</link> of a
+module after its installation to save space at the expense of future compilation
+time.
+</para></listitem>
+
+<listitem><para>
+The locations for the directories used by &kdesrc-build; are configurable (even
+per module).
+</para></listitem>
+
+<listitem><para>
+Can use &sudo;, or a different user-specified command
+to <link linkend="root-installation">install modules</link> so that
+&kdesrc-build; does not need to be run as the super user.
+</para></listitem>
+
+<listitem><para>
+&kdesrc-build; runs <link linkend="build-priority">with reduced priority</link>
+by default to allow you to still use your computer while &kdesrc-build; is
+working.
+</para></listitem>
+
+<listitem><para>
+Has support for using &kde;'s <link linkend="using-branches">tags and
+branches</link>.
+</para></listitem>
+
+<listitem><para>
+There is support for <link linkend="resuming">resuming a build</link> from a
+given module. You can even <link linkend="ignoring-modules">ignore some
+modules</link> temporarily for a given build.
+</para></listitem>
+
+<listitem><para>
+&kdesrc-build; will show the <link linkend="build-progress">progress of your
+build</link> when using &cmake;, and will always time the build
+process so you know after the fact how long it took.
+</para></listitem>
+
+<listitem><para>
+Comes built-in with a sane set of default options appropriate for building
+a base &kde; single-user installation from the anonymous source repositories.
+</para></listitem>
+
+<listitem><para>
+Tilde-expansion for your configuration options. For example, you can
+specify:
+<programlisting>qtdir ~/kdesrc/build/qt</programlisting>
+</para></listitem>
+
+<listitem><para>
+Automatically sets up a build system, with the source directory not the
+same as the build directory, in order to keep the source directory
+pristine.
+</para></listitem>
+
+<listitem><para>
+You can specify global options to apply to every module to check out, and
+you can specify options to apply to individual modules as well.
+</para></listitem>
+
+<listitem><para>
+Forced full rebuilds, by running
+&kdesrc-build; with the <option>--refresh-build</option> option.
+</para></listitem>
+
+<listitem><para>
+You can specify various environment values to be used during the build,
+including <envar>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>
+
+</itemizedlist>
+
+</sect1>
+
+<sect1 id="kdesrc-build-logging">
+<title>&kdesrc-build;'s build logging</title>
+
+<sect2 id="logging-overview">
+<title>Logging overview</title>
+
+<para>Logging is a &kdesrc-build; feature whereby the output from every command
+that &kdesrc-build; runs is saved to a file for examination later, if
+necessary. This is done because it is often necessary to have the output of
+these programs when there is a build failure, because there are so many
+reasons why a build can fail in the first place.</para>
+
+<sect3 id="log-directory-layout">
+<title>Logging directory layout</title>
+
+<para>The logs are always stored under the log directory. The destination of
+the log directory is controlled by the <link linkend="conf-log-dir">log-dir</link>
+option, which defaults to <filename class="directory"><symbol>${source-dir}</symbol>/log</filename> (where
+<symbol>${source-dir}</symbol> is the value of the <link linkend="conf-source-dir">source-dir</link>
+option. The in rest of this section, this value will be referred to as
+<symbol>${log-dir}</symbol>).</para>
+
+<para>Under <symbol>${log-dir}</symbol>, is a set of directories, one for every
+time that &kdesrc-build; was run. Each directory is named with the date, and
+the run number. For instance, the second time that &kdesrc-build; is run on
+May 26, 2004, it would create a directory called <filename>2004-05-26-02</filename>,
+where the 2004-05-26 is for the date, and the -02 is the run number.</para>
+
+<para>For your convenience, &kdesrc-build; will also create a link to the
+logs for your latest run, called <filename class="directory">latest</filename>. So the logs for
+the most recent &kdesrc-build; run should always be under <filename class="directory"><symbol>${log-dir}</symbol>/latest</filename>.
+</para>
+
+<para>Now, each directory for a &kdesrc-build; run will itself contain a set of
+directories, one for every &kde; module that &kdesrc-build; tries to build. Also,
+a file called <filename>build-status</filename> will be contained in the directory,
+which will allow you to determine which modules built and which failed.</para>
+
+<note><para>
+If a module itself has a submodule (such as extragear/multimedia,
+playground/utils, or KDE/kdelibs), then there would actually be a matching
+layout in the log directory. For example, the logs for KDE/kdelibs after the
+last &kdesrc-build; run would be found in <filename class="directory"><symbol>${log-dir}</symbol>/latest/KDE/kdelibs</filename>,
+and not under <filename class="directory"><symbol>${log-dir}</symbol>/latest/kdelibs</filename>.
+</para></note>
+
+<para>In each module log directory, you will find a set of files for each
+operation that &kdesrc-build; performs. If &kdesrc-build; updates a module,
+you may see filenames such as <filename>git-checkout-update.log</filename> (for a
+module checkout or when updating a module
+that has already been checked out). If the <command>configure</command>
+command was run, then you would expect to see a <filename>configure.log</filename>
+in that directory.</para>
+
+<para>If an error occurred, you should be able to see an explanation of why in
+one of the files. To help you determine which file contains the error,
+&kdesrc-build; will create a link from the file containing the error (such as
+<filename>build-1.log</filename> to a file called <filename>error.log</filename>).</para>
+
+<para>The upshot to all of this is that to see why a module failed to build
+after your last &kdesrc-build;, the file you should look at first is
+<filename><symbol>${log-dir}</symbol>/latest/<replaceable>module-name</replaceable>/error.log</filename>.
+</para>
+
+<tip><para>If the file <filename>error.log</filename> is empty (especially after
+an installation), then perhaps there was no error. Some of the tools used by
+the &kde; build system will sometimes mistakenly report an error when there was
+none.</para>
+
+<para>Also, some commands will evade &kdesrc-build;'s output redirection and
+bypass the log file in certain circumstances (normally when performing the
+first &git; checkout), and the error output in that case is not in the log file
+but is instead at the &konsole; or terminal where you ran &kdesrc-build;.</para>
+</tip>
+
+</sect3>
+</sect2>
+</sect1>
+
+</chapter>
diff --git a/doc/index.docbook b/doc/index.docbook
index e4f365d5..02ceb3ba 100644
--- a/doc/index.docbook
+++ b/doc/index.docbook
@@ -79,6 +79,7 @@
   <!ENTITY credits-and-license SYSTEM "credits-and-license.docbook">
   <!ENTITY developer-features SYSTEM "developer-features.docbook">
   <!ENTITY environment SYSTEM "environment.docbook">
+  <!ENTITY features SYSTEM "features.docbook">
 ]>
 
 <book id="kdesrc-build" lang="&language;">
@@ -820,268 +821,7 @@ tool.</para>
 
 </chapter>
 
-<chapter id="features">
-<title>Script Features</title>
-
-<sect1 id="features-overview">
-<title>Feature Overview</title>
-
-<para>
-&kdesrc-build; features include:
-</para>
-
-<itemizedlist>
-
-<listitem><para>
-You can <quote>pretend</quote> to do the operations. If you pass
-<option>--pretend</option> or <option>-p</option> on the
-command line, the script will give a verbose description of the commands
-it is about to execute, without actually executing it. However if you've never
-run &kdesrc-build;, you would want to run the <command>kdesrc-build
-<option><link
-linkend="cmdline-metadata-only">--metadata-only</link></option></command>
-command first in order for <option>--pretend</option> to work.
-
-<tip><para>For an even more verbose description of what &kdesrc-build; is
-doing, try using the <option>--debug</option> option.
-</para></tip>
-
-</para></listitem>
-
-<listitem><para>
-&kdesrc-build; allows you to checkout modules quickly. If the module you are checking out
-has already been checked out previously, then &kdesrc-build; will download only commits
-that are not yet on your computer.
-</para>
-
-<tip><para>There is generally no need for any special preparation to perform
-the initial checkout of a Git module, as the entire Git repository must be
-downloaded anyways, so it is easy for the server to determine what to
-send.</para></tip>
-
-<para>This is faster for you, and helps to ease the load on the kde.org
-anonymous &git; servers.</para>
-</listitem>
-
-<listitem><para>
-Another speedup is provided by starting the build process for a module as soon
-as the source code for that module has been downloaded.  (Available since
-version 1.6)
-</para></listitem>
-
-<listitem><para>
-Excellent support for building the &Qt; library (in case the &kde; software you
-are trying to build depends on a recent &Qt; not available in your
-distribution).
-</para></listitem>
-
-<listitem><para>
-&kdesrc-build; does not require a <acronym>GUI</acronym> present to operate. So,
-you can build &kde; software without needing a graphical environment.
-</para></listitem>
-
-<listitem><para>
-Supports setting default options for all modules (such as the compilation
-settings or the configuration options). Such options can normally be changed
-for specific modules as well.</para>
-
-<para>Also, &kdesrc-build; will <link linkend="kdesrc-build-std-flags">add
-standard flags</link> as appropriate to save you the trouble and possible
-errors from typing them yourself. Nota Bene: this does not apply when a (custom)
-toolchain is configured through e.g.:
-<link linkend="conf-cmake-toolchain">cmake-toolchain</link>
-</para></listitem>
-
-<listitem><para>
-&kdesrc-build; can checkout a specific <link linkend="using-branches">branch
-or tag</link> of a module. You can also ensure that a specific <link
-linkend="conf-revision">revision</link> is checked out of a module.
-</para></listitem>
-
-<listitem><para>
-&kdesrc-build; can automatically switch a source directory to checkout from
-a different repository, branch, or tag. This happens automatically when you
-change an option that changes what the repository &url; should be, but you must
-use the <link linkend="cmdline-src-only">--src-only</link> option to let
-&kdesrc-build; know that it is acceptable to perform the switch.
-</para></listitem>
-
-<listitem><para>
-&kdesrc-build; can <link linkend="partial-builds">checkout only portions of a
-module</link>, for those situations where you only need one program from a
-large module.
-</para></listitem>
-
-<listitem><para>
-For developers: &kdesrc-build; will <link linkend="ssh-agent-reminder">remind
-you</link> if you use git+ssh:// but <application>ssh-agent</application> is
-not running, as this will lead to repeated password requests from
-&ssh;.
-</para></listitem>
-
-<listitem><para>
-Can <link linkend="deleting-build-dir">delete the build directory</link> of a
-module after its installation to save space at the expense of future compilation
-time.
-</para></listitem>
-
-<listitem><para>
-The locations for the directories used by &kdesrc-build; are configurable (even
-per module).
-</para></listitem>
-
-<listitem><para>
-Can use &sudo;, or a different user-specified command
-to <link linkend="root-installation">install modules</link> so that
-&kdesrc-build; does not need to be run as the super user.
-</para></listitem>
-
-<listitem><para>
-&kdesrc-build; runs <link linkend="build-priority">with reduced priority</link>
-by default to allow you to still use your computer while &kdesrc-build; is
-working.
-</para></listitem>
-
-<listitem><para>
-Has support for using &kde;'s <link linkend="using-branches">tags and
-branches</link>.
-</para></listitem>
-
-<listitem><para>
-There is support for <link linkend="resuming">resuming a build</link> from a
-given module. You can even <link linkend="ignoring-modules">ignore some
-modules</link> temporarily for a given build.
-</para></listitem>
-
-<listitem><para>
-&kdesrc-build; will show the <link linkend="build-progress">progress of your
-build</link> when using &cmake;, and will always time the build
-process so you know after the fact how long it took.
-</para></listitem>
-
-<listitem><para>
-Comes built-in with a sane set of default options appropriate for building
-a base &kde; single-user installation from the anonymous source repositories.
-</para></listitem>
-
-<listitem><para>
-Tilde-expansion for your configuration options. For example, you can
-specify:
-<programlisting>qtdir ~/kdesrc/build/qt</programlisting>
-</para></listitem>
-
-<listitem><para>
-Automatically sets up a build system, with the source directory not the
-same as the build directory, in order to keep the source directory
-pristine.
-</para></listitem>
-
-<listitem><para>
-You can specify global options to apply to every module to check out, and
-you can specify options to apply to individual modules as well.
-</para></listitem>
-
-<listitem><para>
-Forced full rebuilds, by running
-&kdesrc-build; with the <option>--refresh-build</option> option.
-</para></listitem>
-
-<listitem><para>
-You can specify various environment values to be used during the build,
-including <envar>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>
-
-</itemizedlist>
-
-</sect1>
-
-<sect1 id="kdesrc-build-logging">
-<title>&kdesrc-build;'s build logging</title>
-
-<sect2 id="logging-overview">
-<title>Logging overview</title>
-
-<para>Logging is a &kdesrc-build; feature whereby the output from every command
-that &kdesrc-build; runs is saved to a file for examination later, if
-necessary. This is done because it is often necessary to have the output of
-these programs when there is a build failure, because there are so many
-reasons why a build can fail in the first place.</para>
-
-<sect3 id="log-directory-layout">
-<title>Logging directory layout</title>
-
-<para>The logs are always stored under the log directory. The destination of
-the log directory is controlled by the <link linkend="conf-log-dir">log-dir</link>
-option, which defaults to <filename class="directory"><symbol>${source-dir}</symbol>/log</filename> (where
-<symbol>${source-dir}</symbol> is the value of the <link linkend="conf-source-dir">source-dir</link>
-option. The in rest of this section, this value will be referred to as
-<symbol>${log-dir}</symbol>).</para>
-
-<para>Under <symbol>${log-dir}</symbol>, is a set of directories, one for every
-time that &kdesrc-build; was run. Each directory is named with the date, and
-the run number. For instance, the second time that &kdesrc-build; is run on
-May 26, 2004, it would create a directory called <filename>2004-05-26-02</filename>,
-where the 2004-05-26 is for the date, and the -02 is the run number.</para>
-
-<para>For your convenience, &kdesrc-build; will also create a link to the
-logs for your latest run, called <filename class="directory">latest</filename>. So the logs for
-the most recent &kdesrc-build; run should always be under <filename class="directory"><symbol>${log-dir}</symbol>/latest</filename>.
-</para>
-
-<para>Now, each directory for a &kdesrc-build; run will itself contain a set of
-directories, one for every &kde; module that &kdesrc-build; tries to build. Also,
-a file called <filename>build-status</filename> will be contained in the directory,
-which will allow you to determine which modules built and which failed.</para>
-
-<note><para>
-If a module itself has a submodule (such as extragear/multimedia,
-playground/utils, or KDE/kdelibs), then there would actually be a matching
-layout in the log directory. For example, the logs for KDE/kdelibs after the
-last &kdesrc-build; run would be found in <filename class="directory"><symbol>${log-dir}</symbol>/latest/KDE/kdelibs</filename>,
-and not under <filename class="directory"><symbol>${log-dir}</symbol>/latest/kdelibs</filename>.
-</para></note>
-
-<para>In each module log directory, you will find a set of files for each
-operation that &kdesrc-build; performs. If &kdesrc-build; updates a module,
-you may see filenames such as <filename>git-checkout-update.log</filename> (for a
-module checkout or when updating a module
-that has already been checked out). If the <command>configure</command>
-command was run, then you would expect to see a <filename>configure.log</filename>
-in that directory.</para>
-
-<para>If an error occurred, you should be able to see an explanation of why in
-one of the files. To help you determine which file contains the error,
-&kdesrc-build; will create a link from the file containing the error (such as
-<filename>build-1.log</filename> to a file called <filename>error.log</filename>).</para>
-
-<para>The upshot to all of this is that to see why a module failed to build
-after your last &kdesrc-build;, the file you should look at first is
-<filename><symbol>${log-dir}</symbol>/latest/<replaceable>module-name</replaceable>/error.log</filename>.
-</para>
-
-<tip><para>If the file <filename>error.log</filename> is empty (especially after
-an installation), then perhaps there was no error. Some of the tools used by
-the &kde; build system will sometimes mistakenly report an error when there was
-none.</para>
-
-<para>Also, some commands will evade &kdesrc-build;'s output redirection and
-bypass the log file in certain circumstances (normally when performing the
-first &git; checkout), and the error output in that case is not in the log file
-but is instead at the &konsole; or terminal where you ran &kdesrc-build;.</para>
-</tip>
-
-</sect3>
-</sect2>
-</sect1>
-
-</chapter>
+&features;
 
 <chapter id="kdesrc-buildrc">
 <title>Configuring &kdesrc-build;</title>