build: new set_utils.cmake for various handy "set()" wrappers

New set_utils.cmake has some handy new utilities: set_cache() is much
like the built-in set() when making a cache variable, and set_option()
is much like build-in option(). The biggest difference is that both
allow an environment variable of the same name, if it exists, to
supply the default value. This is something that cmake does with many
of its own controls, like CMAKE_BUILD_TYPE, but does not make any
provision for built-in set() or option() let users do it.

Signed-off-by: Larry Gritz <[email protected]>

CMakeLists.txt

@@ -144,6 +144,7 @@ include (GNUInstallDirs)
 
 # Utilities
 include (colors)
+include (set_utils)
 include (check_is_enabled)
 include (checked_find_package)
 include (fancy_add_executable)

src/cmake/set_utils.cmake

@@ -0,0 +1,119 @@
+# Copyright Contributors to the OpenImageIO project.
+# SPDX-License-Identifier: Apache-2.0
+# https://github.com/AcademySoftwareFoundation/OpenImageIO
+
+
+# Set a variable to a value if it is not already defined.
+macro (set_if_not var value)
+    if (NOT DEFINED ${var})
+        set (${var} ${value})
+    endif ()
+endmacro ()
+
+
+# Set a cmake variable `var` from an environment variable, if it is not
+# already defined (or if the FORCE flag is used). By default, the env var is
+# the same name as `var`, but you can specify a different env var name with
+# the ENVVAR keyword. If the env var doesn't exist or is empty, and a DEFAULT
+# is supplied, assign the default to the variable instead.  If the VERBOSE
+# CMake variable is set, or if the VERBOSE flag to this function is used,
+# print a message.
+macro (set_from_env var)
+    cmake_parse_arguments(_sfe   # prefix
+        # noValueKeywords:
+        "VERBOSE;FORCE"
+        # singleValueKeywords:
+        "ENVVAR;DEFAULT;NAME"
+        # multiValueKeywords:
+        ""
+        # argsToParse:
+        ${ARGN})
+    if (NOT DEFINED ${var} OR _sfe_FORCE)
+        set_if_not (_sfe_ENVVAR ${var})
+        set_if_not (_sfe_NAME ${var})
+        if (DEFINED ENV{${_sfe_ENVVAR}} AND NOT "$ENV{${_sfe_ENVVAR}}" STREQUAL "")
+            set (${var} $ENV{${_sfe_ENVVAR}})
+            if (_sfe_VERBOSE OR VERBOSE)
+                message (VERBOSE "set ${_sfe_NAME} = $ENV{${_sfe_ENVVAR}} (from env)")
+            endif ()
+        elseif (DEFINED _sfe_DEFAULT)
+            set (${var} ${_sfe_DEFAULT})
+            if (_sfe_VERBOSE OR VERBOSE)
+                message (VERBOSE "set ${_sfe_NAME} = ${_sfe_DEFAULT}")
+            endif ()
+        endif ()
+    endif ()
+endmacro ()
+
+
+
+# Wrapper for CMake `set()` functionality with extensions:
+# - If an env variable of the same name exists, it overrides the default
+#   value.
+# - In verbose mode, print the value and whether it came from the env.
+# - CACHE optional token makes it a cache variable.
+# - ADVANCED optional token sets it as "mark_as_advanced" without the need
+#   for a separate call (only applies to cache variables.)
+# - FILEPATH, PATH, BOOL, STRING optional token works as usual (only applies
+#   to cache variables).
+# - `DOC <docstring>` specifies a doc string for cache variables. If omitted,
+#   an empty doc string will be used.
+# Other extensions may be added in the future.
+macro (super_set name value)
+    cmake_parse_arguments(_sce   # prefix
+        # noValueKeywords:
+        "FORCE;ADVANCED;FILEPATH;PATH;BOOL;STRING;CACHE"
+        # singleValueKeywords:
+        "DOC"
+        # multiValueKeywords:
+        ""
+        # argsToParse:
+        ${ARGN})
+    set (_sce_extra_args "")
+    if (_sce_FILEPATH)
+        set (_sce_type "FILEPATH")
+    elseif (_sce_PATH)
+        set (_sce_type "PATH")
+    elseif (_sce_BOOL)
+        set (_sce_type "BOOL")
+    else ()
+        set (_sce_type "STRING")
+    endif ()
+    if (_sce_FORCE)
+        list (APPEND _sce_extra_args FORCE)
+    endif ()
+    set_if_not (_sce_DOC "empty")
+    set_from_env (_sce_val ENVVAR ${name} NAME ${name} DEFAULT ${value})
+    # if (DEFINED ENV{${name}} AND NOT "$ENV{${name}}" STREQUAL "")
+    #     set (_sce_val $ENV{${name}})
+    #     message (VERBOSE "set ${ColorBoldWhite}Option${ColorReset} ${name} = ${_sce_val} (from env)")
+    # else ()
+    #     set (_sce_val ${value})
+    #     message (VERBOSE "set ${ColorBoldWhite}Option${ColorReset} ${name} = ${_sce_val}")
+    # endif ()
+    if (_sce_CACHE)
+        message (STATUS "set (${name} ${_sce_val} CACHE ${_sce_type} ${_sce_DOC} ${_sce_extra_args})")
+        set (${name} ${_sce_val} CACHE ${_sce_type} ${_sce_DOC} ${_sce_extra_args})
+        # set (${name} ${_sce_val} CACHE ${_sce_type} ${_sce_DOC} ${_sce_extra_args})
+    else ()
+        set (${name} ${_sce_val} ${_sce_extra_args})
+    endif ()
+    if (_sce_ADVANCED)
+        mark_as_advanced (${name})
+    endif ()
+    unset (_sce_extra_args)
+    unset (_sce_type)
+    unset (_sce_val)
+endmacro ()
+
+
+# `set(... CACHE ...)` workalike using super_set underneath.
+macro (set_cache name value docstring)
+    super_set (${name} "${value}" DOC ${docstring} ${ARGN})
+endmacro ()
+
+
+# `option()` workalike using super_set underneath.
+macro (set_option name docstring value)
+    set_cache (${name} "${value}" ${docstring} BOOL ${ARGN})
+endmacro ()