[SYCL] Add -fpreview-breaking-changes option (#11629)

This commit adds the -fpreview-breaking-changes option to supersede the
SYCL2020_CONFORMANT_APIS preprocessor macro. This new option allows the
SYCL library to also make breaking changes outside a SYCL major release
by guarding breaking changes behind the __INTEL_PREVIEW_BREAKING_CHANGES
macro. When
-fpreview-breaking-changes is used together with -fsycl the compiled
program is linked against a variant of the SYCL library with the
__INTEL_PREVIEW_BREAKING_CHANGES macro defined.

---------

Signed-off-by: Larsen, Steffen <[email protected]>

Author: Steffen Larsen

buildbot/configure.py

@@ -51,6 +51,7 @@ def do_configure(args):
     llvm_build_shared_libs = 'OFF'
     llvm_enable_lld = 'OFF'
     sycl_enabled_plugins = ["opencl"]
+    sycl_preview_lib = 'ON'
 
     sycl_enable_xpti_tracing = 'ON'
     xpti_enable_werror = 'OFF'
@@ -141,6 +142,9 @@ def do_configure(args):
     if args.enable_plugin:
         sycl_enabled_plugins += args.enable_plugin
 
+    if args.disable_preview_lib:
+        sycl_preview_lib = 'OFF'
+
     install_dir = os.path.join(abs_obj_dir, "install")
 
     cmake_cmd = [
@@ -174,6 +178,7 @@ def do_configure(args):
         "-DSYCL_CLANG_EXTRA_FLAGS={}".format(sycl_clang_extra_flags),
         "-DSYCL_ENABLE_PLUGINS={}".format(';'.join(set(sycl_enabled_plugins))),
         "-DSYCL_ENABLE_KERNEL_FUSION={}".format(sycl_enable_fusion),
+        "-DSYCL_ENABLE_MAJOR_RELEASE_PREVIEW_LIB={}".format(sycl_preview_lib),
         "-DBUG_REPORT_URL=https://github.com/intel/llvm/issues",
     ]
 
@@ -256,6 +261,7 @@ def main():
     parser.add_argument("--llvm-external-projects", help="Add external projects to build. Add as comma seperated list.")
     parser.add_argument("--ci-defaults", action="store_true", help="Enable default CI parameters")
     parser.add_argument("--enable-plugin", action='append', help="Enable SYCL plugin")
+    parser.add_argument("--disable-preview-lib", action='store_true', help="Disable building of the SYCL runtime major release preview library")
     parser.add_argument("--disable-fusion", action="store_true", help="Disable the kernel fusion JIT compiler")
     parser.add_argument("--add_security_flags", type=str, choices=['none', 'default', 'sanitize'], default=None, help="Enables security flags for compile & link. Two values are supported: 'default' and 'sanitize'. 'Sanitize' option is an extension of 'default' set.")
     args = parser.parse_args()

clang/include/clang/Driver/Options.td

@@ -1306,6 +1306,14 @@ defm cuda_prec_sqrt : BoolFOption<"cuda-prec-sqrt",
 def emit_static_lib : Flag<["--"], "emit-static-lib">,
   HelpText<"Enable linker job to emit a static library.">;
 
+def fpreview_breaking_changes : Flag<["-"], "fpreview-breaking-changes">, Flags<[NoXarchOption]>,
+  Visibility<[ClangOption, CLOption]>,
+  HelpText<"When specified, it informs the compiler driver and compilation phases "
+           "that it is allowed to break backward compatibility. When this option is "
+           "specified the compiler will also set the macro __INTEL_PREVIEW_BREAKING_CHANGES.\n"
+           "When this option is used in conjunction with -fsycl, the driver will link against "
+           "an alternate form of libsycl, libsycl-preview.">;
+
 def mprintf_kind_EQ : Joined<["-"], "mprintf-kind=">, Group<m_Group>,
   HelpText<"Specify the printf lowering scheme (AMDGPU only), allowed values are "
   "\"hostcall\"(printing happens during kernel execution, this scheme "

clang/lib/Driver/ToolChains/Clang.cpp

@@ -4785,6 +4785,11 @@ void Clang::ConstructHostCompilerJob(Compilation &C, const JobAction &JA,
   if (IsMSVCHostCompiler)
     HostCompileArgs.push_back("/Zc:__cplusplus");
 
+  if (TCArgs.hasArg(options::OPT_fpreview_breaking_changes)) {
+    HostCompileArgs.push_back(IsMSVCHostCompiler ? "/D" : "-D");
+    HostCompileArgs.push_back("__INTEL_PREVIEW_BREAKING_CHANGES");
+  }
+
   // FIXME: Reuse existing toolchains which are already supported to put
   // together the options.
   // FIXME: For any potential obscure host compilers that do not use the
@@ -4992,10 +4997,19 @@ static void ProcessVSRuntimeLibrary(const ArgList &Args,
     // Add SYCL dependent library
     if (Args.hasArg(options::OPT_fsycl) &&
         !Args.hasArg(options::OPT_nolibsycl)) {
-      if (RTOptionID == options::OPT__SLASH_MDd)
-        CmdArgs.push_back("--dependent-lib=sycl" SYCL_MAJOR_VERSION "d");
-      else
-        CmdArgs.push_back("--dependent-lib=sycl" SYCL_MAJOR_VERSION);
+      if (RTOptionID == options::OPT__SLASH_MDd) {
+        if (Args.hasArg(options::OPT_fpreview_breaking_changes))
+          CmdArgs.push_back("--dependent-lib=sycl" SYCL_MAJOR_VERSION
+                            "-previewd");
+        else
+          CmdArgs.push_back("--dependent-lib=sycl" SYCL_MAJOR_VERSION "d");
+      } else {
+        if (Args.hasArg(options::OPT_fpreview_breaking_changes))
+          CmdArgs.push_back("--dependent-lib=sycl" SYCL_MAJOR_VERSION
+                            "-preview");
+        else
+          CmdArgs.push_back("--dependent-lib=sycl" SYCL_MAJOR_VERSION);
+      }
       CmdArgs.push_back("--dependent-lib=sycl-devicelib-host");
     }
   }
@@ -5309,6 +5323,9 @@ void Clang::ConstructJob(Compilation &C, const JobAction &JA,
                                  options::OPT_fno_sycl_id_queries_fit_in_int))
       A->render(Args, CmdArgs);
 
+    if (Args.hasArg(options::OPT_fpreview_breaking_changes))
+      CmdArgs.push_back("-D__INTEL_PREVIEW_BREAKING_CHANGES");
+
     if (SYCLStdArg) {
       // Use of -sycl-std=1.2.1 is deprecated. Emit a diagnostic stating so.
       // TODO: remove support at next approprate major release.
@@ -6478,10 +6495,19 @@ void Clang::ConstructJob(Compilation &C, const JobAction &JA,
   // library.
   if (Args.hasArg(options::OPT_fsycl) && !Args.hasArg(options::OPT_nolibsycl)) {
     if (!D.IsCLMode() && TC.getTriple().isWindowsMSVCEnvironment()) {
-      if (isDependentLibAdded(Args, "msvcrtd"))
-        CmdArgs.push_back("--dependent-lib=sycl" SYCL_MAJOR_VERSION "d");
+      if (isDependentLibAdded(Args, "msvcrtd")) {
+        if (Args.hasArg(options::OPT_fpreview_breaking_changes))
+          CmdArgs.push_back("--dependent-lib=sycl" SYCL_MAJOR_VERSION
+                            "-previewd");
+        else
+          CmdArgs.push_back("--dependent-lib=sycl" SYCL_MAJOR_VERSION "d");
+      }
     } else if (!D.IsCLMode() && TC.getTriple().isWindowsGNUEnvironment()) {
-      CmdArgs.push_back("--dependent-lib=sycl" SYCL_MAJOR_VERSION ".dll");
+      if (Args.hasArg(options::OPT_fpreview_breaking_changes))
+        CmdArgs.push_back("--dependent-lib=sycl" SYCL_MAJOR_VERSION
+                          "-preview.dll");
+      else
+        CmdArgs.push_back("--dependent-lib=sycl" SYCL_MAJOR_VERSION ".dll");
     }
     CmdArgs.push_back("--dependent-lib=sycl-devicelib-host");
   }

clang/lib/Driver/ToolChains/Gnu.cpp

@@ -730,7 +730,10 @@ void tools::gnutools::Linker::ConstructJob(Compilation &C, const JobAction &JA,
 
       if (Args.hasArg(options::OPT_fsycl) &&
           !Args.hasArg(options::OPT_nolibsycl)) {
-        CmdArgs.push_back("-lsycl");
+        if (Args.hasArg(options::OPT_fpreview_breaking_changes))
+          CmdArgs.push_back("-lsycl-preview");
+        else
+          CmdArgs.push_back("-lsycl");
         CmdArgs.push_back("-lsycl-devicelib-host");
         // Use of -fintelfpga implies -lOpenCL.
         // FIXME: Adjust to use plugin interface when available.

clang/lib/Driver/ToolChains/MSVC.cpp

@@ -137,8 +137,12 @@ void visualstudio::Linker::ConstructJob(Compilation &C, const JobAction &JA,
                                          TC.getDriver().Dir + "/../lib"));
     // When msvcrtd is added via --dependent-lib, we add the sycld
     // equivalent.  Do not add the -defaultlib as it conflicts.
-    if (!isDependentLibAdded(Args, "msvcrtd"))
-      CmdArgs.push_back("-defaultlib:sycl" SYCL_MAJOR_VERSION ".lib");
+    if (!isDependentLibAdded(Args, "msvcrtd")) {
+      if (Args.hasArg(options::OPT_fpreview_breaking_changes))
+        CmdArgs.push_back("-defaultlib:sycl" SYCL_MAJOR_VERSION "-preview.lib");
+      else
+        CmdArgs.push_back("-defaultlib:sycl" SYCL_MAJOR_VERSION ".lib");
+    }
     CmdArgs.push_back("-defaultlib:sycl-devicelib-host.lib");
   }
 

clang/test/Driver/sycl-offload.c

@@ -654,3 +654,17 @@
 // RUN: %clang -### -fsycl  %s 2>&1 | FileCheck -check-prefix FSYCL-CHECK %s
 // RUN: %clang_cl -### -fsycl  %s 2>&1 | FileCheck -check-prefix FSYCL-CHECK %s
 // FSYCL-CHECK: warning: treating 'c' input as 'c++' when -fsycl is used [-Wexpected-file-type]
+
+/// Check for linked sycl lib when using -fpreview-breaking-changes with -fsycl
+// RUN: %clang -### -fsycl -fpreview-breaking-changes -target x86_64-unknown-windows-msvc %s 2>&1 | FileCheck -check-prefix FSYCL-PREVIEW-BREAKING-CHANGES-CHECK %s
+// RUN: %clang_cl -### -fsycl -fpreview-breaking-changes %s 2>&1 | FileCheck -check-prefix FSYCL-PREVIEW-BREAKING-CHANGES-CHECK-CL %s
+// FSYCL-PREVIEW-BREAKING-CHANGES-CHECK: -defaultlib:sycl{{[0-9]*}}-preview.lib
+// FSYCL-PREVIEW-BREAKING-CHANGES-CHECK-NOT: -defaultlib:sycl{{[0-9]*}}.lib
+// FSYCL-PREVIEW-BREAKING-CHANGES-CHECK-CL: "--dependent-lib=sycl{{[0-9]*}}-preview"
+
+/// Check for linked sycl lib when using -fpreview-breaking-changes with -fsycl
+// RUN: %clang -### -fsycl -fpreview-breaking-changes -target x86_64-unknown-windows-msvc -Xclang --dependent-lib=msvcrtd %s 2>&1 | FileCheck -check-prefix FSYCL-PREVIEW-BREAKING-CHANGES-DEBUG-CHECK %s
+// RUN: %clang_cl -### -fsycl -fpreview-breaking-changes /MDd %s 2>&1 | FileCheck -check-prefix FSYCL-PREVIEW-BREAKING-CHANGES-DEBUG-CHECK %s
+// FSYCL-PREVIEW-BREAKING-CHANGES-DEBUG-CHECK: --dependent-lib=sycl{{[0-9]*}}-previewd
+// FSYCL-PREVIEW-BREAKING-CHANGES-DEBUG-CHECK-NOT: -defaultlib:sycl{{[0-9]*}}.lib
+// FSYCL-PREVIEW-BREAKING-CHANGES-DEBUG-CHECK-NOT: -defaultlib:sycl{{[0-9]*}}-preview.lib

sycl/CMakeLists.txt

@@ -152,6 +152,9 @@ if(SYCL_ENABLE_KERNEL_FUSION AND WIN32)
       BOOL "Kernel fusion not yet supported on Windows" FORCE)
 endif()
 
+# Option for enabling building the SYCL major release preview library.
+option(SYCL_ENABLE_MAJOR_RELEASE_PREVIEW_LIB "Enable build of the SYCL major release preview library" ON)
+
 # Needed for feature_test.hpp
 if ("cuda" IN_LIST SYCL_ENABLE_PLUGINS)
   set(SYCL_BUILD_PI_CUDA ON)
@@ -259,12 +262,21 @@ install(FILES "${sycl_inc_dir}/syclcompat.hpp" DESTINATION ${SYCL_INCLUDE_DIR} C
 
 if (WIN32)
   set(SYCL_RT_LIBS sycl${SYCL_MAJOR_VERSION})
+  if(SYCL_ENABLE_MAJOR_RELEASE_PREVIEW_LIB)
+    list(APPEND SYCL_RT_LIBS sycl${SYCL_MAJOR_VERSION}-preview)
+  endif()
   # Do we really support non-MSVC ABI on WIN?
   if (MSVC)
     list(APPEND SYCL_RT_LIBS sycl${SYCL_MAJOR_VERSION}d)
+    if(SYCL_ENABLE_MAJOR_RELEASE_PREVIEW_LIB)
+      list(APPEND SYCL_RT_LIBS sycl${SYCL_MAJOR_VERSION}-previewd)
+    endif()
   endif()
 else()
   set(SYCL_RT_LIBS sycl)
+  if(SYCL_ENABLE_MAJOR_RELEASE_PREVIEW_LIB)
+    list(APPEND SYCL_RT_LIBS sycl-preview)
+  endif()
 endif()
 
 # This function allows building multiple libraries with the same options.

sycl/doc/PreprocessorMacros.md

@@ -48,10 +48,12 @@ This file describes macros that have effect on SYCL compiler and run-time.
   support for `assert()` via `aspect::ext_oneapi_native_assert`.
   This macro is undefined by default.
 
-- **SYCL2020_CONFORMANT_APIS**
+- **SYCL2020_CONFORMANT_APIS (deprecated)**
   This macro is used to comply with the SYCL 2020 specification, as some of the current 
   implementations may be widespread and not conform to it.
   Defining this macro currently has no effect on the API.
+  This preprocessor macro has been deprecated in favor of the
+  `-fpreview-breaking-changes` compiler option.
 
 ## Version macros
 

sycl/include/sycl/handler.hpp

@@ -1243,7 +1243,8 @@ class __SYCL_EXPORT handler {
                   "Kernel argument cannot have a sycl::nd_item type in "
                   "sycl::parallel_for with sycl::range");
 
-#ifdef SYCL2020_CONFORMANT_APIS
+#if defined(SYCL2020_CONFORMANT_APIS) ||                                       \
+    defined(__INTEL_PREVIEW_BREAKING_CHANGES)
     static_assert(
         (std::is_invocable_v<KernelType, item<Dims>> ||
          std::is_invocable_v<
@@ -1337,7 +1338,8 @@ class __SYCL_EXPORT handler {
     verifyUsedKernelBundle(detail::KernelInfo<NameT>::getName());
     using LambdaArgType =
         sycl::detail::lambda_arg_type<KernelType, nd_item<Dims>>;
-#ifdef SYCL2020_CONFORMANT_APIS
+#if defined(SYCL2020_CONFORMANT_APIS) ||                                       \
+    defined(__INTEL_PREVIEW_BREAKING_CHANGES)
     static_assert(
         std::is_convertible_v<sycl::nd_item<Dims>, LambdaArgType>,
         "Kernel argument of a sycl::parallel_for with sycl::nd_range "

sycl/include/sycl/sycl.hpp

@@ -96,7 +96,8 @@
 #include <sycl/ext/oneapi/sub_group_mask.hpp>
 #include <sycl/ext/oneapi/weak_object.hpp>
 
-#ifndef SYCL2020_CONFORMANT_APIS
+#if !defined(SYCL2020_CONFORMANT_APIS) &&                                      \
+    !defined(__INTEL_PREVIEW_BREAKING_CHANGES)
 // We used to include those and some code might be reliant on that.
 #include <cmath>
 #include <complex>