Add option to configure and build without graphics (#8)

Make the configuration and build of graphical demos and
their dependencies (Magnum, Corrade, SDL2) depend on a
new CMake cache variable ENABLE_GRAPHICS. Auto-configure
this new variable based on the result of find_package(SDL2).

A warning is emitted if ENABLE_GRAPHICS is unset and SDL2 is
not found. The warning can be silenced by explicitly setting
the option to OFF. In case the option is explicitly set to ON
and SDL2 is not found, a fatal error is emitted.

Add an explanation of the new option in the README.

Add a new CI step building the no-graphics version. Set
ENABLE_GRAPHICS=ON explicitly in the baseline CI build.

.github/workflows/ci.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: clang-format
         uses: jidicula/clang-format-action@v4.11.0
@@ -101,9 +101,31 @@ jobs:
           cmake -B ${{github.workspace}}/build
           -DCMAKE_BUILD_TYPE=${{env.BUILD_TYPE}}
           -DCMAKE_CXX_COMPILER=clang++
+          -DENABLE_GRAPHICS=ON
           -DENABLE_SPIR=ON -DENABLE_CUDA=OFF -DENABLE_HIP=OFF
           -DCMAKE_CXX_FLAGS='-Wall -Wextra -Wpedantic -Werror'
           -G Ninja
 
       - name: Build
         run: cmake --build ${{github.workspace}}/build -- -k 0
+
+  cmake-build-nographics:
+    runs-on: ubuntu-latest
+    container:
+      image: intel/oneapi-basekit:latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Configure CMake (no graphics)
+        run: >
+          cmake -B ${{github.workspace}}/build
+          -DCMAKE_BUILD_TYPE=${{env.BUILD_TYPE}}
+          -DCMAKE_CXX_COMPILER=icpx
+          -DENABLE_GRAPHICS=OFF
+          -DENABLE_SPIR=ON -DENABLE_CUDA=OFF -DENABLE_HIP=OFF
+          -DCMAKE_CXX_FLAGS='-Wall -Wextra -Wpedantic -Werror'
+
+      - name: Build (no graphics)
+        run: cmake --build ${{github.workspace}}/build -- -k -j

CMakeLists.txt

@@ -15,30 +15,19 @@ endif()
 set(CMAKE_CXX_STANDARD 17)
 
 # Configure Magnum
-list(APPEND CMAKE_MODULE_PATH
-     "${PROJECT_SOURCE_DIR}/modules/magnum-bootstrap/modules"
-     "${PROJECT_SOURCE_DIR}/modules/magnum-integration/modules")
-set(MAGNUM_WITH_SDL2APPLICATION ON CACHE BOOL "" FORCE)
-set(MAGNUM_WITH_ANYIMAGEIMPORTER ON CACHE BOOL "" FORCE)
-set(MAGNUM_WITH_STBIMAGEIMPORTER ON CACHE BOOL "" FORCE)
-set(IMGUI_DIR ${PROJECT_SOURCE_DIR}/modules/imgui)
-set(MAGNUM_WITH_IMGUI ON CACHE BOOL "" FORCE)
-add_subdirectory(modules/corrade EXCLUDE_FROM_ALL)
-add_subdirectory(modules/magnum EXCLUDE_FROM_ALL)
-add_subdirectory(modules/magnum-plugins EXCLUDE_FROM_ALL)
-add_subdirectory(modules/magnum-integration EXCLUDE_FROM_ALL)
-find_package(Magnum REQUIRED GL Sdl2Application Shaders Primitives Trade)
-find_package(MagnumIntegration REQUIRED ImGui)
+include(cmake/ConfigureMagnum.cmake)
 
 # Configure SYCL
 include(cmake/ConfigureSYCL.cmake)
 
 # Configure the demo projects
 set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR} CACHE PATH "" FORCE)
-add_subdirectory(src/fluid)
-add_subdirectory(src/game_of_life)
-add_subdirectory(src/mandelbrot)
-add_subdirectory(src/nbody)
 add_subdirectory(src/matrix_multiply_omp_compare)
 add_subdirectory(src/MPI_for_CUDA_backend)
 add_subdirectory(src/scan_parallel_inclusive)
+if(ENABLE_GRAPHICS)
+     add_subdirectory(src/fluid)
+     add_subdirectory(src/game_of_life)
+     add_subdirectory(src/mandelbrot)
+     add_subdirectory(src/nbody)
+endif()

README.md

@@ -29,6 +29,7 @@ Drag the mouse around the screen to create fluid particles with velocities in
 direction of the mouse travel. The fluid fades slowly over time so as not to fill
 the container.
 
+## Non-graphical Demos
 ### MPI for CUDA Backend 
 MPI, the Message Passing Interface, is a standard API for communicating data via 
 messages between distributed processes that is commonly used in HPC to build 
@@ -83,7 +84,9 @@ include them in the checkout via
 `git clone --recurse-submodules <this repo's URL>`. SDL2 needs to be supplied by
 the user and can be installed with common package managers on most systems, or
 built from source. If you install SDL2 from source in a non-default location,
-pass it into the CMake configuration with `-DSDL2_ROOT=<path>`.
+pass it into the CMake configuration with `-DSDL2_ROOT=<path>`. It is possible
+to build the project without the graphical demos using `-DENABLE_GRAPHICS=OFF`
+if SDL2 cannot be provided - see the Building section below.
 
 Although the code should compile with any SYCL implementation, the CMake
 configuration assumes the DPC++ compiler driver CLI for compilation flags setup.
@@ -96,7 +99,8 @@ The project uses a standard CMake build configuration system. Ensure the SYCL
 compiler is used by the configuration either by setting the
 environment variable `CXX=<compiler>` or passing the configuration flag
 `-DCMAKE_CXX_COMPILER=<compiler>` where `<compiler>` is your SYCL compiler's
-executable (for example Intel `icpx` or LLVM `clang++`). \
+executable (for example Intel `icpx` or LLVM `clang++`).
+
 To check out the repository and build the examples, use simply:
 ```
 git clone --recurse-submodules <this repo's URL>
@@ -117,3 +121,10 @@ be overridden with `-D<OPTION>=<VALUE>` with the following options:
 | `ENABLE_HIP` | `ON` or `OFF` |
 | `CUDA_COMPUTE_CAPABILITY` | Integer, e.g. `70` meaning capability 7.0 (arch `sm_70`) |
 | `HIP_GFX_ARCH` | String, e.g. `gfx1030` |
+
+### Building without graphics
+It is possible to build only the non-graphical demos by adding the option
+`-DENABLE_GRAPHICS=OFF` to the CMake configuration command. In this case
+building of the Magnum library will be skipped and the SDL2 library is not
+required as dependency. The option `--recurse-submodules` can also be skipped
+during the checkout when building only the non-graphical demos.

cmake/ConfigureMagnum.cmake

@@ -0,0 +1,56 @@
+############################################################################
+#
+#  Copyright (C) Codeplay Software Limited
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+#
+#  Description:
+#    CMake helper script configuring the graphics wrapper library Magnum
+#
+############################################################################
+
+# Auto-configure ENABLE_GRAPHICS if not set on command line
+find_package(SDL2 QUIET)
+if (NOT DEFINED ENABLE_GRAPHICS)
+    if(SDL2_FOUND)
+        set(ENABLE_GRAPHICS ON CACHE BOOL "Build graphical demos")
+        message(STATUS "Auto-configured ENABLE_GRAPHICS=ON")
+    else()
+        message(WARNING "SDL2 not found, disabling all graphical demos. If you "
+                "are building the project intentionally without graphical "
+                "demos, add -DENABLE_GRAPHICS=OFF to your cmake configuration "
+                "command.")
+        set(ENABLE_GRAPHICS OFF CACHE BOOL "Build graphical demos")
+    endif()
+elseif(ENABLE_GRAPHICS AND NOT SDL2_FOUND)
+    message(FATAL_ERROR "ENABLE_GRAPHICS was set to ON, but SDL was not found. "
+            "Cannot build the graphical demos.  Set ENABLE_GRAPHICS=OFF to "
+            "build the project without them.")
+endif()
+
+# Configure Magnum
+if (ENABLE_GRAPHICS)
+    list(APPEND CMAKE_MODULE_PATH
+         "${PROJECT_SOURCE_DIR}/modules/magnum-bootstrap/modules"
+         "${PROJECT_SOURCE_DIR}/modules/magnum-integration/modules")
+    set(MAGNUM_WITH_SDL2APPLICATION ON CACHE BOOL "" FORCE)
+    set(MAGNUM_WITH_ANYIMAGEIMPORTER ON CACHE BOOL "" FORCE)
+    set(MAGNUM_WITH_STBIMAGEIMPORTER ON CACHE BOOL "" FORCE)
+    set(IMGUI_DIR ${PROJECT_SOURCE_DIR}/modules/imgui)
+    set(MAGNUM_WITH_IMGUI ON CACHE BOOL "" FORCE)
+    add_subdirectory(modules/corrade EXCLUDE_FROM_ALL)
+    add_subdirectory(modules/magnum EXCLUDE_FROM_ALL)
+    add_subdirectory(modules/magnum-plugins EXCLUDE_FROM_ALL)
+    add_subdirectory(modules/magnum-integration EXCLUDE_FROM_ALL)
+    find_package(Magnum REQUIRED GL Sdl2Application Shaders Primitives Trade)
+    find_package(MagnumIntegration REQUIRED ImGui)
+endif()