Samples and Utility libraries (#37)

Co-authored-by: Ivan Siutsou <ivan@streamhpc.com>
Co-authored-by: Istvan Kiss <istvan@streamhpc.com>
Co-authored-by: Ben Ashbaugh <ben.ashbaugh@intel.com>
Co-authored-by: Alastair Murray <alastair.murray@codeplay.com>

Author: 5 people

.github/workflows/presubmit.yml

@@ -28,17 +28,25 @@ jobs:
           submodules: recursive
       - name: Build
         run: |
-            mkdir build
-            cd build
+            if [[ "${{ matrix.os }}" == "ubuntu-20.04" ]]; then
+              sudo apt update
+              sudo apt install -y libtclap-dev libglm-dev libglew-dev libsfml-dev libstb-dev libidn11 libx11-dev libxrandr-dev libxi-dev mesa-common-dev libgl1-mesa-dev libglu1-mesa-dev libudev-dev
+            elif [[ "${{ matrix.os }}" == "macos-latest" ]]; then
+              brew install tclap glm glew sfml mesa-glu
+              git clone https://github.com/Microsoft/vcpkg.git
+              ./vcpkg/bootstrap-vcpkg.sh
+              ./vcpkg/vcpkg install stb
+              TOOLCHAIN_ARG="-D CMAKE_TOOLCHAIN_FILE=./vcpkg/scripts/buildsystems/vcpkg.cmake"
+            fi
             if [[ "${{ matrix.compiler }}" == "gcc" ]]; then
               CC=gcc
               CXX=g++
             elif [[ "${{ matrix.compiler }}" == "clang" ]]; then
               CC=clang
               CXX=clang++
             fi
-            cmake -DCMAKE_C_COMPILER=$CC -DCMAKE_CXX_COMPILER=$CXX ../
-            make -j2 VERBOSE=1
+            cmake -D CMAKE_C_COMPILER=$CC -D CMAKE_CXX_COMPILER=$CXX $TOOLCHAIN_ARG -S . -B build
+            cmake --build ./build --verbose --parallel 2
   buildwin:
     needs: format
     name: Build Windows
@@ -50,10 +58,11 @@ jobs:
           submodules: recursive
       - name: Build
         run: |
-          mkdir build
-          cd build
-          cmake ../
-          cmake --build .
+          git clone https://github.com/Microsoft/vcpkg.git
+          .\vcpkg\bootstrap-vcpkg.bat
+          .\vcpkg\vcpkg.exe --triplet=x64-windows install sfml tclap glm glew stb
+          cmake -D CMAKE_TOOLCHAIN_FILE=.\vcpkg\scripts\buildsystems\vcpkg.cmake -S . -B build
+          cmake --build ./build -- /verbosity:minimal /maxCpuCount /noLogo
 
   python:
     name: Exercise Python examples on ${{matrix.os}}

.gitignore

@@ -4,3 +4,4 @@ install/
 # vim
 *~
 .*.sw[op]
+.vscode

.gitlab/ubuntu-18.04-rocm.Dockerfile

@@ -0,0 +1,10 @@
+FROM streamhpc/opencl-sdk-base:ubuntu-18.04-20211119
+RUN set -ex; \
+    export DEBIAN_FRONTEND=noninteractive ; \
+#   Register ROCm APT repo
+    wget --quiet --recursive --no-directories --no-parent "https://repo.radeon.com/amdgpu-install/latest/ubuntu/bionic/" --accept "amdgpu-install-*_all.deb" ; \
+    apt install -y -qq ./amdgpu-install-*_all.deb libnuma-dev initramfs-tools ; \
+    apt update -qq; \
+    rm ./amdgpu-install-*_all.deb ; \
+#   Install OpenCL package only (and dependency)
+    amdgpu-install -y --usecase=opencl

.gitlab/ubuntu-18.04.Dockerfile

@@ -0,0 +1,45 @@
+FROM ubuntu:18.04 AS apt-installs
+RUN set -ex; \
+    export DEBIAN_FRONTEND=noninteractive ; \
+    apt update -qq; \
+#   install wget to download repository keys and CMake tarballs
+#   install software-properties-common for the apt-add-repository command
+    apt install -y -qq wget software-properties-common ; \
+#   Canonical hosts recent GCC compilers in ubuntu-toolchain-r/test
+    apt-add-repository -y ppa:ubuntu-toolchain-r/test ; \
+#   LLVM hosts most toolchain in separate repos. We only register those absent from ubuntu-toolchain-r/test
+    wget -q -O - https://apt.llvm.org/llvm-snapshot.gpg.key | apt-key add - ; \
+    apt-add-repository -y 'deb [arch=amd64] https://apt.llvm.org/bionic/ llvm-toolchain-bionic-11 main' ; \
+    apt-add-repository -y 'deb [arch=amd64] https://apt.llvm.org/bionic/ llvm-toolchain-bionic-12 main' ; \
+    apt-add-repository -y 'deb [arch=amd64] https://apt.llvm.org/bionic/ llvm-toolchain-bionic-13 main' ; \
+#   install ninja, GCC 7-10, LLVM 8-13 and build-essential to get linkers, etc.
+#   install git to download dependencies
+#   install ruby to run CMock
+#   install libidn11 which CMake 3.1.3 only depends on
+#   install ca-certificates to `git clone` via HTTPS
+#   install SFML dependencies
+#           libx11-dev libxrandr-dev libxi-dev
+#           mesa-common-dev for gl.h
+#           libgl1-mesa-dev for libGL.so
+#           libglu1-mesa-dev for glu.h
+#           libudev-dev
+#   install Vcpkg dependencies
+#           curl zip unzip tar
+    apt install -y -qq build-essential g++-7 g++-8 g++-9 g++-10 clang-8 clang-9 clang-10 clang-11 clang-12 clang-13 ninja-build git ruby libidn11 ca-certificates libx11-dev libxrandr-dev libxi-dev mesa-common-dev libgl1-mesa-dev libglu1-mesa-dev libudev-dev curl zip unzip tar
+
+#   install CMake minimum (3.0.2 (Headers, ICD Loader), 3.1.3 (CLHPP), 3.10.3 (SDK)) and latest (3.21.2)
+RUN mkdir -p /opt/Kitware/CMake ; \
+    wget -c https://github.com/Kitware/CMake/releases/download/v3.0.2/cmake-3.0.2-Linux-i386.tar.gz -O - | tar -xz --directory /opt/Kitware/CMake ; \
+    mv /opt/Kitware/CMake/cmake-3.0.2-Linux-i386 /opt/Kitware/CMake/3.0.2 ; \
+    wget -c https://github.com/Kitware/CMake/releases/download/v3.1.3/cmake-3.1.3-Linux-x86_64.tar.gz -O - | tar -xz --directory /opt/Kitware/CMake ; \
+    mv /opt/Kitware/CMake/cmake-3.1.3-Linux-x86_64 /opt/Kitware/CMake/3.1.3 ; \
+    wget -c https://github.com/Kitware/CMake/releases/download/v3.10.3/cmake-3.10.3-Linux-x86_64.tar.gz -O - | tar -xz --directory /opt/Kitware/CMake ; \
+    mv /opt/Kitware/CMake/cmake-3.10.3-Linux-x86_64 /opt/Kitware/CMake/3.10.3 ; \
+    wget -c https://github.com/Kitware/CMake/releases/download/v3.21.2/cmake-3.21.2-linux-x86_64.tar.gz -O - | tar -xz --directory /opt/Kitware/CMake ; \
+    mv /opt/Kitware/CMake/cmake-3.21.2-linux-x86_64 /opt/Kitware/CMake/3.21.2
+
+#   install Vcpkg
+RUN git clone --depth 1 https://github.com/Microsoft/vcpkg.git /opt/Microsoft/vcpkg ; \
+    /opt/Microsoft/vcpkg/bootstrap-vcpkg.sh ; \
+#   install SFML, TCLAP, GLM
+    /opt/Microsoft/vcpkg/vcpkg install sfml tclap glm glew

CMakeLists.txt

@@ -14,29 +14,91 @@
 
 cmake_minimum_required(VERSION 3.0)
 
-set(CMAKE_CXX_STANDARD 11)
+set(CMAKE_CXX_STANDARD 14)
 
-project(OpenCL-SDK)
+project(OpenCL-SDK
+  VERSION 1.0
+  LANGUAGES
+    C CXX
+)
+
+include(CMakeDependentOption)
+option(OPENCL_SDK_BUILD_SAMPLES "Build sample code" ON)
+cmake_dependent_option(OPENCL_SDK_BUILD_OPENGL_SAMPLES "Build OpenCL-OpenGL interop sample code" ON OPENCL_SDK_BUILD_SAMPLES OFF)
+cmake_dependent_option(OPENCL_SDK_TEST_SAMPLES "Add CTest to samples (where applicable)" ON OPENCL_SDK_BUILD_SAMPLES OFF)
+
+include(CTest)
 
 if (NOT CMAKE_BUILD_TYPE)
     message(STATUS "No build type selected, default to Release")
     set(CMAKE_BUILD_TYPE "Release" CACHE PATH "Build Type" FORCE)
 endif()
 
-set(OPENCL_ICD_LOADER_HEADERS_DIR
-    "${PROJECT_SOURCE_DIR}/external/OpenCL-Headers" CACHE PATH "Path to OpenCL
-    Headers")
-
 if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
     set(CMAKE_INSTALL_PREFIX "${PROJECT_SOURCE_DIR}/install" CACHE PATH "Install Path" FORCE)
 endif()
 
-set(OPENCL_SDK_INCLUDE_DIRS
-    "${PROJECT_SOURCE_DIR}/external/OpenCL-Headers"
-    "${PROJECT_SOURCE_DIR}/external/OpenCL-CLHPP/include")
+add_subdirectory(external/OpenCL-Headers)
+add_subdirectory(external/OpenCL-ICD-Loader)
+add_subdirectory(external/OpenCL-CLHPP)
+
+if(OPENCL_SDK_BUILD_SAMPLES)
+  list(APPEND CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/cmake/Modules)
+  add_subdirectory(third_party/cargs)
+  find_package(TCLAP REQUIRED)
+  find_package(Stb REQUIRED)
+  if(OPENCL_SDK_BUILD_OPENGL_SAMPLES)
+    cmake_minimum_required(VERSION 3.10) # SFML 2 won't find Freetype::Freetype under 3.10
+    find_package(OpenGL REQUIRED)
+    if(CMAKE_SYSTEM_NAME MATCHES Linux) # TODO: Add EGL support
+      # OpenGL doesn't explicitly depend on X11 (as of CMake v3.2) but we'll need it
+      find_package(X11 REQUIRED)
+    endif()
+    find_package(GLEW REQUIRED)
+    if(NOT TARGET OpenGL::GLU)
+      # GLU is a dependency of GLEW but it's not advertized as an OpenGL COMPONENT
+      message(FATAL_ERROR "GLEW depends on GLU but was not found.")
+    endif()
+    find_package(SFML 2
+      REQUIRED
+      COMPONENTS window graphics
+    )
+    find_package(GLEW REQUIRED)
+    find_package(glm CONFIG REQUIRED)
+  endif(OPENCL_SDK_BUILD_OPENGL_SAMPLES)
+endif(OPENCL_SDK_BUILD_SAMPLES)
+
+add_subdirectory(lib)
+if(OPENCL_SDK_BUILD_SAMPLES)
+  add_subdirectory(samples)
+endif()
 
-add_subdirectory(${PROJECT_SOURCE_DIR}/external/OpenCL-ICD-Loader)
-add_subdirectory(${PROJECT_SOURCE_DIR}/samples)
+include(GNUInstallDirs)
+file(
+  WRITE ${PROJECT_BINARY_DIR}/OpenCL/OpenCLConfig.cmake
+  [[
+get_filename_component(PARENT_DIR ${CMAKE_CURRENT_LIST_DIR} PATH)
+include("${PARENT_DIR}/OpenCLHeaders/OpenCLHeadersConfig.cmake")
+include("${PARENT_DIR}/OpenCLICDLoader/OpenCLICDLoaderConfig.cmake")
+include("${PARENT_DIR}/OpenCLHeadersCpp/OpenCLHeadersCppConfig.cmake")
+include("${PARENT_DIR}/OpenCLUtils/OpenCLUtilsConfig.cmake")
+include("${PARENT_DIR}/OpenCLUtilsCpp/OpenCLUtilsCppConfig.cmake")
+  ]]
+)
+set(config_package_location ${CMAKE_INSTALL_DATADIR}/cmake/OpenCL)
+install(
+  FILES ${PROJECT_BINARY_DIR}/OpenCL/OpenCLConfig.cmake
+  DESTINATION ${config_package_location}
+)
 
-set_target_properties(OpenCL PROPERTIES LIBRARY_OUTPUT_DIRECTORY
-    ${CMAKE_CURRENT_BINARY_DIR})
+unset(CMAKE_SIZEOF_VOID_P)
+include(CMakePackageConfigHelpers)
+write_basic_package_version_file(
+  ${CMAKE_CURRENT_BINARY_DIR}/OpenCL/OpenCLConfigVersion.cmake
+  VERSION ${PROJECT_VERSION}
+  COMPATIBILITY AnyNewerVersion
+)
+install(
+  FILES ${CMAKE_CURRENT_BINARY_DIR}/OpenCL/OpenCLConfigVersion.cmake
+  DESTINATION ${config_package_location}
+)

README.md

@@ -1,4 +1,4 @@
-# OpenCL-SDK (in development)
+# OpenCL<sup>TM</sup> SDK (in development)
 
 This is the Khronos OpenCL SDK. It brings together all the components needed to
 develop OpenCL applications:
@@ -13,40 +13,57 @@ It also contains resources useful to OpenCL developers:
 - Code samples (`samples/`)
 - Documentation (`docs/`)
 
-## Setting Up the SDK
+## Build Instructions
 
-This repository uses sub-modules for the OpenCL Headers, OpenCL C++ bindings, and OpenCL ICD Loader.
+### Dependencies
 
-To clone a new repository with all sub-modules included, use the `--recursive` option.
-Note that this option clones all sub-modules and their dependencies, which are not required for the OpenCL SDK:
+- This repository uses sub-modules for the OpenCL Headers, OpenCL C++ bindings, and OpenCL ICD Loader and some of their transitive dependencies.
 
-```sh
-$ git clone --recursive https://github.com/KhronosGroup/OpenCL-SDK.git
-```
+  - To clone a new repository with all sub-modules included, use the `--recursive` option. Note that this option clones all sub-modules and their dependencies, which are not strictly required for the OpenCL SDK:
 
-Alternatively, to clone only the sub-modules for the OpenCL SDK, first clone this repository without sub-modules included:
+        git clone --recursive https://github.com/KhronosGroup/OpenCL-SDK.git
 
-```sh
-$ git clone https://github.com/KhronosGroup/OpenCL-SDK.git
-```
+  - Alternatively, to clone only the sub-modules for the OpenCL SDK, first clone this repository without sub-modules included then setup submodules non-recursively:
 
-Then setup sub-modules:
+        git clone https://github.com/KhronosGroup/OpenCL-SDK.git
+        git submodule init
+        git submodule update
 
-```sh
-$ git submodule init
-$ git submodule update
-```
+- The SDK uses CMake for its build system.
+If CMake is not provided by your build system or OS package manager, please consult the [CMake website](https://cmake.org).
 
-## Building the Samples
+- The SDK samples depend on
 
-This repository uses CMake as its build system.
-The suggested build directory is `build`.
+  - [Templatized C++ Command Line Parser Library](http://tclap.sourceforge.net/) (aka. TCLAP)
+  - [Simple and Fast Multimedia Library](https://www.sfml-dev.org/) (aka. SFML)
+  - [OpenGL Mathematics](https://glm.g-truc.net/0.9.9/index.html) (aka. GLM)
 
-To generate build files, use for example:
+### Example Build
 
-```sh
-$ mkdir build && cd build
-$ cmake ..
-```
+> The example build guide uses [Vcpkg](https://vcpkg.io/en/index.html) to fetch all dependencies. Note that Vcpkg is _not_ a requirement and is only used for convenience. One may provide dependencies through any other CMake mechanism. For details on how to install Vcpkg, refer to it's [Getting Started Guide](https://vcpkg.io/en/getting-started.html). The example build assumes targeting 64-bit Windows.
 
-Then build with the generated build files.
+1. Clone this repo with the rest of the OpenCL SDK components:
+
+       git clone https://github.com/KhronosGroup/OpenCL-SDK.git
+       git submodule init
+       git submodule update
+
+1. Install dependencies
+
+       vcpkg --triplet x64-windows install sfml tclap glm
+
+1. Build and install SDK with samples and no downstream unit tests
+
+       cmake -A x64 `
+             -D BUILD_TESTING=OFF `
+             -D BUILD_DOCS=OFF `
+             -D BUILD_EXAMPLES=OFF `
+             -D BUILD_TESTS=OFF `
+             -D OPENCL_SDK_BUILD_SAMPLES=ON `
+             -D OPENCL_SDK_TEST_SAMPLES=OFF `
+             -D CMAKE_TOOLCHAIN_FILE=/vcpkg/install/root/scripts/buildsystems/vcpkg.cmake `
+             -D VCPKG_TARGET_TRIPLET=x64-windows
+             -B ./OpenCL-SDK/build -S ./OpenCL-SDK
+       cmake --build ./OpenCL-SDK/build --target install
+
+_(Note: on Linux paths to dependent libraries are automatically handled by RPATH in both the build and install tree. On Windows all DLLs have to be on the `PATH`. Vcpkg copies dependent DLLs to the build tree, but in order to do the same in the install tree, sufficiently new CMake version is required. CMake 3.21 instroduces `install(IMPORTED_RUNTIME_ARTIFACTS)`.)_

cmake/Modules/FindStb.cmake

@@ -0,0 +1,30 @@
+# - Find Stb
+# Find the Stb headers
+#
+# Stb_INCLUDE_DIR - where to find the TCLAP headers
+# Stb_FOUND       - True if TCLAP is found
+
+if (Stb_INCLUDE_DIR)
+  # already in cache, be silent
+  set (Stb_FIND_QUIETLY TRUE)
+endif (Stb_INCLUDE_DIR)
+
+# find the headers
+find_path (Stb_INCLUDE_PATH stb_image.h
+  PATHS
+    ${Stb_DIR}
+  PATH_SUFFIXES
+    include
+    include/stb
+  )
+
+# handle the QUIETLY and REQUIRED arguments and set Stb_FOUND to
+# TRUE if all listed variables are TRUE
+include (FindPackageHandleStandardArgs)
+find_package_handle_standard_args (Stb "Stb (https://github.com/nothings/stb) could not be found. Set Stb_INCLUDE_PATH to point to the headers adding '-D Stb_INCLUDE_PATH=/path/to/stb' to the cmake command." Stb_INCLUDE_PATH)
+
+if (Stb_FOUND)
+  set (Stb_INCLUDE_DIR ${Stb_INCLUDE_PATH})
+endif (Stb_FOUND)
+
+mark_as_advanced(Stb_INCLUDE_PATH)

cmake/Modules/FindTCLAP.cmake

@@ -0,0 +1,28 @@
+# - Find TCLAP
+# Find the TCLAP headers
+#
+# TCLAP_INCLUDE_DIR - where to find the TCLAP headers
+# TCLAP_FOUND       - True if TCLAP is found
+
+if (TCLAP_INCLUDE_DIR)
+  # already in cache, be silent
+  set (TCLAP_FIND_QUIETLY TRUE)
+endif (TCLAP_INCLUDE_DIR)
+
+# find the headers
+find_path (TCLAP_INCLUDE_PATH tclap/CmdLine.h
+  PATHS
+  ${CMAKE_SOURCE_DIR}/include
+  ${CMAKE_INSTALL_PREFIX}/include
+  )
+
+# handle the QUIETLY and REQUIRED arguments and set TCLAP_FOUND to
+# TRUE if all listed variables are TRUE
+include (FindPackageHandleStandardArgs)
+find_package_handle_standard_args (TCLAP "TCLAP (http://tclap.sourceforge.net/) could not be found. Set TCLAP_INCLUDE_PATH to point to the headers adding '-DTCLAP_INCLUDE_PATH=/path/to/tclap' to the cmake command." TCLAP_INCLUDE_PATH)
+
+if (TCLAP_FOUND)
+  set (TCLAP_INCLUDE_DIR ${TCLAP_INCLUDE_PATH})
+endif (TCLAP_FOUND)
+
+mark_as_advanced(TCLAP_INCLUDE_PATH)