[sdk/kdesrc-build/underscore_names] /: Check that all option names read from config are recognised

[Andrew Shark]

Git commit d78948069ac534e936969f25bacdfed5ccffa194 by Andrew Shark.
Committed on 09/01/2024 at 22:08.
Pushed by ashark into branch 'underscore_names'.

Check that all option names read from config are recognised

For every option name read from the config, we will check if it is in `@all_possible_options` array. And if not, raise an exception.

To differentiate between normal config options and non-standard config options (options with custom name defined by user), we will prepend non-standard options with underscore. So users can still use this convenience feature.

Other changes of this commit:
- Allow substituting references to global options when they have underscore in their name.
- Add ability to _use_ custom variable immediately after defining in global section
- Fix end word typo in `t/data/kde-projects/kdesrc-buildrc-with-deps`.
- Temporary show a help message for the recently renamed option "kdedir".

M  +19   -1    doc/kdesrc-buildrc.docbook
M  +18   -6    modules/ksb/Application.pm
M  +2    -2    t/data/branch-time-based/kdesrc-buildrc
M  +1    -1    t/data/kde-projects/kdesrc-buildrc-with-deps

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

diff --git a/doc/kdesrc-buildrc.docbook b/doc/kdesrc-buildrc.docbook
index 53396e46..68cd4d7e 100644
--- a/doc/kdesrc-buildrc.docbook
+++ b/doc/kdesrc-buildrc.docbook
@@ -95,7 +95,7 @@ linkend="conf-use-modules">use-modules</link> for more information.
 <replaceable>option-value</replaceable>.</para>
 
 <para>One modification that &kdesrc-build; performs is that a sequence
-<userinput>${<replaceable>name-of-option</replaceable>}</userinput> is replaced
+"<userinput>${<replaceable>name-of-option</replaceable>}</userinput>" is replaced
 with the value of that option from the global configuration. This allows you
 to reference the value of existing options, including options already set by
 &kdesrc-build;.</para>
@@ -104,6 +104,24 @@ to reference the value of existing options, including options already set by
 To see an example of this in use, see
 <xref linkend="make-options-example"/>.</para>
 
+<para>You can also introduce your own non-standard global variables for referencing them further in the config.
+To do this, your option name should be prepended with underscore symbol. Example:
+<example id="custom-global-option-example">
+<title>Introducing your own global option for referencing later in config</title>
+<programlisting>
+global
+  _ver 6  # ← your custom variable (starting with underscore)
+  _kde ~/kde${_ver}  # ← custom variable can contain another defined variable
+  source-dir ${_kde}/src  # ← note that nested variable (_kde → _ver) is also resolved
+end global
+
+options kdepim
+  log-dir /custom/path/logs${_ver} # ← you can use custom variable just like a standard
+end options
+</programlisting>
+</example>
+</para>
+
 </sect3>
 
 <sect3 id="kdesrc-buildrc-options-groups">
diff --git a/modules/ksb/Application.pm b/modules/ksb/Application.pm
index 26cf9ec2..2a99c248 100644
--- a/modules/ksb/Application.pm
+++ b/modules/ksb/Application.pm
@@ -805,18 +805,18 @@ sub _readNextLogicalLine
 
 # Takes an input line, and extracts it into an option name, and simplified
 # value. The value has "false" converted to 0, white space simplified (like in
-# Qt), and tildes (~) in what appear to be path-like entries are converted to
-# the home directory path.
+# Qt), tildes (~) in what appear to be path-like entries are converted to
+# the home directory path, and reference to global option is substituted with its value.
 #
 # First parameter is the build context (used for translating option values).
 # Second parameter is the line to split.
 # Return value is (option-name, option-value)
-sub _splitOptionAndValue
+sub _splitOptionAndValue_and_substitute_value
 {
     my $ctx = assert_isa(shift, 'ksb::BuildContext');
     my $input = shift;
     my $fileName = shift->currentFilename();
-    my $optionRE = qr/\$\{([a-zA-Z0-9-]+)\}/;
+    my $optionRE = qr/\$\{([a-zA-Z0-9-_]+)\}/;  # Example of matched string is "${option-name}" or "${_option-name}".
 
     # The option is the first word, followed by the
     # flags on the rest of the line.  The interpretation
@@ -836,7 +836,6 @@ sub _splitOptionAndValue
     $value = 0 if lc($value) eq 'false';
 
     # Replace reference to global option with their value.
-    # The regex basically just matches ${option-name}.
     my ($sub_var_name) = ($value =~ $optionRE);
     while ($sub_var_name)
     {
@@ -936,6 +935,8 @@ sub _parseModuleOptions ($ctx, $fileReader, $module, $endRE=undef)
     _markModuleSource($module, $fileReader->currentFilename() . ":$.");
     $module->setOption('#entry_num', $moduleID++);
 
+    my @all_possible_options = sort keys %{$ctx->{build_options}->{global}};
+
     # Read in each option
     while (($_ = _readNextLogicalLine($fileReader)) && ($_ !~ $endRE))
     {
@@ -949,7 +950,18 @@ sub _parseModuleOptions ($ctx, $fileReader, $module, $endRE=undef)
             die make_exception('Config', "Invalid file $current_file");
         }
 
-        my ($option, $value) = _splitOptionAndValue($ctx, $_, $fileReader);
+        my ($option, $value) = _splitOptionAndValue_and_substitute_value($ctx, $_, $fileReader);
+
+
+        if (substr($option, 0, 1) eq "_") {  # option names starting with underscore are treated as user custom variables
+            $ctx->setOption($option, $value);  # merge the option to the build context right now, so we could already (while parsing global section) use this variable in other global options values.
+        }
+        elsif (!grep {$_ eq $option} @all_possible_options) {
+            if ($option eq "kdedir") {  # todo This message is temporary. Remove it after 09.04.2024.
+                error "r[Please edit your config. Replace \"b[kdedir]r[\" with \"b[install-dir]r[\".";
+            }
+            die ksb::BuildException::Config->new($option, "Unrecognized option \"$option\" found at $current_file:$.");
+        }
 
         eval { $module->setOption($option, $value); };
         if (my $err = $@) {
diff --git a/t/data/branch-time-based/kdesrc-buildrc b/t/data/branch-time-based/kdesrc-buildrc
index deb945f9..e0324af7 100644
--- a/t/data/branch-time-based/kdesrc-buildrc
+++ b/t/data/branch-time-based/kdesrc-buildrc
@@ -1,11 +1,11 @@
 global
     source-dir /tmp
     git-repository-base kde kde:
-    bisect-tag master@{3 weeks ago}
+    _bisect-tag master@{3 weeks ago}
 end global
 
 module-set pim
     repository kde
     use-modules kdepim kdepim-runtime akonadi
-    revision ${bisect-tag}
+    revision ${_bisect-tag}
 end module-set
diff --git a/t/data/kde-projects/kdesrc-buildrc-with-deps b/t/data/kde-projects/kdesrc-buildrc-with-deps
index dd190939..c014c4de 100644
--- a/t/data/kde-projects/kdesrc-buildrc-with-deps
+++ b/t/data/kde-projects/kdesrc-buildrc-with-deps
@@ -41,4 +41,4 @@ module-set workspace-stuff
     repository kde-projects
     use-modules kdesrc-build
     cmake-options -DSET_FOO:BOOL=ON
-end-module-set
+end module-set