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

[Andrew Shark]

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

doc: advanced-features - separate docbook

A  +420  -0    doc/advanced-features.docbook
M  +6    -420  doc/index.docbook

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

diff --git a/doc/advanced-features.docbook b/doc/advanced-features.docbook
new file mode 100644
index 00000000..edb19da7
--- /dev/null
+++ b/doc/advanced-features.docbook
@@ -0,0 +1,420 @@
+<sect1 id="advanced-features">
+<title>Advanced features</title>
+
+<sect2 id="partial-builds">
+<title>Partially building a module</title>
+<para>It is possible to build only pieces from a single &kde; module. For
+example, you may want to compile only one program from a module. &kdesrc-build;
+has features to make this easy. There are several complementing ways to
+do this.
+</para>
+
+<sect3 id="not-compiling">
+<title>Removing directories from a build</title>
+<para>It is possible to download an entire repository
+but have the build system leave out a few directories when it does
+the build. This requires that the module uses &cmake; and that the
+module's build system allows the directory to remove to be
+optional.
+</para>
+
+<para>This is controlled with the &do-not-compile; option.</para>
+
+<important><para>
+This option requires at least that the
+build system for the module is reconfigured after changing
+it. This is done using the <userinput><command>kdesrc-build</command>
+<option>&cmd-reconfigure;</option>
+<option><replaceable>module</replaceable></option></userinput> command.
+</para></important>
+
+<informalexample>
+<para>To remove the <filename class="directory">python</filename> directory
+from the kdebindings build process:</para>
+
+<screen>
+module <replaceable>kdebindings</replaceable>
+  &do-not-compile; <replaceable>python</replaceable>
+end module
+</screen>
+
+</informalexample>
+
+<note><para>This function depends on some standard conventions used in most
+&kde; modules. Therefore it may not work for all programs.</para></note>
+
+</sect3>
+
+</sect2>
+
+<sect2 id="using-branches">
+<title>Branching and tagging support for &kdesrc-build;</title>
+
+<sect3 id="branches-and-tags">
+<title>What are branches and tags?</title>
+
+<para>&git; supports managing the history of the &kde; source code. &kde;
+uses this support to create branches for development, and to tag the repository
+every so often with a new version release.
+</para>
+
+<para>For example, the &kmail; developers may be working on a new feature in
+a different branch in order to avoid breaking the version being used by most
+developers. This branch has development ongoing inside it, even while the
+main branch (called master) may have development going on inside of it.
+</para>
+
+<para>A tag, on the other hand, is a specified point in the source code repository
+at a position in time. This is used by the &kde; administration team to mark
+off a version of code suitable for release and still allow the developers to
+work on the code.
+</para>
+
+</sect3>
+
+<sect3 id="branch-support">
+<title>How to use branches and tags</title>
+
+<para>Support for branches and tags is handled by a set of options, which
+range from a generic request for a version, to a specific &url; to download
+for advanced users.
+</para>
+
+<para>The easiest method is to use the &branch; and &tag; options. You simply
+use the option along with the name of the desired branch or tag for a module,
+and &kdesrc-build; will try to determine the appropriate location within the
+&kde; repository to download from. For most &kde; modules this works very
+well.</para>
+
+<informalexample>
+<para>To download kdelibs from &kde; 4.6 (which is simply known as the 4.6 branch):
+</para>
+
+<screen>
+module kdelibs
+  branch <replaceable>4.6</replaceable>
+  # other options...
+end module
+</screen>
+
+<para>Or, to download kdemultimedia as it was released with &kde; 4.6.1:</para>
+
+<screen>
+module kdemultimedia
+  tag <replaceable>4.6.1</replaceable>
+  # other options...
+end module
+</screen>
+
+</informalexample>
+
+<tip><para>You can specify a global branch value. But if you do so, do not forget
+to specify a different branch for modules that should not use the global branch!
+</para></tip>
+</sect3>
+
+</sect2>
+
+<sect2 id="stopping-the-build-early">
+<title>Stopping the build early</title>
+
+<sect3 id="the-build-continues">
+<title>The build normally continues even if failures occur</title>
+
+<para>&kdesrc-build; normally will update, build and install all modules
+in the specified list of modules to build, even if a module fails to build.
+This is usually a convenience to allow you to update software packages even
+if a simple mistake is made in one of the source repositories during
+development that causes the build to break.
+</para>
+
+<para>
+However you may wish for &kdesrc-build; to stop what it is doing once a
+module fails to build and install. This can help save you time that will be
+wasted trying to make progress when modules remaining in the build list will
+not be able to successfully build either, especially if you have not ever
+successfully built the modules in the list.
+</para>
+
+</sect3>
+
+<sect3 id="stop-on-failure-stops-early">
+<title>Not stopping early with --no-stop-on-failure</title>
+
+<para>
+The primary method to do this is to use the
+<link linkend="cmdline-stop-on-failure">--no-stop-on-failure</link>
+command line option when you run &kdesrc-build;.
+</para>
+
+<para>This option can also be set in the
+<link linkend="conf-stop-on-failure">configuration file</link> to make
+it the normal mode of operation.
+</para>
+
+<para>It is also possible to tell &kdesrc-build; at runtime to stop building
+<emphasis>after</emphasis> completing the current module it is working on.
+This is as opposed to interrupting &kdesrc-build; using a command like
+<keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo>, which interrupts
+&kdesrc-build; immediately, losing the progress of the current module.
+</para>
+
+<important><para>Interrupting &kdesrc-build; during a module install when
+the <link linkend="conf-use-clean-install">use-clean-install</link> option
+is enabled will mean that the interrupted module will be unavailable until
+&kdesrc-build; is able to successfully build the module!</para>
+
+<para>If you need to interrupt &kdesrc-build; without permitting a graceful shutdown
+in this situation, at least try to avoid doing this while &kdesrc-build; is
+installing a module.</para>
+</important>
+
+</sect3>
+
+<sect3 id="stopping-early-without-stop-on-failure">
+<title>Stopping &kdesrc-build; gracefully when stop-on-failure is false</title>
+
+<para>As mentioned above, it is possible to cause &kdesrc-build; to gracefully
+shutdown early once it has completed the module it is currently working on.
+To do this, you need to send the POSIX <literal>HUP</literal> signal to &kdesrc-build;
+</para>
+
+<para>You can do this with a command such as <command>pkill</command> (on &Linux; systems) as follows:</para>
+
+<programlisting>
+<prompt>$ </prompt><userinput><command>pkill <option>-HUP</option> kdesrc-build</command></userinput>
+</programlisting>
+
+<para>If done successfully, you will see a message in the &kdesrc-build; output similar
+to:</para>
+
+<programlisting>
+[ build ] recv SIGHUP, will end after this module
+</programlisting>
+
+<note>
+<para>&kdesrc-build; may show this message multiple times depending on the
+number of individual &kdesrc-build; processes that are active. This is
+normal and not an indication of an error.</para>
+</note>
+
+<para>
+Once &kdesrc-build; has acknowledged the signal, it will stop processing
+after the current module is built and installed. If &kdesrc-build; is still
+updating source code when the request is received, &kdesrc-build; will stop
+after the module source code update is complete. Once both the update and build
+processes have stopped early, &kdesrc-build; will print its partial results
+and exit.
+</para>
+
+</sect3>
+
+</sect2>
+
+<sect2 id="building-successfully">
+<title>How &kdesrc-build; tries to ensure a successful build</title>
+
+<sect3 id="automatic-rebuilds">
+<title>Automatic rebuilds</title>
+
+<para>&kdesrc-build; used to include features to automatically attempt to
+rebuild the module after a failure (as sometimes this re-attempt would work,
+due to bugs in the build system at that time). Thanks to switching to &cmake;
+the build system no longer suffers from these bugs, and so &kdesrc-build; will
+not try to build a module more than once. There are situations where
+&kdesrc-build; will automatically take action though:</para>
+
+<itemizedlist>
+
+<listitem><para>If you change <link linkend="conf-configure-flags">configure-flags</link>
+or <link linkend="conf-cmake-options">cmake-options</link> for a module, then
+&kdesrc-build; will detect that and automatically re-run configure or cmake
+for that module.</para></listitem>
+
+<listitem><para>If the buildsystem does not exist (even if &kdesrc-build; did
+not delete it) then &kdesrc-build; will automatically re-create it. This is
+useful to allow for performing a full <link
+linkend="cmdline-refresh-build">--refresh-build</link> for a specific module
+without having that performed on other modules.</para></listitem>
+
+</itemizedlist>
+
+</sect3>
+
+<sect3 id="manual-rebuilds">
+<title>Manually rebuilding a module</title>
+<para>If you make a change to a module's option settings, or the module's
+source code changes in a way &kdesrc-build; does not recognize, you may need to
+manually rebuild the module.</para>
+
+<para>You can do this by simply running <userinput><command>kdesrc-build</command>
+ <option>--refresh-build</option> <option><replaceable>module</replaceable></option></userinput>.
+</para>
+
+<para>If you would like to have &kdesrc-build; automatically rebuild the module
+during the next normal build update instead, you can create a special file.
+Every module has a build directory. If you create a file called <filename>.refresh-me</filename>
+in the build directory for a module, &kdesrc-build; will rebuild the module
+next time the build process occurs, even if it would normally perform the
+faster incremental build.</para>
+
+<tip>
+<para>By default, the build directory is <filename class="directory">~/kde/build/<replaceable>module</replaceable>/</filename>.
+If you change the setting of the &build-dir; option, then use that instead of
+<filename class="directory">~/kde/build</filename>.</para>
+</tip>
+
+<informalexample>
+<para>Rebuild using <filename>.refresh-me</filename> for module <replaceable>kdelibs</replaceable>:</para>
+<screen>
+<prompt>%</prompt> <userinput><command>touch</command> <filename>~/kdesrc/build/<replaceable>kdelibs</replaceable>/.refresh-me</filename></userinput>
+<prompt>%</prompt> <userinput><command>kdesrc-build</command></userinput>
+</screen>
+</informalexample>
+</sect3>
+
+</sect2>
+
+<sect2 id="changing-environment">
+<title>Changing environment variable settings</title>
+<para>Normally &kdesrc-build; uses the environment that is present when
+starting up when running programs to perform updates and builds. This is useful
+for when you are running &kdesrc-build; from the command line.</para>
+
+<para>However, you may want to change the setting for environment variables
+that &kdesrc-build; does not provide an option for directly. (For instance,
+to setup any required environment variables when running &kdesrc-build; on
+a timer such as &cron;) This is possible with the &set-env; option.</para>
+
+<para>Unlike most options, it can be set more than once, and it accepts two
+entries, separated by a space. The first one is the name of the environment
+variable to set, and the remainder of the line is the value.</para>
+
+<informalexample>
+<para>Set <userinput><envar>DISTRO</envar>=<replaceable>BSD</replaceable></userinput>
+for all modules:</para>
+<screen>
+global
+  set-env <replaceable>DISTRO</replaceable> <replaceable>BSD</replaceable>
+end global
+</screen>
+</informalexample>
+
+</sect2>
+
+<sect2 id="resuming">
+<title>Resuming builds</title>
+
+<sect3 id="resuming-failed">
+<title>Resuming a failed or canceled build</title>
+
+<para>You can tell &kdesrc-build; to start building from a different module
+than it normally would. This can be useful when a set of modules failed, or
+if you canceled a build run in the middle. You can control this using the
+&cmd-resume-from; option and the &cmd-resume-after; option.</para>
+
+<note><para>Older versions of &kdesrc-build; would skip the source update when
+resuming a build. This is no longer done by default, but you can always use
+the <option>--no-src</option> command line option
+to skip the source update.</para></note>
+
+<informalexample>
+<para>Resuming the build starting from kdebase:</para>
+
+<screen>
+<prompt>%</prompt> <userinput><command>kdesrc-build</command> <option>--resume-from=<replaceable>kdebase</replaceable></option></userinput>
+</screen>
+</informalexample>
+
+<informalexample>
+<para>Resuming the build starting after kdebase (in case you manually fixed
+the issue and installed the module yourself):</para>
+
+<screen>
+<prompt>%</prompt> <userinput><command>kdesrc-build</command> <option>--resume-after=<replaceable>kdebase</replaceable></option></userinput>
+</screen>
+</informalexample>
+
+<para>If the last &kdesrc-build; build ended with a build failure, you can also
+use the <link linkend="cmdline-resume">--resume</link> command line option,
+which resumes the last build starting at the module that failed. The source and
+metadata updates are skipped as well (but if you need these, it's generally
+better to use <link linkend="cmdline-resume-from">--resume-from</link>
+instead).</para>
+
+
+</sect3>
+
+<sect3 id="ignoring-modules">
+<title>Ignoring modules in a build</title>
+
+<para>Similar to the way you can <link linkend="resuming-failed">resume the
+build from a module</link>, you can instead choose to update and build everything
+normally, but ignore a set of modules.</para>
+
+<para>You can do this using the &cmd-ignore-modules; option. This option tells
+&kdesrc-build; to ignore all the modules on the command line when
+performing the update and build.</para>
+
+<informalexample>
+<para>Ignoring extragear/multimedia and kdereview during a full run:</para>
+<screen>
+<prompt>%</prompt> <userinput><command>kdesrc-build</command> <option>--ignore-modules</option> <replaceable>extragear/multimedia kdereview</replaceable></userinput>
+</screen>
+</informalexample>
+
+</sect3>
+</sect2>
+
+<sect2 id="changing-env-from-cmd-line">
+<title>Changing options from the command line</title>
+
+<sect3 id="changing-global-opts">
+<title>Changing global options</title>
+<para>You can change the setting of options read from the <link linkend="configure-data">configuration file</link> directly
+from the command line. This change will override the configuration file
+setting, but is only temporary. It only takes effect as long as it is still
+present on the command line.</para>
+
+<para>&kdesrc-build; allows you to change options named like <replaceable>option-name</replaceable>
+by passing an argument on the command line in the form <userinput><option>--<replaceable>option-name</replaceable>=value</option></userinput>.
+&kdesrc-build; will recognize whether it does not know what the option is, and search
+for the name in its list of option names. If it does not recognize the name, it
+will warn you, otherwise it will remember the value you set it to and override
+any setting from the configuration file.</para>
+
+<informalexample>
+<para>Setting the &source-dir; option to <filename>/dev/null</filename> for
+testing:</para>
+
+<screen>
+<prompt>%</prompt> <userinput><command>kdesrc-build</command> <option>--pretend</option> <option>--<replaceable>source-dir</replaceable>=<replaceable>/dev/null</replaceable></option></userinput>
+</screen>
+
+</informalexample>
+
+</sect3>
+
+<sect3 id="changing-module-opts">
+<title>Changing module options</title>
+<para>It is also possible to change options only for a specific module. The
+syntax is similar: --<replaceable>module</replaceable>,<replaceable>option-name</replaceable>=<replaceable>value</replaceable>.
+</para>
+
+<para>This change overrides any duplicate setting for the module found in the
+<link linkend="configure-data">configuration file</link>, and applies only while the option is passed on the command line.</para>
+
+<informalexample>
+<para>Using a different build directory for the kdeedu module:</para>
+
+<screen>
+<prompt>%</prompt> <userinput><command>kdesrc-build</command> <option>--<replaceable>kdeedu</replaceable>,<replaceable>build-dir</replaceable>=<replaceable>temp-build</replaceable></option></userinput>
+</screen>
+
+</informalexample>
+
+</sect3>
+
+</sect2>
+
+</sect1>
diff --git a/doc/index.docbook b/doc/index.docbook
index 55e0c874..228b67bb 100644
--- a/doc/index.docbook
+++ b/doc/index.docbook
@@ -63,6 +63,11 @@
   <!ENTITY cmd-resume-after '<link linkend="cmdline-resume-after">--resume-after</link>'>
   <!ENTITY cmd-reconfigure '<link linkend="cmdline-reconfigure">--reconfigure</link>'>
   <!ENTITY cmd-refresh-build '<link linkend="cmdline-refresh-build">--refresh-build</link>'>
+
+  <!-- These define docbook files to include.
+       Just add them as necessary.
+  -->
+  <!ENTITY advanced-features SYSTEM "advanced-features.docbook">
 ]>
 
 <book id="kdesrc-build" lang="&language;">
@@ -4164,426 +4169,7 @@ build a module.
 
 </sect1>
 
-<sect1 id="advanced-features">
-<title>Advanced features</title>
-
-<sect2 id="partial-builds">
-<title>Partially building a module</title>
-<para>It is possible to build only pieces from a single &kde; module. For
-example, you may want to compile only one program from a module. &kdesrc-build;
-has features to make this easy. There are several complementing ways to
-do this.
-</para>
-
-<sect3 id="not-compiling">
-<title>Removing directories from a build</title>
-<para>It is possible to download an entire repository
-but have the build system leave out a few directories when it does
-the build. This requires that the module uses &cmake; and that the
-module's build system allows the directory to remove to be
-optional.
-</para>
-
-<para>This is controlled with the &do-not-compile; option.</para>
-
-<important><para>
-This option requires at least that the
-build system for the module is reconfigured after changing
-it. This is done using the <userinput><command>kdesrc-build</command>
-<option>&cmd-reconfigure;</option>
-<option><replaceable>module</replaceable></option></userinput> command.
-</para></important>
-
-<informalexample>
-<para>To remove the <filename class="directory">python</filename> directory
-from the kdebindings build process:</para>
-
-<screen>
-module <replaceable>kdebindings</replaceable>
-  &do-not-compile; <replaceable>python</replaceable>
-end module
-</screen>
-
-</informalexample>
-
-<note><para>This function depends on some standard conventions used in most
-&kde; modules. Therefore it may not work for all programs.</para></note>
-
-</sect3>
-
-</sect2>
-
-<sect2 id="using-branches">
-<title>Branching and tagging support for &kdesrc-build;</title>
-
-<sect3 id="branches-and-tags">
-<title>What are branches and tags?</title>
-
-<para>&git; supports managing the history of the &kde; source code. &kde;
-uses this support to create branches for development, and to tag the repository
-every so often with a new version release.
-</para>
-
-<para>For example, the &kmail; developers may be working on a new feature in
-a different branch in order to avoid breaking the version being used by most
-developers. This branch has development ongoing inside it, even while the
-main branch (called master) may have development going on inside of it.
-</para>
-
-<para>A tag, on the other hand, is a specified point in the source code repository
-at a position in time. This is used by the &kde; administration team to mark
-off a version of code suitable for release and still allow the developers to
-work on the code.
-</para>
-
-</sect3>
-
-<sect3 id="branch-support">
-<title>How to use branches and tags</title>
-
-<para>Support for branches and tags is handled by a set of options, which
-range from a generic request for a version, to a specific &url; to download
-for advanced users.
-</para>
-
-<para>The easiest method is to use the &branch; and &tag; options. You simply
-use the option along with the name of the desired branch or tag for a module,
-and &kdesrc-build; will try to determine the appropriate location within the
-&kde; repository to download from. For most &kde; modules this works very
-well.</para>
-
-<informalexample>
-<para>To download kdelibs from &kde; 4.6 (which is simply known as the 4.6 branch):
-</para>
-
-<screen>
-module kdelibs
-  branch <replaceable>4.6</replaceable>
-  # other options...
-end module
-</screen>
-
-<para>Or, to download kdemultimedia as it was released with &kde; 4.6.1:</para>
-
-<screen>
-module kdemultimedia
-  tag <replaceable>4.6.1</replaceable>
-  # other options...
-end module
-</screen>
-
-</informalexample>
-
-<tip><para>You can specify a global branch value. But if you do so, do not forget
-to specify a different branch for modules that should not use the global branch!
-</para></tip>
-</sect3>
-
-</sect2>
-
-<sect2 id="stopping-the-build-early">
-<title>Stopping the build early</title>
-
-<sect3 id="the-build-continues">
-<title>The build normally continues even if failures occur</title>
-
-<para>&kdesrc-build; normally will update, build and install all modules
-in the specified list of modules to build, even if a module fails to build.
-This is usually a convenience to allow you to update software packages even
-if a simple mistake is made in one of the source repositories during
-development that causes the build to break.
-</para>
-
-<para>
-However you may wish for &kdesrc-build; to stop what it is doing once a
-module fails to build and install. This can help save you time that will be
-wasted trying to make progress when modules remaining in the build list will
-not be able to successfully build either, especially if you have not ever
-successfully built the modules in the list.
-</para>
-
-</sect3>
-
-<sect3 id="stop-on-failure-stops-early">
-<title>Not stopping early with --no-stop-on-failure</title>
-
-<para>
-The primary method to do this is to use the
-<link linkend="cmdline-stop-on-failure">--no-stop-on-failure</link>
-command line option when you run &kdesrc-build;.
-</para>
-
-<para>This option can also be set in the
-<link linkend="conf-stop-on-failure">configuration file</link> to make
-it the normal mode of operation.
-</para>
-
-<para>It is also possible to tell &kdesrc-build; at runtime to stop building
-<emphasis>after</emphasis> completing the current module it is working on.
-This is as opposed to interrupting &kdesrc-build; using a command like
-<keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo>, which interrupts
-&kdesrc-build; immediately, losing the progress of the current module.
-</para>
-
-<important><para>Interrupting &kdesrc-build; during a module install when
-the <link linkend="conf-use-clean-install">use-clean-install</link> option
-is enabled will mean that the interrupted module will be unavailable until
-&kdesrc-build; is able to successfully build the module!</para>
-
-<para>If you need to interrupt &kdesrc-build; without permitting a graceful shutdown
-in this situation, at least try to avoid doing this while &kdesrc-build; is
-installing a module.</para>
-</important>
-
-</sect3>
-
-<sect3 id="stopping-early-without-stop-on-failure">
-<title>Stopping &kdesrc-build; gracefully when stop-on-failure is false</title>
-
-<para>As mentioned above, it is possible to cause &kdesrc-build; to gracefully
-shutdown early once it has completed the module it is currently working on.
-To do this, you need to send the POSIX <literal>HUP</literal> signal to &kdesrc-build;
-</para>
-
-<para>You can do this with a command such as <command>pkill</command> (on &Linux; systems) as follows:</para>
-
-<programlisting>
-<prompt>$ </prompt><userinput><command>pkill <option>-HUP</option> kdesrc-build</command></userinput>
-</programlisting>
-
-<para>If done successfully, you will see a message in the &kdesrc-build; output similar
-to:</para>
-
-<programlisting>
-[ build ] recv SIGHUP, will end after this module
-</programlisting>
-
-<note>
-<para>&kdesrc-build; may show this message multiple times depending on the
-number of individual &kdesrc-build; processes that are active. This is
-normal and not an indication of an error.</para>
-</note>
-
-<para>
-Once &kdesrc-build; has acknowledged the signal, it will stop processing
-after the current module is built and installed. If &kdesrc-build; is still
-updating source code when the request is received, &kdesrc-build; will stop
-after the module source code update is complete. Once both the update and build
-processes have stopped early, &kdesrc-build; will print its partial results
-and exit.
-</para>
-
-</sect3>
-
-</sect2>
-
-<sect2 id="building-successfully">
-<title>How &kdesrc-build; tries to ensure a successful build</title>
-
-<sect3 id="automatic-rebuilds">
-<title>Automatic rebuilds</title>
-
-<para>&kdesrc-build; used to include features to automatically attempt to
-rebuild the module after a failure (as sometimes this re-attempt would work,
-due to bugs in the build system at that time). Thanks to switching to &cmake;
-the build system no longer suffers from these bugs, and so &kdesrc-build; will
-not try to build a module more than once. There are situations where
-&kdesrc-build; will automatically take action though:</para>
-
-<itemizedlist>
-
-<listitem><para>If you change <link linkend="conf-configure-flags">configure-flags</link>
-or <link linkend="conf-cmake-options">cmake-options</link> for a module, then
-&kdesrc-build; will detect that and automatically re-run configure or cmake
-for that module.</para></listitem>
-
-<listitem><para>If the buildsystem does not exist (even if &kdesrc-build; did
-not delete it) then &kdesrc-build; will automatically re-create it. This is
-useful to allow for performing a full <link
-linkend="cmdline-refresh-build">--refresh-build</link> for a specific module
-without having that performed on other modules.</para></listitem>
-
-</itemizedlist>
-
-</sect3>
-
-<sect3 id="manual-rebuilds">
-<title>Manually rebuilding a module</title>
-<para>If you make a change to a module's option settings, or the module's
-source code changes in a way &kdesrc-build; does not recognize, you may need to
-manually rebuild the module.</para>
-
-<para>You can do this by simply running <userinput><command>kdesrc-build</command>
- <option>--refresh-build</option> <option><replaceable>module</replaceable></option></userinput>.
-</para>
-
-<para>If you would like to have &kdesrc-build; automatically rebuild the module
-during the next normal build update instead, you can create a special file.
-Every module has a build directory. If you create a file called <filename>.refresh-me</filename>
-in the build directory for a module, &kdesrc-build; will rebuild the module
-next time the build process occurs, even if it would normally perform the
-faster incremental build.</para>
-
-<tip>
-<para>By default, the build directory is <filename class="directory">~/kde/build/<replaceable>module</replaceable>/</filename>.
-If you change the setting of the &build-dir; option, then use that instead of
-<filename class="directory">~/kde/build</filename>.</para>
-</tip>
-
-<informalexample>
-<para>Rebuild using <filename>.refresh-me</filename> for module <replaceable>kdelibs</replaceable>:</para>
-<screen>
-<prompt>%</prompt> <userinput><command>touch</command> <filename>~/kdesrc/build/<replaceable>kdelibs</replaceable>/.refresh-me</filename></userinput>
-<prompt>%</prompt> <userinput><command>kdesrc-build</command></userinput>
-</screen>
-</informalexample>
-</sect3>
-
-</sect2>
-
-<sect2 id="changing-environment">
-<title>Changing environment variable settings</title>
-<para>Normally &kdesrc-build; uses the environment that is present when
-starting up when running programs to perform updates and builds. This is useful
-for when you are running &kdesrc-build; from the command line.</para>
-
-<para>However, you may want to change the setting for environment variables
-that &kdesrc-build; does not provide an option for directly. (For instance,
-to setup any required environment variables when running &kdesrc-build; on
-a timer such as &cron;) This is possible with the &set-env; option.</para>
-
-<para>Unlike most options, it can be set more than once, and it accepts two
-entries, separated by a space. The first one is the name of the environment
-variable to set, and the remainder of the line is the value.</para>
-
-<informalexample>
-<para>Set <userinput><envar>DISTRO</envar>=<replaceable>BSD</replaceable></userinput>
-for all modules:</para>
-<screen>
-global
-  set-env <replaceable>DISTRO</replaceable> <replaceable>BSD</replaceable>
-end global
-</screen>
-</informalexample>
-
-</sect2>
-
-<sect2 id="resuming">
-<title>Resuming builds</title>
-
-<sect3 id="resuming-failed">
-<title>Resuming a failed or canceled build</title>
-
-<para>You can tell &kdesrc-build; to start building from a different module
-than it normally would. This can be useful when a set of modules failed, or
-if you canceled a build run in the middle. You can control this using the
-&cmd-resume-from; option and the &cmd-resume-after; option.</para>
-
-<note><para>Older versions of &kdesrc-build; would skip the source update when
-resuming a build. This is no longer done by default, but you can always use
-the <option>--no-src</option> command line option
-to skip the source update.</para></note>
-
-<informalexample>
-<para>Resuming the build starting from kdebase:</para>
-
-<screen>
-<prompt>%</prompt> <userinput><command>kdesrc-build</command> <option>--resume-from=<replaceable>kdebase</replaceable></option></userinput>
-</screen>
-</informalexample>
-
-<informalexample>
-<para>Resuming the build starting after kdebase (in case you manually fixed
-the issue and installed the module yourself):</para>
-
-<screen>
-<prompt>%</prompt> <userinput><command>kdesrc-build</command> <option>--resume-after=<replaceable>kdebase</replaceable></option></userinput>
-</screen>
-</informalexample>
-
-<para>If the last &kdesrc-build; build ended with a build failure, you can also
-use the <link linkend="cmdline-resume">--resume</link> command line option,
-which resumes the last build starting at the module that failed. The source and
-metadata updates are skipped as well (but if you need these, it's generally
-better to use <link linkend="cmdline-resume-from">--resume-from</link>
-instead).</para>
-
-
-</sect3>
-
-<sect3 id="ignoring-modules">
-<title>Ignoring modules in a build</title>
-
-<para>Similar to the way you can <link linkend="resuming-failed">resume the
-build from a module</link>, you can instead choose to update and build everything
-normally, but ignore a set of modules.</para>
-
-<para>You can do this using the &cmd-ignore-modules; option. This option tells
-&kdesrc-build; to ignore all the modules on the command line when
-performing the update and build.</para>
-
-<informalexample>
-<para>Ignoring extragear/multimedia and kdereview during a full run:</para>
-<screen>
-<prompt>%</prompt> <userinput><command>kdesrc-build</command> <option>--ignore-modules</option> <replaceable>extragear/multimedia kdereview</replaceable></userinput>
-</screen>
-</informalexample>
-
-</sect3>
-</sect2>
-
-<sect2 id="changing-env-from-cmd-line">
-<title>Changing options from the command line</title>
-
-<sect3 id="changing-global-opts">
-<title>Changing global options</title>
-<para>You can change the setting of options read from the <link linkend="configure-data">configuration file</link> directly
-from the command line. This change will override the configuration file
-setting, but is only temporary. It only takes effect as long as it is still
-present on the command line.</para>
-
-<para>&kdesrc-build; allows you to change options named like <replaceable>option-name</replaceable>
-by passing an argument on the command line in the form <userinput><option>--<replaceable>option-name</replaceable>=value</option></userinput>.
-&kdesrc-build; will recognize whether it does not know what the option is, and search
-for the name in its list of option names. If it does not recognize the name, it
-will warn you, otherwise it will remember the value you set it to and override
-any setting from the configuration file.</para>
-
-<informalexample>
-<para>Setting the &source-dir; option to <filename>/dev/null</filename> for
-testing:</para>
-
-<screen>
-<prompt>%</prompt> <userinput><command>kdesrc-build</command> <option>--pretend</option> <option>--<replaceable>source-dir</replaceable>=<replaceable>/dev/null</replaceable></option></userinput>
-</screen>
-
-</informalexample>
-
-</sect3>
-
-<sect3 id="changing-module-opts">
-<title>Changing module options</title>
-<para>It is also possible to change options only for a specific module. The
-syntax is similar: --<replaceable>module</replaceable>,<replaceable>option-name</replaceable>=<replaceable>value</replaceable>.
-</para>
-
-<para>This change overrides any duplicate setting for the module found in the
-<link linkend="configure-data">configuration file</link>, and applies only while the option is passed on the command line.</para>
-
-<informalexample>
-<para>Using a different build directory for the kdeedu module:</para>
-
-<screen>
-<prompt>%</prompt> <userinput><command>kdesrc-build</command> <option>--<replaceable>kdeedu</replaceable>,<replaceable>build-dir</replaceable>=<replaceable>temp-build</replaceable></option></userinput>
-</screen>
-
-</informalexample>
-
-</sect3>
-
-</sect2>
-
-</sect1>
+&advanced-features;
 
 <sect1 id="developer-features">
 <title>Features for &kde; developers</title>