More documentation/comments

Author: aelovikov-intel

sycl/include/sycl/detail/core.hpp

@@ -8,6 +8,16 @@
 
 #pragma once
 
+// This is an ongoing experimental activity in its early stage. No code outside
+// this project must rely on the behavior of this header file - keep using
+// <sycl/sycl.hpp>.
+//
+// Short-term plan/action items (in no particular order):
+//  * Update more tests to use this instead of full <sycl/sycl.hpp>.
+//  * Refactor includes so that transitive dependencies don't bring as much as
+//    they currently do.
+//  * Determine what else should be included here.
+
 #include <sycl/accessor.hpp>
 #include <sycl/buffer.hpp>
 #include <sycl/queue.hpp>

sycl/test-e2e/README.md

@@ -8,6 +8,7 @@
  * [Creating or modifying tests](#creating-or-modifying-tests)
    * [LIT feature checks](#lit-feature-checks)
    * [llvm-lit parameters](#llvm-lit-parameters)
+ * [sycl/detail/core.hpp header file](#sycl/detail/core.hpp)
 
 # Overview
 This directory contains SYCL-related tests distributed in subdirectories based
@@ -282,3 +283,15 @@ llvm-lit --param dpcpp_compiler=path/to/clang++ --param dump_ir=True \
          SYCL/External/RSBench
 ```
 
+## sycl/detail/core.hpp
+
+While SYCL specification dictates that the only user-visible interface is
+`<sycl/sycl.hpp>` header file we found out that as the implementation and
+multiple extensions grew, the compile time was getting worse and worse,
+negatively affecting our CI turnaround time. We are just starting some efforts
+to create a much smaller set of basic feature needed for every SYCL end-to-end
+test/program so that this issue could be somewhat mitigated. This activity is in
+its early stage and NO production code should rely on it. It WILL be changed as
+we go with our experiments. For any code outside of this project only the
+`<sycl/sycl.hpp>` must be used until we feel confident to propose an extension
+that can provide an alternative.