[SYCL] Improve SYCL library versioning macro

sycl/CMakeLists.txt

@@ -188,10 +188,9 @@ set(SYCL_EXT_ONEAPI_BACKEND_CUDA ${LLVM_HAS_NVPTX_TARGET})
 set(SYCL_EXT_ONEAPI_BACKEND_HIP ${LLVM_HAS_AMDGPU_TARGET})
 
 # Configure SYCL version macro
-set(sycl_inc_dir ${CMAKE_CURRENT_SOURCE_DIR}/include)
-set(sycl_src_dir ${CMAKE_CURRENT_SOURCE_DIR}/source)
-string(TIMESTAMP __SYCL_COMPILER_VERSION "%Y%m%d")
-configure_file("source/version.hpp.in" "${SYCL_INCLUDE_BUILD_DIR}/sycl/version.hpp")
+set(SYCL_ROOT_SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR})
+set(sycl_src_dir ${SYCL_ROOT_SOURCE_DIR}/source)
+include(SYCLVersionFromVCS)
 configure_file("source/feature_test.hpp.in" "${SYCL_INCLUDE_BUILD_DIR}/sycl/feature_test.hpp")
 
 # Generate device_aspect_macros.hpp
@@ -217,6 +216,7 @@ install(FILES
 include(AddBoostMp11Headers)
 include(FetchBoostUnorderedHeaders)
 
+set(sycl_inc_dir ${SYCL_ROOT_SOURCE_DIR}/include)
 # This is workaround to detect changes (add or modify) in subtree which
 # are not detected by copy_directory command.
 # TODO: detect and process remove header/directory case

sycl/cmake/modules/SYCLVersionFromVCS.cmake

@@ -0,0 +1,32 @@
+# Helper utility to generate sycl/version.hpp file which contains various
+# identifiers which can be used to distinguish different builds between each
+# other:
+#
+# __LIBSYCL_TIMESTAMP - timestamp of the latest commit made into sycl/ directory
+# in YYYYMMDD format
+#
+# __SYCL_COMPILER_VERSION - date when configure step was launched in YYYYMMDD
+# format. Deprecated
+#
+# Note: it may not always be the case that CMake configuration step was re-run
+# when a new commits is added and therefore, execute_process won't be re-run and
+# the hash won't be updated. It is not considered to be a problem, because for
+# local incremental builds made during the library/headers development the date
+# doesn't matter much and we can guarantee it to be always correct when we do
+# nightly builds.
+
+# Grab the date of the latest commit in sycl folder
+execute_process(
+  # date in YYYYMMDD mode, see strftime for reference
+  COMMAND git log -1 --format=%ad --date=format:%Y%m%d -- ${SYCL_ROOT_SOURCE_DIR}
+  OUTPUT_VARIABLE __LIBSYCL_TIMESTAMP
+  OUTPUT_STRIP_TRAILING_WHITESPACE
+)
+
+# Legacy thing for backwards compatibility. Use of the current date is not
+# reliable, because we can always make new build from older commits.
+string(TIMESTAMP __SYCL_COMPILER_VERSION "%Y%m%d")
+configure_file(
+  "${sycl_src_dir}/version.hpp.in"
+  "${SYCL_INCLUDE_BUILD_DIR}/sycl/version.hpp"
+)

sycl/doc/PreprocessorMacros.md

@@ -57,6 +57,11 @@ This file describes macros that have effect on SYCL compiler and run-time.
 
 ## Version macros
 
+- `__LIBSYCL_TIMESTAMP` is set to an integer literal which corresponds to a date
+  when the latest commit into `sycl/` subproject was done. It could be used
+  to distinguish between different library builds (which includes SYCL headers)
+  to workaround any bugs, or API/ABI-breaking changes. The format is `YYYYMMDD`.
+
 - `__LIBSYCL_MAJOR_VERSION` is set to SYCL runtime library major version.
 - `__LIBSYCL_MINOR_VERSION` is set to SYCL runtime library minor version.
 - `__LIBSYCL_PATCH_VERSION` is set to SYCL runtime library patch version.

sycl/source/version.hpp.in

@@ -1,12 +1,36 @@
-//==------ version.hpp --- SYCL compiler version macro ---------*- C++ -*---==//
+//==------- version.hpp --- SYCL library version macro ---------*- C++ -*---==//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
+// __SYCL_COMPILER_VERSION is a legacy macro which does not represent a compiler
+// version, but instead only conveys a date when sycl library was built.
+
+#if /* defined(__GNUC__) || */ defined(__clang__)
+// clang supports GCC-style pragma messages, but GCC does not!
+// include/sycl/version.hpp error: missing binary operator before token "("
+//   14 | #define __SYCL_COMPILER_VERSION _Pragma("GCC warning \"..\"") 20241120
+
+#cmakedefine __SYCL_COMPILER_VERSION _Pragma(                                                 \
+    "GCC warning \"__SYCL_COMPILER_VERSION is deprecated, use __LIBSYCL_TIMESTAMP instead\"") \
+    ${__SYCL_COMPILER_VERSION}
+#elif defined(_MSC_VER)
+#cmakedefine __SYCL_COMPILER_VERSION ${__SYCL_COMPILER_VERSION}
+// It seems like MSVC ignores that pragma if its embedded into a macro
+// definition, so we have it on a standalone line
+_Pragma("deprecated(\"__SYCL_COMPILER_VERSION\")")
+#else
+// As a fallback, we still define the macro, but without a deprecation warning.
+// This path is only expected to be taken when 3rd-party host compiler is used
+// and that is not clang/msvc
 #cmakedefine __SYCL_COMPILER_VERSION ${__SYCL_COMPILER_VERSION}
+#endif
+
+#cmakedefine __LIBSYCL_TIMESTAMP ${__LIBSYCL_TIMESTAMP}
+
 #define __LIBSYCL_MAJOR_VERSION ${SYCL_MAJOR_VERSION}
 #define __LIBSYCL_MINOR_VERSION ${SYCL_MINOR_VERSION}
 #define __LIBSYCL_PATCH_VERSION ${SYCL_PATCH_VERSION}

sycl/test/libsycl-timestamp.cpp

@@ -0,0 +1,9 @@
+// RUN: %clangxx -fsycl -fsyntax-only -Xclang -verify %s
+// expected-no-diagnostics
+
+#include <sycl/sycl.hpp>
+
+#ifndef __LIBSYCL_TIMESTAMP
+#error "__LIBSYCL_TIMESTAMP is expected to be defined by sycl.hpp"
+Some weird code to cause compilation error
+#endif

sycl/test/warnings/sycl-compiler-version-cl.cpp

@@ -0,0 +1,10 @@
+// RUN: %clangxx -fsycl -fsycl-host-compiler=cl %s \
+// RUN:     -fsycl-host-compiler-options="/std:c++17 /Zc:__cplusplus" -c \
+// RUN:     -o %t.out | FileCheck %s
+// REQUIRES: windows
+
+#include <sycl/sycl.hpp>
+
+// CHECK: '__SYCL_COMPILER_VERSION': name was marked as #pragma deprecated
+#if __SYCL_COMPILER_VERSION >= 2024
+#endif

sycl/test/warnings/sycl-compiler-version-clang.cpp

@@ -0,0 +1,7 @@
+// RUN: %clangxx -fsycl %s -fsyntax-only -Xclang -verify
+
+#include <sycl/sycl.hpp>
+
+// expected-warning@+1 {{__SYCL_COMPILER_VERSION is deprecated, use __LIBSYCL_TIMESTAMP instead}}
+#if __SYCL_COMPILER_VERSION >= 2024
+#endif

sycl/test/warnings/sycl-compiler-version-gcc.cpp

@@ -0,0 +1,12 @@
+// RUN: %clangxx -fsycl -fsycl-host-compiler=g++ %s -c %t.out | FileCheck %s
+// XFAIL: *
+// It seems like gcc doesn't properly support _Pragma directive as its own
+// documentation says. Therefore, for gcc as host compiler we don't currently
+// emit a deprecation warning.
+// REQUIRES: linux
+
+#include <sycl/sycl.hpp>
+
+// CHECK: __SYCL_COMPILER_VERSION is deprecated, use __LIBSYCL_TIMESTAMP instead
+#if __SYCL_COMPILER_VERSION >= 2024
+#endif

sycl/unittests/misc/CMakeLists.txt

@@ -4,4 +4,5 @@ add_sycl_unittest(MiscTests SHARED
   CircularBuffer.cpp
   OsUtils.cpp
   PropertyUtils.cpp
+  LibSYCLTimestamp.cpp
 )

sycl/unittests/misc/LibSYCLTimestamp.cpp

@@ -0,0 +1,55 @@
+//==------------------------ LibSYCLTimestamp.cpp --------------------------==//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include <sycl/version.hpp>
+
+#include <gtest/gtest.h>
+
+#include <string>
+#include <cctype>
+
+#define _STR(e) #e
+#define STR(e) _STR(e)
+
+TEST(LibSYCLTimestamp, Format) {
+  // __LIBSYCL_TIMESTAMP format is YYYYMMDD
+  std::string Timestamp = STR(__LIBSYCL_TIMESTAMP);
+
+  ASSERT_EQ(Timestamp.size(), 8u);
+
+  for (char C : Timestamp) {
+    ASSERT_TRUE(std::isdigit(C));
+  }
+
+  constexpr size_t Y0 = 0;
+  constexpr size_t Y1 = 1;
+  constexpr size_t M0 = 4;
+  constexpr size_t M1 = 5;
+  constexpr size_t D0 = 6;
+  constexpr size_t D1 = 7;
+
+  // Safe enough test for the next 900+ years
+  ASSERT_EQ(Timestamp[Y0], '2');
+  // Safe enough test for the next 70+ years
+  ASSERT_EQ(Timestamp[Y1], '0');
+
+  ASSERT_TRUE(Timestamp[M0] == '0' || Timestamp[M1] == '1');
+  if (Timestamp[M0] == '1')
+    ASSERT_TRUE(Timestamp[M1] >= '0' && Timestamp[M1] <= '2');
+  ASSERT_FALSE(Timestamp[M0] == '0' && Timestamp[M1] == '0');
+
+  ASSERT_TRUE(Timestamp[D0] >= '0' && Timestamp[D0] <= '3');
+  if (Timestamp[D0] == '3')
+    ASSERT_TRUE(Timestamp[D1] == '0' || Timestamp[D1] == '1');
+  ASSERT_FALSE(Timestamp[D0] == '0' && Timestamp[D1] == '0');
+}
+
+TEST(LibSYCLTimestasmp, BasicAcceptance) {
+  // Date when this feature was introduced
+  ASSERT_TRUE(__LIBSYCL_TIMESTAMP >= 20241128);
+}