Complete deprecated warnings support and doc (TriBITSPub#429)

* Update the deprecation message to mention the cache var TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE and how to set it to remove deprecation warnings. * Add non-cache var TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE_DEFAULT so that a TriBITS project can provide its own default for cache var TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE. * Add documentation for the cache var TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE in the TriBITS build reference and developers guides. * Fix TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE_ALL_VALID_VALUES to pull in ${TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE_VALUES_THAT_CALL_MESSAGE} and ${TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE_VALUES_THAT_DONT_CALL_MESSAGE} instead of pulling in ${TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE_VALUES_THAT_CALL_MESSAGE} twice. (If user would have tried to set -DTRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE=IGNORE, it would have errored out of the configure.) * ???
bartlettroscoe · Dec 14, 2022 · 2943b81 · 2943b81
1 parent 07aeef0
commit 2943b81
Show file tree

Hide file tree

Showing 5 changed files with 90 additions and 33 deletions.
diff --git a/test/core/TestingFunctionMacro_UnitTests.cmake b/test/core/TestingFunctionMacro_UnitTests.cmake
@@ -367,7 +367,7 @@ function(unittest_tribits_misc)
   tribits_filter_and_assert_categories(CATEGORIES)
   set(MESSAGE_WRAPPER_UNIT_TEST_MODE FALSE)
   unittest_compare_const(MESSAGE_WRAPPER_INPUT
-    "DEPRECATION;The test category 'WEEKLY' is deprecated; and is replaced with 'HEAVY'.  Please change to use 'HEAVY' instead.")
+    "DEPRECATION;The test category 'WEEKLY' is deprecated; and is replaced with 'HEAVY'.  Please change to use 'HEAVY' instead.;${TRIBITS_DEPRECATE_MSG_LAST_PART}")
   unittest_compare_const(CATEGORIES "BASIC;HEAVY;NIGHTLY")
 
   message("Testing tribits_filter_and_assert_categories( ... HEAVY)")
@@ -1768,7 +1768,7 @@ function(unittest_tribits_add_test_categories)
   tribits_add_test( ${EXEN} CATEGORIES WEEKLY )
   unittest_compare_const(
     MESSAGE_WRAPPER_INPUT
-    "DEPRECATION;The test category 'WEEKLY' is deprecated; and is replaced with 'HEAVY'.  Please change to use 'HEAVY' instead.;-- PackageA_SomeExec: Added test (HEAVY, PROCESSORS=1)!"
+    "DEPRECATION;The test category 'WEEKLY' is deprecated; and is replaced with 'HEAVY'.  Please change to use 'HEAVY' instead.;${TRIBITS_DEPRECATE_MSG_LAST_PART};-- PackageA_SomeExec: Added test (HEAVY, PROCESSORS=1)!"
     )
   unittest_compare_const(
     TRIBITS_ADD_TEST_ADD_TEST_INPUT
@@ -4615,7 +4615,7 @@ function(unittest_tribits_deprecated)
   tribits_deprecated("This is a deprecation message with TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE unset")
   unittest_compare_const(
     MESSAGE_WRAPPER_INPUT
-    "DEPRECATION;This is a deprecation message with TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE unset"
+    "DEPRECATION;This is a deprecation message with TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE unset;${TRIBITS_DEPRECATE_MSG_LAST_PART}"
     )
 
   message("Testing tribits_deprecated() with multiple message arguments")
@@ -4625,7 +4625,7 @@ function(unittest_tribits_deprecated)
     " multiple message arguments")
   unittest_compare_const(
     MESSAGE_WRAPPER_INPUT
-    "DEPRECATION;This is a deprecation message with; multiple message arguments"
+    "DEPRECATION;This is a deprecation message with; multiple message arguments;${TRIBITS_DEPRECATE_MSG_LAST_PART}"
     )
 
   message("Testing tribits_deprecated() with TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE set to empty string")
@@ -4634,7 +4634,7 @@ function(unittest_tribits_deprecated)
   tribits_deprecated("This is a deprecation message with TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE set to empty string")
   unittest_compare_const(
     MESSAGE_WRAPPER_INPUT
-    "DEPRECATION;This is a deprecation message with TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE set to empty string"
+    "DEPRECATION;This is a deprecation message with TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE set to empty string;${TRIBITS_DEPRECATE_MSG_LAST_PART}"
     )
 
   message("Testing tribits_deprecated() with TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE set to DEPRECATION")
@@ -4643,7 +4643,7 @@ function(unittest_tribits_deprecated)
   tribits_deprecated("This is a deprecation message with TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE set to DEPRECATION")
   unittest_compare_const(
     MESSAGE_WRAPPER_INPUT
-    "DEPRECATION;This is a deprecation message with TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE set to DEPRECATION"
+    "DEPRECATION;This is a deprecation message with TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE set to DEPRECATION;${TRIBITS_DEPRECATE_MSG_LAST_PART}"
     )
 
   message("Testing tribits_deprecated() with TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE set to AUTHOR_WARNING")
@@ -4652,7 +4652,7 @@ function(unittest_tribits_deprecated)
   tribits_deprecated("This is a deprecation message with TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE set to AUTHOR_WARNING")
   unittest_compare_const(
     MESSAGE_WRAPPER_INPUT
-    "AUTHOR_WARNING;This is a deprecation message with TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE set to AUTHOR_WARNING"
+    "AUTHOR_WARNING;This is a deprecation message with TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE set to AUTHOR_WARNING;${TRIBITS_DEPRECATE_MSG_LAST_PART}"
     )
 
   message("Testing tribits_deprecated() with TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE set to SEND_ERROR")
@@ -4661,7 +4661,7 @@ function(unittest_tribits_deprecated)
   tribits_deprecated("This is a deprecation message with TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE set to SEND_ERROR")
   unittest_compare_const(
     MESSAGE_WRAPPER_INPUT
-    "SEND_ERROR;This is a deprecation message with TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE set to SEND_ERROR"
+    "SEND_ERROR;This is a deprecation message with TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE set to SEND_ERROR;${TRIBITS_DEPRECATE_MSG_LAST_PART}"
     )
 
   message("Testing tribits_deprecated() with TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE set to FATAL_ERROR")
@@ -4670,7 +4670,7 @@ function(unittest_tribits_deprecated)
   tribits_deprecated("This is a deprecation message with TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE set to FATAL_ERROR")
   unittest_compare_const(
     MESSAGE_WRAPPER_INPUT
-    "FATAL_ERROR;This is a deprecation message with TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE set to FATAL_ERROR"
+    "FATAL_ERROR;This is a deprecation message with TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE set to FATAL_ERROR;${TRIBITS_DEPRECATE_MSG_LAST_PART}"
     )
 
   message("Testing tribits_deprecated() with TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE set to INVALID")
@@ -4679,7 +4679,7 @@ function(unittest_tribits_deprecated)
   tribits_deprecated("This is a deprecation message with TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE set to INVALID")
   unittest_compare_const(
     MESSAGE_WRAPPER_INPUT
-    "FATAL_ERROR;Invalid value for TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE: 'INVALID'"
+    "FATAL_ERROR;Invalid value for; TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE=;'INVALID'"
     )
 
 endfunction()
@@ -4699,7 +4699,7 @@ function(unittest_tribits_deprecated_command)
   tribits_deprecated_command(tribits_some_deprecated_command)
   unittest_compare_const(
     MESSAGE_WRAPPER_INPUT
-    "DEPRECATION;TriBITS command 'tribits_some_deprecated_command' is deprecated."
+    "DEPRECATION;TriBITS command 'tribits_some_deprecated_command' is deprecated.;${TRIBITS_DEPRECATE_MSG_LAST_PART}"
     )
 
   message("Testing tribits_deprecated_command() with TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE set to AUTHOR_WARNING")
@@ -4708,7 +4708,7 @@ function(unittest_tribits_deprecated_command)
   tribits_deprecated_command(tribits_some_other_deprecated_command)
   unittest_compare_const(
     MESSAGE_WRAPPER_INPUT
-    "AUTHOR_WARNING;TriBITS command 'tribits_some_other_deprecated_command' is deprecated."
+    "AUTHOR_WARNING;TriBITS command 'tribits_some_other_deprecated_command' is deprecated.;${TRIBITS_DEPRECATE_MSG_LAST_PART}"
     )
 
   message("Testing tribits_deprecated_command() with a message")
@@ -4719,7 +4719,7 @@ function(unittest_tribits_deprecated_command)
     )
   unittest_compare_const(
     MESSAGE_WRAPPER_INPUT
-    "DEPRECATION;TriBITS command 'tribits_another_deprecated_command' is deprecated.\n\nUse tribits_some_new_command instead."
+    "DEPRECATION;TriBITS command 'tribits_another_deprecated_command' is deprecated.\n\nUse tribits_some_new_command instead.;${TRIBITS_DEPRECATE_MSG_LAST_PART}"
     )
 
   message("Testing tribits_deprecated_command() with multiple MESSAGE arguments")
@@ -4731,7 +4731,7 @@ function(unittest_tribits_deprecated_command)
     )
   unittest_compare_const(
     MESSAGE_WRAPPER_INPUT
-    "DEPRECATION;TriBITS command 'tribits_yet_another_deprecated_command' is deprecated.\n\nThis is a deprecation message with; multiple arguments."
+    "DEPRECATION;TriBITS command 'tribits_yet_another_deprecated_command' is deprecated.\n\nThis is a deprecation message with; multiple arguments.;${TRIBITS_DEPRECATE_MSG_LAST_PART}"
     )
 
 endfunction()
@@ -4756,6 +4756,11 @@ set( TRIBITS_ADD_TEST_ADD_TEST_UNITTEST TRUE )
 # Capture the add_test() arguments for tribits_add_test().
 set( TRIBITS_ADD_TEST_ADD_TEST_CAPTURE TRUE )
 
+# String for common part of tribits_deprecate() message
+set(TRIBITS_DEPRECATE_MSG_LAST_PART
+  "\n\nNOTE: To Make these warnings go away, set -D"
+  " TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE=IGNORE (see the build reference guide).")
+
 message("\n***")
 message("*** Testing misc TriBITS functions and macros")
 message("***\n")

diff --git a/tribits/CHANGELOG.md b/tribits/CHANGELOG.md
@@ -2,6 +2,18 @@
 ChangeLog for TriBITS
 ----------------------------------------
 
+## 2022-11-03:
+
+* **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

diff --git a/tribits/core/utils/TribitsDeprecatedHelpers.cmake b/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()
 

diff --git a/tribits/doc/build_ref/TribitsBuildReferenceBody.rst b/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
 -------------------------
 

diff --git a/tribits/doc/guides/TribitsCoreDetailedReference.rst b/tribits/doc/guides/TribitsCoreDetailedReference.rst
@@ -98,6 +98,7 @@ a given TriBITS project are:
 * `CMAKE_INSTALL_RPATH_USE_LINK_PATH`_
 * `MPI_EXEC_MAX_NUMPROCS`_
 * `PythonInterp_FIND_VERSION`_
+* `TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE`_
 
 These options are described below.
 
@@ -862,6 +863,19 @@ These options are described below.
 
     -D PythonInterp_FIND_VERSION="3.6.2"
 
+.. _TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE:
+
+**TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE**
+
+  Determines how the function `tribits_deprecated()`_ behaves.  To change the
+  default behavor, such as call ``message(FATAL_ERROR ...)``, set::
+
+    set(TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE_DEFAULT  FATAL_ERROR)
+
+  in the project's `<projectDir>/ProjectName.cmake`_ file, or
+  `<projectDir>/CMakeLists.txt`_ file, or on the individual package basis in
+  its `<packageDir>/CMakeLists.txt`_ file.
+
 
 TriBITS Macros and Functions
 ----------------------------