Merge pull request #3931 from divmadan/devel/header_deprecation

[common] Add and use a macro to specify EOL for deprecated headers
PointCloudLibrary · May 7, 2020 · 32e61b5 · 32e61b5
2 parents cedac79 + 1f386ce
commit 32e61b5
Show file tree

Hide file tree

Showing 6 changed files with 48 additions and 24 deletions.
diff --git a/common/include/pcl/make_shared.h b/common/include/pcl/make_shared.h
@@ -36,7 +36,7 @@
 
 #pragma once
 
-#warning "Do not use this header, its contents have been moved to pcl/memory.h"
+PCL_DEPRECATED_HEADER(1, 13, "Use <pcl/memory.h> instead.")
 
 #include <pcl/memory.h>
 
diff --git a/common/include/pcl/pcl_macros.h b/common/include/pcl/pcl_macros.h
@@ -99,6 +99,25 @@
   #define _PCL_DEPRECATED_IMPL(Message)
 #endif
 
+// Macro for pragma operator
+#if (defined (__GNUC__) || defined(__clang__))
+  #define PCL_PRAGMA(x) _Pragma (#x)
+#elif _MSC_VER
+  #define PCL_PRAGMA(x) __pragma (#x)
+#else
+  #define PCL_PRAGMA
+#endif
+
+// Macro for emitting pragma warning for deprecated headers
+#if (defined (__GNUC__) || defined(__clang__))
+  #define _PCL_DEPRECATED_HEADER_IMPL(Message) PCL_PRAGMA (GCC warning Message)
+#elif _MSC_VER
+  #define _PCL_DEPRECATED_HEADER_IMPL(Message) PCL_PRAGMA (warning (Message))
+#else
+  #warning "You need to implement _PCL_DEPRECATED_HEADER_IMPL for this compiler"
+  #define _PCL_DEPRECATED_HEADER_IMPL(Message)
+#endif
+
 /**
  * \brief A handy way to inform the user of the removal deadline
  */
@@ -133,10 +152,33 @@
       Major,                                                                           \
       _PCL_COMPAT_MINOR_VERSION(                                                       \
           Minor,                                                                       \
-          _PCL_DEPRECATED_IMPL(_PCL_PREPARE_REMOVAL_MESSAGE(Major, Minor, Message)),    \
+          _PCL_DEPRECATED_IMPL(_PCL_PREPARE_REMOVAL_MESSAGE(Major, Minor, Message)),   \
           unneeded_deprecation),                                                       \
       major_version_mismatch)
 
+/**
+ * \brief macro for compatibility across compilers and help remove old deprecated
+ *        headers for the Major.Minor release
+ *
+ * \details compiler errors of `unneeded_header` and `major_version_mismatch`
+ * are hints to the developer that those items can be safely removed.
+ * Behavior of PCL_DEPRECATED_HEADER(1, 99, "Use file <newfile.h> instead.")
+ *   * till PCL 1.98: "This header is deprecated. Use file <newfile.h> instead. (It will be removed in PCL 1.99)"
+ *   * PCL 1.99 onwards: compiler error with "unneeded_header"
+ *   * PCL 2.0 onwards: compiler error with "major_version_mismatch"
+ */
+#define PCL_DEPRECATED_HEADER(Major, Minor, Message)                                   \
+  _PCL_COMPAT_MAJOR_VERSION(                                                           \
+      Major,                                                                           \
+      _PCL_COMPAT_MINOR_VERSION(                                                       \
+          Minor,                                                                       \
+          _PCL_DEPRECATED_HEADER_IMPL(_PCL_PREPARE_REMOVAL_MESSAGE(                    \
+              Major,                                                                   \
+              Minor,                                                                   \
+              "This header is deprecated. " Message)),                                 \
+          unneeded_header),                                                            \
+      major_version_mismatch)
+
 #if defined _WIN32
 // Define math constants, without including math.h, to prevent polluting global namespace with old math methods
 // Copied from math.h
@@ -304,24 +346,6 @@ pcl_round (float number)
     #define PCLAPI(rettype) PCL_EXTERN_C PCL_EXPORTS rettype PCL_CDECL
 #endif
 
-// Macro for pragma operator
-#if (defined (__GNUC__) || defined(__clang__))
-  #define PCL_PRAGMA(x) _Pragma (#x)
-#elif _MSC_VER
-  #define PCL_PRAGMA(x) __pragma (#x)
-#else
-  #define PCL_PRAGMA
-#endif
-
-// Macro for emitting pragma warning
-#if (defined (__GNUC__) || defined(__clang__))
-  #define PCL_PRAGMA_WARNING(x) PCL_PRAGMA (GCC warning x)
-#elif _MSC_VER
-  #define PCL_PRAGMA_WARNING(x) PCL_PRAGMA (warning (x))
-#else
-  #define PCL_PRAGMA_WARNING
-#endif
-
 //for clang cf. http://clang.llvm.org/docs/LanguageExtensions.html
 #ifndef __has_extension
   #define __has_extension(x) 0 // Compatibility with pre-3.0 compilers.

diff --git a/common/include/pcl/point_traits.h b/common/include/pcl/point_traits.h
@@ -38,6 +38,6 @@
 
 #pragma once
 
-#warning "Deprecated in favor of type_traits.h"
+PCL_DEPRECATED_HEADER(1, 13, "Use <pcl/type_traits.h> instead.")
 
 #include <pcl/type_traits.h>
diff --git a/kdtree/include/pcl/kdtree/flann.h b/kdtree/include/pcl/kdtree/flann.h
@@ -40,7 +40,7 @@
 
 #include <pcl/pcl_macros.h>
 
-PCL_PRAGMA_WARNING("This header is deprecated and will be removed in an upcoming release.")
+PCL_DEPRECATED_HEADER(1, 12, "")
 
 #if defined _MSC_VER
 #  pragma warning(disable: 4267 4244)

diff --git a/keypoints/include/pcl/keypoints/uniform_sampling.h b/keypoints/include/pcl/keypoints/uniform_sampling.h
@@ -40,7 +40,7 @@
 #pragma once
 
 #ifdef __DEPRECATED
-#warning UniformSampling is not a Keypoint anymore, use <pcl/filters/uniform_sampling.h> instead.
+PCL_DEPRECATED_HEADER(1, 12, "UniformSampling is not a Keypoint anymore, use <pcl/filters/uniform_sampling.h> instead.")
 #endif
 
 #include <pcl/filters/uniform_sampling.h>
diff --git a/tracking/include/pcl/tracking/boost.h b/tracking/include/pcl/tracking/boost.h
@@ -41,6 +41,6 @@
 
 #include <pcl/pcl_macros.h>
 
-PCL_PRAGMA_WARNING("This header is deprecated and will be removed in an upcoming release.")
+PCL_DEPRECATED_HEADER(1, 12, "")
 
 #include <boost/random.hpp>