[kde-doc-english] [kdesrc-build] /: rc-file: Add specific "option override" entry type.
Michael Pyne
mpyne at kde.org
Sat Jan 11 21:09:16 UTC 2014
Git commit 38ea997502e18313e6fe0f7120dee9ed8544bd82 by Michael Pyne.
Committed on 11/01/2014 at 20:28.
Pushed by mpyne into branch 'master'.
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
M +67 -1 doc/index.docbook
M +30 -20 modules/ksb/Application.pm
http://commits.kde.org/kdesrc-build/38ea997502e18313e6fe0f7120dee9ed8544bd82
diff --git a/doc/index.docbook b/doc/index.docbook
index 702590e..473415b 100644
--- a/doc/index.docbook
+++ b/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">
diff --git a/modules/ksb/Application.pm b/modules/ksb/Application.pm
index f10cce5..58f6092 100644
--- a/modules/ksb/Application.pm
+++ b/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?
- elsif (exists $seenModuleSetItems{$modulename}) {
+ # Duplicate module entry? (Note, this must be checked before the check
+ # 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
- }
- # Duplicate module entry?
- elsif (exists $seenModules{$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};
+ # TODO: Remove compat handling of 'module $foo' as 'options $foo',
+ # probably 2014-04-01?
+ if ($type ne 'options') {
+ warning ("Don't use b[r[module $modulename] on line $., use b[g[options $modulename]");
+ }
- next; # Skip all the stuff below
+ next; # Don't add to module list
}
else {
$newModule = _parseModuleOptions($ctx, $fileReader, $modulename);
More information about the kde-doc-english
mailing list