From 8c3ffe05e1293e64c8d10bcd68092fe9de9673ff Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Martin=20Ho=C5=99e=C5=88ovsk=C3=BD?=
 <martin.horenovsky@gmail.com>
Date: Sun, 20 Jul 2025 21:40:18 +0200
Subject: [PATCH] Skeleton for applying deprecation warnings

---
 BUILD.bazel                                   |  2 ++
 CMake/CatchConfigOptions.cmake                |  1 +
 docs/configuration.md                         | 15 +++++++++++++++
 src/CMakeLists.txt                            |  1 +
 src/catch2/catch_all.hpp                      |  1 +
 src/catch2/catch_user_config.hpp.in           | 10 ++++++++++
 .../internal/catch_deprecation_macro.hpp      | 19 +++++++++++++++++++
 src/catch2/meson.build                        |  1 +
 8 files changed, 50 insertions(+)
 create mode 100644 src/catch2/internal/catch_deprecation_macro.hpp

diff --git a/BUILD.bazel b/BUILD.bazel
index 0499beaa..e8d7802e 100644
--- a/BUILD.bazel
+++ b/BUILD.bazel
@@ -32,6 +32,7 @@ expand_template(
         "#cmakedefine CATCH_CONFIG_CPP17_STRING_VIEW": "",
         "#cmakedefine CATCH_CONFIG_CPP17_UNCAUGHT_EXCEPTIONS": "",
         "#cmakedefine CATCH_CONFIG_CPP17_VARIANT": "",
+        "#cmakedefine CATCH_CONFIG_DEPRECATION_ANNOTATIONS": "",
         "#cmakedefine CATCH_CONFIG_DISABLE_EXCEPTIONS_CUSTOM_HANDLER": "",
         "#cmakedefine CATCH_CONFIG_DISABLE_EXCEPTIONS": "",
         "#cmakedefine CATCH_CONFIG_DISABLE_STRINGIFICATION": "",
@@ -55,6 +56,7 @@ expand_template(
         "#cmakedefine CATCH_CONFIG_NO_CPP17_STRING_VIEW": "",
         "#cmakedefine CATCH_CONFIG_NO_CPP17_UNCAUGHT_EXCEPTIONS": "",
         "#cmakedefine CATCH_CONFIG_NO_CPP17_VARIANT": "",
+        "#cmakedefine CATCH_CONFIG_NO_DEPRECATION_ANNOTATIONS": "",
         "#cmakedefine CATCH_CONFIG_NO_GETENV": "",
         "#cmakedefine CATCH_CONFIG_NO_GLOBAL_NEXTAFTER": "",
         "#cmakedefine CATCH_CONFIG_NO_POSIX_SIGNALS": "",
diff --git a/CMake/CatchConfigOptions.cmake b/CMake/CatchConfigOptions.cmake
index f61a9657..b12ac641 100644
--- a/CMake/CatchConfigOptions.cmake
+++ b/CMake/CatchConfigOptions.cmake
@@ -44,6 +44,7 @@ set(_OverridableOptions
   "GETENV"
   "EXPERIMENTAL_STATIC_ANALYSIS_SUPPORT"
   "USE_BUILTIN_CONSTANT_P"
+  "DEPRECATION_ANNOTATIONS"
 )
 
 foreach(OptionName ${_OverridableOptions})
diff --git a/docs/configuration.md b/docs/configuration.md
index f268ba50..182606ea 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -263,6 +263,21 @@ namespace Catch {
 }
 ```
 
+
+## Disabling deprecation warnings
+
+> Introduced in Catch2 X.Y.Z
+
+Catch2 has started using the C++ macro `[[deprecated]]` to mark things
+that are deprecated and should not be used any more. If you need to
+temporarily disable these warnings, use
+
+    CATCH_CONFIG_NO_DEPRECATION_ANNOTATIONS
+
+Catch2 currently does not support more fine-grained deprecation warning
+control, nor do we plan to.
+
+
 ## Overriding Catch's debug break (`-b`)
 
 > [Introduced](https://github.com/catchorg/Catch2/pull/1846) in Catch2 2.11.2.
diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt
index 49b2d1d1..9930c484 100644
--- a/src/CMakeLists.txt
+++ b/src/CMakeLists.txt
@@ -85,6 +85,7 @@ set(IMPL_HEADERS
   ${SOURCES_DIR}/internal/catch_debug_console.hpp
   ${SOURCES_DIR}/internal/catch_debugger.hpp
   ${SOURCES_DIR}/internal/catch_decomposer.hpp
+  ${SOURCES_DIR}/internal/catch_deprecation_macro.hpp
   ${SOURCES_DIR}/internal/catch_enforce.hpp
   ${SOURCES_DIR}/internal/catch_enum_values_registry.hpp
   ${SOURCES_DIR}/internal/catch_errno_guard.hpp
diff --git a/src/catch2/catch_all.hpp b/src/catch2/catch_all.hpp
index 0d173715..5893b590 100644
--- a/src/catch2/catch_all.hpp
+++ b/src/catch2/catch_all.hpp
@@ -66,6 +66,7 @@
 #include <catch2/internal/catch_debug_console.hpp>
 #include <catch2/internal/catch_debugger.hpp>
 #include <catch2/internal/catch_decomposer.hpp>
+#include <catch2/internal/catch_deprecation_macro.hpp>
 #include <catch2/internal/catch_enforce.hpp>
 #include <catch2/internal/catch_enum_values_registry.hpp>
 #include <catch2/internal/catch_errno_guard.hpp>
diff --git a/src/catch2/catch_user_config.hpp.in b/src/catch2/catch_user_config.hpp.in
index 3acda688..70ad24dd 100644
--- a/src/catch2/catch_user_config.hpp.in
+++ b/src/catch2/catch_user_config.hpp.in
@@ -187,6 +187,16 @@
 #endif
 
 
+#cmakedefine CATCH_CONFIG_DEPRECATION_ANNOTATIONS
+#cmakedefine CATCH_CONFIG_NO_DEPRECATION_ANNOTATIONS
+
+#if defined( CATCH_CONFIG_DEPRECATION_ANNOTATIONS ) && \
+    defined( CATCH_CONFIG_NO_DEPRECATION_ANNOTATIONS )
+#    error Cannot force DEPRECATION_ANNOTATIONS to both ON and OFF
+#endif
+
+
+
 // ------
 // Simple toggle defines
 // their value is never used and they cannot be overridden
diff --git a/src/catch2/internal/catch_deprecation_macro.hpp b/src/catch2/internal/catch_deprecation_macro.hpp
new file mode 100644
index 00000000..7834882b
--- /dev/null
+++ b/src/catch2/internal/catch_deprecation_macro.hpp
@@ -0,0 +1,19 @@
+
+//              Copyright Catch2 Authors
+// Distributed under the Boost Software License, Version 1.0.
+//   (See accompanying file LICENSE.txt or copy at
+//        https://www.boost.org/LICENSE_1_0.txt)
+
+// SPDX-License-Identifier: BSL-1.0
+#ifndef CATCH_DEPRECATION_MACRO_HPP_INCLUDED
+#define CATCH_DEPRECATION_MACRO_HPP_INCLUDED
+
+#include <catch2/catch_user_config.hpp>
+
+#if !defined( CATCH_CONFIG_NO_DEPRECATION_ANNOTATIONS )
+#    define DEPRECATED( msg ) [[deprecated( msg )]]
+#else
+#    define DEPRECATED( msg )
+#endif
+
+#endif // CATCH_DEPRECATION_MACRO_HPP_INCLUDED
diff --git a/src/catch2/meson.build b/src/catch2/meson.build
index 90a04f00..77aa180a 100644
--- a/src/catch2/meson.build
+++ b/src/catch2/meson.build
@@ -92,6 +92,7 @@ internal_headers = [
   'internal/catch_debug_console.hpp',
   'internal/catch_debugger.hpp',
   'internal/catch_decomposer.hpp',
+  'internal/catch_deprecation_macro.hpp',
   'internal/catch_enforce.hpp',
   'internal/catch_enum_values_registry.hpp',
   'internal/catch_errno_guard.hpp',