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

doc/index.docbook

@@ -1335,7 +1335,8 @@ but is instead at the &konsole; or terminal where you ran &kdesrc-build;.</para>
 <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">
@@ -1414,6 +1415,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">

modules/ksb/Application.pm

@@ -879,7 +879,7 @@ sub _parseModuleOptions
     }
 
     my $endWord = $module->isa('ksb::BuildContext') ? 'global' : 'module';
-    my $endRE = qr/^end\s+$endWord/;
+    my $endRE = qr/^end[\w\s]*$/;
 
     # Read in each option
     while ($_ = _readNextLogicalLine($fileReader))
@@ -1090,7 +1090,7 @@ sub _readConfigurationOptions
     my $pendingOptionsRef = shift;
     my @module_list;
     my $rcfile = $ctx->rcFile();
-    my ($option, $modulename, %readModules);
+    my ($option, %readModules);
 
     my $fileReader = ksb::RecursiveFH->new();
     $fileReader->pushBasePath(dirname($rcfile)); # rcfile should already be absolute
@@ -1134,7 +1134,7 @@ sub _readConfigurationOptions
         next if (/^\s*$/); # Skip blank lines
 
         # Get modulename (has dash, dots, slashes, or letters/numbers)
-        ($modulename) = /^module\s+([-\/\.\w]+)\s*$/;
+        my ($type, $modulename) = /^(options|module)\s+([-\/\.\w]+)\s*$/;
         my $newModule;
 
         # Module-set?
@@ -1157,8 +1157,27 @@ sub _readConfigurationOptions
             my @moduleSetItems = $newModule->moduleNamesToFind();
             @seenModuleSetItems{@moduleSetItems} = ($newModule) x scalar @moduleSetItems;
         }
-        # Module override?
+        # Duplicate module entry? (Note, this must be checked before the check
-        elsif (exists $seenModuleSetItems{$modulename}) {
+        # below for 'options' sets)
+        elsif (exists $seenModules{$modulename}) {
+            # Overwrite options set for existing modules.
+            # But allow duplicate 'options' declarations without error.
+            if ($type ne 'options') {
+                warning ("Don't use b[r[module $modulename] on line $., use b[g[options $modulename]");
+            }
+
+            $newModule = $seenModules{$modulename};
+
+            # _parseModuleOptions will re-use newModule, but we still need to
+            # be careful not to mask cmdline options in pendingOptsKeys.
+            _parseModuleOptions($ctx, $fileReader, $newModule);
+
+            delete @{$newModule->{options}}{@pendingOptsKeys};
+
+            next; # Skip all the stuff below
+        }
+        # Module override (for use-modules from a module-set), or option overrride?
+        elsif ($type eq 'options' || exists $seenModuleSetItems{$modulename}) {
             # Parse the modules...
             $newModule = _parseModuleOptions($ctx, $fileReader, "#overlay_$modulename");
 
@@ -1173,22 +1192,13 @@ sub _readConfigurationOptions
             # Don't mask global cmdline options.
             delete @{$moduleOptsRef}{@pendingOptsKeys};
 
-            next; # Don't add to module list
+            # TODO: Remove compat handling of 'module $foo' as 'options $foo',
-        }
+            # probably 2014-04-01?
-        # Duplicate module entry?
+            if ($type ne 'options') {
-        elsif (exists $seenModules{$modulename}) {
+                warning ("Don't use b[r[module $modulename] on line $., use b[g[options $modulename]");
-            # Overwrite options set for existing modules.
+            }
-            warning ("Multiple module declarations for $modulename");
-
-            $newModule = $seenModules{$modulename};
-
-            # _parseModuleOptions will re-use newModule, but we still need to
-            # be careful not to mask cmdline options in pendingOptsKeys.
-            _parseModuleOptions($ctx, $fileReader, $newModule);
-
-            delete @{$newModule->{options}}{@pendingOptsKeys};
 
-            next; # Skip all the stuff below
+            next; # Don't add to module list
         }
         else {
             $newModule = _parseModuleOptions($ctx, $fileReader, $modulename);