Make picker, thread and combine standard config helper functions

Document them as well

Reviewed-by: Andy Polyakov <appro@openssl.org>

4 files changed, 52 insertions, 32 deletions

diff --git a/Configurations/10-main.conf b/Configurations/10-main.conf
index 5a3a5faa93..87160968ca 100644
--- a/Configurations/10-main.conf
+++ b/Configurations/10-main.conf
@@ -1,22 +1,6 @@
 ## -*- mode: perl; -*-
 ## Standard openssl configuration targets.
 
-sub picker {
-    my %opts = @_;
-    return sub { add($opts{default} || (),
-                     $opts{$config{build_type}} || ())->(); }
-}
-
-sub threads {
-    my @flags = @_;
-    return sub { add($disabled{threads} ? () : @flags)->(); }
-}
-
-sub combine {
-    my @stuff = @_;
-    return sub { add(@stuff)->(); }
-}
-
 # Helper functions for the Windows configs
 my $vc_win64a_info = {};
 sub vc_win64a_info {
diff --git a/Configurations/90-team.conf b/Configurations/90-team.conf
index c7f287fb23..92f8422454 100644
--- a/Configurations/90-team.conf
+++ b/Configurations/90-team.conf
@@ -1,16 +1,6 @@
 ## -*- mode: perl; -*-
 ## Build configuration targets for openssl-team members
 
-sub threads {
-    my @flags = @_;
-    return sub { add($disabled{threads} ? () : @flags)->(); }
-}
-
-sub combine {
-    my @stuff = @_;
-    return sub { add(@stuff)->(); }
-}
-
 %targets = (
     "purify" => {
         cc               => "purify gcc",
diff --git a/Configurations/99-personal-levitte.conf b/Configurations/99-personal-levitte.conf
index d1ddf2ef54..c67252b510 100644
--- a/Configurations/99-personal-levitte.conf
+++ b/Configurations/99-personal-levitte.conf
@@ -1,12 +1,6 @@
 ## -*- mode: perl; -*-
 ## Personal configuration targets
 
-sub picker {
-    my %opts = @_;
-    return sub { add($opts{default} || (),
-                     $opts{$config{build_type}} || ())->(); }
-}
-
 %targets = (
     "levitte-linux-elf" => {
         inherit_from     => [ "linux-elf" ],
diff --git a/Configure b/Configure
index 4145e39878..060df7399b 100755
--- a/Configure
+++ b/Configure
@@ -1961,6 +1961,11 @@ exit(0);
 
 # Configuration file reading #########################################
 
+# Note: All of the helper functions are for lazy evaluation.  They all
+# return a CODE ref, which will return the intended value when evaluated.
+# Thus, whenever there's mention of a returned value, it's about that
+# intended value.
+
 # Helper function to implement conditional inheritance depending on the
 # value of $disabled{asm}.  Used in inherit_from values as follows:
 #
@@ -1973,6 +1978,53 @@ sub asm {
     }
 }
 
+# Helper function to implement conditional value variants, with a default
+# plus additional values based on the value of $config{build_type}.
+# Arguments are given in hash table form:
+#
+#       picker(default => "Basic string: ",
+#              debug   => "debug",
+#              release => "release")
+#
+# When configuring with --debug, the resulting string will be
+# "Basic string: debug", and when not, it will be "Basic string: release"
+#
+# This can be used to create variants of sets of flags according to the
+# build type:
+#
+#       cflags => picker(default => "-Wall",
+#                        debug   => "-g -O0",
+#                        release => "-O3")
+#
+sub picker {
+    my %opts = @_;
+    return sub { add($opts{default} || (),
+                     $opts{$config{build_type}} || ())->(); }
+}
+
+# Helper function to combine several values of different types into one.
+# This is useful if you want to combine a string with the result of a
+# lazy function, such as:
+#
+#       cflags => combine("-Wall", sub { $disabled{zlib} ? () : "-DZLIB" })
+#
+sub combine {
+    my @stuff = @_;
+    return sub { add(@stuff)->(); }
+}
+
+# Helper function to implement conditional values depending on the value
+# of $disabled{threads}.  Can be used as follows:
+#
+#       cflags => combine("-Wall", threads("-pthread"))
+#
+sub threads {
+    my @flags = @_;
+    return sub { add($disabled{threads} ? () : @flags)->(); }
+}
+
+
+
 our $add_called = 0;
 # Helper function to implement adding values to already existing configuration
 # values.  It handles elements that are ARRAYs, CODEs and scalars