[sdk/kdesrc-build/docbook_historied_per_file] doc/kdesrc-buildrc: Support phase selection individually for modules and module-sets

[Andrew Shark]

Git commit 68dbc8f847165e08fcd7559df8eefd7971d8a68b by Andrew Shark.
Committed on 28/01/2024 at 21:24.
Pushed by ashark into branch 'docbook_historied_per_file'.

Support phase selection individually for modules and module-sets

Previously we could only select phases globally from command line. They were applied to all modules.

Sometimes user want to control phase selection for individual module.

The clone is happening from the remote/origin by default. This becomes a problem when user is working with a local branch that is not presented in remote. For example, user may not have a developer account, or just does not want to upload his work even in work/user branch yet.

He just wants kdesrc-build to not touch the sources of that module (while the other modules still be updated), and does not want to exclude module from build phase.

Let's say user wants to work with `kio`, and testing it with `ark`.
Previously, user could achieve this task by running `kdesrc-build` several times. Different quirks were needed. Example:
- `kdesrc-build ark --include-dependencies` - build ark with dependencies (including kio) as normal
- `...` - make changes to the kio project
- `kdesrc-build kio --no-src --no-include-dependencies`
- `kdesrc-build ark --include-dependencies --ignore-modules kio`

After this commit user can specify the `no-src` option for the `kio` module, and then just run `kdesrc-build ark --include-dependencies`. The `kio` will not be updated in this process, but will not be excluded from build phase.

BUG: 354796

Original commit: d8104fa8
https://invent.kde.org/sdk/kdesrc-build/-/commit/d8104fa8e9defa5b25f7eab538a7b0f2fc652e1d

M  +88   -14   doc/kdesrc-buildrc/conf-options-table.docbook

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

diff --git a/doc/kdesrc-buildrc/conf-options-table.docbook b/doc/kdesrc-buildrc/conf-options-table.docbook
index ed52e6bc..63adbf01 100644
--- a/doc/kdesrc-buildrc/conf-options-table.docbook
+++ b/doc/kdesrc-buildrc/conf-options-table.docbook
@@ -1038,20 +1038,6 @@ end options
 </entry>
 </row>
 
-<row id="conf-no-src">
-<entry><link linkend="conf-no-src">no-src</link></entry>
-<entry>
-<simplelist type='horiz' columns='2'>
-<member>Type</member><member>Boolean</member>
-<member>Default value</member><member>False</member>
-</simplelist>
-<para>If this option is set to true then &kdesrc-build; will not update the
-source code for the module automatically. It will still try to build the
-module if it normally would have tried anyways.</para>
-<para>Related command-line option: <xref linkend="cmdline-no-src"/></para>
-</entry>
-</row>
-
 <row id="conf-override-build-system">
 <entry><link linkend="conf-override-build-system">override-build-system</link></entry>
 <entry>
@@ -1314,6 +1300,94 @@ installations. However this only works on build systems that support
 </tgroup>
 </table>
 
+<table id="options-phase-selection-table">
+<para>These options do not require any value (except "filter-out-phases"). They are applied if they are presented in a section.</para>
+<title>Phase selection options</title>
+<tgroup cols="2">
+
+<thead>
+<row>
+<entry>Option name</entry>
+<entry>Scope</entry>
+<entry>Description</entry>
+</row>
+</thead>
+<tbody>
+
+<row id="conf-no-src">
+<entry><link linkend="conf-no-src">no-src</link></entry>
+<entry><simplelist type='vert'><member>global</member><member>module</member><member>module-set</member><member>options</member></simplelist></entry>
+<entry>
+<para>Remove <emphasis>update</emphasis> phase. The other phases that were presented will still be processed.</para>
+<para>Related command-line option: <xref linkend="cmdline-no-src"/></para>
+</entry>
+</row>
+
+<row id="conf-no-install">
+<entry><link linkend="conf-no-install">no-install</link></entry>
+<entry><simplelist type='vert'><member>global</member><member>module</member><member>module-set</member><member>options</member></simplelist></entry>
+<entry>
+<para>Remove <emphasis>install</emphasis> phase. The other phases that were presented will still be processed.</para>
+<para>Related command-line option: <xref linkend="cmdline-no-install"/></para>
+</entry>
+</row>
+
+<row id="conf-no-tests">
+<entry><link linkend="conf-no-tests">no-tests</link></entry>
+<entry><simplelist type='vert'><member>global</member><member>module</member><member>module-set</member><member>options</member></simplelist></entry>
+<entry>
+<para>Remove <emphasis>test</emphasis> phase. The other phases that were presented will still be processed.</para>
+<para>Related command-line option: --no-tests</para>
+</entry>
+</row>
+
+<row id="conf-no-build">
+<entry><link linkend="conf-no-build">no-build</link></entry>
+<entry><simplelist type='vert'><member>global</member><member>module</member><member>module-set</member><member>options</member></simplelist></entry>
+<entry>
+<para>Remove <emphasis>build</emphasis> phase. The other phases that were presented will still be processed.</para>
+<para>Related command-line option: <xref linkend="cmdline-no-build"/></para>
+</entry>
+</row>
+
+<row id="conf-build-only">
+<entry><link linkend="conf-build-only">build-only</link></entry>
+<entry><simplelist type='vert'><member>global</member><member>module</member><member>module-set</member><member>options</member></simplelist></entry>
+<entry>
+<para>If had <emphasis>build</emphasis> phase, remove any other phases. Otherwise, remove all phases.</para>
+<para>Related command-line option: <xref linkend="cmdline-build-only"/></para>
+</entry>
+</row>
+
+<row id="conf-install-only">
+<entry><link linkend="conf-install-only">install-only</link></entry>
+<entry><simplelist type='vert'><member>global</member><member>module</member><member>module-set</member><member>options</member></simplelist></entry>
+<entry>
+<para>If had <emphasis>install</emphasis> phase, remove any other phases. Otherwise, remove all phases.</para>
+<para>Related command-line option: <xref linkend="cmdline-install-only"/></para>
+</entry>
+</row>
+
+<row id="conf-uninstall">
+<entry><link linkend="conf-uninstall">uninstall</link></entry>
+<entry><simplelist type='vert'><member>global</member><member>module</member><member>module-set</member><member>options</member></simplelist></entry>
+<entry>
+<para>If had <emphasis>uninstall</emphasis> phase, remove any other phases. Otherwise, remove all phases.</para>
+<para>Related command-line option: --uninstall</para>
+</entry>
+</row>
+
+<row id="conf-filter-out-phases">
+<entry><link linkend="conf-filter-out-phases">filter-out-phases</link></entry>
+<entry><simplelist type='vert'><member>global</member><member>module</member><member>module-set</member><member>options</member></simplelist></entry>
+<entry>
+<para>Remove those phases that are listed (space separated) in this option. The other phases that were presented will still be processed.</para>
+</entry>
+</row>
+
+</tbody>
+</tgroup>
+</table>
 
 <table id="options-module-set-table">
 <title>Module-set and global scope options</title>