Add a framework for issuing deprecation messages (#429)

test/core/CMakeLists.txt

@@ -49,7 +49,7 @@ tribits_add_advanced_test( TestingFunctionMacro_UnitTests
       -D${PROJECT_NAME}_TRIBITS_DIR=${${PROJECT_NAME}_TRIBITS_DIR}
       -P "${CMAKE_CURRENT_SOURCE_DIR}/TestingFunctionMacro_UnitTests.cmake"
     PASS_REGULAR_EXPRESSION_ALL
-      "Final UnitTests Result: num_run = 707"
+      "Final UnitTests Result: num_run = 717"
       "Final UnitTests Result: PASSED"
   )
 

test/core/TestingFunctionMacro_UnitTests.cmake

@@ -64,6 +64,7 @@ include(TribitsGetVersionDate)
 include(TribitsTplFindIncludeDirsAndLibraries)
 include(TribitsReportInvalidTribitsUsage)
 include(TribitsGitRepoVersionInfo)
+include(TribitsDeprecatedHelpers)
 include(UnitTestHelpers)
 include(GlobalSet)
 include(GlobalNullSet)
@@ -4579,6 +4580,120 @@ function(unittest_tribits_eti_generate_macros)
 endfunction()
 
 
+function(unittest_tribits_deprecated)
+
+  message("\n***")
+  message("*** Testing tribits_deprecated()")
+  message("***\n")
+
+  set(MESSAGE_WRAPPER_UNIT_TEST_MODE  TRUE)
+
+  message("Testing tribits_deprecated() with TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE unset")
+  unset(TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE)
+  global_set(MESSAGE_WRAPPER_INPUT)
+  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"
+    )
+
+  message("Testing tribits_deprecated() with TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE set to empty string")
+  set(TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE "")
+  global_set(MESSAGE_WRAPPER_INPUT)
+  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"
+    )
+
+  message("Testing tribits_deprecated() with TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE set to DEPRECATION")
+  set(TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE "DEPRECATION")
+  global_set(MESSAGE_WRAPPER_INPUT)
+  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"
+    )
+
+  message("Testing tribits_deprecated() with TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE set to AUTHOR_WARNING")
+  set(TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE "AUTHOR_WARNING")
+  global_set(MESSAGE_WRAPPER_INPUT)
+  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"
+    )
+
+  message("Testing tribits_deprecated() with TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE set to SEND_ERROR")
+  set(TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE "SEND_ERROR")
+  global_set(MESSAGE_WRAPPER_INPUT)
+  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"
+    )
+
+  message("Testing tribits_deprecated() with TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE set to FATAL_ERROR")
+  set(TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE "FATAL_ERROR")
+  global_set(MESSAGE_WRAPPER_INPUT)
+  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"
+    )
+
+  message("Testing tribits_deprecated() with TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE set to INVALID")
+  set(TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE "INVALID")
+  global_set(MESSAGE_WRAPPER_INPUT)
+  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'"
+    )
+
+endfunction()
+
+
+function(unittest_tribits_deprecated_command)
+
+  message("\n***")
+  message("*** Testing tribits_deprecated_command()")
+  message("***\n")
+
+  set(MESSAGE_WRAPPER_UNIT_TEST_MODE  TRUE)
+
+  message("Testing tribits_deprecated_command() with TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE unset")
+  unset(TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE)
+  global_set(MESSAGE_WRAPPER_INPUT)
+  tribits_deprecated_command(tribits_some_deprecated_command)
+  unittest_compare_const(
+    MESSAGE_WRAPPER_INPUT
+    "DEPRECATION;TriBITS command 'tribits_some_deprecated_command' is deprecated."
+    )
+
+  message("Testing tribits_deprecated_command() with TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE set to AUTHOR_WARNING")
+  set(TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE "AUTHOR_WARNING")
+  global_set(MESSAGE_WRAPPER_INPUT)
+  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."
+    )
+
+  message("Testing tribits_deprecated_command() with a message")
+  unset(TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE)
+  global_set(MESSAGE_WRAPPER_INPUT)
+  tribits_deprecated_command(tribits_another_deprecated_command
+    MESSAGE "Use tribits_some_new_command instead."
+    )
+  unittest_compare_const(
+    MESSAGE_WRAPPER_INPUT
+    "DEPRECATION;TriBITS command 'tribits_another_deprecated_command' is deprecated.\n\nUse tribits_some_new_command instead."
+    )
+
+endfunction()
+
+
 ################################################################################
 #
 # Execute the unit tests
@@ -4664,9 +4779,16 @@ unittest_tribits_add_eti_instantiations_cumulative()
 unittest_tribits_eti_mangle_symbol()
 unittest_tribits_eti_generate_macros()
 
+message("\n***")
+message("*** Testing deprecation helpers")
+message("***\n")
+
+unittest_tribits_deprecated()
+unittest_tribits_deprecated_command()
+
 message("\n***")
 message("*** Determine final result of all unit tests")
 message("***\n")
 
 # Pass in the number of expected tests that must pass!
-unittest_final_result(707)
+unittest_final_result(717)

tribits/core/package_arch/TribitsGlobalMacros.cmake

@@ -71,6 +71,7 @@ include(Split)
 include(TimingUtils)
 include(SetDefaultAndFromEnv) # Used by some call-back files
 include(TribitsFilepathHelpers)
+include(TribitsDeprecatedHelpers)
 
 # Standard CMake includes
 include(CheckIncludeFileCXX)
@@ -958,6 +959,13 @@ macro(tribits_define_global_options_and_define_extra_repos)
     CACHE BOOL
     "Set to 'ON' to see the machine load for advanced tests." )
 
+  tribits_add_enum_cache_var(TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE
+    DEFAULT_VAL "DEPRECATION"
+    DOC_STRING "Mode for dealing with usage of TriBITS deprecated functionality"
+    ALLOWED_STRINGS_LIST ${TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE_ALL_VALID_VALUES}
+    IS_ADVANCED
+    )
+
   mark_as_advanced(BUILD_TESTING)
   mark_as_advanced(CMAKE_BACKWARDS_COMPATIBILITY)
   mark_as_advanced(DART_TESTING_TIMEOUT)

tribits/core/utils/TribitsDeprecatedHelpers.cmake

@@ -0,0 +1,113 @@
+# @HEADER
+# ************************************************************************
+#
+# TriBITS: Tribal Build, Integrate, and Test System
+# Copyright 2013 Sandia Corporation
+#
+# Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation,
+# the U.S. Government retains certain rights in this software.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# 1. Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+#
+# 2. Redistributions in binary form must reproduce the above copyright
+# notice, this list of conditions and the following disclaimer in the
+# documentation and/or other materials provided with the distribution.
+#
+# 3. Neither the name of the Corporation nor the names of the
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
+# EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+# ************************************************************************
+# @HEADER
+
+include(MessageWrapper)
+include(TribitsParseArgumentsHelpers)
+
+
+set(TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE_VALUES_THAT_CALL_MESSAGE
+  DEPRECATION  AUTHOR_WARNING  SEND_ERROR  FATAL_ERROR
+  )
+set(TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE_VALUES_THAT_DONT_CALL_MESSAGE
+  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}
+  )
+
+
+# @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.
+#
+# Usage::
+#
+#   tribits_deprecated(<message>)
+#
+function(tribits_deprecated  message)
+  if ("${TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE}" STREQUAL "")
+    set(TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE DEPRECATION)
+  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}" "${message}")
+  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()
+
+
+# @FUNCTION: tribits_deprecated_command()
+#
+# Notify the user that a TriBITS function or macro is deprecated. This should
+# be the first command called at the top of any deprecated function or macro.
+#
+# Usage::
+#
+#   tribits_deprecated_command(<name>
+#     [MESSAGE <message>]
+#     )
+#
+function(tribits_deprecated_command  name)
+  # Parse input arguments
+  set(argOneValArgKeywords  MESSAGE)
+  cmake_parse_arguments(PARSE_ARGV  1  PREFIX
+    ""   # options
+    "${argOneValArgKeywords}"   # one_value_keywords
+    ""   # multi_value_keywords
+    )
+  tribits_check_for_unparsed_arguments(PREFIX)
+
+  set(deprecationMessage "TriBITS command '${name}' is deprecated.")
+  if (NOT "${PREFIX_MESSAGE}" STREQUAL "")
+    string(APPEND deprecationMessage "\n\n${PREFIX_MESSAGE}")
+  endif()
+
+  tribits_deprecated("${deprecationMessage}")
+endfunction()

tribits/doc/guides/UtilsMacroFunctionDocTemplate.rst

@@ -40,6 +40,8 @@
 @FUNCTION: timer_get_rel_seconds() +
 @FUNCTION: timer_print_rel_time() +
 @FUNCTION: tribits_add_enum_cache_var() +
+@FUNCTION: tribits_deprecated() +
+@FUNCTION: tribits_deprecated_command() +
 @FUNCTION: tribits_strip_quotes_from_str() +
 @FUNCTION: unittest_compare_const() +
 @FUNCTION: unittest_has_substr_const() +