TRILFRAME-120-A : Handling non-CACHED cmake vars

Author: William McLendon

CHANGELOG.md

@@ -17,9 +17,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 #### Todo (for Unreleased)
 -->
 
-## [0.3.1] <!-- YYYY-MM-DD --> [Unreleased]
+## [0.4.0] <!-- YYYY-MM-DD --> [Unreleased]
 #### Added
 #### Changed
+- TODO: Add notes for !16/!17 // TRILFRAME-120 + TRILFRAME-136
 - Changes to `opt-set-cmake-var` behaviour:
   - Trigger a WARNING if `PARENT_SCOPE` and a _TYPE_ is provided since CMake
     requires TYPED vars to be CACHE vars and `PARENT_SCOPE` will force the

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "setprogramoptions"
-version = "0.3.1"
+version = "0.4.0"
 description = "Program options helper."
 authors = [
     "William McLendon <wcmclen@sandia.gov>"

src/setprogramoptions/SetProgramOptions.py

@@ -109,7 +109,6 @@ class ExpandVarsInText(ExceptionControl):
 
     def __init__(self):
         self.exception_control_level = 4
-        self.exception_control_compact_warnings = True
 
     class VariableFieldData(object):
         """
@@ -526,6 +525,7 @@ def _gen_option_entry(self, option_entry: dict, generator='bash') -> Union[str,
 
                 # Update the var formatter's ECL to match the current value.
                 self._var_formatter.exception_control_level = self.exception_control_level
+                self._var_formatter.exception_control_compact_warnings = self.exception_control_compact_warnings
 
                 # format the value
                 formatter = self._var_formatter

src/setprogramoptions/SetProgramOptionsCMake.py

@@ -20,8 +20,19 @@
 ``-DVAR_NAME:BOOL=ON`` using the ``SetProgramOptions`` method ``gen_option_list``
 with the ``bash`` generator.
 
-In the case of bash command entries the ``PARENT_SCOPE`` optional parameter is
-ignored.
+When using the BASH generator to generate command line arguments, CMake
+uses the syntax ``-D<VARNAME>[:<TYPE>]=<VALUE>``. The ``TYPE`` field is optional
+and if left out CMake will default to a ``STRING`` type. Further, all CMake
+varaibles set via the command line using ``-D`` will be CACHE variables and each
+``-D`` operation should be considered a FORCE operation too. For example,
+``-DFOO:STRING=BAR`` is roughly equivalent to the CMake command:
+``set(FOO CACHE STRING "docstring" FORCE)``.
+
+The ``PARENT_SCOPE`` option applies only to non-cache variables and its presence
+will instruct CMake to make that variable non-cache. Care should be taken when
+using ``PARENT_SCOPE`` as combining it with the usual CACHE operations results
+in CMake creating a non-cached variable whose contents are the list containing
+``<varname>;CACHE;<type>;doc string``.
 
 See CMake documentation on the `set() <https://cmake.org/cmake/help/latest/command/set.html>`_
 command for more information on how fragment file entries are generated.
@@ -73,7 +84,6 @@ class ExpandVarsInTextCMake(ExpandVarsInText):
 
     def __init__(self):
         self.exception_control_level = 3
-        self.exception_control_compact_warnings = True
 
     def _fieldhandler_BASH_CMAKE(self, field):
         """
@@ -183,7 +193,7 @@ def _program_option_handler_opt_set_cmake_fragment(self, params: list, value: st
         """
         return None
 
-    def _program_option_handler_opt_set_cmake_var_bash(self, params, value) -> str:
+    def _program_option_handler_opt_set_cmake_var_bash(self, params: list, value: str) -> str:
         """
         Line-item generator for ``opt-set-cmake-var`` entries when the *generator*
         is set to ``bash``.
@@ -196,30 +206,50 @@ def _program_option_handler_opt_set_cmake_var_bash(self, params, value) -> str:
             side-effects since :py:meth:`setprogramoptions.SetProgramOptions._gen_option_entry`
             performs a deep-copy of these parameters prior to calling this.
             Any changes we make are ephemeral.
+
+        Args:
+            params (list): The parameters of the operation.
+            value (str): The value of the option that is being assigned.
+
+        Raises:
+            ValueError: This can potentially raise a ``ValueError`` if
+                ``exception_control_level`` is set to 5 if there are
+                operations that are skipped in Bash generation. If ``ecl``
+                is less than 5 then warnings are generated to note the
+                exclusion.
         """
         varname = params[0]
         params = params[1 : 4]
         param_opts = self._helper_opt_set_cmake_var_parse_parameters(params)
 
+        # PARENT_SCOPE (i.e., type-1 non-cached operations) should not be
+        # written to the set of Bash parameters.
+        if param_opts['VARIANT'] == 1:
+            msg = f"bash generator - `{varname}={value}` skipped because"
+            msg += f" it is a non-cached (type-1) operation."
+            msg += f" To generate a bash arg for this consider adding FORCE or a TYPE."
+            self.exception_control_event("WARNING", ValueError, message=msg)
+            return None
+
+        # If varname has already been assigned and this assignment
+        # does not include FORCE then we should skip adding it to the
+        # set of command line options.
+        if varname in self._var_formatter_cache and not param_opts['FORCE']:
+            msg = f"bash generator - `{varname}={value}` skipped because"
+            msg += f" CACHE var `{varname}` is already set and CMake requires"
+            msg += f" FORCE to be set to change the value."
+            self.exception_control_event("WARNING", ValueError, message=msg)
+            return None
+
+        # Prepend `-D` to the parameters
         params = ["-D", varname]
 
-        if param_opts['VARIANT'] == 1:
-            # if PARENT_SCOPE was given to something that is typed and forced us to
-            # be a type-1 variant, then we assign the list "<value>;CACHE;<type>;<docstring>"
-            if param_opts['TYPE'] != None:
-                value += f";CACHE;{param_opts['TYPE']};"
-
-        if param_opts['VARIANT'] == 2 and param_opts['TYPE'] is not None:
-            params.append(":" + param_opts['TYPE'])
-
-        # Cache 'known' CMake vars here.
-        try:
-            if self._var_formatter_cache[varname] is not None and not param_opts['FORCE']:
-                # Do not add this to the output unless it's a forceful set
-                return None
-        except:
-            pass
+        # If the type is provided then include the `:<typename>` argument.
+        # Note: CMake defaults to STRING if not provided.
+        #if param_opts['VARIANT'] == 2 and param_opts['TYPE'] is not None:           # DEADCODE: this can't be false now
+        params.append(":" + param_opts['TYPE'])
 
+        # Save variable to the cache of 'known'/'set' cmake variables
         self._var_formatter_cache[varname] = value
 
         return self._generic_program_option_handler_bash(params, value)

src/setprogramoptions/unittests/files_ini/config_test_setprogramoptions.ini

@@ -14,8 +14,10 @@ opt-set cmake
 opt-set -G : Ninja
 
 [TRILINOS_COMMON]
-opt-set-cmake-var  Trilinos_ENABLE_COMPLEX       BOOL   : ON
-opt-set-cmake-var  Trilinos_ENABLE_THREAD_SAFE   BOOL   : ON
+opt-set-cmake-var  Trilinos_ENABLE_COMPLEX              BOOL   : ON
+opt-set-cmake-var  Trilinos_ENABLE_THREAD_SAFE          BOOL   : ON
+# These are left UNTYPED so they aren't considered CACHE
+# vars. This will cause the bash generator to skip them.
 opt-set-cmake-var  Trilinos_PARALLEL_COMPILE_JOBS_LIMIT : 20
 opt-set-cmake-var  Trilinos_PARALLEL_LINK_JOBS_LIMIT    : 4
 
@@ -58,10 +60,10 @@ opt-set-cmake-var CMAKE_VAR_A PARENT_SCOPE FORCE : CMAKE_VAR_A_VAL
 opt-set-cmake-var CMAKE_VAR_A FORCE        : ON
 opt-set-cmake-var CMAKE_VAR_B PARENT_SCOPE : ON
 opt-set-cmake-var CMAKE_VAR_C BOOL         : ON
-opt-set-cmake-var CMAKE_VAR_F BOOL FORCE   : ON
-opt-set-cmake-var CMAKE_VAR_G FORCE BOOL   : ON
-opt-set-cmake-var CMAKE_VAR_H BOOL PARENT_SCOPE : ON
-opt-set-cmake-var CMAKE_VAR_I PARENT_SCOPE BOOL : ON
+opt-set-cmake-var CMAKE_VAR_D BOOL FORCE   : ON
+opt-set-cmake-var CMAKE_VAR_E FORCE BOOL   : ON
+opt-set-cmake-var CMAKE_VAR_F BOOL PARENT_SCOPE : ON
+opt-set-cmake-var CMAKE_VAR_G PARENT_SCOPE BOOL : ON
 
 [TEST_CMAKE_CACHE_PARAM_TEST_02]
 # Validate what happens if there's a bad param.
@@ -136,28 +138,38 @@ opt-set FOO : "${FOOBAR|ENV} -baz"
 opt-set FOO : "${FOOBAR} -baz"
 
 
+#
+# Variable expansion tests
+#
 [TEST_VAR_EXPANSION_COMMON]
+# Create the CACHE variable CMAKE_CXX_FLAGS of STRING type.
 opt-set-cmake-var CMAKE_CXX_FLAGS STRING : "${LDFLAGS|ENV} -foo"
 
-
 [TEST_VAR_EXPANSION_UPDATE_01]
+# Test an 'update' of CMAKE_CXX_FLAGS that is not FORCE
+# - In practice, CMake would not actually update CMAKE_CXX_FLAGS
+#   here because it's a CACHE var (per TEST_VAR_EXPANSION_COMMON)
+#   And CMake won't overwrite CACHE vars unless FORCEd.
 opt-set cmake
 use TEST_VAR_EXPANSION_COMMON
-opt-set-cmake-var CMAKE_CXX_FLAGS STRING FORCE : "${CMAKE_CXX_FLAGS|CMAKE} -bar"
+opt-set-cmake-var CMAKE_CXX_FLAGS STRING : "${CMAKE_CXX_FLAGS|CMAKE} -bar"
 
 [TEST_VAR_EXPANSION_UPDATE_02]
-use TEST_VAR_EXPANSION_UPDATE_01
+opt-set cmake
+use TEST_VAR_EXPANSION_COMMON
+# This should be a problem for Bash generation since the CMake var
+# CMAKE_F90_FLAGS would be unknown to bash. Depending on the
+# exception_control_level this will either trigger an exception when
+# sent to the bash generator or it could resolve the CMAKE var to an
+# empty string + warning.
 opt-set-cmake-var CMAKE_F90_FLAGS STRING: "${CMAKE_F90_FLAGS|CMAKE} -baz"
 
 [TEST_VAR_EXPANSION_UPDATE_03]
+# Updates CMAKE_CXX_FLAGS using a FORCE operation.
+# In practice, this would result in CMAKE_CXX_FLAGS = "${LDFLAGS|ENV} -foo -bif"
 use TEST_VAR_EXPANSION_UPDATE_01
 opt-set-cmake-var CMAKE_CXX_FLAGS STRING FORCE : "${CMAKE_CXX_FLAGS|CMAKE} -bif"
 
-[TEST_VAR_EXPANSION_UPDATE_04]
-opt-set cmake
-use TEST_VAR_EXPANSION_COMMON
-# Test (return None) at SetProgramOptionsCMake.py:_program_option_handler_opt_set_cmake_var_bash:188
-opt-set-cmake-var CMAKE_CXX_FLAGS STRING : "${LDFLAGS|ENV} -foobar"
 
 [TEST_STRING_DOUBLE_QUOTES]
 opt-set-cmake-var FOO STRING: foo::bar::baz<Type>
@@ -166,9 +178,13 @@ opt-set-cmake-var BAR STRING: "600"
 
 [TEST_CMAKE_VAR_REMOVE]
 # Test whether or not opt-remove works for a cmake var
-opt-set-cmake-var FOO_TEST: "FOO"
-opt-set-cmake-var BAR_TEST: "BAR"
-opt-set-cmake-var FOO     : "BAZ"
-# this should remove `FOO_TEST` from the option list so we will only
-# have `BAR_TEST` and `FOO` left.
+opt-set-cmake-var FOO_TEST STRING : "FOO"
+opt-set-cmake-var BAR_TEST STRING : "BAR"
+opt-set-cmake-var BAZ_TEST STRING : "BAZ"
+# opt-remove FOO_TEST should remove the FOO_TEST entry
+# and leave only the BAR_TEST and BAZ_TEST entries.
 opt-remove FOO_TEST
+
+
+[TEST_CMAKE_VAR_FORCE_ONLY]
+opt-set-cmake-var FOO FORCE : "BAR"