[sdk/kdesrc-build/docbook_historied_per_file] doc: Some fixes to make the "skipping build" feature hopefully more useful:

[Michael Pyne]

Git commit 9aee3f12a3aaded1d016426bad966bfd41712683 by Michael Pyne.
Committed on 28/08/2010 at 02:28.
Pushed by ashark into branch 'docbook_historied_per_file'.

Some fixes to make the "skipping build" feature hopefully more useful:

* It is now controlled by an option 'build-when-unchanged' which defaults to true,
  so the optimization must now be explicitly enabled.
* The build is only skipped if the module was successfully installed (as determined
  by the persistent data recorded last run).
* A command-line option, --force-build is added, along with
  --no-build-when-unchanged to be symmetric with the rc-file option.

The new command line option and rc-file option are also documented and added to the
Kate/Kwrite syntax highlighting file.

BUG:248826
FIXED-IN:1.12.1

svn path=/trunk/KDE/kdesdk/doc/scripts/kdesrc-build/; revision=1168981

Original commit: 142c7911
https://invent.kde.org/sdk/kdesrc-build/-/commit/142c791111caa8b2473fd93cfe2af2a905b7fbf2

M  +15   -0    doc/cmdline/supported-cmdline-params.docbook
M  +26   -0    doc/kdesrc-buildrc/conf-options-table.docbook

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

diff --git a/doc/cmdline/supported-cmdline-params.docbook b/doc/cmdline/supported-cmdline-params.docbook
index 84096a9a..3e64fdc3 100644
--- a/doc/cmdline/supported-cmdline-params.docbook
+++ b/doc/cmdline/supported-cmdline-params.docbook
@@ -158,6 +158,21 @@ Do not automatically install packages after they are built.
 </para></listitem>
 </varlistentry>
 
+<varlistentry id="cmdline-no-build-when-unchanged">
+<term><parameter>--no-build-when-unchanged</parameter></term>
+<term><parameter>--force-build</parameter></term>
+<listitem><para>
+This option explicitly disables skipping the build process (an optimization
+controlled by the <link
+linkend="conf-build-when-unchanged">build-when-unchanged</link> option. This is
+useful for making &kdesrc-build; run the build when you have changed something
+that &kdesrc-build; cannot check.</para>
+
+<para><parameter>--force-build</parameter> performs the exact same function, and
+is perhaps easier to remember.</para>
+</listitem>
+</varlistentry>
+
 <varlistentry id="cmdline-debug">
 <term><parameter>--debug</parameter></term>
 <listitem><para>
diff --git a/doc/kdesrc-buildrc/conf-options-table.docbook b/doc/kdesrc-buildrc/conf-options-table.docbook
index 55b53bb2..fdf70245 100644
--- a/doc/kdesrc-buildrc/conf-options-table.docbook
+++ b/doc/kdesrc-buildrc/conf-options-table.docbook
@@ -124,6 +124,32 @@ Perhaps surprisingly, this option can be changed per module.
 </entry>
 </row>
 
+<row id="conf-build-when-unchanged">
+<entry>build-when-unchanged</entry>
+<entry>Module setting overrides global</entry>
+<entry><para>Use this option in order to control whether &kdesrc-build; always
+tries to build a module that has not had any source code updates.</para>
+
+<para>By setting <option>build-when-unchanged</option> to
+<replaceable>true</replaceable>, &kdesrc-build; always attempts the build phase
+for a module, even if the module did not have any source code updates. This is
+the default setting since it is more likely to lead to a correct
+build.</para>
+
+<para>By setting <option>build-when-unchanged</option> to
+<replaceable>false</replaceable>, &kdesrc-build; will only attempt to run the
+build phase for a module if the module has a source code update, or in other
+situations where it is likely that a rebuild is actually required. This can save
+time, especially if you run &kdesrc-build; daily, or more frequently.</para>
+
+<important><para>This feature is provided as an optimization only. Like many
+other optimizations, there are trade-offs for the correctness of your
+installation. For instance, changes to the qt-copy or kdelibs modules may cause
+a rebuild of other modules to be necessary, even if the source code doesn't
+change at all.</para></important>
+</entry>
+</row>
+
 <row id="conf-checkout-only">
 <entry>checkout-only</entry>
 <entry>Module setting overrides global</entry>