Automatic snapshot commit from tribits at b0749b08

Origin repo remote tracking branch: 'github/master'
Origin repo remote repo URL: 'github = [email protected]:TriBITSPub/TriBITS.git'
Git describe: Vera4.0-RC1-start-1416-g5d375826

At commit:

commit b0749b08964ba9133f200b331e5b8d104f0d3588
Author:  Roscoe A. Bartlett <[email protected]>
Date:    Tue Dec 20 07:06:40 2022 -0700
Summary: Add replace_set_and_inc_dirs_r.sh and CHANGLOG entry (trilinos#429)

cmake/tribits/CHANGELOG.md

@@ -2,6 +2,32 @@
 ChangeLog for TriBITS
 ----------------------------------------
 
+## 2022-12-20:
+
+* **Deprecated:** The macro `set_and_inc_dirs()` is deprecated and replaced by
+  `tribits_set_and_inc_dirs()`.  Use the script
+  `TriBITS/refactoring/replace_set_and_inc_dirs_r.sh` to update
+  `CMakeLists.txt` files.
+
+## 2022-11-03:
+
+* **Deprecated:** The long-deprecated TriBITS function override
+  `include_directories()` now emits a deprecated warning.  To replace all
+  usages of `include_directories()` that should be
+  `tribits_include_directories()`, use the script
+  `TriBITS/refactoring/replace_include_directories_r.sh` (see documentation in
+  that script).
+
+* **Deprecated:** Many previously deprecated TriBITS features now will trigger
+  a CMake DEPRECATION warning message by default (by calling
+  `message(DEPRECATION ...)`).  The message printed to the CMake output will
+  typically describe how to remove the usage of the deprecated feature.  To
+  remove deprecation warnings, change to use the non-deprecated features
+  mentioned in the deprecation warning message.  To temporarily disable
+  deprecation warnings, configure with `-D
+  TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE=IGNORE` (see build reference entry
+  for `TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE` for more details).
+
 ## 2022-10-20:
 
 * **Changed:** Disabling an external package/TPL will now disable any

cmake/tribits/core/package_arch/TribitsAddLibrary.cmake

@@ -49,7 +49,7 @@ include(RemoveGlobalDuplicates)
 include(TribitsGeneralMacros)
 include(TribitsReportInvalidTribitsUsage)
 include(TribitsDeprecatedHelpers)
-include(SetAndIncDirs)
+include(TribitsSetAndIncDirs)
 
 
 # @FUNCTION: tribits_add_library()

cmake/tribits/core/package_arch/TribitsGlobalMacros.cmake

@@ -959,8 +959,12 @@ macro(tribits_define_global_options_and_define_extra_repos)
     CACHE BOOL
     "Set to 'ON' to see the machine load for advanced tests." )
 
+  if ("${TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE_DEFAULT}" STREQUAL "")
+    set(TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE_DEFAULT  "DEPRECATION")
+  endif()
+
   tribits_add_enum_cache_var(TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE
-    DEFAULT_VAL "DEPRECATION"
+    DEFAULT_VAL "${TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE_DEFAULT}"
     DOC_STRING "Mode for dealing with usage of TriBITS deprecated functionality"
     ALLOWED_STRINGS_LIST ${TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE_ALL_VALID_VALUES}
     IS_ADVANCED

cmake/tribits/core/package_arch/TribitsIncludeDirectories.cmake

@@ -43,14 +43,14 @@ include(TribitsDeprecatedHelpers)
 
 # @MACRO: tribits_include_directories()
 #
-# This function is to override the standard behavior of the built-in CMake
-# ``include_directories()`` command.
+# This function overrides the standard behavior of the built-in CMake
+# ``include_directories()`` command for special behavior for installation
+# testing.
 #
 # Usage::
 #
 #   tribits_include_directories(
-#     [REQUIRED_DURING_INSTALLATION_TESTING] <dir0> <dir1> ...
-#     )
+#     [REQUIRED_DURING_INSTALLATION_TESTING] <dir0> <dir1> ... )
 #
 # If specified, ``REQUIRED_DURING_INSTALLATION_TESTING`` can appear anywhere
 # in the argument list.
@@ -62,10 +62,10 @@ include(TribitsDeprecatedHelpers)
 # Testing`_). Normally we want the include directories to be handled as cmake
 # usually does.  However during TriBITS installation testing we do not want
 # most of the include directories to be used as the majority of the files
-# should come from the installation we are building against.  There is an
-# exception to this and that is when there are test only headers that are
-# needed.  For that case ``REQUIRED_DURING_INSTALLATION_TESTING`` must be
-# passed in to ensure the include paths are added for installation testing.
+# should come from the installation we are building against.  The exception is
+# when there are test only headers that are needed.  For that case
+# ``REQUIRED_DURING_INSTALLATION_TESTING`` must be passed in to ensure the
+# include paths are added for installation testing.
 #
 macro(tribits_include_directories)
 
@@ -81,13 +81,25 @@ macro(tribits_include_directories)
     ${ARGN}
     )
 
-  if(NOT ${PROJECT_NAME}_ENABLE_INSTALLATION_TESTING OR PARSE_REQUIRED_DURING_INSTALLATION_TESTING)
-    _include_directories(${PARSE_UNPARSED_ARGUMENTS})
+  if(NOT ${PROJECT_NAME}_ENABLE_INSTALLATION_TESTING
+      OR PARSE_REQUIRED_DURING_INSTALLATION_TESTING
+    )
+    if (TRIBITS_HIDE_DEPRECATED_INCLUDE_DIRECTORIES_OVERRIDE)
+      include_directories(${PARSE_UNPARSED_ARGUMENTS})
+    else()
+      _include_directories(${PARSE_UNPARSED_ARGUMENTS})
+    endif()
   endif()
 endmacro()
 
 
+if (NOT TRIBITS_HIDE_DEPRECATED_INCLUDE_DIRECTORIES_OVERRIDE)
+
 # Deprecated.  Use tribits_include_directories() instead!
+#
+# To hide this macro from even being defined, set
+# ``TRIBITS_HIDE_DEPRECATED_INCLUDE_DIRECTORIES_OVERRIDE=TRUE``.
+#
 macro(include_directories)
 
   tribits_deprecated_command(include_directories
@@ -106,7 +118,11 @@ macro(include_directories)
     ${ARGN}
     )
 
-  if(NOT ${PROJECT_NAME}_ENABLE_INSTALLATION_TESTING OR PARSE_REQUIRED_DURING_INSTALLATION_TESTING)
+  if(NOT ${PROJECT_NAME}_ENABLE_INSTALLATION_TESTING
+      OR PARSE_REQUIRED_DURING_INSTALLATION_TESTING
+    )
     _include_directories(${PARSE_UNPARSED_ARGUMENTS})
   endif()
 endmacro()
+
+endif (NOT TRIBITS_HIDE_DEPRECATED_INCLUDE_DIRECTORIES_OVERRIDE)

cmake/tribits/core/utils/SetAndIncDirs.cmake → cmake/tribits/core/package_arch/TribitsSetAndIncDirs.cmake

@@ -38,19 +38,29 @@
 # @HEADER
 
 
-# @MACRO: set_and_inc_dirs()
+# @MACRO: tribits_set_and_inc_dirs()
 #
-# Set a variable to an include directory and call ``include_directories()``
-# (removes boiler-plate code).
+# Set a variable to an include directory and call
+# `tribits_include_directories()`_ (removes boiler-plate code).
 #
 # Usage:
 #
-#   set_and_inc_dirs(<dirVarName> <includeDir>)
+#   tribits_set_and_inc_dirs(<dirVarName> <includeDir>)
 #
 # On output, this sets ``<dirVarName>`` to ``<includeDir>`` in the local scope
-# and calls ``include_directories(<includeDir>)``.
+# and calls ``tribits_include_directories(<includeDir>)``.
+#
+macro(tribits_set_and_inc_dirs  dirVarName  includeDir)
+  set(${dirVarName} ${includeDir})
+  tribits_include_directories(${${dirVarName}})
+endmacro()
+
+
+# Deprecated!  Use tribits_set_and_inc_dirs() instead!
 #
 macro(set_and_inc_dirs  DIR_VAR_NAME  INCLUDE_DIR)
+  tribits_deprecated_command(set_and_inc_dirs
+    MESSAGE "Use tribits_set_and_inc_dirs() instead." )
   set(${DIR_VAR_NAME} ${INCLUDE_DIR})
-  include_directories(${${DIR_VAR_NAME}})
+  tribits_include_directories(${${DIR_VAR_NAME}})
 endmacro()

cmake/tribits/core/utils/TribitsDeprecatedHelpers.cmake

@@ -42,34 +42,33 @@ include(TribitsParseArgumentsHelpers)
 
 
 set(TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE_VALUES_THAT_CALL_MESSAGE
-  DEPRECATION  AUTHOR_WARNING  SEND_ERROR  FATAL_ERROR
-  )
+  DEPRECATION  AUTHOR_WARNING  SEND_ERROR  FATAL_ERROR )
 set(TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE_VALUES_THAT_DONT_CALL_MESSAGE
-  IGNORE
-  )
+  IGNORE )
 set(TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE_ALL_VALID_VALUES
   ${TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE_VALUES_THAT_CALL_MESSAGE}
-  ${TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE_VALUES_THAT_CALL_MESSAGE}
-  )
+  ${TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE_VALUES_THAT_DONT_CALL_MESSAGE} )
 
 
 # @FUNCTION: tribits_deprecated()
 #
-# Notify the user that some TriBITS functionality is deprecated. Depending on
-# the value of TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE, this can do one of
-# several things:
-#
-# - ``DEPRECATION`` or empty string: issue a CMake ``DEPRECATION`` message and
-#   continue.
-# - ``AUTHOR_WARNING``: issue a CMake ``AUTHOR_WARNING`` message and continue.
-# - ``SEND_ERROR``: issue a CMake ``SEND_ERROR`` message and continue.
-# - ``FATAL_ERROR``: issue a CMake ``FATAL_ERROR`` message and exit.
-# - ``IGNORE``: issue no message and continue.
+# Notify the user that some TriBITS functionality is deprecated.
 #
 # Usage::
 #
 #   tribits_deprecated(<message>)
 #
+# Depending on the value of the cache variable
+# `TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE`_, this can do one of several
+# things:
+#
+# - ``DEPRECATION`` or empty string (or variable not defined): Issue a CMake
+#    ``DEPRECATION`` message and continue.
+# - ``AUTHOR_WARNING``: Issue a CMake ``AUTHOR_WARNING`` message and continue.
+# - ``SEND_ERROR``: Issue a CMake ``SEND_ERROR`` message and continue.
+# - ``FATAL_ERROR``: Issue a CMake ``FATAL_ERROR`` message and exit.
+# - ``IGNORE``: Issue no message and continue.
+#
 function(tribits_deprecated)
   cmake_parse_arguments(PARSE_ARGV 0 FWD "" "" "")
 
@@ -78,9 +77,16 @@ function(tribits_deprecated)
   endif()
 
   if ("${TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE}"  IN_LIST  TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE_VALUES_THAT_CALL_MESSAGE)
-    message_wrapper("${TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE}" ${FWD_UNPARSED_ARGUMENTS})
-  elseif (NOT "${TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE}"  IN_LIST  TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE_ALL_VALID_VALUES)
-    message_wrapper(FATAL_ERROR "Invalid value for TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE: '${TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE}'")
+    message_wrapper("${TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE}"
+      ${FWD_UNPARSED_ARGUMENTS}
+      "\n\nNOTE: To Make these warnings go away, set -D"
+      " TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE=IGNORE (see the build reference guide).")
+  elseif (NOT "${TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE}"  IN_LIST
+      TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE_ALL_VALID_VALUES
+    )
+    message_wrapper(FATAL_ERROR "Invalid value for"
+      " TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE="
+      "'${TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE}'")
   endif()
 endfunction()
 

cmake/tribits/doc/build_ref/TribitsBuildReferenceBody.rst

@@ -2089,6 +2089,26 @@ This will override the global behavior set by
 ``<TRIBITS_PACKAGE>``.
 
 
+Adjusting CMake DEPRECATION warnings
+------------------------------------
+
+By default, deprecated TriBITS features being used in the project's CMake
+files will result in CMake deprecation warning messages (issued by calling
+``message(DEPRECATION ...)`` internally).  The handling of these deprecation
+warnings can be changed by setting the CMake cache variable
+``TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE``.  For example, to remove all
+deprecation warnings, set::
+
+  -D TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE=IGNORE
+
+Other valid values include:
+
+* ``DEPRECATION``: Issue a CMake ``DEPRECATION`` message and continue (default).
+* ``AUTHOR_WARNING``: Issue a CMake ``AUTHOR_WARNING`` message and continue.
+* ``SEND_ERROR``: Issue a CMake ``SEND_ERROR`` message and continue.
+* ``FATAL_ERROR``: Issue a CMake ``FATAL_ERROR`` message and exit.
+
+
 Disabling deprecated code
 -------------------------