[sdk/kdesrc-build/docbook_historied_per_file] doc: Add --resume (and --stop-on-failure) command line options.

[Michael Pyne]

Git commit 09b14a79b4c3223731b3b7f040da61795b5ef9bf by Michael Pyne.
Committed on 16/03/2014 at 03:15.
Pushed by ashark into branch 'docbook_historied_per_file'.

Add --resume (and --stop-on-failure) command line options.

Now you don't have to do --stop-on-failure=1.

--resume is documented in the man page and docbook, but basically lets
you resume the last build list quickly without source or metadata
updates, starting from the module that failed. If you want to skip the
failed module, look into --resume-after and --stop-before.

BUG:331941
FIXED-IN:1.16

Original commit: 72229099
https://invent.kde.org/sdk/kdesrc-build/-/commit/7222909901afcf1a2f1f395714e6ed0ac46020f6

M  +40   -0    doc/cmdline/supported-cmdline-params.docbook
M  +8    -0    doc/using-kdesrc-build/advanced-features.docbook

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

diff --git a/doc/cmdline/supported-cmdline-params.docbook b/doc/cmdline/supported-cmdline-params.docbook
index b838a4ca..3e85994f 100644
--- a/doc/cmdline/supported-cmdline-params.docbook
+++ b/doc/cmdline/supported-cmdline-params.docbook
@@ -274,6 +274,33 @@ yourself, and want &kdesrc-build; to start again with the next
 module.</para></listitem>
 </varlistentry>
 
+<varlistentry id="cmdline-resume">
+<term><parameter>--resume</parameter></term>
+<listitem><para>
+
+This option can be used to run &kdesrc-build; after it has had a build failure.
+</para><para>
+
+It resumes the build from the module that failed, using the list of modules
+that were waiting to be built before, and disables source and metadata updates
+as well. The use case is when a simple mistake or missing dependency causes the
+build failure. Once you correct the error you can quickly get back into
+building the modules you were building before, without fiddling with
+<option><link linkend="cmdline-resume-from">--resume-from</link></option> and
+<option><link linkend="cmdline-stop-before">--stop-before</link></option>.
+
+</para><para>
+This is even handier with the <option><link
+linkend="cmdline-stop-on-failure">--stop-on-failure</link></option> command
+line argument, especially if you're initially setting up your development
+environment.
+
+</para><para>
+This option was added with &kdesrc-build; 1.16.
+
+</para></listitem>
+</varlistentry>
+
 <varlistentry id="cmdline-stop-before">
 <term><parameter>--stop-before</parameter></term>
 <listitem><para>
@@ -304,6 +331,19 @@ This command line option was added with &kdesrc-build; 1.16.
 </para></listitem>
 </varlistentry>
 
+<varlistentry id="cmdline-stop-on-failure">
+<term><parameter>--stop-on-failure</parameter></term>
+<listitem><para>
+This option causes the build to abort as soon as a failure occurs. Useful when
+you're setting up your initial development environment. Without this flag,
+&kdesrc-build; will try to press on with the rest of the modules in the build
+to avoid wasting time in case the problem is with a single module.
+</para><para>
+This option was added with &kdesrc-build; 1.16. See also the
+<link linkend="conf-stop-on-failure">stop-on-failure</link> option.
+</para></listitem>
+</varlistentry>
+
 <varlistentry id="cmdline-rc-file">
 <term><parameter>--rc-file</parameter></term>
 <listitem><para>
diff --git a/doc/using-kdesrc-build/advanced-features.docbook b/doc/using-kdesrc-build/advanced-features.docbook
index a2068400..62a2b38b 100644
--- a/doc/using-kdesrc-build/advanced-features.docbook
+++ b/doc/using-kdesrc-build/advanced-features.docbook
@@ -349,6 +349,14 @@ the issue and installed the module yourself):</para>
 </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">