CMake: Rename and document the feature evaluation functions

Rename various functions and variables to hopefully make the behavior
of feature evaluation clearer.

The previous names like 'set_value' or 'set_cache_value' or 'cache'
were too generic and unclear. One would have to carefully read the
code to understand what was actually set.

Add some doc comments about what FEATURE_foo and QT_FEATURE_foo
represent.

Amends c4f5762b20dc20bab3cc62e9166d0e5b36e21cc6

Pick-to: 6.2
Task-number: QTBUG-94921
Change-Id: Ie6a7b83a4d54a83976b2706d4af82b39832d79f1
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
Reviewed-by: Joerg Bornemann <joerg.bornemann@qt.io>

1 files changed, 60 insertions, 25 deletions

diff --git a/cmake/QtFeature.cmake b/cmake/QtFeature.cmake
index 747e0e9405..f5712cbc44 100644
--- a/cmake/QtFeature.cmake
+++ b/cmake/QtFeature.cmake
@@ -227,45 +227,54 @@ function(_qt_internal_dump_expression_values expression_dump expression)
     set(${expression_dump} "${${expression_dump}}" PARENT_SCOPE)
 endfunction()
 
-function(qt_feature_set_cache_value resultVar feature condition calculated label)
+# Stores the user provided value to FEATURE_${feature} if provided.
+# If not provided, stores ${computed} instead.
+# ${computed} is also stored when reconfiguring and the condition does not align with the user
+# provided value.
+#
+function(qt_feature_check_and_save_user_provided_value resultVar feature condition computed label)
     if (DEFINED "FEATURE_${feature}")
-        # Revisit value:
-        set(cache "${FEATURE_${feature}}")
+        # Revisit new user provided value
+        set(user_value "${FEATURE_${feature}}")
+        set(result "${user_value}")
 
-        # If the build is marked as dirty and the cache value doesn't meet the new condition,
-        # reset it to the calculated one.
+        # If the build is marked as dirty and the user_value doesn't meet the new condition,
+        # reset it to the computed one.
         get_property(dirty_build GLOBAL PROPERTY _qt_dirty_build)
-        if(NOT condition AND cache AND dirty_build)
-            set(cache "${calculated}")
-            message(WARNING "Reset FEATURE_${feature} value to ${calculated}, because it doesn't \
+        if(NOT condition AND result AND dirty_build)
+            set(result "${computed}")
+            message(WARNING "Reset FEATURE_${feature} value to ${result}, because it doesn't \
 meet its condition after reconfiguration.")
         endif()
 
         set(bool_values OFF NO FALSE N ON YES TRUE Y)
-        if ((cache IN_LIST bool_values) OR (cache GREATER_EQUAL 0))
-            set(result "${cache}")
+        if ((result IN_LIST bool_values) OR (result GREATER_EQUAL 0))
+            # All good!
         else()
-            message(FATAL_ERROR "Sanity check failed: FEATURE_${feature} has invalid value \"${cache}\"!")
+            message(FATAL_ERROR
+                "Sanity check failed: FEATURE_${feature} has invalid value \"${result}\"!")
         endif()
 
         # Fix-up user-provided values
-        set("FEATURE_${feature}" "${cache}" CACHE BOOL "${label}" FORCE)
+        set("FEATURE_${feature}" "${result}" CACHE BOOL "${label}" FORCE)
     else()
         # Initial setup:
-        set("FEATURE_${feature}" "${calculated}" CACHE BOOL "${label}")
-        set(result "${calculated}")
+        set(result "${computed}")
+        set("FEATURE_${feature}" "${result}" CACHE BOOL "${label}")
     endif()
 
     set("${resultVar}" "${result}" PARENT_SCOPE)
 endfunction()
 
-macro(qt_feature_set_value feature cache condition label conditionExpression)
-    set(result "${cache}")
+# Saves the final user value to QT_FEATURE_${feature}, after checking that the condition is met.
+macro(qt_feature_check_and_save_internal_value
+        feature saved_user_value condition label conditionExpression)
+    set(result "${saved_user_value}")
 
-    if (NOT (condition) AND (cache))
+    if ((NOT condition) AND result)
         _qt_internal_dump_expression_values(conditionDump "${conditionExpression}")
         string(JOIN " " conditionString ${conditionExpression})
-        qt_configure_add_report_error("Feature \"${feature}\": Forcing to \"${cache}\" breaks its \
+        qt_configure_add_report_error("Feature \"${feature}\": Forcing to \"${result}\" breaks its \
 condition:\n    ${conditionString}\nCondition values dump:\n    ${conditionDump}\n" RECORD_ON_FEATURE_EVALUATION)
     endif()
 
@@ -279,6 +288,30 @@ condition:\n    ${conditionString}\nCondition values dump:\n    ${conditionDump}
     set(QT_KNOWN_FEATURES "${QT_KNOWN_FEATURES}" CACHE INTERNAL "" FORCE)
 endmacro()
 
+
+# The build system stores 2 CMake cache variables for each feature, to allow detecting value changes
+# during subsequent reconfigurations.
+#
+#
+# `FEATURE_foo` stores the user provided feature value for the current configuration run.
+# It can be set directly by the user, or derived from INPUT_foo (also set by the user).
+#
+# If a value is not provided on initial configuration, the value will be auto-computed based on the
+# various conditions of the feature.
+# TODO: Document the various conditions and how they relate to each other.
+#
+#
+# `QT_FEATURE_foo` stores the value of the feature from the previous configuration run.
+# Its value is updated once with the newest user provided value after some checks are performed.
+#
+# This variable also serves as the main source of truth throughout the build system code to check
+# if the feature is enabled, e.g. if(QT_FEATURE_foo)
+#
+# It is not meant to be set by the user. It is only modified by the build system.
+#
+# Comparing the values of QT_FEATURE_foo and FEATURE_foo, the build system can detect whether
+# the user changed the value for a feature and thus recompute any dependent features.
+#
 function(qt_evaluate_feature feature)
     # If the feature was already evaluated as dependency nothing to do here.
     if(DEFINED "QT_FEATURE_${feature}")
@@ -316,12 +349,12 @@ function(qt_evaluate_feature feature)
     qt_evaluate_config_expression(enable_result ${arg_ENABLE})
     qt_evaluate_config_expression(auto_detect ${arg_AUTODETECT})
     if(${disable_result})
-        set(result OFF)
+        set(computed OFF)
     elseif((${enable_result}) OR (${auto_detect}))
-        set(result ${condition})
+        set(computed ${condition})
     else()
         # feature not auto-detected and not explicitly enabled
-        set(result OFF)
+        set(computed OFF)
     endif()
 
     if("${arg_EMIT_IF}" STREQUAL "")
@@ -347,13 +380,15 @@ function(qt_evaluate_feature feature)
             "Feature ${feature} is insignificant in this configuration, "
             "ignoring related command line option(s).")
         qt_configure_add_report_entry(TYPE WARNING MESSAGE "${msg}")
-        set(result OFF)
+        set(computed OFF)
         set(FEATURE_${feature} OFF)
     endif()
 
-    qt_feature_set_cache_value(cache "${feature}" "${condition}" "${result}" "${arg_LABEL}")
-    qt_feature_set_value("${feature}" "${cache}" "${condition}" "${arg_LABEL}"
-                         "${arg_CONDITION}")
+    qt_feature_check_and_save_user_provided_value(
+        saved_user_value "${feature}" "${condition}" "${computed}" "${arg_LABEL}")
+
+    qt_feature_check_and_save_internal_value(
+        "${feature}" "${saved_user_value}" "${condition}" "${arg_LABEL}" "${arg_CONDITION}")
 
     # Store each feature's label for summary info.
     set(QT_FEATURE_LABEL_${feature} "${arg_LABEL}" CACHE INTERNAL "")