[kde-doc-english] [kdesrc-build] /: Add and document --rebuild-failures command line option.

[Michael Pyne]

Git commit 51c3a7ec543aedc87b685f88fd6b5fbeac5ea350 by Michael Pyne.
Committed on 26/08/2015 at 20:53.
Pushed by mpyne into branch 'master'.

Add and document --rebuild-failures command line option.

M  +18   -0    doc/index.docbook
M  +23   -0    doc/man-kdesrc-build.1.docbook
M  +23   -1    modules/ksb/Application.pm

http://commits.kde.org/kdesrc-build/51c3a7ec543aedc87b685f88fd6b5fbeac5ea350

diff --git a/doc/index.docbook b/doc/index.docbook
index 00b4644..6e647ec 100644
--- a/doc/index.docbook
+++ b/doc/index.docbook
@@ -2877,6 +2877,24 @@ linkend="cmdline-pretend">--pretend</link></option> command line option to work.
 </para></listitem>
 </varlistentry>
 
+<varlistentry id="cmdline-rebuild-failures">
+<term><parameter>--rebuild-failures</parameter></term>
+<listitem><para>
+Use this option to build only those modules which failed to build on a previous
+&kdesrc-build; run. This is useful if a significant number of failures occurred mixed with
+successful builds. After fixing the issue causing the build failures you can then easily
+build only the modules that failed previously.</para>
+
+<note><para>Note that the list of <quote>previously-failed modules</quote> is
+reset every time a &kdesrc-build; run finishes with some module failures.
+However it is not reset by a completely successful build, so you can
+successfully rebuild a module or two and this flag will still
+work.</para></note>
+
+<para>This option was added for &kdesrc-build; 15.09.</para>
+</listitem>
+</varlistentry>
+
 <varlistentry id="cmdline-ignore-modules">
 <term><parameter>--ignore-modules</parameter></term>
 <listitem><para>
diff --git a/doc/man-kdesrc-build.1.docbook b/doc/man-kdesrc-build.1.docbook
index c02635f..2813876 100644
--- a/doc/man-kdesrc-build.1.docbook
+++ b/doc/man-kdesrc-build.1.docbook
@@ -456,6 +456,29 @@ combining short options into one at this point. (E.g. running
 
 <varlistentry>
 <term>
+<option>--rebuild-failures</option>
+</term>
+
+<listitem>
+<para>
+    Use this option to build only those modules which failed to build on a
+    previous <command>kdesrc-build</command> run. This is useful if a
+    significant number of failures occurred mixed with successful builds. After
+    fixing the issue causing the build failures you can then easily build only
+    the modules that failed previously.</para>
+
+    <para>Note that the list of <quote>previously-failed modules</quote> is
+    reset every time a <command>kdesrc-build</command> run finishes with some
+    module failures.  However it is not reset by a completely successful build,
+    so you can successfully rebuild a module or two and this flag will still
+    work.</para>
+
+    <para>This option was added for kdesrc-build 15.09.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
 <option>--stop-on-failure</option>
 </term>
 
diff --git a/modules/ksb/Application.pm b/modules/ksb/Application.pm
index 8718d6c..89f0105 100644
--- a/modules/ksb/Application.pm
+++ b/modules/ksb/Application.pm
@@ -278,7 +278,7 @@ DONE
         'print-modules', 'pretend|dry-run|p', 'refresh-build',
         'start-program|run=s{,}',
         'revision=i', 'resume-from=s', 'resume-after=s',
-        'resume', 'stop-on-failure',
+        'rebuild-failures', 'resume', 'stop-on-failure',
         'stop-after=s', 'stop-before=s', 'set-module-option-value=s',
         'metadata-only', 'include-dependencies',
 
@@ -367,6 +367,17 @@ sub generateModuleList
         unshift @selectors, split(/,\s*/, $moduleList);
     }
 
+    if (exists $pendingGlobalOptions->{'rebuild-failures'}) {
+        my $moduleList = $ctx->getPersistentOption('global', 'last-failed-module-list');
+        if (!$moduleList) {
+            error ("b[y[--rebuild-failures] was specified, but unable to determine");
+            error ("which modules have previously failed to build.");
+            croak_runtime("Invalid --rebuild-failures flag");
+        }
+
+        unshift @selectors, split(/,\s*/, $moduleList);
+    }
+
     # _readConfigurationOptions will add pending global opts to ctx while ensuring
     # returned modules/sets have any such options stripped out. It will also add
     # module-specific options to any returned modules/sets.
@@ -627,6 +638,17 @@ sub runAllModulePhases
 
     _cleanup_log_directory($ctx) if $ctx->getOption('purge-old-logs');
     _output_failed_module_lists($ctx);
+
+    # Record all failed modules. Unlike the 'resume-list' option this doesn't
+    # include any successfully-built modules in between failures.
+    my $failedModules = join(',', map { "$_" } $ctx->listFailedModules());
+    if ($failedModules) {
+        # We don't clear the list of failed modules on success so that
+        # someone can build one or two modules and still use
+        # --rebuild-failures
+        $ctx->setPersistentOption('global', 'last-failed-module-list', $failedModules);
+    }
+
     _installCustomSessionDriver($ctx) if $ctx->getOption('install-session-driver');
 
     my $color = 'g[b[';