diff --git a/RELEASE-NOTES.md b/RELEASE-NOTES.md index b38d9f3444..61114d38a9 100644 --- a/RELEASE-NOTES.md +++ b/RELEASE-NOTES.md @@ -18,6 +18,11 @@ The Axom project release numbers follow [Semantic Versioning](http://semver.org/ ## [Unreleased] - Release date yyyy-mm-dd +### Added +- Slic: Adds the `AXOM_ENABLE_SLIC_DEBUG_MACROS` CMake option to enable the + `SLIC_ASSERT`, `SLIC_CHECK`, and `SLIC_DEBUG` macro families independently of + `AXOM_DEBUG`. + ## [Version 0.15.0] - Release date 2026-08-28 ### Added diff --git a/src/axom/slic/CMakeLists.txt b/src/axom/slic/CMakeLists.txt index be27eb1328..a1823ed65f 100644 --- a/src/axom/slic/CMakeLists.txt +++ b/src/axom/slic/CMakeLists.txt @@ -82,6 +82,12 @@ axom_add_library(NAME slic FOLDER axom/slic ) +if(AXOM_ENABLE_SLIC_DEBUG_MACROS) + blt_add_target_definitions(TO slic + SCOPE PUBLIC + TARGET_DEFINITIONS AXOM_ENABLE_SLIC_DEBUG_MACROS) +endif() + axom_write_unified_header( NAME slic HEADERS ${slic_headers} ) diff --git a/src/axom/slic/docs/sphinx/sections/wrapping_slic_in_macros.rst b/src/axom/slic/docs/sphinx/sections/wrapping_slic_in_macros.rst index 75a470b116..243bb3968d 100644 --- a/src/axom/slic/docs/sphinx/sections/wrapping_slic_in_macros.rst +++ b/src/axom/slic/docs/sphinx/sections/wrapping_slic_in_macros.rst @@ -109,6 +109,15 @@ operations when certain flags are toggled on or functions are called. Other macr such as ``SLIC_ERROR`` and ``SLIC_ASSERT`` can be made not collective when certain functions are called. +The ``SLIC_ASSERT``, ``SLIC_CHECK``, and ``SLIC_DEBUG`` families are active +when the ``AXOM_DEBUG_DEFINE`` CMake setting enables ``AXOM_DEBUG``. The +default value, ``AXOM_DEBUG_DEFINE=DEFAULT``, enables them in ``Debug`` and +``RelWithDebInfo`` configurations. Set ``AXOM_DEBUG_DEFINE=ON`` to enable +``AXOM_DEBUG`` in every configuration or ``AXOM_DEBUG_DEFINE=OFF`` to disable +it in every configuration. These Slic macro families can also be enabled +independently of ``AXOM_DEBUG`` by configuring Axom with +``-DAXOM_ENABLE_SLIC_DEBUG_MACROS=ON``. + The table below details the built-in SLIC macros as well as some notes about when they are collective calls: .. list-table:: SLIC macro availability and collective behavior @@ -121,7 +130,8 @@ The table below details the built-in SLIC macros as well as some notes about whe * - ``SLIC_ASSERT`` ``SLIC_ASSERT_MSG`` - - - Only available in debug configurations (i.e. when ``AXOM_DEBUG`` is defined) + - - Available when enabled by ``AXOM_DEBUG_DEFINE`` or + ``AXOM_ENABLE_SLIC_DEBUG_MACROS=ON`` - Not available in device code - - Collective by default - Collective after calling ``slic::enableAbortOnError()`` @@ -129,7 +139,8 @@ The table below details the built-in SLIC macros as well as some notes about whe * - ``SLIC_CHECK`` ``SLIC_CHECK_MSG`` - - - Only available in debug configurations (i.e. when ``AXOM_DEBUG`` is defined) + - - Available when enabled by ``AXOM_DEBUG_DEFINE`` or + ``AXOM_ENABLE_SLIC_DEBUG_MACROS=ON`` - Not available in device code - - Not collective by default - Collective after ``slic::debug::checksAreErrors`` is set to ``true``, defaults to ``false`` @@ -144,7 +155,8 @@ The table below details the built-in SLIC macros as well as some notes about whe ``SLIC_DEBUG_ROOT_ONCE`` ``SLIC_DEBUG_ROOT_IF_ONCE`` ``SLIC_DEBUG_PRINT_CONTAINER_ONCE`` - - - Only available in debug configurations (i.e. when ``AXOM_DEBUG`` is defined) + - - Available when enabled by ``AXOM_DEBUG_DEFINE`` or + ``AXOM_ENABLE_SLIC_DEBUG_MACROS=ON`` - - Never * - ``SLIC_INFO`` @@ -186,13 +198,15 @@ Doxygen generated API documentation on Macros can be found here: `SLIC Macros <. Consider the following rules of thumb when choosing from the above logging macros: -* The `SLIC_ABORT` and `SLIC_CHECK` macros are typically used to check preconditions/postconditions of functions - and help catch developer errors. They are only available in debug configurations (i.e. when `AXOM_DEBUG` is available). +* The `SLIC_ASSERT` and `SLIC_CHECK` macros are typically used to check preconditions/postconditions of functions + and help catch developer errors. They are available when enabled by + ``AXOM_DEBUG_DEFINE`` or ``AXOM_ENABLE_SLIC_DEBUG_MACROS=ON``. * `SLIC_WARNING` and `SLIC_ERROR` are available in all configurations and can be used to check for conditions that might affect the results. They are also useful for validating user inputs. -* `SLIC_INFO` and `SLIC_DEBUG` macros are typically used to provide information about the state of an application. - The `SLIC_*_IF` variants can be used to conditionally log messages. `SLIC_DEBUG` macros are compiled out in non-debug configurations - (i.e. their messages will not get logged), while `SLIC_INFO` macros are always available. +* `SLIC_INFO` and `SLIC_DEBUG` macros are typically used to provide information about the state of an application. + The `SLIC_*_IF` variants can be used to conditionally log messages. `SLIC_DEBUG` macros are compiled out unless + enabled by ``AXOM_DEBUG_DEFINE`` or ``AXOM_ENABLE_SLIC_DEBUG_MACROS=ON``, + while `SLIC_INFO` macros are always available. * The `SLIC_*_ROOT` variants can help reduce logging verbosity when called in an MPI application, especially if all MPI ranks are expected to have the same data (for example, if a value was broadcast from one rank to all the other ranks). * The `SLIC_*_ONCE` variants can help reduce logging verbosity when only the first invocation at a call-site is necessary. diff --git a/src/axom/slic/interface/slic_macros.hpp b/src/axom/slic/interface/slic_macros.hpp index 0d2ed6a7cc..bbc7b662b8 100644 --- a/src/axom/slic/interface/slic_macros.hpp +++ b/src/axom/slic/interface/slic_macros.hpp @@ -299,7 +299,7 @@ ///@} // Use complete debug macros when not on device -#if defined(AXOM_DEBUG) && !defined(AXOM_DEVICE_CODE) +#if (defined(AXOM_DEBUG) || defined(AXOM_ENABLE_SLIC_DEBUG_MACROS)) && !defined(AXOM_DEVICE_CODE) //----------------------------------------------------------------------------- /// @{ @@ -324,7 +324,9 @@ * \param [in] EXP user-supplied boolean expression. * * \warning This macro calls processAbort() iff EXP is false. - * \note This macro is only active when AXOM_DEBUG is defined. + * \note This macro is active when the AXOM_DEBUG_DEFINE CMake setting enables + * AXOM_DEBUG (by default in Debug and RelWithDebInfo builds), or when + * AXOM_ENABLE_SLIC_DEBUG_MACROS=ON. * * Usage: * \code @@ -342,7 +344,9 @@ * \param [in] msg user-supplied message * * \warning This macro calls processAbort() iff EXP is false. - * \note This macro is only active when AXOM_DEBUG is defined. + * \note This macro is active when the AXOM_DEBUG_DEFINE CMake setting enables + * AXOM_DEBUG (by default in Debug and RelWithDebInfo builds), or when + * AXOM_ENABLE_SLIC_DEBUG_MACROS=ON. * \see SLIC_ASSERT( EXP ) * * Usage: @@ -399,7 +403,9 @@ * application is not aborted. * * \param [in] EXP user-supplied boolean expression. - * \note This macro is only active when AXOM_DEBUG is defined. + * \note This macro is active when the AXOM_DEBUG_DEFINE CMake setting enables + * AXOM_DEBUG (by default in Debug and RelWithDebInfo builds), or when + * AXOM_ENABLE_SLIC_DEBUG_MACROS=ON. * * Usage: * \code @@ -416,7 +422,9 @@ * \param [in] EXP user-supplied boolean expression. * \param [in] msg user-supplied message * - * \note This macro is only active when AXOM_DEBUG is defined. + * \note This macro is active when the AXOM_DEBUG_DEFINE CMake setting enables + * AXOM_DEBUG (by default in Debug and RelWithDebInfo builds), or when + * AXOM_ENABLE_SLIC_DEBUG_MACROS=ON. * \see SLIC_DEBUG( EXP ) * * Usage: @@ -456,7 +464,7 @@ // Use assert when on device (note that messages are omitted). // Device HIP assert() tested with rocm@6.1.2 // (ROCm support for device assert() begins with version 5.1.0). -#elif defined(AXOM_DEBUG) && defined(AXOM_DEVICE_CODE) +#elif (defined(AXOM_DEBUG) || defined(AXOM_ENABLE_SLIC_DEBUG_MACROS)) && defined(AXOM_DEVICE_CODE) #define SLIC_ASSERT(EXP) assert(EXP) #define SLIC_ASSERT_MSG(EXP, msg) assert(EXP) #define SLIC_CHECK(EXP) assert(EXP) @@ -469,7 +477,7 @@ #define SLIC_CHECK(ignore_EXP) ((void)0) #define SLIC_CHECK_MSG(ignore_EXP, ignore_msg) ((void)0) -#endif /* END ifdef AXOM_DEBUG */ +#endif /* END if debug macros are enabled */ /*! * \def SLIC_INFO( msg ) @@ -662,7 +670,7 @@ #define SLIC_INFO_ROOT_IF_ONCE(EXP, msg) \ SLIC_DETAIL_LOG_IF_ONCE(SLIC_INFO_IF, (EXP) && (axom::slic::isRoot()), msg) -#ifdef AXOM_DEBUG +#if defined(AXOM_DEBUG) || defined(AXOM_ENABLE_SLIC_DEBUG_MACROS) /*! * \def SLIC_DEBUG( msg ) @@ -670,7 +678,9 @@ * * \param [in] msg user-supplied message * - * \note The SLIC_Debug macro is active when AXOM_DEBUG is defined. + * \note This macro is active when the AXOM_DEBUG_DEFINE CMake setting enables + * AXOM_DEBUG (by default in Debug and RelWithDebInfo builds), or when + * AXOM_ENABLE_SLIC_DEBUG_MACROS=ON. * * Usage: * \code @@ -686,7 +696,9 @@ * * \param [in] msg user-supplied message * - * \note The SLIC_DEBUG_ONCE macro is active when AXOM_DEBUG is defined. + * \note This macro is active when the AXOM_DEBUG_DEFINE CMake setting enables + * AXOM_DEBUG (by default in Debug and RelWithDebInfo builds), or when + * AXOM_ENABLE_SLIC_DEBUG_MACROS=ON. * * Usage: * \code @@ -703,7 +715,9 @@ * \param [in] EXP user-supplied boolean expression. * \param [in] msg user-supplied message. * - * \note The SLIC_DEBUG_IF macro is active when AXOM_DEBUG is defined. + * \note This macro is active when the AXOM_DEBUG_DEFINE CMake setting enables + * AXOM_DEBUG (by default in Debug and RelWithDebInfo builds), or when + * AXOM_ENABLE_SLIC_DEBUG_MACROS=ON. * * Usage: * \code @@ -729,7 +743,9 @@ * \param [in] EXP user-supplied boolean expression. * \param [in] msg user-supplied message. * - * \note The SLIC_DEBUG_IF_ONCE macro is active when AXOM_DEBUG is defined. + * \note This macro is active when the AXOM_DEBUG_DEFINE CMake setting enables + * AXOM_DEBUG (by default in Debug and RelWithDebInfo builds), or when + * AXOM_ENABLE_SLIC_DEBUG_MACROS=ON. * * Usage: * \code @@ -745,7 +761,9 @@ * * \param [in] msg user-supplied message. * - * \note The SLIC_DEBUG_ROOT macro is active when AXOM_DEBUG is defined. + * \note This macro is active when the AXOM_DEBUG_DEFINE CMake setting enables + * AXOM_DEBUG (by default in Debug and RelWithDebInfo builds), or when + * AXOM_ENABLE_SLIC_DEBUG_MACROS=ON. * * Usage: * \code @@ -761,7 +779,9 @@ * * \param [in] msg user-supplied message. * - * \note The SLIC_DEBUG_ROOT_ONCE macro is active when AXOM_DEBUG is defined. + * \note This macro is active when the AXOM_DEBUG_DEFINE CMake setting enables + * AXOM_DEBUG (by default in Debug and RelWithDebInfo builds), or when + * AXOM_ENABLE_SLIC_DEBUG_MACROS=ON. * * Usage: * \code @@ -779,7 +799,9 @@ * \param [in] EXP user-supplied boolean expression. * \param [in] msg user-supplied message. * - * \note The SLIC_DEBUG_ROOT_IF macro is active when AXOM_DEBUG is defined. + * \note This macro is active when the AXOM_DEBUG_DEFINE CMake setting enables + * AXOM_DEBUG (by default in Debug and RelWithDebInfo builds), or when + * AXOM_ENABLE_SLIC_DEBUG_MACROS=ON. * * Usage: * \code @@ -796,7 +818,9 @@ * \param [in] EXP user-supplied boolean expression. * \param [in] msg user-supplied message. * - * \note The SLIC_DEBUG_ROOT_IF_ONCE macro is active when AXOM_DEBUG is defined. + * \note This macro is active when the AXOM_DEBUG_DEFINE CMake setting enables + * AXOM_DEBUG (by default in Debug and RelWithDebInfo builds), or when + * AXOM_ENABLE_SLIC_DEBUG_MACROS=ON. * * Usage: * \code @@ -815,7 +839,9 @@ * \param [in] name The name of the container in the printed message. * \param [in] container The container (array, vector, view). * - * \note The SLIC_DEBUG_PRINT_CONTAINER macro is active when AXOM_DEBUG is defined. + * \note This macro is active when the AXOM_DEBUG_DEFINE CMake setting enables + * AXOM_DEBUG (by default in Debug and RelWithDebInfo builds), or when + * AXOM_ENABLE_SLIC_DEBUG_MACROS=ON. * * Usage: * \code @@ -840,7 +866,9 @@ * \param [in] name The name of the container in the printed message. * \param [in] container The container (array, vector, view). * - * \note The SLIC_DEBUG_PRINT_CONTAINER_ONCE macro is active when AXOM_DEBUG is defined. + * \note This macro is active when the AXOM_DEBUG_DEFINE CMake setting enables + * AXOM_DEBUG (by default in Debug and RelWithDebInfo builds), or when + * AXOM_ENABLE_SLIC_DEBUG_MACROS=ON. * * Usage: * \code diff --git a/src/axom/slic/tests/CMakeLists.txt b/src/axom/slic/tests/CMakeLists.txt index c6c95f2372..0e5af05c09 100644 --- a/src/axom/slic/tests/CMakeLists.txt +++ b/src/axom/slic/tests/CMakeLists.txt @@ -14,6 +14,7 @@ set(serial_slic_tests slic_asserts.cpp slic_fmt.cpp slic_interface.cpp + slic_enable_debug_macros.cpp slic_macros.cpp slic_scoped_abort.cpp slic_uninit.cpp ) diff --git a/src/axom/slic/tests/slic_asserts.cpp b/src/axom/slic/tests/slic_asserts.cpp index 19478e10c4..cb312adada 100644 --- a/src/axom/slic/tests/slic_asserts.cpp +++ b/src/axom/slic/tests/slic_asserts.cpp @@ -67,7 +67,7 @@ class SetFixtureS : public ::testing::Test public: void SetUp() { -#ifdef AXOM_DEBUG +#if defined(AXOM_DEBUG) || defined(AXOM_ENABLE_SLIC_DEBUG_MACROS) EXPECT_DEATH_IF_SUPPORTED(SLIC_ASSERT_MSG(false, "Testing assert in fixture setup"), ""); #else SLIC_WARNING("Testing warning in fixture setup"); @@ -83,7 +83,7 @@ class SetFixtureT : public ::testing::Test public: void TearDown() { -#ifdef AXOM_DEBUG +#if defined(AXOM_DEBUG) || defined(AXOM_ENABLE_SLIC_DEBUG_MACROS) EXPECT_DEATH_IF_SUPPORTED(SLIC_ASSERT_MSG(false, "Testing assert in fixture teardown"), ""); #else SLIC_WARNING("Testing warning in fixture teardown"); @@ -115,7 +115,7 @@ class SetFixtureD : public ::testing::Test TEST(slic_usage, in_test) { SLIC_ASSERT_MSG(true, "Testing SLIC assert (true) in test body"); -#ifdef AXOM_DEBUG +#if defined(AXOM_DEBUG) || defined(AXOM_ENABLE_SLIC_DEBUG_MACROS) EXPECT_DEATH_IF_SUPPORTED(SLIC_ASSERT_MSG(false, "Testing SLIC assert(false) in test body"), "") << "SLIC assert (false) from a test"; #else @@ -128,7 +128,7 @@ TEST(slic_usage, in_test) TEST(slic_usage, in_ctor) { -#ifdef AXOM_DEBUG +#if defined(AXOM_DEBUG) || defined(AXOM_ENABLE_SLIC_DEBUG_MACROS) EXPECT_DEATH_IF_SUPPORTED(AssertCtor(), "") << " SLIC assert from class .ctor "; #else AssertCtor(); @@ -138,7 +138,7 @@ TEST(slic_usage, in_ctor) TEST(slic_usage, in_method) { AssertMethod am; -#ifdef AXOM_DEBUG +#if defined(AXOM_DEBUG) || defined(AXOM_ENABLE_SLIC_DEBUG_MACROS) EXPECT_DEATH_IF_SUPPORTED(am.foo(), "") << " SLIC assert from class method "; #else am.foo(); @@ -147,7 +147,7 @@ TEST(slic_usage, in_method) TEST(slic_usage, in_dtor) { -#ifdef AXOM_DEBUG +#if defined(AXOM_DEBUG) || defined(AXOM_ENABLE_SLIC_DEBUG_MACROS) EXPECT_DEATH_IF_SUPPORTED(AssertDtor(), "") << " SLIC assert from class .ctor "; #else AssertDtor(); diff --git a/src/axom/slic/tests/slic_enable_debug_macros.cpp b/src/axom/slic/tests/slic_enable_debug_macros.cpp new file mode 100644 index 0000000000..d7cb1ad92a --- /dev/null +++ b/src/axom/slic/tests/slic_enable_debug_macros.cpp @@ -0,0 +1,36 @@ +// Copyright (c) Lawrence Livermore National Security, LLC and other +// Axom Project Contributors. See top-level LICENSE and COPYRIGHT +// files for dates and other details. +// +// SPDX-License-Identifier: (BSD-3-Clause) + +#include "axom/config.hpp" + +// Exercise the Slic debug macro guard independently of AXOM_DEBUG. +#ifdef AXOM_DEBUG + #undef AXOM_DEBUG +#endif + +#define AXOM_ENABLE_SLIC_DEBUG_MACROS 1 + +#include "axom/slic.hpp" + +#include "gtest/gtest.h" + +TEST(slic_enable_debug_macros, enabled_without_axom_debug) +{ + axom::slic::SimpleLogger logger; + int evaluation_count = 0; + + SLIC_ASSERT(++evaluation_count == 1); + SLIC_CHECK(++evaluation_count == 2); + SLIC_DEBUG(++evaluation_count); + + EXPECT_EQ(evaluation_count, 3); +} + +int main(int argc, char* argv[]) +{ + ::testing::InitGoogleTest(&argc, argv); + return RUN_ALL_TESTS(); +} diff --git a/src/axom/slic/tests/slic_macros.cpp b/src/axom/slic/tests/slic_macros.cpp index b2d0576369..64ab1a8e77 100644 --- a/src/axom/slic/tests/slic_macros.cpp +++ b/src/axom/slic/tests/slic_macros.cpp @@ -326,7 +326,7 @@ TEST(slic_macros, test_info_macros) TEST(slic_macros, test_debug_macros) { EXPECT_TRUE(slic::internal::is_stream_empty()); -#ifdef AXOM_DEBUG +#if defined(AXOM_DEBUG) || defined(AXOM_ENABLE_SLIC_DEBUG_MACROS) EXPECT_SLIC_LOG(SLIC_DEBUG("test debug message"), "DEBUG", "test debug message"); EXPECT_SLIC_ONCE(SLIC_DEBUG_ONCE("test debug message once"), "DEBUG", "test debug message once"); @@ -351,7 +351,7 @@ TEST(slic_macros, test_debug_macros) // clang-format on #else - // SLIC_DEBUG macros only log messages when AXOM_DEBUG is defined + // SLIC_DEBUG macros only log messages when Slic debug macros are enabled SLIC_DEBUG("test debug message"); SLIC_DEBUG_ONCE("test debug message"); @@ -409,10 +409,10 @@ TEST(slic_macros, test_assert_macros) constexpr int val = 42; SLIC_ASSERT(val < 0); expected_line_number = __LINE__ - 1; -#if defined(AXOM_DEBUG) && !defined(AXOM_DEVICE_CODE) +#if (defined(AXOM_DEBUG) || defined(AXOM_ENABLE_SLIC_DEBUG_MACROS)) && !defined(AXOM_DEVICE_CODE) check_level_msg_line_file("ERROR", "Failed Assert: val < 0", expected_line_number); #else - // SLIC_ASSERT macros only log messages when AXOM_DEBUG is defined + // SLIC_ASSERT macros only log messages when Slic debug macros are enabled AXOM_UNUSED_VAR(val); AXOM_UNUSED_VAR(expected_line_number); EXPECT_TRUE(slic::internal::is_stream_empty()); @@ -423,12 +423,12 @@ TEST(slic_macros, test_assert_macros) SLIC_ASSERT_MSG(val < 0, "val should be negative!"); expected_line_number = __LINE__ - 1; -#if defined(AXOM_DEBUG) && !defined(AXOM_DEVICE_CODE) +#if (defined(AXOM_DEBUG) || defined(AXOM_ENABLE_SLIC_DEBUG_MACROS)) && !defined(AXOM_DEVICE_CODE) check_level_msg_line_file("ERROR", "Failed Assert: val < 0\nval should be negative!", expected_line_number); #else - // SLIC_ASSERT macros only log messages when AXOM_DEBUG is defined + // SLIC_ASSERT macros only log messages when Slic debug macros are enabled AXOM_UNUSED_VAR(val); AXOM_UNUSED_VAR(expected_line_number); EXPECT_TRUE(slic::internal::is_stream_empty()); @@ -444,10 +444,10 @@ TEST(slic_macros, test_check_macros) constexpr int val = 42; SLIC_CHECK(val < 0); expected_line_number = __LINE__ - 1; -#if defined(AXOM_DEBUG) && !defined(AXOM_DEVICE_CODE) +#if (defined(AXOM_DEBUG) || defined(AXOM_ENABLE_SLIC_DEBUG_MACROS)) && !defined(AXOM_DEVICE_CODE) check_level_msg_line_file("WARNING", "Failed Check: val < 0", expected_line_number); #else - // SLIC_CHECK macros only log messages when AXOM_DEBUG is defined + // SLIC_CHECK macros only log messages when Slic debug macros are enabled AXOM_UNUSED_VAR(val); AXOM_UNUSED_VAR(expected_line_number); EXPECT_TRUE(slic::internal::is_stream_empty()); @@ -458,12 +458,12 @@ TEST(slic_macros, test_check_macros) SLIC_CHECK_MSG(val < 0, "val should be negative!"); expected_line_number = __LINE__ - 1; -#if defined(AXOM_DEBUG) && !defined(AXOM_DEVICE_CODE) +#if (defined(AXOM_DEBUG) || defined(AXOM_ENABLE_SLIC_DEBUG_MACROS)) && !defined(AXOM_DEVICE_CODE) check_level_msg_line_file("WARNING", "Failed Check: val < 0\nval should be negative!", expected_line_number); #else - // SLIC_CHECK macros only log messages when AXOM_DEBUG is defined + // SLIC_CHECK macros only log messages when Slic debug macros are enabled AXOM_UNUSED_VAR(val); AXOM_UNUSED_VAR(expected_line_number); EXPECT_TRUE(slic::internal::is_stream_empty()); diff --git a/src/axom/slic/tests/slic_macros_parallel.cpp b/src/axom/slic/tests/slic_macros_parallel.cpp index 98ec942fc1..b1465b7d59 100644 --- a/src/axom/slic/tests/slic_macros_parallel.cpp +++ b/src/axom/slic/tests/slic_macros_parallel.cpp @@ -881,7 +881,7 @@ TEST_P(SlicMacrosParallel, test_debug_macros) EXPECT_TRUE(slic::internal::are_all_streams_empty()); -#ifdef AXOM_DEBUG +#if defined(AXOM_DEBUG) || defined(AXOM_ENABLE_SLIC_DEBUG_MACROS) EXPECT_SLIC_LOG_ALL_RANKS(SLIC_DEBUG("test debug message"), "DEBUG", "test debug message"); @@ -1015,7 +1015,7 @@ TEST_P(SlicMacrosParallel, test_debug_macros) slic::internal::clear_streams(); #else - // SLIC_DEBUG macros only log messages when AXOM_DEBUG is defined + // SLIC_DEBUG macros only log messages when Slic debug macros are enabled AXOM_UNUSED_VAR(expected_line_number); SLIC_DEBUG("test debug message"); @@ -1088,7 +1088,7 @@ TEST_P(SlicMacrosParallel, test_abort_error_macros) slic::disableAbortOnError(); } -#if defined(AXOM_DEBUG) && !defined(AXOM_DEVICE_CODE) +#if (defined(AXOM_DEBUG) || defined(AXOM_ENABLE_SLIC_DEBUG_MACROS)) && !defined(AXOM_DEVICE_CODE) bool abort_enabled = slic::isAbortOnErrorsEnabled(); @@ -1177,7 +1177,7 @@ TEST_P(SlicMacrosParallel, test_abort_error_macros) } axom::slic::setIsRoot(true); #else - // SLIC_ASSERT macros only log messages when AXOM_DEBUG is defined + // SLIC_ASSERT macros only log messages when Slic debug macros are enabled // Quiet warning about has_aborted and reset_state never being referenced AXOM_UNUSED_VAR(has_aborted); @@ -1221,7 +1221,7 @@ TEST_P(SlicMacrosParallel, test_abort_warning_macros) slic::disableAbortOnWarning(); } -#if defined(AXOM_DEBUG) && !defined(AXOM_DEVICE_CODE) +#if (defined(AXOM_DEBUG) || defined(AXOM_ENABLE_SLIC_DEBUG_MACROS)) && !defined(AXOM_DEVICE_CODE) bool abort_enabled = slic::isAbortOnWarningsEnabled(); @@ -1314,7 +1314,7 @@ TEST_P(SlicMacrosParallel, test_abort_warning_macros) #else AXOM_UNUSED_VAR(expected_line_number); - // SLIC_CHECK macros only log messages when AXOM_DEBUG is defined + // SLIC_CHECK macros only log messages when Slic debug macros are enabled EXPECT_TRUE(slic::internal::are_all_streams_empty()); #endif @@ -1332,7 +1332,7 @@ TEST_P(SlicMacrosParallel, test_assert_macros) EXPECT_TRUE(slic::internal::are_all_streams_empty()); constexpr int val = 42; -#if defined(AXOM_DEBUG) && !defined(AXOM_DEVICE_CODE) +#if (defined(AXOM_DEBUG) || defined(AXOM_ENABLE_SLIC_DEBUG_MACROS)) && !defined(AXOM_DEVICE_CODE) EXPECT_SLIC_LOG_ALL_RANKS(SLIC_ASSERT(val < 0), "ERROR", "Failed Assert: val < 0"); @@ -1342,7 +1342,7 @@ TEST_P(SlicMacrosParallel, test_assert_macros) // clang-format on #else - // SLIC_ASSERT macros only log messages when AXOM_DEBUG is defined + // SLIC_ASSERT macros only log messages when Slic debug macros are enabled AXOM_UNUSED_VAR(val); SLIC_ASSERT(val < 0); @@ -1365,7 +1365,7 @@ TEST_P(SlicMacrosParallel, test_check_macros) constexpr int val = 42; -#if defined(AXOM_DEBUG) && !defined(AXOM_DEVICE_CODE) +#if (defined(AXOM_DEBUG) || defined(AXOM_ENABLE_SLIC_DEBUG_MACROS)) && !defined(AXOM_DEVICE_CODE) EXPECT_SLIC_LOG_ALL_RANKS(SLIC_CHECK(val < 0), "WARNING", "Failed Check: val < 0"); // Single line - Placement of ")" matters for __LINE__ for slic call and checking @@ -1374,7 +1374,7 @@ TEST_P(SlicMacrosParallel, test_check_macros) // clang-format on #else - // SLIC_CHECK macros only log messages when AXOM_DEBUG is defined + // SLIC_CHECK macros only log messages when Slic debug macros are enabled AXOM_UNUSED_VAR(val); SLIC_CHECK(val < 0); diff --git a/src/axom/slic/tests/slic_uninit.cpp b/src/axom/slic/tests/slic_uninit.cpp index 6f7dc13838..91cc5e339f 100644 --- a/src/axom/slic/tests/slic_uninit.cpp +++ b/src/axom/slic/tests/slic_uninit.cpp @@ -22,7 +22,7 @@ void testInit(const std::string& label, std::function f) TEST(slic_uninit, log_macro) { -#ifdef AXOM_DEBUG +#if defined(AXOM_DEBUG) || defined(AXOM_ENABLE_SLIC_DEBUG_MACROS) testInit("debug message", []() { SLIC_DEBUG("test debug message"); }); testInit("debug_if", []() { SLIC_DEBUG_IF(true, "debug message should print"); }); #endif @@ -37,7 +37,7 @@ TEST(slic_uninit, log_macro) TEST(slic_uninit, tests_and_asserts) { -#ifdef AXOM_DEBUG +#if defined(AXOM_DEBUG) || defined(AXOM_ENABLE_SLIC_DEBUG_MACROS) testInit("check", []() { SLIC_CHECK(false); }); testInit("check_msg", []() { SLIC_CHECK_MSG(false, "checked false; this should print"); }); testInit("assert", []() { SLIC_ASSERT(false); }); diff --git a/src/cmake/AxomOptions.cmake b/src/cmake/AxomOptions.cmake index 3be6be1b51..424c1083e4 100644 --- a/src/cmake/AxomOptions.cmake +++ b/src/cmake/AxomOptions.cmake @@ -56,6 +56,10 @@ option(AXOM_ENABLE_TOOLS "Enables Axom Tools" ON) option(AXOM_ENABLE_TUTORIALS "Builds Axom tutorials as part of the Axom build" ON) mark_as_advanced(AXOM_ENABLE_TUTORIALS) +option(AXOM_ENABLE_SLIC_DEBUG_MACROS + "Enables SLIC_ASSERT, SLIC_CHECK, and SLIC_DEBUG macros independently of AXOM_DEBUG" + OFF) + #------------------------------------------------------------------------------ # Test execution controls #------------------------------------------------------------------------------ diff --git a/src/cmake/axom-config.cmake.in b/src/cmake/axom-config.cmake.in index 66987f6603..38cbd5d7fc 100644 --- a/src/cmake/axom-config.cmake.in +++ b/src/cmake/axom-config.cmake.in @@ -79,6 +79,7 @@ if(NOT AXOM_FOUND) set(AXOM_DEBUG_DEFINE_STRING "@AXOM_DEBUG_DEFINE_STRING@") # Component-specific options + set(AXOM_ENABLE_SLIC_DEBUG_MACROS "@AXOM_ENABLE_SLIC_DEBUG_MACROS@") set(AXOM_SIDRE_IO_USE_SCALAR_STATE_STRING "@AXOM_SIDRE_IO_USE_SCALAR_STATE_STRING@") #---------------------------------------------------------------------------- diff --git a/src/docs/sphinx/coding_guide/sec10_dev_macros.rst b/src/docs/sphinx/coding_guide/sec10_dev_macros.rst index c70a5bcaf8..22a414a0f6 100644 --- a/src/docs/sphinx/coding_guide/sec10_dev_macros.rst +++ b/src/docs/sphinx/coding_guide/sec10_dev_macros.rst @@ -79,6 +79,16 @@ for a debug build **must** be guarded using the `AXOM_DEBUG` macro:: // rest of method implementation } +The ``AXOM_DEBUG_DEFINE`` CMake setting controls when ``AXOM_DEBUG`` is +defined. Its supported values are: + +* ``DEFAULT``: define it for ``Debug`` and ``RelWithDebInfo`` configurations. +* ``ON``: define it for every configuration. +* ``OFF``: do not define it in any configuration. + +Thus, ``AXOM_DEBUG`` normally follows the build configuration, but +``AXOM_DEBUG_DEFINE`` can explicitly override that behavior. + Axom provides various other macro constants for conditionally-compiled code which reflect which built-in and third-party libraries are being used and which Axom components are enabled. The macro constants are defined in the @@ -131,29 +141,32 @@ problematic usage. Here's an example of common *SLIC* macro usage in AXOM:: return bar; } -This example uses slic macros that are only active when the code is compiled -in debug mode. When compiled in release mode, for example, the macros are -empty and so do nothing. Also, when a condition is encountered that is -problematic, such as 'in_val < 0' or 'in_foo == nullptr', the code will +This example uses Slic macros that are active when ``AXOM_DEBUG_DEFINE`` +enables ``AXOM_DEBUG`` or when Axom is configured with +``AXOM_ENABLE_SLIC_DEBUG_MACROS=ON``. Otherwise, the macros are empty and do +nothing. When a condition is encountered that is problematic, such as +'in_val < 0' or 'in_foo == nullptr', the code will emit the condition and an optional message and not halt. This allows calling code to catch the issue (in this case a null return value) and react. There are other macros (e.g., SLIC_ASSERT) that will halt the code if that is desired. -Slic macros operate in one of two compilation-defined modes. Some macros are -active only in for a debug compile. Others are active for any build type. +Slic macros operate in one of two compilation-defined modes. Some macros are +controlled by the debug-macro settings described above. Others are active for +any build type. Macros provided for each of these modes can be used to halt the code or not after describing the condition that triggered them. The following table summarizes the SLIC macros. -============== ================ ==================== - Macro type When active? Halts code? -============== ================ ==================== - ERROR Always Yes - WARNING Always No - ASSERT Debug only Yes - CHECK Debug only No -============== ================ ==================== +============== ========================================== ==================== + Macro type When active? Halts code? +============== ========================================== ==================== + ERROR Always Yes + WARNING Always No + ASSERT When Slic debug macros are enabled Yes + CHECK When Slic debug macros are enabled No + DEBUG When Slic debug macros are enabled No +============== ========================================== ==================== Typically, we use macros ERROR/WARNING macros rarely. They are used primarily to catch cases that are obvious programming errors or would put an application @@ -161,7 +174,7 @@ in a state where continuing is seriously in doubt. CHECK macros are used most often, since they provide useful debugging information and do not halt the code -- they allow users to catch cases from which they can recover. ASSERT macros are used in cases where halting the code is desired, but only in -debug mode. +builds where Slic debug macros are enabled. Please see the `slic.hpp` header file to see which macros are available and how to use them. @@ -170,4 +183,3 @@ how to use them. benefit users and other developers. We want to help folks use our software correctly and not "spam" them with too much information. - diff --git a/src/docs/sphinx/quickstart_guide/config_build.rst b/src/docs/sphinx/quickstart_guide/config_build.rst index 87e1c27b20..cc262f3faa 100644 --- a/src/docs/sphinx/quickstart_guide/config_build.rst +++ b/src/docs/sphinx/quickstart_guide/config_build.rst @@ -398,35 +398,41 @@ to specify paths to Axom external dependencies. Axom build options, compiler support, and parallelism ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -+------------------------------+---------+----------------------------------------+ -| OPTION | Default | Description | -+==============================+=========+========================================+ -| AXOM_DEBUG_DEFINE | DEFAULT | Controls whether the `AXOM_DEBUG` | -| | | compiler define is enabled | -| | | | -| | | By DEFAULT, it is enabled for | -| | | `Debug` and `RelWithDebInfo` configs | -| | | but this can be overridden by setting | -| | | `AXOM_DEBUG_DEFINE` to `ON` or `OFF` | -+------------------------------+---------+----------------------------------------+ -| ENABLE_ALL_WARNINGS | ON | Enable extra compiler warnings | -| | | in all build targets | -+------------------------------+---------+----------------------------------------+ -| ENABLE_WARNINGS_AS_ERRORS | OFF | Compiler warnings treated as errors | -+------------------------------+---------+----------------------------------------+ -| BUILD_SHARED_LIBS | OFF | Build shared libraries. | -| | | Default is Static libraries | -+------------------------------+---------+----------------------------------------+ -| ENABLE_FORTRAN | OFF | Enable Fortran compiler support | -+------------------------------+---------+----------------------------------------+ -| AXOM_ENABLE_MPI | OFF | Enable MPI | -+------------------------------+---------+----------------------------------------+ -| AXOM_ENABLE_OPENMP | OFF | Enable OpenMP | -+------------------------------+---------+----------------------------------------+ -| AXOM_ENABLE_CUDA | OFF | Enable CUDA | -+------------------------------+---------+----------------------------------------+ -| AXOM_ENABLE_HIP | OFF | Enable HIP | -+------------------------------+---------+----------------------------------------+ ++-------------------------------+---------+----------------------------------------+ +| OPTION | Default | Description | ++===============================+=========+========================================+ +| AXOM_DEBUG_DEFINE | DEFAULT | Controls whether the ``AXOM_DEBUG`` | +| | | compiler define is enabled | +| | | | +| | | By ``DEFAULT``, it is enabled for | +| | | ``Debug`` and ``RelWithDebInfo`` | +| | | configurations | +| | | but this can be overridden by setting | +| | | it to ``ON`` or ``OFF`` | ++-------------------------------+---------+----------------------------------------+ +| AXOM_ENABLE_SLIC_DEBUG_MACROS | OFF | Enable the ``SLIC_ASSERT``, | +| | | ``SLIC_CHECK``, and ``SLIC_DEBUG`` | +| | | macro families independently of | +| | | ``AXOM_DEBUG`` | ++-------------------------------+---------+----------------------------------------+ +| ENABLE_ALL_WARNINGS | ON | Enable extra compiler warnings | +| | | in all build targets | ++-------------------------------+---------+----------------------------------------+ +| ENABLE_WARNINGS_AS_ERRORS | OFF | Compiler warnings treated as errors | ++-------------------------------+---------+----------------------------------------+ +| BUILD_SHARED_LIBS | OFF | Build shared libraries. | +| | | Default is Static libraries | ++-------------------------------+---------+----------------------------------------+ +| ENABLE_FORTRAN | OFF | Enable Fortran compiler support | ++-------------------------------+---------+----------------------------------------+ +| AXOM_ENABLE_MPI | OFF | Enable MPI | ++-------------------------------+---------+----------------------------------------+ +| AXOM_ENABLE_OPENMP | OFF | Enable OpenMP | ++-------------------------------+---------+----------------------------------------+ +| AXOM_ENABLE_CUDA | OFF | Enable CUDA | ++-------------------------------+---------+----------------------------------------+ +| AXOM_ENABLE_HIP | OFF | Enable HIP | ++-------------------------------+---------+----------------------------------------+ Note that, in most Axom components, node-level parallelism features, enabled with OpenMP, CUDA (NVIDIA GPUs), and HIP (AMD GPUs), are implemented using RAJA. See diff --git a/src/examples/radiuss_tutorial/lesson_01/README.md b/src/examples/radiuss_tutorial/lesson_01/README.md index 3851829caf..1fcb2de60e 100644 --- a/src/examples/radiuss_tutorial/lesson_01/README.md +++ b/src/examples/radiuss_tutorial/lesson_01/README.md @@ -66,7 +66,7 @@ We now add a `BasicLogger` instance to the application with * ``slic::message::Error``: Used for logging error messages. By default prints a stacktrace and exits the application. * ``slic::message::Warning``: Used for logging warning messages. By default, this prints a warning message and continues executing the application. * ``slic::message::Info``: Used for logging informational messages. -* ``slic::message::Debug``: Used for logging debug messages. By default, these are compiled out in ``Release`` configurations. +* ``slic::message::Debug``: Used for logging debug messages. By default, these are compiled out in ``Release`` configurations. To retain them independently of the build configuration, configure Axom with ``-DAXOM_ENABLE_SLIC_DEBUG_MACROS=ON``. We are now free to use `slic`-based logging macros throughout our application, for example: ```cpp