ENH: Add CTK_DEPRECATED_SINCE API deprecation framework

Introduces a versioned API deprecation system modeled after Qt's
QT_DEPRECATED_SINCE so that future PRs can evolve CTK public APIs
without breaking external projects.

New header Libs/ctkDeprecated.h provides:

  CTK_VERSION_CHECK(major, minor, patch)
  CTK_DEPRECATED_SINCE(major, minor)

CMakeLists.txt adds a CTK_DISABLE_DEPRECATED_BEFORE cache variable
(hex 0xMMmmpp, default 0x000000 = keep all). ctkMacroBuildLib.cmake
propagates the configured value as a PUBLIC compile definition so
downstream consumers automatically inherit the project-wide setting,
and adds ${CTK_SOURCE_DIR}/Libs to each library's include path so
that ctkDeprecated.h can be included from anywhere in the build tree.

Libs/ctkDeprecated.h is installed to ${CTK_INSTALL_INCLUDE_DIR} so
that installed CTK headers can use the macros against external
consumers.

This commit only adds the framework. No CTK API is migrated yet.
Follow-up PRs will use CTK_DEPRECATED_SINCE() to evolve specific
APIs (e.g. ctkDICOMModalities) one at a time.

Assisted-by: Claude Code -- mechanical refactor of commontk#1411 to isolate
  the deprecation framework from the ctkDICOMModalities migration

Author: hjmjohnson

CMake/LastConfigureStep/CTKGenerateCTKConfig.cmake

@@ -150,6 +150,8 @@ foreach(lib ${CTK_LIBRARIES} CTKTesting)
   list(APPEND _include_dirs ${${lib}_INCLUDE_DIRS})
   set(CTK_CONFIG_CODE "${CTK_CONFIG_CODE}set(${lib}_INCLUDE_DIRS \"${${lib}_INCLUDE_DIRS}\")\n")
 endforeach()
+# ctkDeprecated.h lives directly under Libs/; build-tree consumers need it on the include path.
+list(APPEND _include_dirs ${CTK_SOURCE_DIR}/Libs)
 list(REMOVE_DUPLICATES _include_dirs)
 set(CTK_CONFIG_CODE "${CTK_CONFIG_CODE}set(CTK_INCLUDE_DIRS \"${_include_dirs}\")\n")
 set(CTK_CONFIG_CODE "${CTK_CONFIG_CODE}# CTK library directories that could be used for linking\n")

CMake/ctkMacroBuildLib.cmake

@@ -63,6 +63,7 @@ macro(ctkMacroBuildLib)
   set(my_includes
     ${CMAKE_CURRENT_SOURCE_DIR}
     ${CMAKE_CURRENT_BINARY_DIR}
+    ${CTK_SOURCE_DIR}/Libs            # for ctkDeprecated.h
     )
 
   # Add the include directories from the library dependencies
@@ -111,8 +112,11 @@ ${${MY_EXPORT_CUSTOM_CONTENT_FROM_VARIABLE}}
     ${MY_RESOURCES}
     )
 
-  target_compile_definitions(${lib_name} PRIVATE
-    HAVE_QT${CTK_QT_VERSION}
+  target_compile_definitions(${lib_name}
+    PUBLIC
+      CTK_DISABLE_DEPRECATED_BEFORE=${CTK_DISABLE_DEPRECATED_BEFORE}
+    PRIVATE
+      HAVE_QT${CTK_QT_VERSION}
     )
 
   # Configure CMake Qt automatic code generation

CMakeLists.txt

@@ -171,6 +171,14 @@ set(CTK_PATCH_VERSION 0)
 set(CTK_VERSION
     "${CTK_MAJOR_VERSION}.${CTK_MINOR_VERSION}.${CTK_PATCH_VERSION}")
 
+# CTK_DISABLE_DEPRECATED_BEFORE controls which deprecated CTK APIs are compiled in.
+# Format is the hex encoding 0xMMmmpp (one byte each for major / minor / patch).
+# Example: -DCTK_DISABLE_DEPRECATED_BEFORE=0x000100 hides APIs deprecated in or before 0.1.0.
+# The default 0x000000 keeps all deprecated APIs available.
+# See Libs/ctkDeprecated.h for the CTK_DEPRECATED_SINCE() helper macro.
+set(CTK_DISABLE_DEPRECATED_BEFORE "0x000000" CACHE STRING
+    "Disable CTK APIs deprecated in or before this version (hex: 0xMMmmpp)")
+
 # Append the library version information to the library target
 # properties.  A parent project may set its own properties and/or may
 # block this.
@@ -290,6 +298,10 @@ foreach(file
   install(FILES ${file} DESTINATION ${CTK_INSTALL_CMAKE_DIR} COMPONENT Development)
 endforeach()
 
+# Public CTK headers that are not specific to any single library.
+install(FILES Libs/ctkDeprecated.h
+  DESTINATION ${CTK_INSTALL_INCLUDE_DIR} COMPONENT Development)
+
 install(FILES
   CMake/ctkLinkerAsNeededFlagCheck/CMakeLists.txt
   CMake/ctkLinkerAsNeededFlagCheck/A.cpp

Libs/ctkDeprecated.h

@@ -0,0 +1,56 @@
+/*=========================================================================
+
+  Library:   CTK
+
+  Copyright (c) Kitware Inc.
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0.txt
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+
+=========================================================================*/
+
+#ifndef __ctkDeprecated_h
+#define __ctkDeprecated_h
+
+// CTK API deprecation framework, modeled after Qt's QT_DEPRECATED_SINCE.
+//
+// Usage in a CTK header:
+//
+//   #include <ctkDeprecated.h>
+//
+//   #if CTK_DEPRECATED_SINCE(0, 1)
+//     CTK_FOO_EXPORT void oldApi();   // deprecated as of CTK 0.1
+//   #endif
+//
+// Downstream projects can hide deprecated APIs by defining
+// CTK_DISABLE_DEPRECATED_BEFORE at compile time, e.g.
+//
+//   -DCTK_DISABLE_DEPRECATED_BEFORE=0x000100   # hide APIs deprecated in or before 0.1.0
+//
+// The CTK build propagates the configured value as a PUBLIC compile
+// definition so consumers automatically inherit the project-wide setting
+// (see CMake/ctkMacroBuildLib.cmake).
+
+// Encode a (major, minor, patch) triple into a comparable hex value.
+#define CTK_VERSION_CHECK(major, minor, patch) (((major) << 16) | ((minor) << 8) | (patch))
+
+// Default: keep all deprecated APIs available.
+#ifndef CTK_DISABLE_DEPRECATED_BEFORE
+#  define CTK_DISABLE_DEPRECATED_BEFORE 0x000000
+#endif
+
+// Evaluates to true when an API deprecated in (major, minor) is still compiled
+// in; APIs deprecated in or before CTK_DISABLE_DEPRECATED_BEFORE are hidden.
+#define CTK_DEPRECATED_SINCE(major, minor) \
+    (CTK_VERSION_CHECK(major, minor, 0) > CTK_DISABLE_DEPRECATED_BEFORE)
+
+#endif