Git commit 7a781d2cb74cf7876ce96654dd4013347ee6c71a by Michael Pyne. Committed on 14/07/2022 at 04:11. Pushed by ashark into branch 'docbook_historied_per_file'.
Support SIGHUP for graceful script exit. This helps if a user started a long build without --stop-on-failure and needs it to stop without risking interrupting kdesrc-build during an install step. Fixes #96. Original commit: e5a9295b https://invent.kde.org/sdk/kdesrc-build/-/commit/e5a9295bccf07ed0ca9d9729b7ca72ec193f5a2d M +1 -1 doc/index.docbook M +96 -0 doc/using-kdesrc-build/advanced-features.docbook https://invent.kde.org/sdk/kdesrc-build/-/commit/7a781d2cb74cf7876ce96654dd4013347ee6c71a diff --git a/doc/index.docbook b/doc/index.docbook index 8f17fd5e..73310e92 100644 --- a/doc/index.docbook +++ b/doc/index.docbook @@ -2,7 +2,7 @@ <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [ <!-- Documentation for kdesrc-build. - Copyright (c) 2005-2008, 2010-2020 Michael Pyne <[email protected]> + Copyright (c) 2005-2008, 2010-2022 Michael Pyne <[email protected]> Copyright (c) 2005 Carlos Leonhard Woelz <[email protected]> Copyright (c) 2009 Burkhard Lück <[email protected]> diff --git a/doc/using-kdesrc-build/advanced-features.docbook b/doc/using-kdesrc-build/advanced-features.docbook index 6c41cc2e..0e4d568f 100644 --- a/doc/using-kdesrc-build/advanced-features.docbook +++ b/doc/using-kdesrc-build/advanced-features.docbook @@ -175,6 +175,102 @@ as well. </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>Stopping early with --stop-on-failure</title> + +<para> +The primary method to do this is to use the +<link linkend="cmdline-stop-on-failure">--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; early without --stop-on-failure</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>
