[sdk/kdesrc-build/docbook_historied_per_file] doc/kdesrc-buildrc: rc-file: Add specific "option override" entry type.

[Michael Pyne]

Git commit a825ec00f754dae8edc158f90405fa9b61ad611e by Michael Pyne.
Committed on 11/01/2014 at 21:06.
Pushed by ashark into branch 'docbook_historied_per_file'.

rc-file: Add specific "option override" entry type.

Add a specific config file grouping (which acts just like a module
declaration), to allow for specifying options to override a
previously-declared module.

The use case here is for a module-set: You can specify options which
apply to an entire module-set when declaring the module-set, and then
override those options with any changes in a later "options"
declaration.

These declarations can stack too, so this can also be useful for
multi-level file includes (but this is less useful since an "options"
declaration requires a specific module, it doesn't work on module-sets;
in that case you'd want to have the different module-sets in your
most-specific included config files instead of in a base file).

Tested on my personal test case for bug 321883, and on a --pretend run,
and with a bug 321883 test case modified to not pre-declare the
overridden module first.

Example:
    module-set kde-mm
        repository kde-projects
        use-modules kde/kdemultimedia
    end module-set

    options kmix # Not mentioned before this line
        branch KDE/4.11
    end options

In this case kmix would use KDE/4.11 branch while juk (and the rest of
kde-mm) would use whatever the global branch or branch-group was
(probably 'master').

BUG:321667

Original commit: 38ea9975
https://invent.kde.org/sdk/kdesrc-build/-/commit/38ea997502e18313e6fe0f7120dee9ed8544bd82

M  +67   -1    doc/kdesrc-buildrc/kdesrc-buildrc-overview.docbook

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

diff --git a/doc/kdesrc-buildrc/kdesrc-buildrc-overview.docbook b/doc/kdesrc-buildrc/kdesrc-buildrc-overview.docbook
index 8db8c20f..bfb5d158 100644
--- a/doc/kdesrc-buildrc/kdesrc-buildrc-overview.docbook
+++ b/doc/kdesrc-buildrc/kdesrc-buildrc-overview.docbook
@@ -4,7 +4,8 @@
 <para>
 To use the script, you must have a file in your home directory called
 <filename>.kdesrc-buildrc</filename>, which describes the modules you would
-like to download and build.
+like to download and build, and any options or configuration parameters to
+use for these modules.
 </para>
 
 <sect2 id="kdesrc-buildrc-layout">
@@ -83,6 +84,71 @@ linkend="conf-use-modules">use-modules</link> for more information.
 </para>
 
 </sect3>
+
+<sect3 id="kdesrc-buildrc-options-groups">
+<title><quote>options</quote> modules</title>
+
+<para>There is a final type of configuration file entry,
+<literal>options</literal> groups, which may be given wherever a
+<literal>module</literal> or <literal>module-set</literal> may be used.</para>
+
+<programlisting>
+options <replaceable>module-name</replaceable>
+<replaceable>option-name option-value</replaceable>
+<replaceable>[...]</replaceable>
+end options
+</programlisting>
+
+<para>An <literal>options</literal> group may have options set for it just like
+a module declaration, and is associated with an existing module. Any options
+set these way will be used to <emphasis>override</emphasis> options set for the
+associated module.</para>
+
+<important><para>The associated module name <emphasis>must</emphasis> match the
+name given in the <literal>options</literal> declaration. Be careful of
+mis-typing the name.</para></important>
+
+<para>This is useful to allow for declaring an entire
+<literal>module-set</literal> worth of modules, all using the same options, and
+then using <literal>options</literal> groups to make individual changes.</para>
+
+<example id="ex-options-group">
+<title>Example of using options</title>
+
+<para>In this example we choose to build all modules from the &kde; multimedia
+software grouping. However we want to use a different version of the &kmix;
+application (perhaps for testing a bug fix). It works as follows:</para>
+
+<programlisting>
+module-set <replaceable>kde-multimedia-set</replaceable>
+  repository <userinput>kde-projects</userinput>
+  use-modules <replaceable>kde/kdemultimedia</replaceable>
+  branch <replaceable>master</replaceable>
+end module-set
+
+# kmix is a part of kde/kdemultimedia group, even though we never named
+# kmix earlier in this file, &kdesrc-build; will figure out the change.
+options <replaceable>kmix</replaceable>
+  branch <replaceable>KDE/4.12</replaceable>
+end options
+</programlisting>
+
+<para>Now when you run &kdesrc-build;, all of the &kde; multimedia programs will
+be built from the <quote>master</quote> branch of the source repository, but
+&kmix; will be built from the older <quote>KDE/4.12</quote> branch. By using
+<literal>options</literal> you didn't have to individually list all the
+<emphasis>other</emphasis> &kde; multimedia programs to give them the right
+branch option.</para>
+
+</example>
+
+<note>
+<para>Note that this feature is only available in &kdesrc-build; from version
+1.16, or using the development version of &kdesrc-build; after
+2014-01-12.</para></note>
+
+</sect3>
+
 </sect2>
 
 <sect2 id="kdesrc-buildrc-including">