[SYCL] Deprecate syclcompat (intel#19976)

AlexeySachkov · web-flow · commit 9c43c168f194 · 2025-09-08T12:16:05.000+02:00
This is a cherry-pick of intel#19861 Patch-by: Udit Kumar Agarwal <udit.agarwal@intel.com>
diff --git a/sycl/doc/syclcompat/README.md b/sycl/doc/syclcompat/README.md
@@ -1,3 +1,7 @@
+**⚠️ DEPRECATION NOTICE ⚠️**
+
+**SYCLcompat is deprecated and will be removed in a future release. Users are encouraged to migrate to native SYCL APIs or alternative compatibility solutions. The `syclcompat` namespace has been marked with `[[deprecated]]` attribute.**
+
 # SYCLcompat
 
 SYCLcompat is a header-only library that intends to help developers familiar
diff --git a/sycl/include/syclcompat/atomic.hpp b/sycl/include/syclcompat/atomic.hpp
@@ -40,7 +40,7 @@
 
 #include <syclcompat/traits.hpp>
 
-namespace syclcompat {
+namespace [[deprecated("syclcompat is deprecated")]] syclcompat {
 
 /// Atomically add the value operand to the value at the addr and assign the
 /// result to the value at addr.
diff --git a/sycl/include/syclcompat/defs.hpp b/sycl/include/syclcompat/defs.hpp
@@ -66,7 +66,7 @@ template <int Arg> class syclcompat_kernel_scalar;
   SYCLCOMPAT_MAKE_VERSION(SYCLCOMPAT_MAJOR_VERSION, SYCLCOMPAT_MINOR_VERSION,  \
                           SYCLCOMPAT_PATCH_VERSION)
 
-namespace syclcompat {
+namespace [[deprecated("syclcompat is deprecated")]] syclcompat {
 enum error_code { success = 0, backend_error = 1, default_error = 999 };
 /// A dummy function introduced to assist auto migration.
 /// The SYCLomatic user should replace it with a real error-handling function.
diff --git a/sycl/include/syclcompat/device.hpp b/sycl/include/syclcompat/device.hpp
@@ -56,7 +56,7 @@
 #include <sycl/properties/queue_properties.hpp>
 #include <sycl/queue.hpp>
 
-namespace syclcompat {
+namespace [[deprecated("syclcompat is deprecated")]] syclcompat {
 
 namespace detail {
 static void parse_version_string(const std::string &ver, int &major,
diff --git a/sycl/include/syclcompat/dims.hpp b/sycl/include/syclcompat/dims.hpp
@@ -26,7 +26,7 @@
 
 #include <sycl/range.hpp>
 
-namespace syclcompat {
+namespace [[deprecated("syclcompat is deprecated")]] syclcompat {
 
 class dim3 {
 public:
diff --git a/sycl/include/syclcompat/group_utils.hpp b/sycl/include/syclcompat/group_utils.hpp
@@ -38,7 +38,7 @@
 #include <syclcompat/defs.hpp>
 #include <syclcompat/math.hpp>
 
-namespace syclcompat {
+namespace [[deprecated("syclcompat is deprecated")]] syclcompat {
 namespace group {
 namespace detail {
 
diff --git a/sycl/include/syclcompat/id_query.hpp b/sycl/include/syclcompat/id_query.hpp
@@ -25,7 +25,7 @@
 #include <sycl/ext/oneapi/free_function_queries.hpp>
 #include <sycl/nd_item.hpp>
 
-namespace syclcompat {
+namespace [[deprecated("syclcompat is deprecated")]] syclcompat {
 
 using sycl::ext::oneapi::this_work_item::get_nd_item;
 
diff --git a/sycl/include/syclcompat/kernel.hpp b/sycl/include/syclcompat/kernel.hpp
@@ -54,7 +54,7 @@
 #include <sycl/nd_range.hpp>
 #include <sycl/queue.hpp>
 
-namespace syclcompat {
+namespace [[deprecated("syclcompat is deprecated")]] syclcompat {
 
 typedef void (*kernel_functor)(sycl::queue &, const sycl::nd_range<3> &,
                                unsigned int, void **, void **);
diff --git a/sycl/include/syclcompat/launch.hpp b/sycl/include/syclcompat/launch.hpp
@@ -33,7 +33,7 @@
 #include <syclcompat/dims.hpp>
 #include <syclcompat/launch_policy.hpp>
 
-namespace syclcompat {
+namespace [[deprecated("syclcompat is deprecated")]] syclcompat {
 
 namespace detail {
 
@@ -120,8 +120,8 @@ launch(const dim3 &grid, const dim3 &threads, Args... args) {
 
 } // namespace syclcompat
 
-namespace syclcompat::experimental {
-
+namespace [[deprecated("syclcompat is deprecated")]] syclcompat {
+namespace experimental {
 namespace detail {
 
 template <auto F, typename LaunchPolicy, typename... Args>
@@ -145,7 +145,6 @@ sycl::event launch(LaunchPolicy launch_policy, sycl::queue q, Args... args) {
     }
   });
 }
-
 }
 
 
@@ -161,4 +160,5 @@ sycl::event launch(LaunchPolicy launch_policy, Args... args) {
   return launch<F>(launch_policy, get_default_queue(), args...);
 }
 
-} // namespace syclcompat::experimental
+} // namespace experimental
+} // namespace syclcompat
diff --git a/sycl/include/syclcompat/launch_policy.hpp b/sycl/include/syclcompat/launch_policy.hpp
@@ -34,7 +34,7 @@
 #include <syclcompat/dims.hpp>
 #include <syclcompat/traits.hpp>
 
-namespace syclcompat {
+namespace [[deprecated("syclcompat is deprecated")]] syclcompat {
 namespace experimental {
 
 namespace sycl_exp = sycl::ext::oneapi::experimental;
diff --git a/sycl/include/syclcompat/math.hpp b/sycl/include/syclcompat/math.hpp
@@ -46,7 +46,7 @@
 #include <sycl/ext/oneapi/experimental/complex/complex.hpp>
 #include <syclcompat/traits.hpp>
 
-namespace syclcompat {
+namespace [[deprecated("syclcompat is deprecated")]] syclcompat {
 namespace detail {
 
 namespace complex_namespace = sycl::ext::oneapi::experimental;
diff --git a/sycl/include/syclcompat/memory.hpp b/sycl/include/syclcompat/memory.hpp
@@ -66,7 +66,7 @@
 #error "Only support Windows and Linux."
 #endif
 
-namespace syclcompat {
+namespace [[deprecated("syclcompat is deprecated")]] syclcompat {
 
 template <typename AllocT>
 #ifdef __SYCL_DEVICE_ONLY__
diff --git a/sycl/include/syclcompat/syclcompat.hpp b/sycl/include/syclcompat/syclcompat.hpp
@@ -22,6 +22,24 @@
 
 #pragma once
 
+// MSVC ignores [[deprecated]] attribute on namespace unless compiled with
+// /W3 or above.
+#ifdef _MSC_VER
+#define __SYCLCOMPAT_STRINGIFY(x) #x
+#define __SYCLCOMPAT_TOSTRING(x) __SYCLCOMPAT_STRINGIFY(x)
+
+#define __SYCLCOMPAT_WARNING(msg)                                              \
+  __pragma(message(__FILE__                                                    \
+                   "(" __SYCLCOMPAT_TOSTRING(__LINE__) "): warning: " msg))
+
+__SYCLCOMPAT_WARNING("syclcompat is deprecated and the deprecation warnings "
+                     "are ignored unless compiled with /W3 or above.")
+
+#undef __SYCLCOMPAT_WARNING
+#undef __SYCLCOMPAT_TOSTRING
+#undef __SYCLCOMPAT_STRINGIFY
+#endif
+
 #include <syclcompat/atomic.hpp>
 #include <syclcompat/defs.hpp>
 #include <syclcompat/device.hpp>
diff --git a/sycl/include/syclcompat/traits.hpp b/sycl/include/syclcompat/traits.hpp
@@ -33,7 +33,7 @@
 #include <sycl/nd_range.hpp>
 #include <type_traits>
 
-namespace syclcompat {
+namespace [[deprecated("syclcompat is deprecated")]] syclcompat {
 
 // Equivalent to C++20's std::type_identity (used to create non-deduced
 // contexts)
diff --git a/sycl/include/syclcompat/util.hpp b/sycl/include/syclcompat/util.hpp
@@ -65,7 +65,7 @@ __SYCL_CONVERGENT__ extern SYCL_EXTERNAL __SYCL_EXPORT
     __spirv_GroupNonUniformShuffleUp(__spv::Scope::Flag, T, unsigned) noexcept;
 #endif
 
-namespace syclcompat {
+namespace [[deprecated("syclcompat is deprecated")]] syclcompat {
 
 namespace detail {
 
diff --git a/sycl/test/syclcompat/warnings_deprecated.cpp b/sycl/test/syclcompat/warnings_deprecated.cpp
@@ -0,0 +1,50 @@
+// Test to verify that syclcompat namespace and APIs generate deprecation
+// warnings.
+
+// RUN: %clangxx -fsycl -fsyntax-only -Xclang -verify -Xclang -verify-ignore-unexpected=note,warning %s -Wall -Wextra
+
+#include <syclcompat/syclcompat.hpp>
+
+int main() {
+  // Test deprecated namespace
+  // expected-warning@+1{{'syclcompat' is deprecated}}
+  syclcompat::dim3 grid(1, 1, 1);
+
+  // expected-warning@+1{{'syclcompat' is deprecated}}
+  auto queue = syclcompat::get_default_queue();
+
+  // Test deprecated memory APIs
+  // expected-warning@+1{{'syclcompat' is deprecated}}
+  void *ptr = syclcompat::malloc(1024);
+
+  // expected-warning@+1{{'syclcompat' is deprecated}}
+  syclcompat::free(ptr);
+
+  // Test deprecated utility APIs
+  // expected-warning@+1{{'syclcompat' is deprecated}}
+  auto device_count = syclcompat::device_count();
+
+  // expected-warning@+1{{'syclcompat' is deprecated}}
+  syclcompat::wait();
+
+  // Test deprecated atomic APIs
+  int value = 42;
+  int operand = 10;
+  // expected-warning@+1{{'syclcompat' is deprecated}}
+  syclcompat::atomic_fetch_add(&value, operand);
+
+  // Test deprecated math APIs
+  // expected-warning@+1{{'syclcompat' is deprecated}}
+  auto result = syclcompat::max(1, 2);
+
+  // Test deprecated device APIs
+  // expected-warning@+1{{'syclcompat' is deprecated}}
+  syclcompat::device_info info;
+
+  // Test deprecated experimental APIs
+  // expected-warning@+1{{'syclcompat' is deprecated}}
+  syclcompat::experimental::launch_policy my_config(
+      sycl::nd_range<1>{{32}, {32}});
+
+  return 0;
+}

Original file line number	Diff line number	Diff line change
`@@ -33,7 +33,7 @@`
`33`	`33`	`#include <syclcompat/dims.hpp>`
`34`	`34`	`#include <syclcompat/launch_policy.hpp>`
`35`	`35`
`36`		`-namespace syclcompat {`
	`36`	`+namespace [[deprecated("syclcompat is deprecated")]] syclcompat {`
`37`	`37`
`38`	`38`	`namespace detail {`
`39`	`39`
`@@ -120,8 +120,8 @@ launch(const dim3 &grid, const dim3 &threads, Args... args) {`
`120`	`120`
`121`	`121`	`} // namespace syclcompat`
`122`	`122`
`123`		`-namespace syclcompat::experimental {`
`124`		`-`
	`123`	`+namespace [[deprecated("syclcompat is deprecated")]] syclcompat {`
	`124`	`+namespace experimental {`
`125`	`125`	`namespace detail {`
`126`	`126`
`127`	`127`	`template <auto F, typename LaunchPolicy, typename... Args>`
`@@ -145,7 +145,6 @@ sycl::event launch(LaunchPolicy launch_policy, sycl::queue q, Args... args) {`
`145`	`145`	`}`
`146`	`146`	`});`
`147`	`147`	`}`
`148`		`-`
`149`	`148`	`}`
`150`	`149`
`151`	`150`
`@@ -161,4 +160,5 @@ sycl::event launch(LaunchPolicy launch_policy, Args... args) {`
`161`	`160`	`return launch<F>(launch_policy, get_default_queue(), args...);`
`162`	`161`	`}`
`163`	`162`
`164`		`-} // namespace syclcompat::experimental`
	`163`	`+} // namespace experimental`
	`164`	`+} // namespace syclcompat`