Samples and Utility libraries

[MathiasMagnus]

This PR ships a larger batch of samples and the initial set of C/C++ utility libraries and SDK libraries. This PR includes:

• Temporary redirection of git submodules to the related Stream HPC SDK repos. This PR is dependent on changes found in:
  • OpenCL-SDK base changes in OpenCL-Headers
  • OpenCL-SDK base changes in OpenCL-ICD-Loader
  • OpenCL-SDK base changes in OpenCL-CLHPP
• References to existing and new chapters of the OpenCL-Guide:
  • Getting Started Guide: Windows & CMake support
  • Initial OpenCL-OpenGL interop overview
• The batch of samples include:
  • SAXPY (C & C++)
  • Reduction (C & C++)
  • Histogram soon (C++)
  • Blur (C)
  • Load/Save Binaries (C)
  • Conway's Game of Life (C++)
  • NBody (C++)
• All samples are accompanied by README markdown detailing the purpose of the samples, their feature set, some of their internal working and the utilized API surface.
• Two libraries are built within the SDK
  • OpenCLUtils(Cpp) which consumers of the SDK can use to facilitate some common OpenCL tasks
  • The utility libraries only depend on other OpenCL packages
  • OpenCLSDK(Cpp) which the samples use to deduplicate some of the common aspects of SDK samples, such as command-line parsing and window handling
  • The OpenCLSDK libraries have more dependencies, but nothing out of ordinary
  • The windowing library of choice is SFML, because it has explicit support for Android, and that is a platform the SDK wishes to target along with the native samples
• Building the development packages only don't require any dependencies, a non-recursive clone with submodules is enough. This is tested in CI.

Some notes on the shape of the SDK samples and some of the design choices:

• The C dependent libraries are bundled within the source tree. This was done because while Linux typically has these libraries available via the system package managers, users of Windows will have to rely on C/C++ package managers like Conan/Vcpkg/Hunter/etc. Once the availability of the deps improve, removing them from the repository may be appropriate.
  • Although it is a contentious topic, using Git submodules as a form of package management isn't ideal, nor is bundling deps in the source tree. While pkg managers gain popularity, best case scenario is catering to both crowds: those not using pkg managers but wanting a clean build experience and those who readily have custom built versions of all their deps, often newer than those bundled.
  • Being an author of various Vcpkg ports myself and maintaining HIP libraries, I know for a fact that self-hosting and wanting to provide a clean build experience for 3 platforms has non-zero cost. Offloading that pain to package manager maintainers is the best and easiest approach.
  • Do note that once the CMake rework of the SDK goes through, one of my first tasks will be to simplify the OpenCL Vcpkg port.
  • TCLAP has not been bundled. Should it be decided that the SDK should bundle that as well, we can add it next to the other deps.

[CLAassistant]

All committers have signed the CLA.

[MathiasMagnus]

@bashbaug I think I know where your woes are coming from (and both are totally legit).

1. Not finding the library happens only with multi-config generators. Building using the default Unix Makefiles or Ninja works. Working on a fix.

2. The headers is a sticky subject. (Semi-extensive exploration of the phase space is here, which I intend on merging into either the OpenCL-Guide or the SDK.) The 'current working directory' (henceforth cwd)-relative solution is simple, but is fairly brittle. Copying the kernels into the build tree is problematic because

   • One may copy at configuration time using file(COPY ...) or configure_file() but then one needs to reconfigure to update the files on disk. (It's annoying to develop samples that way.)
   • One may set it as a post-build step, but then it will only trigger when one modifies the host code. (This is annoying too.)
   • One may promote it to a build step, in which case utility targets like saxpy-kernel and nbody-kernel-shader start mildly polluting the list of available targets. Samples run fine from the install tree, because install commands can properly track the timestamps of both the executables and the kernel files.

Symlinking the kernels would be awesome, as it follows updates to code in the source tree, but that has many problems too:

• The problem with that 🥁🥁🥁🥁🥁🥁🥁🥁 file(CREATE_LINK ...) is CMake 3.14. (And cmake -E create_symlink as non-UNIX-only is 3.13.) We can raise minimum version when building the samples to 3.13 / 3.14 or accept the bloat

  if(CMAKE_SYSTEM_NAME MATHCES Windows)
  execute_process(COMMAND "mklink ...")
  else()
  execute_process(COMMAND "ln -s ...")
  endif()

  but even then, symlinking on Windows without admin rights requires developer mode enabled on the system. 🤯 Wow...

Ultimately I accepted the fact that running the samples from the build tree requires making the cwd the path to the kernel in the source tree, but if it bugs anyone, pick an item from the above list or the samples should move away from the CWD-relative location of device code.

[MathiasMagnus]

All samples now execute correctly from the build tree as well as the install tree in both single and multi-config generators.