Add CPack

.clang-tidy

@@ -14,10 +14,11 @@ Checks: >
   -cppcoreguidelines-non-private-member-variables-in-classes,
   -cppcoreguidelines-pro-bounds-pointer-arithmetic,
   -cppcoreguidelines-macro-usage,
+  -cppcoreguidelines-pro-type-vararg,
   -cppcoreguidelines-avoid-magic-numbers,
+  -cppcoreguidelines-pro-bounds-array-to-pointer-decay,
   -readability-magic-numbers,
   -readability-function-cognitive-complexity,
-  -readability-magic-numbers,
   -misc-non-private-member-variables-in-classes,
   -clang-analyzer-optin.cplusplus.UninitializedObject,
   -misc-static-assert,

.gitattributes → .gitattributes_example

@@ -2,6 +2,11 @@
 *.jpg filter=lfs diff=lfs merge=lfs -text
 *.jpeg filter=lfs diff=lfs merge=lfs -text
 *.gif filter=lfs diff=lfs merge=lfs -text
+*.ico filter=lfs diff=lfs merge=lfs -text
+*.icns filter=lfs diff=lfs merge=lfs -text
+*.bmp filter=lfs diff=lfs merge=lfs -text
+*.tif filter=lfs diff=lfs merge=lfs -text
+*.tiff filter=lfs diff=lfs merge=lfs -text
 *.webp filter=lfs diff=lfs merge=lfs -text
 *.mp4 filter=lfs diff=lfs merge=lfs -text
 *.webm filter=lfs diff=lfs merge=lfs -text

.github/workflows/cmake.yml

@@ -18,7 +18,6 @@ jobs:
 
       - name: Install GitHub CLI
         run: |
-          brew update
           brew install llvm
           ln -s "$(brew --prefix llvm)/bin/clang-format" "/usr/local/bin/clang-format"
           ln -s "$(brew --prefix llvm)/bin/clang-tidy" "/usr/local/bin/clang-tidy"

.gitignore

@@ -1,3 +1,15 @@
+# Application build output
 build/
+
+# Created by CPack when executing tests.
+Testing/
+
+# Generated by the profiler on debug.
+profile.json
 *-profile.json
+
+# Created by running the application.
 *.log
+
+# User defined CMake preset file.
+CMakeUserPresets.json

CMakeLists.txt

@@ -1,21 +1,29 @@
 cmake_minimum_required(VERSION 3.22)
 
-include(cmake/AppleBuild.cmake)
+include(cmake/UniversalAppleBuild.cmake)
 
 project(
-  BasicGuiProjectSetupSDL2OpenGL
+  BasicGuiProjectSetupOpenGL
   DESCRIPTION "Base gui project setup with SDL2 and OpenGL."
+  VERSION 1.0.0
   LANGUAGES CXX)
 
 set(CMAKE_CXX_STANDARD 20)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 
+set(PROJECT_COMPANY_NAME "My Company")
+set(PROJECT_COMPANY_NAMESPACE "com.mycompany")  # Reverse domain name notation
+
 include(cmake/StandardProjectSettings.cmake)
+include(GNUInstallDirs)
 
-# Link this "library" to use the warnings specified in CompilerWarnings.cmake
+# Link this "library" to use the warnings specified in CompilerWarnings.cmake.
 add_library(project_warnings INTERFACE)
 include(cmake/CompilerWarnings.cmake)
 set_project_warnings(project_warnings)
 
+enable_testing()
+
+add_subdirectory(packaging)
 add_subdirectory(vendor)
 add_subdirectory(src)

CMakePresets.json

@@ -0,0 +1,56 @@
+{
+  "version": 6,
+  "cmakeMinimumRequired": {
+    "major": 3,
+    "minor": 22,
+    "patch": 0
+  },
+  "configurePresets": [
+    {
+      "name": "debug",
+      "displayName": "Debug",
+      "generator": "Ninja",
+      "binaryDir": "build/debug",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug"
+      }
+    },
+    {
+      "name": "release",
+      "displayName": "Release",
+      "generator": "Ninja",
+      "binaryDir": "build/release",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Release"
+      }
+    },
+    {
+      "name": "xcode-debug",
+      "displayName": "Debug (Xcode)",
+      "generator": "Xcode",
+      "binaryDir": "build/xcode-debug",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug"
+      },
+      "condition": {
+        "type": "equals",
+        "lhs": "${hostSystemName}",
+        "rhs": "Darwin"
+      }
+    },
+    {
+      "name": "xcode-release",
+      "displayName": "Release (Xcode)",
+      "generator": "Xcode",
+      "binaryDir": "build/xcode-release",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Release"
+      },
+      "condition": {
+        "type": "equals",
+        "lhs": "${hostSystemName}",
+        "rhs": "Darwin"
+      }
+    }
+  ]
+}

CODE_OF_CONDUCT.md

@@ -101,7 +101,7 @@ Violating these terms may lead to a permanent ban.
 ### 4. Permanent Ban
 
 **Community Impact**: Demonstrating a pattern of violation of community
-standards, including sustained inappropriate behavior,  harassment of an
+standards, including sustained inappropriate behavior, harassment of an
 individual, or aggression toward or disparagement of classes of individuals.
 
 **Consequence**: A permanent ban from any sort of public interaction within

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 Martin Helmut Fieber
+Copyright (c) 2022-2023 Martin Helmut Fieber
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,33 +1,22 @@
 # Base GUI project setup with SDL2 and OpenGL
 
-C++ gui project template with SDL2 and OpenGL 4.1.
+C++ GUI project template with [SDL2](https://www.libsdl.org) and [Dear ImGUI](https://github.com/ocornut/imgui) with
+OpenGL 4.1.
 
 ![Image of the example app.](example-app.png)
 
-## Setup
+## How to get started
 
-The project uses [CMake](https://cmake.org) and [Ninja](https://ninja-build.org).
+After using this template to create your own repository, it is time to first run and then customize!
 
-Build the application in debug mode:
+- Start here: [Quick Start](docs/QuickStart.md)
+- Continue here: [Usage Guide](docs/README.md)
 
-```shell
-cmake -GNinja -DCMAKE_BUILD_TYPE=Debug -B build/debug
-ninja -C build/debug
-```
+## Other versions
 
-Run the application:
-
-```shell
-cd ./build/debug/src/app && ./App
-```
-
-### Using Litr
-
-When using [Litr](https://github.com/krieselreihe/litr), the quick setup to build and run the application is:
-
-```shell
-litr build,start
-```
+There is also a [SDL2 version using the SDL2 Renderer](https://github.com/MartinHelmut/cpp-gui-template-sdl2) instead of
+OpenGL specifically, but it does not support
+multi-viewports or detached widgets.
 
 ## Disclaimer
 

cmake/CompilerWarnings.cmake

@@ -41,7 +41,7 @@ function(set_project_warnings project_name)
   set(CLANG_WARNINGS
     -Wall
     -Wextra # reasonable and standard
-    # -Wshadow # warn the user if a variable declaration shadows one from a
+    -Wshadow # warn the user if a variable declaration shadows one from a
     # parent context
     -Wnon-virtual-dtor # warn the user if a class with virtual functions has a
     # non-virtual destructor. This helps catch hard to
@@ -56,9 +56,6 @@ function(set_project_warnings project_name)
     -Wnull-dereference # warn if a null dereference is detected
     -Wformat=2 # warn on security issues around functions that format output
     # (ie printf)
-    # @todo: Temporarily deactivated for SDL2
-    # -Wdouble-promotion # warn if float is implicit promoted to double
-    # -Wold-style-cast # warn for c-style casts
     )
 
   if (WARNINGS_AS_ERRORS)
@@ -69,7 +66,7 @@ function(set_project_warnings project_name)
   set(GCC_WARNINGS
     ${CLANG_WARNINGS}
     -Wmisleading-indentation # warn if indentation implies blocks where blocks
-    # @todo: Currently not supported in CI due to an old gcc version.
+    # @todo: Somehow those make problems in some versions of Clang in Windows. So I deactivate them for now.
     # -Wduplicated-branches # warn if if / else branches have duplicated code
     # -Wduplicated-cond # warn if if / else chain has duplicated conditions
     # -Wlogical-op # warn about logical operations being used where bitwise were

cmake/StandardProjectSettings.cmake

@@ -4,7 +4,7 @@ if (NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
   set(CMAKE_BUILD_TYPE Debug CACHE STRING "Choose the type of build." FORCE)
 
   # Set the possible values of build type for cmake-gui, ccmake
-  set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS "Debug" "Release")
+  set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS "Debug" "Release" "RelWithDebInfo")
 endif ()
 
 find_program(CCACHE ccache)
@@ -23,11 +23,6 @@ if (DEACTIVATE_LOGGING)
   add_compile_definitions(APP_DEACTIVATE_LOGGING)
 endif ()
 
-option(TRACE "Enable detailed execution flow tracing" OFF)
-if (TRACE)
-  add_compile_definitions(TRACE)
-endif ()
-
 option(DEBUG "Enable debug statements and asserts" OFF)
 if (DEBUG OR CMAKE_BUILD_TYPE STREQUAL "Debug")
   add_compile_definitions(DEBUG APP_PROFILE)

cmake/StaticAnalyzers.cmake

@@ -1,14 +1,14 @@
 if (NOT CMAKE_BUILD_TYPE STREQUAL "Release")
   find_program(CLANGTIDY clang-tidy)
   if (CLANGTIDY)
-    message(STATUS "Using clang-tidy")
+    message(STATUS "Using clang-tidy, found ${CLANGTIDY}")
     set(CMAKE_CXX_CLANG_TIDY "${CLANGTIDY};-extra-arg=-Wno-unknown-warning-option")
   else ()
     message(WARNING "clang-tidy requested but executable not found")
   endif ()
 
   # This will gradually increase memory usage of the program,
-  # running on Apple M1, 13.0.
+  # discovered on Apple M1, 13.0.
   if (NOT WIN32)
     message(STATUS "Using address sanitizer")
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -O0 -fsanitize=address -g")

cmake/AppleBuild.cmake → cmake/UniversalAppleBuild.cmake

@@ -1,9 +1,8 @@
 # This file needs to be included before calling `project`.
-if (CMAKE_SYSTEM_NAME STREQUAL "Darwin")
+if (APPLE AND "${CMAKE_GENERATOR}" STREQUAL "Xcode")
   # Generate universal executable for Apple hardware.
-  set(CMAKE_OSX_ARCHITECTURES "arm64;x86_64" CACHE STRING "")
+  set(CMAKE_OSX_ARCHITECTURES "$(ARCHS_STANDARD)")
 
   # Support older macOS versions.
   set(CMAKE_OSX_DEPLOYMENT_TARGET 10.15 CACHE STRING "Minimum OS X deployment version")
-  set(CMAKE_OSX_SYSROOT macosx10.15)
 endif ()

docs/ApplicationIcons.md

@@ -0,0 +1,120 @@
+# Application icons
+
+## Generate app icons
+
+### macOS
+
+To generate a `.icns` file on macOS, an `.iconset` folder needs to be converted via `iconutil`. The
+folder `src/assets/icons/icon.iconset` contains all needed icon sizes. To generate the needed app icon under `src/assets/icons/icon.icns`, run from inside the `src/assets/icons` folder:
+
+```shell
+iconutil -c icns icon.iconset
+```
+
+### Windows
+
+To create the `icon.ico` file [ImageMagick](https://www.imagemagick.org) is used. From inside the `src/assets/icons` folder run:
+
+```shell
+convert \
+  windows/icon_16x16.png windows/icon_32x32.png \
+  windows/icon_64x64.png windows/icon_128x128.png \
+  windows/icon_256x256.png windows/icon_512x512.png \
+  icon.ico
+```
+
+Verify that the `icon.ico` was successfully created:
+
+```shell
+identify icon.ico
+```
+
+### Linux
+
+There is no need to generate an icon set for Linux. A high resolution PNG (1024x1024px) is enough for the app icon. This is located under `icons/BaseAppIcon.png`.
+
+## Icon design guidelines
+
+The example project contains an example icon. To get guiding for creating an own unique app icon, here a couple of resources:
+
+- [Windows app icon guidelines](https://learn.microsoft.com/en-us/windows/apps/design/style/iconography/app-icon-design)
+- [Apple human interface design, icons guide](https://developer.apple.com/design/human-interface-guidelines/foundations/app-icons/)
+
+## Integrating icons
+
+How are those application icons connected to become the icon of the generated executable? Through the packaging process and manifest files.
+
+### Package app icons
+
+For macOS and Windows app icons are packed as static resources via CMake's [target_sources](https://cmake.org/cmake/help/latest/command/target_sources.html) function in `src/app/cmake/AppAssets.cmake`. For example, adding the Windows `.ico` file to the main executable:
+
+```cmake
+# src/app/cmake/AppAssets.cmake
+target_sources(App PUBLIC ${PROJECT_SOURCE_DIR}/src/assets/icons/icon.ico)
+```
+
+On Linux, it needs to be part of the installation process that is defined in `src/app/cmake/packaging/Linux.cmake`, where application icons are installed in a shared directory `share/pixmaps`. This does look like the following:
+
+```cmake
+# src/app/cmake/packaging/Linux.cmake
+install(FILES ${PROJECT_SOURCE_DIR}/src/assets/icons/BaseAppIcon.png
+  DESTINATION share/pixmaps)
+```
+
+### Manifest files
+
+The manifest files then link the app icon to the executable.
+
+#### macOS
+
+For macOS the manifest file is an [Info.plist](https://developer.apple.com/documentation/bundleresources/information_property_list) defining application properties. It is located at `src/app/Manifests/Info.plist` and added to the app bundle through `src/app/cmake/packaging/Darwin.cmake`. Here the CMake function [set_target_properties](https://cmake.org/cmake/help/latest/command/set_target_properties.html) defines `MACOSX_BUNDLE_INFO_PLIST` for the manifest location. The icon name is defined inside the `Info.plist` file under the property name `CFBundleIconFile`.
+
+```cmake
+# src/app/cmake/packaging/Darwin.cmake
+
+# Reduced version of `set_target_properties` as example to set the manifest file.
+set_target_properties(App PROPERTIES
+  MACOSX_BUNDLE_INFO_PLIST "${CMAKE_CURRENT_SOURCE_DIR}/Manifests/Info.plist")
+```
+
+#### Windows
+
+The resource file `src/app/Manifests/app.rc` will bind the icon to the Windows executable. The resource file itself is then added as part of the application bundle via [target_sources](https://cmake.org/cmake/help/latest/command/target_sources.html) in `src/app/cmake/AppAssets.cmake`.
+
+```cmake
+target_sources(App PUBLIC
+    ${PROJECT_SOURCE_DIR}/src/assets/icons/icon.ico
+    ${PROJECT_SOURCE_DIR}/src/app/Manifests/app.rc)
+```
+
+#### Linux
+
+For Linux a `src/app/Manifests/App.desktop.in` defines the created shortcut with icon. The `.in` file will be processed by CMake via [configure_file](https://cmake.org/cmake/help/latest/command/configure_file.html) in `src/app/cmake/packaging/Linux.cmake`.
+
+It will take the `.in` file and produce a final `.desktop` file for Linux with the given icon name under the property `Icon=`.
+
+```cmake
+# src/app/cmake/packaging/Linux.cmake
+configure_file(
+  ${PROJECT_SOURCE_DIR}/src/app/Manifests/App.desktop.in
+  ${CMAKE_CURRENT_BINARY_DIR}/App.desktop
+  @ONLY)
+```
+
+The icon and the `.desktop` file then need to be installed.
+
+```cmake
+# src/app/cmake/packaging/Linux.cmake
+
+# Install .desktop file under share/applications
+install(FILES ${CMAKE_CURRENT_BINARY_DIR}/App.desktop
+  DESTINATION share/applications)
+
+# Install icon file under share/pixmaps
+install(FILES ${PROJECT_SOURCE_DIR}/src/assets/icons/BaseAppIcon.png
+  DESTINATION share/pixmaps)
+```
+
+***
+
+Next up: [Fonts](Fonts.md)