Introduced ENZOE_<LANG>_FLIST variables

mabruzzo · mabruzzo · commit b14cede39265 · 2024-06-17T09:27:02.000-04:00
The purpose of these variables is to act similarly to the standard
``CMAKE_&lt;LANG&gt;_FLAGS`` variables, but only affect the source files
directly used by Cello/Enzo-E. (The whole idea is to explicitly avoid
is this new set of variables won't affect any external dependencies that
is being compiled as a part of this build)
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -309,6 +309,34 @@ add_subdirectory(src/External)
 #   2. language-specific generator-expressions are not supported on all
 #      build-generators (this isn't really a problem per-se, but it would be
 #      nice to be as flexible as possible)
+
+# handle flags within ENZOE_<LANG>_FLIST for each language used be Enzo-E
+include("GenericOptionCommand")
+get_property(_ENZOE_LANG_LIST GLOBAL PROPERTY ENABLED_LANGUAGES)
+
+foreach(lang IN LISTS _ENZOE_LANG_LIST)
+  # first, initialize ENZOE_<LANG>_FLIST if it hasn't already been initialized
+  generic_option(
+    ENZOE_${lang}_FLIST STRING "\
+specifies flags that are passed to the compiler (in all configurations) for \
+compiling the ${lang} files that are used in Cello and Enzo-E. There are 3 \
+main differences from CMAKE_${lang}_FLAGS: \
+(i) these flags won't be passed to any external dependencies that are \
+compiled as part of this build \
+(ii) these flags will NOT be passed to the linker, and \
+(ii) these flags must be specified as a semi-colon delimited list of values."
+    # if there are any, the default values would be set in machine file
+    DEFAULT_VALUE "${ENZOE_${lang}_FLIST_INIT}"
+    FORBID_EXISTING_NONCACHE_VAR # <- discourage bad habits!
+  )
+
+  # now setup cmake to make use of any compiler flags in the list
+  if(NOT ("${ENZOE_${LANG}_FLIST}" STREQUAL ""))
+    message("$<$<COMPILE_LANGUAGE:${LANG}>:${ENZOE_${LANG}_FLIST}>")
+  endif()
+endforeach()
+
+# introduce floating-point related compiler options
 option(OPTIMIZE_FP "Enables value-unsafe floating-point optimizations (this may already be enabled on some compilers like icc)." OFF)
 option(USE_SIMD "Use OpenMP SIMD directives. This may already be enabled on some compilers (like icc)." OFF)
 include("FPOptimizationCompileOptions")
@@ -319,6 +347,7 @@ elseif (USE_SIMD)
   message(FATAL_ERROR "Can only use `USE_SIMD=ON` when `OPTIMIZE_FP=ON`.")
 endif()
 
+# introduce required Fortran Compiler Options
 include("RequiredFortranCompileOptions")
 get_required_fortran_options(_ENZOE_REQ_FORTRAN_OPTS)
 add_compile_options("${_ENZOE_REQ_FORTRAN_OPTS}")
diff --git a/cmake/GenericOptionCommand.cmake b/cmake/GenericOptionCommand.cmake
@@ -0,0 +1,111 @@
+# See LICENSE_ENZO file for license and copyright information
+
+#.rst:
+# GenericOptionCommand
+# --------------------
+#
+# Defines a command, ``generic_option``, that acts like a more general form of
+# the built-in ``option`` command.
+#
+# In slightly more detail, it provides a variable that the user can optionally
+# specify::
+#
+#   generic_option(<variable> <type> <help_text>
+#                  DEFAULT_VALUE <default_value>
+#                  [FORBID_EXISTING_NONCACHE_VAR])
+#
+# Similar to the ``option`` command, the default behavior is to
+#   - do nothing if ``<variable>`` is already defined (as a normal or cache
+#     variable).
+#   - initialize ``<variable>`` as a cache variable of type ``TYPE``
+#     with the specified ``<default_value>``. If ``DEFAULT_VALUE`` is not
+#     specified, then the default is ``OFF`` for a ``BOOL`` variable and
+#     ``""`` in other cases.
+#
+# When the ``FORBID_EXISTING_NONCACHE_VAR`` option is specified, this command
+# will immediately abort cmake with an error if ``<variable>`` is already
+# exists as a non-cache variable. NOTE: if it exists as a cache variable and as
+# a normal variable that is okay (there isn't any way to identify this case
+# anyways)
+
+if(__GenericOptionCommand)
+  return()
+endif()
+set(__GenericOptionCommand YES)
+
+
+function(generic_option variable type help_text)
+  
+  # on the off-chance that the variable-name matches a value used in this
+  # function, let's check if it already exists (BEFORE DEFINING ANY VARIABLES)
+  if (DEFINED "${variable}")
+    set(is_already_defined TRUE)
+  else()
+    set(is_already_defined FALSE)
+  endif()
+
+  # parse args
+  set(options FORBID_EXISTING_NONCACHE_VAR)
+  set(oneValueArgs DEFAULT_VALUE)
+  set(multiValueArgs "")
+  cmake_parse_arguments(PARSE_ARGV 3 __GENERIC_OPTION "${options}" "${oneValueArgs}"
+                        "${multiValueArgs}" )#${ARGN} )
+
+  # some basic error-handling
+  set(_funcname "generic_option")
+  if (DEFINED __GENERIC_OPTION_UNPARSED_ARGUMENTS)
+    message(FATAL_ERROR
+      "${_funcname} recieved invalid arguments: "
+      "\"${__GENERIC_OPTION_UNPARSED_ARGUMENTS}\"")
+  elseif (DEFINED __GENERIC_OPTION_KEYWORDS_MISSING_VALUES)
+    message(FATAL_ERROR
+      "${_funcname} received the ${__GENERIC_OPTION_KEYWORDS_MISSING_VALUES} "
+      "keyword(s) without any associated arguments.")
+  elseif ("${type}" STREQUAL "INTERNAL")
+    message(FATAL_ERROR "${_funcname} does not support the INTERNAL type")
+  elseif ("${type}" MATCHES "^PATH|FILEPATH$")
+    # these types have some weird handling related to relative-paths
+    message(FATAL_ERROR
+      "${_funcname} doesn't currently support the ${type} type")
+  elseif (NOT "${type}" MATCHES "^BOOL|STRING$")
+    message(FATAL_ERROR "invalid type passed to ${_funcname}")
+  endif()
+
+  if ("${__GENERIC_OPTION_FORBID_EXISTING_NONCACHE_VAR}" AND
+      "${is_already_defined}" AND (NOT DEFINED CACHE{${variable}}))
+    # by trial and error, the output format now seems nicer (not sure why we
+    # need to escape some line-breaks but not others)
+    message(FATAL_ERROR "\
+The \"${variable}\" variable is expressly forbidden from being defined as a \
+regular variable before the appropriate call to ${_funcname}. \
+You probably made the mistake of writing some cmake-code with ``set(...)`` \
+somewhere to define the variable.
+  -> if you are a user, you should assign a value to the variable on the
+     the command-line with the -D<var>=<value> flag or by modifying values
+     in the CMakeCache.txt file (by modifying it directly OR using some kind
+     of gui-program)
+  -> if you are a developer, you are probably trying to assign a default value
+     to \"${variable}\". In this case, you should prefer to specify the
+     initial-value to ${_func_name} by using the DEFAULT_VALUE keyword. If you
+     instead choose to refactor, keep in mind that it's a little tricky to get
+     this \"right\" (it can be tricky to allow users to override the value)")
+  endif()
+ 
+  cmake_policy(GET CMP0077 _CMP0077_val)
+  if ("${_CMP0077_val}" STREQUAL "OLD")
+    message(FATAL_ERROR "${_func_name} needs NEW behavior of CMP0077")
+  endif()
+
+  if (NOT "${is_already_defined}")
+    if (DEFINED __GENERIC_OPTION_DEFAULT_VALUE)
+      set("${variable}" "${__GENERIC_OPTION_DEFAULT_VALUE}" CACHE "${type}"
+          "${help_text}")
+    elseif("${type}" STREQUAL "BOOL")
+      set("${variable}" "OFF" CACHE BOOL "${help_text}")
+    else()
+      set("${variable}" "" CACHE "${type}" "${help_text}")
+    endif()
+  endif()
+
+endfunction()
+
diff --git a/config/darwin_clang.cmake b/config/darwin_clang.cmake
@@ -45,12 +45,19 @@ if(NOT __processedUserDefaults)
   # instruction set of the machine used to compile the code.
   set(CONFIG_ARCH_FLAGS "-march=native")
 
-  # add flag to unroll loops (this flag would also be enabled anyways when
-  # OPTIMIZE_FP=TRUE)
-  set(CMAKE_C_FLAGS "-funroll-loops" CACHE STRING "Default C flags")
-  set(CMAKE_CXX_FLAGS "${CMAKE_C_FLAGS}" CACHE STRING "Default C++ flags")
+  # if you choose to add other flags, you should generally prefer to use:
+  #     ENZOE_C_FLIST_INIT, ENZOE_CXX_FLIST_INIT, ENZOE_Fortran_FLIST_INIT
+  # rather than CMAKE_C_FLAGS, CMAKE_CXX_FLAGS, and CMAKE_Fortran_FLAGS
+  # -> These alternatives will affect Cello/Enzo-E, but won't influence any
+  #    dependencies compiled in the same-build
+  # -> plus, the alternatives let users easily overwrite them
 
-  # Setting package paths (e.g., Grackle) - (meant for personal machine files)
+  # in this case, we add a flag to unroll loops
+  # (aside: this flag would be enabled anyways when OPTIMIZE_FP=TRUE)
+  set(ENZOE_C_FLIST_INIT "-Wall;-funroll-loops")
+  set(ENZOE_CXX_FLIST_INIT "${ENZOE_C_FLIST_INIT}")
+
+  # Set package paths (e.g., Grackle) - Only do this in personal machine files
 
   # Mark done
   set(__processedUserDefaults ON)
diff --git a/config/expanse_icc.cmake b/config/expanse_icc.cmake
@@ -17,17 +17,24 @@ if(NOT __processedUserDefaults)
   # compiler are handled internally (if those flags don't work, please update
   # the relevant internal logic rather than specifying them here)
 
-  # add optional flags to C and C++ compilers that provide useful warnings
-  set(CMAKE_C_FLAGS "-Wall" CACHE STRING "Default C flags")
-  set(CMAKE_CXX_FLAGS "${CMAKE_C_FLAGS}" CACHE STRING "Default C++ flags")
-
   # these flag(s) are currently only used when using openmp-simd optimizations
   # (to specify available/prefered instruction sets).
   # This particular value tells the compiler to optimize the code for the
   # instruction set of the machine used to compile the code.
   set(CONFIG_ARCH_FLAGS "-xHost")
 
-  # Setting package paths (e.g., Grackle)
+  # if you choose to add other flags, you should generally prefer to use:
+  #     ENZOE_C_FLIST_INIT, ENZOE_CXX_FLIST_INIT, ENZOE_Fortran_FLIST_INIT
+  # rather than CMAKE_C_FLAGS, CMAKE_CXX_FLAGS, and CMAKE_Fortran_FLAGS
+  # -> These alternatives will affect Cello/Enzo-E, but won't influence any
+  #    dependencies compiled in the same-build
+  # -> plus, the alternatives let users easily overwrite them
+
+  # add optional flags to C and C++ compilers that provide useful warnings
+  set(ENZOE_C_FLIST_INIT "-Wall")
+  set(ENZOE_CXX_FLIST_INIT "${ENZOE_C_FLIST_INIT}")
+
+  # Set package paths (e.g., Grackle) - Only do this in personal machine files
 
   # Mark done
   set(__processedUserDefaults ON)
diff --git a/config/frontera_icc.cmake b/config/frontera_icc.cmake
@@ -23,7 +23,14 @@ if(NOT __processedUserDefaults)
   # Lake (CLX) Compute Nodes
   set(CONFIG_ARCH_FLAGS "-xCORE-AVX512")
 
-  # Setting package paths (e.g., Grackle)
+  # if you choose to add other flags, you should generally prefer to use:
+  #     ENZOE_C_FLIST_INIT, ENZOE_CXX_FLIST_INIT, ENZOE_Fortran_FLIST_INIT
+  # rather than CMAKE_C_FLAGS, CMAKE_CXX_FLAGS, and CMAKE_Fortran_FLAGS
+  # -> These alternatives will affect Cello/Enzo-E, but won't influence any
+  #    dependencies compiled in the same-build
+  # -> plus, the alternatives let users easily overwrite them
+
+  # Set package paths (e.g., Grackle) - Only do this in personal machine files
 
   # Mark done
   set(__processedUserDefaults ON)
diff --git a/config/hlrn_gcc.cmake b/config/hlrn_gcc.cmake
@@ -19,15 +19,22 @@ if(NOT __processedUserDefaults)
   # the relevant internal logic rather than specifying them here)
 
   # add optional flags to C and C++ compilers that provide useful warnings
-  #set(CMAKE_C_FLAGS "-Wall" CACHE STRING "Default C flags")
-  #set(CMAKE_CXX_FLAGS "${CMAKE_C_FLAGS}" CACHE STRING "Default C++ flags")
+  #set(ENZOE_C_FLIST "-Wall" CACHE STRING "Default C flags")
+  #set(ENZOE_CXX_FLIST "${ENZOE_C_FLIST}" CACHE STRING "Default C++ flags")
 
   # these flag(s) are currently only used when using openmp-simd optimizations
   # (to specify available/prefered instruction sets).
   # This particular value tells the compiler to optimize the code for the
   # instruction set of the machine used to compile the code.
   set(CONFIG_ARCH_FLAGS "-march=skylake-avx512")
 
+  # if you choose to add other flags, you should generally prefer to use:
+  #     ENZOE_C_FLIST_INIT, ENZOE_CXX_FLIST_INIT, ENZOE_Fortran_FLIST_INIT
+  # rather than CMAKE_C_FLAGS, CMAKE_CXX_FLAGS, and CMAKE_Fortran_FLAGS
+  # -> These alternatives will affect Cello/Enzo-E, but won't influence any
+  #    dependencies compiled in the same-build
+  # -> plus, the alternatives let users easily overwrite them
+
   # Mark done
   set(__processedUserDefaults ON)
 
diff --git a/config/linux_gcc.cmake b/config/linux_gcc.cmake
@@ -23,13 +23,20 @@ if(NOT __processedUserDefaults)
   # instruction set of the machine used to compile the code.
   set(CONFIG_ARCH_FLAGS "-march=native")
 
+  # if you choose to add other flags, you should generally prefer to use:
+  #     ENZOE_C_FLIST_INIT, ENZOE_CXX_FLIST_INIT, ENZOE_Fortran_FLIST_INIT
+  # rather than CMAKE_C_FLAGS, CMAKE_CXX_FLAGS, and CMAKE_Fortran_FLAGS
+  # -> These alternatives will affect Cello/Enzo-E, but won't influence any
+  #    dependencies compiled in the same-build
+  # -> plus, the alternatives let users easily overwrite them
+
   # add optional flags to C and C++ compilers that provide useful warnings
   # (also add flag to unroll loops - this flag would also be enabled anyways
   # when OPTIMIZE_FP=TRUE)
-  set(CMAKE_C_FLAGS "-Wall -funroll-loops" CACHE STRING "Default C flags")
-  set(CMAKE_CXX_FLAGS "${CMAKE_C_FLAGS}" CACHE STRING "Default C++ flags")
+  set(ENZOE_C_FLIST_INIT "-Wall;-funroll-loops")
+  set(ENZOE_CXX_FLIST_INIT "${ENZOE_C_FLIST}")
 
-  # Setting package paths (e.g., Grackle) - (meant for personal machine files)
+  # Set package paths (e.g., Grackle) - Only do this in personal machine files
 
   # Mark done
   set(__processedUserDefaults ON)
diff --git a/config/linux_icc.cmake b/config/linux_icc.cmake
@@ -19,17 +19,24 @@ if(NOT __processedUserDefaults)
   # compiler are handled internally (if those flags don't work, please update
   # the relevant internal logic rather than specifying them here)
 
-  # add optional flags to C and C++ compilers that provide useful warnings
-  set(CMAKE_C_FLAGS "-Wall" CACHE STRING "Default C flags")
-  set(CMAKE_CXX_FLAGS "${CMAKE_C_FLAGS}" CACHE STRING "Default C++ flags")
-
   # these flag(s) are currently only used when using openmp-simd optimizations
   # (to specify available/prefered instruction sets).
   # This particular value tells the compiler to optimize the code for the
   # instruction set of the machine used to compile the code.
   set(CONFIG_ARCH_FLAGS "-xHost")
 
-  # Setting package paths (e.g., Grackle)
+  # if you choose to add other flags, you should generally prefer to use:
+  #     ENZOE_C_FLIST_INIT, ENZOE_CXX_FLIST_INIT, ENZOE_Fortran_FLIST_INIT
+  # rather than CMAKE_C_FLAGS, CMAKE_CXX_FLAGS, and CMAKE_Fortran_FLAGS
+  # -> These alternatives will affect Cello/Enzo-E, but won't influence any
+  #    dependencies compiled in the same-build
+  # -> plus, the alternatives let users easily overwrite them
+
+  # add optional flags to C and C++ compilers that provide useful warnings
+  set(ENZOE_C_FLIST_INIT "-Wall")
+  set(ENZOE_CXX_FLIST_INIT "${ENZOE_C_FLIST_INIT}")
+
+  # Set package paths (e.g., Grackle) - Only do this in personal machine files
 
   # Mark done
   set(__processedUserDefaults ON)
diff --git a/config/msu_hpcc_gcc.cmake b/config/msu_hpcc_gcc.cmake
@@ -17,7 +17,18 @@ if(NOT __processedUserDefaults)
   # compiler are handled internally (if those flags don't work, please update
   # the relevant internal logic rather than specifying them here) 
 
-  # Setting package paths (e.g., Grackle)
+  # in principle we should set flags to specify hardware architecture (so that
+  # they can be used with openmp-simd optimizations
+  # set(CONFIG_ARCH_FLAGS ...)
+
+  # if you choose to add other flags, you should generally prefer to use:
+  #     ENZOE_C_FLIST_INIT, ENZOE_CXX_FLIST_INIT, ENZOE_Fortran_FLIST_INIT
+  # rather than CMAKE_C_FLAGS, CMAKE_CXX_FLAGS, and CMAKE_Fortran_FLAGS
+  # -> These alternatives will affect Cello/Enzo-E, but won't influence any
+  #    dependencies compiled in the same-build
+  # -> plus, the alternatives let users easily overwrite them
+
+  # Set package paths (e.g., Grackle) - Only do this in personal machine files
 
   # Mark done
   set(__processedUserDefaults ON)
diff --git a/config/pleiades_icc.cmake b/config/pleiades_icc.cmake
@@ -17,7 +17,18 @@ if(NOT __processedUserDefaults)
   # compiler are handled internally (if those flags don't work, please update
   # the relevant internal logic rather than specifying them here)
 
-  # Setting package paths (e.g., Grackle)
+  # in principle we should set flags to specify hardware architecture (so that
+  # they can be used with openmp-simd optimizations
+  # set(CONFIG_ARCH_FLAGS ...)
+
+  # if you choose to add other flags, you should generally prefer to use:
+  #     ENZOE_C_FLIST_INIT, ENZOE_CXX_FLIST_INIT, ENZOE_Fortran_FLIST_INIT
+  # rather than CMAKE_C_FLAGS, CMAKE_CXX_FLAGS, and CMAKE_Fortran_FLAGS
+  # -> These alternatives will affect Cello/Enzo-E, but won't influence any
+  #    dependencies compiled in the same-build
+  # -> plus, the alternatives let users easily overwrite them
+
+  # Set package paths (e.g., Grackle) - Only do this in personal machine files
 
   # Setting test environment
   set(PARALLEL_LAUNCHER "mpiexec" CACHE STRING "Use mpiexec for launching parallel tests")
diff --git a/doc/source/tutorial/getting_started.rst b/doc/source/tutorial/getting_started.rst
@@ -166,6 +166,7 @@ Configuration options
 Current ``cmake`` options are listed in the following subsubsections.
 Skip ahead to :ref:`how_to_specify_the_configuration` for details about how to specify the configuration.
 
+
 General Configuration
 ^^^^^^^^^^^^^^^^^^^^^
 
@@ -352,6 +353,33 @@ The following options don't really belong in any other category
      - Precompile headers to try to reduce compile time
      - ON
 
+.. _about_enzoe_lang_flist:
+
+``ENZOE_<LANG>_FLIST`` Variables
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+We strongly encourage users and developers to make use of the options described in the preceding subsections.
+They exist to provide a curated/consistent experience in a variety of scenarios.
+(If you think that some option is missing, please let us know!)
+
+With that said, we also recognize that the need may arise where a user/developer may want to specify arbitrary flags.
+We provide the ``ENZOE_<LANG>_FLIST`` variables for this purpose (where ``<LANG>`` is ``C``, ``CXX``, ``Fortran``).
+Flags passed to this variable will be passed to the compiler while compiling source files (that are written in ``<LANG>``) that are directly used in the Cello/Enzo-E libraries and resulting executable.
+Here are 2 illustrative examples:
+
+ * First we show that in order to pass multiple flags, the flags need to be specified by a semicolon delimited list.
+   If you stored ``"-Wall;-Wpedantic;-funroll-loops"`` within the ``ENZOE_CXX_FLIST`` variable, then all C++ files used to build Cello and Enzo-E would be passed those flags.
+
+ * Next we show that to properly pass "options groups" you may need to make use of shell-like quoting with the ``SHELL:`` prefix (this relates option de-duplication performed by cmake).
+   Thus storing ``"SHELL:-option1 A;-Wall;SHELL:-option2 B"`` within ``ENZOE_Fortran_FLIST`` would cause all Fortran files used in Enzo-E and Cello to be passed ``-option1 A -Wall -option2 B``. 
+
+
+CMake offers a similar set of standard variables named ``CMAKE_<LANG>_FLAGS`` that serve a similar purpose, but they behave slightly differently.
+**Most importantly**, flags passed ``CMAKE_<LANG>_FLAGS`` will be used to specify flags that are passed to ALL source-files (of the given language) compiled in a given build -- including the source files of any external dependencies that the build is automatically compiling (in the near future, this may include Grackle).
+The contents of ``CMAKE_<LANG>_FLAGS`` are also passed to the compiler front-end during linking.
+Additionally, the contents of ``CMAKE_<LANG>_FLAGS`` are command line snippets (i.e. options are separated by whitespace rather than semi-colons and no shell-quoting is needed).
+
+
 .. _how_to_specify_the_configuration:
 
 Specifying Configuration Options
@@ -412,6 +440,12 @@ through the global default), the running
 ``cmake -DEnzo-E_CONFIG=my_config_name -DUSE_DOUBLE_PREC=OFF ..`` will result in a single
 precision version of Enzo-E.
 
+Some of these files may also initialize the ``ENZOE_<LANG>_FLIST_INIT`` variables.
+When defined, these variables are used to provide defaults for the ``ENZOE_<LANG>_FLIST`` variables, which are discussed :ref:`up above <about_enzoe_lang_flist>`.
+As discussed above, these variables provide a mechanism to quickly and easily provide extra flags to the compiler.
+Ideally you should only need to rely upon these for quick-and-easy-tests and the other options should meet most of your needs.
+If you find the existing options don't meet your needs, please let us know
+
 Options in the machine file can also include the paths to external libraries and
 can be set via a "cached string", i.e., via
 
