diff --git a/test/core/CMakeLists.txt b/test/core/CMakeLists.txt index 132e8fcba..442c5b3b8 100644 --- a/test/core/CMakeLists.txt +++ b/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" ) diff --git a/test/core/TestingFunctionMacro_UnitTests.cmake b/test/core/TestingFunctionMacro_UnitTests.cmake index f242f7992..a94ac9de3 100644 --- a/test/core/TestingFunctionMacro_UnitTests.cmake +++ b/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) diff --git a/tribits/core/package_arch/TribitsGlobalMacros.cmake b/tribits/core/package_arch/TribitsGlobalMacros.cmake index 47949d9d3..331e1823e 100644 --- a/tribits/core/package_arch/TribitsGlobalMacros.cmake +++ b/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) diff --git a/tribits/core/utils/TribitsDeprecatedHelpers.cmake b/tribits/core/utils/TribitsDeprecatedHelpers.cmake new file mode 100644 index 000000000..32931ba09 --- /dev/null +++ b/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() +# +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( +# [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() diff --git a/tribits/doc/guides/UtilsMacroFunctionDocTemplate.rst b/tribits/doc/guides/UtilsMacroFunctionDocTemplate.rst index 081f74acc..fa59e566a 100644 --- a/tribits/doc/guides/UtilsMacroFunctionDocTemplate.rst +++ b/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() +