Merge branch 'main' into cuda

Author: aminya

.cmake-format.yaml

@@ -1,8 +1,20 @@
+format:
+  line_width: 120
+  tab_size: 2
+  max_pargs_hwrap: 3
+  separate_ctrl_name_with_space: false
+  separate_fn_name_with_space: false
+  dangle_parens: false
+  line_ending: unix
+markup:
+  bullet_char: "*"
+  enum_char: .
+  enable_markup: false
 parse:
   additional_commands:
     project_options:
       pargs:
-        nargs: '*'
+        nargs: "*"
         flags: []
       spelling: project_options
       kwargs:
@@ -12,7 +24,7 @@ parse:
         CONAN_OPTIONS: +
     catch_discover_tests:
       pargs:
-        nargs: '*'
+        nargs: "*"
         flags: []
       kwargs:
         OUTPUT_DIR: 1
@@ -22,15 +34,15 @@ parse:
         TEST_PREFIX: 1
     conan_add_remote:
       pargs:
-        nargs: '*'
+        nargs: "*"
         flags: []
       kwargs:
         INDEX: 1
         NAME: 1
         URL: 1
     conan_cmake_install:
       pargs:
-        nargs: '*'
+        nargs: "*"
         flags: []
       kwargs:
         BUILD: +
@@ -56,7 +68,7 @@ parse:
         SETTINGS_HOST: +
     cpmaddpackage:
       pargs:
-        nargs: '*'
+        nargs: "*"
         flags: []
       spelling: CPMAddPackage
       kwargs: &id001
@@ -85,19 +97,19 @@ parse:
         OPTIONS: +
     cpmfindpackage:
       pargs:
-        nargs: '*'
+        nargs: "*"
         flags: []
       spelling: CPMFindPackage
       kwargs: *id001
     cpmdeclarepackage:
       pargs:
-        nargs: '*'
+        nargs: "*"
         flags: []
       spelling: CPMDeclarePackage
       kwargs: *id001
     packageproject:
       pargs:
-        nargs: '*'
+        nargs: "*"
         flags: []
       spelling: packageProject
       kwargs:
@@ -121,15 +133,3 @@ parse:
     cpmgetpackageversion:
       pargs: 2
       spelling: CPMGetPackageVersion
-format:
-  line_width: 120
-  tab_size: 2
-  max_pargs_hwrap: 3
-  separate_ctrl_name_with_space: false
-  separate_fn_name_with_space: false
-  dangle_parens: false
-  line_ending: unix
-markup:
-  bullet_char: '*'
-  enum_char: .
-  enable_markup: false

README.md

@@ -15,10 +15,10 @@ cmake_minimum_required(VERSION 3.16)
 # You can later set fine-grained standards for each target using `target_compile_features`
 # set(CMAKE_CXX_STANDARD 17)
 
-# Add project_options v0.13.1
+# Add project_options v0.14.2
 # https://github.com/cpp-best-practices/project_options
 include(FetchContent)
-FetchContent_Declare(_project_options URL https://github.com/cpp-best-practices/project_options/archive/refs/tags/v0.13.1.zip)
+FetchContent_Declare(_project_options URL https://github.com/cpp-best-practices/project_options/archive/refs/tags/v0.14.2.zip)
 FetchContent_MakeAvailable(_project_options)
 include(${_project_options_SOURCE_DIR}/Index.cmake)
 
@@ -27,7 +27,7 @@ include(${_project_options_SOURCE_DIR}/Index.cmake)
 # run_vcpkg()
 
 # Set the project name and language
-project(myproject LANGUAGES CXX)
+project(myproject LANGUAGES CXX C)
 
 # Initialize project_options variable related to this project
 # This overwrites `project_options` and sets `project_warnings`
@@ -36,25 +36,27 @@ project_options(
       ENABLE_CACHE
       ENABLE_CPPCHECK
       ENABLE_CLANG_TIDY
-      # WARNINGS_AS_ERRORS
       # ENABLE_CONAN
       # ENABLE_IPO
-      # ENABLE_INCLUDE_WHAT_YOU_USE
-      # ENABLE_COVERAGE
-      # ENABLE_PCH
-      # PCH_HEADERS
       # ENABLE_DOXYGEN
-      # ENABLE_USER_LINKER
-      # ENABLE_BUILD_WITH_TIME_TRACE
-      # ENABLE_UNITY
+      # ENABLE_COVERAGE
+      # WARNINGS_AS_ERRORS
       # ENABLE_SANITIZER_ADDRESS
       # ENABLE_SANITIZER_LEAK
       # ENABLE_SANITIZER_UNDEFINED_BEHAVIOR
       # ENABLE_SANITIZER_THREAD
       # ENABLE_SANITIZER_MEMORY
+      # ENABLE_INCLUDE_WHAT_YOU_USE
+      # ENABLE_PCH
+      # PCH_HEADERS
+      # ENABLE_USER_LINKER
+      # ENABLE_BUILD_WITH_TIME_TRACE
+      # ENABLE_UNITY
       # CONAN_OPTIONS
 )
+```
 
+```cmake
 # add your executables, libraries, etc. here:
 
 add_executable(myprogram main.cpp)
@@ -74,27 +76,28 @@ target_link_system_libraries(
 
 It accepts the following named flags:
 
-- `WARNINGS_AS_ERRORS`: Treat the warnings as errors
+- `ENABLE_CACHE`: Enable cache if available
 - `ENABLE_CPPCHECK`: Enable static analysis with Cppcheck
 - `ENABLE_CLANG_TIDY`: Enable static analysis with clang-tidy
+- `ENABLE_CONAN`: Use Conan for dependency management
 - `ENABLE_IPO`: Enable Interprocedural Optimization (Link Time Optimization, LTO) in the release build
-- `ENABLE_INCLUDE_WHAT_YOU_USE`: Enable static analysis with include-what-you-use
 - `ENABLE_COVERAGE`: Enable coverage reporting for gcc/clang
-- `ENABLE_CACHE`: Enable cache if available
-- `ENABLE_PCH`: Enable Precompiled Headers
-- `ENABLE_CONAN`: Use Conan for dependency management
 - `ENABLE_DOXYGEN`: Enable Doxygen doc builds of source
-- `ENABLE_USER_LINKER`: Enable a specific linker if available
-- `ENABLE_BUILD_WITH_TIME_TRACE`: Enable `-ftime-trace` to generate time tracing `.json` files on clang
-- `ENABLE_UNITY`: Enable Unity builds of projects
+- `WARNINGS_AS_ERRORS`: Treat the warnings as errors
 - `ENABLE_SANITIZER_ADDRESS`: Enable address sanitizer
 - `ENABLE_SANITIZER_LEAK`: Enable leak sanitizer
 - `ENABLE_SANITIZER_UNDEFINED_BEHAVIOR`: Enable undefined behavior sanitizer
 - `ENABLE_SANITIZER_THREAD`: Enable thread sanitizer
 - `ENABLE_SANITIZER_MEMORY`: Enable memory sanitizer
+- `ENABLE_PCH`: Enable Precompiled Headers
+- `ENABLE_INCLUDE_WHAT_YOU_USE`: Enable static analysis with include-what-you-use
+- `ENABLE_USER_LINKER`: Enable a specific linker if available
+- `ENABLE_BUILD_WITH_TIME_TRACE`: Enable `-ftime-trace` to generate time tracing `.json` files on clang
+- `ENABLE_UNITY`: Enable Unity builds of projects
 
-It gets the following named parameters (each accepting multiple values):
+It gets the following named parameters that can have different values in front of them:
 
+- `DOXYGEN_THEME`: the name of the Doxygen theme to use. Supported themes: `awesome-sidebar` (default), `awesome` and `original`.
 - `PCH_HEADERS`: the list of the headers to precompile
 - `MSVC_WARNINGS`: Override the defaults for the MSVC warnings
 - `CLANG_WARNINGS`: Override the defaults for the CLANG warnings
@@ -113,7 +116,7 @@ Named String:
 - `VCPKG_DIR`: (Defaults to `~/vcpkg`). You can provide the vcpkg installation directory using this optional parameter.
   If the directory does not exist, it will automatically install vcpkg in this directory.
 
-- `VCPKG_URL`: (Defaults to `https://github.com/microsoft/vcpkg.git`). This option allows setting URL of the vcpkg repository. By default, the official vcpkg repository is used.
+- `VCPKG_URL`: (Defaults to `https://github.com/microsoft/vcpkg.git`). This option allows setting the URL of the vcpkg repository. By default, the official vcpkg repository is used.
 
 ## `target_link_system_libraries` function
 
@@ -134,14 +137,28 @@ target_link_libraries(main_cuda PRIVATE project_options project_warnings)
 target_link_cuda(main_cuda)
 ```
 
-## Changing the project_options parameters dynamically
+## Changing the project_options dynamically
+
+During the test and development, it can be useful to change options on the fly. For example, to enable sanitizers when running tests. You can include `DynamicOptions.cmake`, which imports the `dynamic_project_options` function.
+
+`dynamic_project_options` provides a recommended set of defaults (all static analysis and runtime analysis enabled for platforms where that is possible) while also providing a high-level option `ENABLE_DEVELOPER_MODE` (defaulted to `ON`) which can be turned off for easy use by non-developers.
 
-It might be useful to change the test and development options on the fly (e.g., to enable sanitizers when running tests). To do this, you can include the `GlobalOptions.cmake`, which adds global options for the arguments of `project_options` function.
+The goal of the `dynamic_project_options` is to give a safe and well-analyzed environment to the developer by default while simultaneously making it easy for a user of the project to compile while not having to worry about clang-tidy, sanitizers, cppcheck, etc.
 
-⚠️ It is highly recommended to keep the build declarative and reproducible by using the function arguments as explained above. The user of your code should not need to pass any special flags to build the library for normal usage. Please do not use this for anything other than test and development.
+The defaults presented to the user can be modified with
+
+- `set(<featurename>_DEFAULT value)` - for user and developer builds
+- `set(<featurename>_USER_DEFAULT value)` - for user builds
+- `set(<featureoptionname>_DEVELOPER_DEFAULT value)` - for developer builds
+
+If you need to fix a setting for the sake of a command-line configuration, you can use:
+
+```shell
+cmake -DOPT_<featurename>:BOOL=value
+```
 
 <details>
-<summary>Click to show the example:</summary>
+<summary> 👉 Click to show the example:</summary>
 
 ```cmake
 cmake_minimum_required(VERSION 3.16)
@@ -152,61 +169,37 @@ cmake_minimum_required(VERSION 3.16)
 # You can later set fine-grained standards for each target using `target_compile_features`
 # set(CMAKE_CXX_STANDARD 17)
 
-# Add project_options v0.13.1
+# Add project_options v0.14.2
 # https://github.com/cpp-best-practices/project_options
 include(FetchContent)
-FetchContent_Declare(_project_options URL https://github.com/cpp-best-practices/project_options/archive/refs/tags/v0.13.1.zip)
+FetchContent_Declare(_project_options URL https://github.com/cpp-best-practices/project_options/archive/refs/tags/v0.14.2.zip)
 FetchContent_MakeAvailable(_project_options)
 include(${_project_options_SOURCE_DIR}/Index.cmake)
 
- # ❗ Add global CMake options
-include(${_project_options_SOURCE_DIR}/src/GlobalOptions.cmake)
+ # ❗ Add dynamic CMake options
+include(${_project_options_SOURCE_DIR}/src/DynamicOptions.cmake)
 
 # uncomment to enable vcpkg:
 # # Setup vcpkg - should be called before defining project()
 # run_vcpkg()
 
 # Set the project name and language
-project(myproject LANGUAGES CXX)
-
-# ❗ enable sanitizers if running the tests
-option(FEATURE_TESTS "Enable the tests" OFF)
-if(FEATURE_TESTS)
-    if(CMAKE_SYSTEM_NAME STREQUAL "Windows")
-        set(ENABLE_SANITIZER_ADDRESS OFF)
-        set(ENABLE_SANITIZER_UNDEFINED_BEHAVIOR OFF)
-    else()
-        set(ENABLE_SANITIZER_ADDRESS "ENABLE_SANITIZER_ADDRESS")
-        set(ENABLE_SANITIZER_UNDEFINED_BEHAVIOR "ENABLE_SANITIZER_UNDEFINED_BEHAVIOR")
-    endif()
-endif()
+project(myproject LANGUAGES CXX C)
+
+# Set PCH to be on by default for all non-Developer Mode Builds
+# (this is just intended as an example of what is possible)
+set(ENABLE_PCH_USER_DEFAULT ON)
 
 # Initialize project_options variable related to this project
 # This overwrites `project_options` and sets `project_warnings`
 # uncomment the options to enable them:
-project_options(
-      ENABLE_CACHE
-      ENABLE_CPPCHECK
-      ENABLE_CLANG_TIDY
-      # WARNINGS_AS_ERRORS
-      # ENABLE_CONAN
-      # ENABLE_IPO
-      # ENABLE_INCLUDE_WHAT_YOU_USE
-      # ENABLE_COVERAGE
-      # ENABLE_PCH
-      # PCH_HEADERS
-      # ENABLE_DOXYGEN
-      # ENABLE_IPO
-      # ENABLE_USER_LINKER
-      # ENABLE_BUILD_WITH_TIME_TRACE
-      # ENABLE_UNITY
-      # ❗ Now, the address and undefined behavior sanitizers are enabled through CMake options
-      ${ENABLE_SANITIZER_ADDRESS}
-      ${ENABLE_SANITIZER_UNDEFINED_BEHAVIOR}
-      # ENABLE_SANITIZER_LEAK
-      # ENABLE_SANITIZER_THREAD
-      # ENABLE_SANITIZER_MEMORY
+dynamic_project_options(
+  # set PCH headers you want enabled. Format can be slow, so this might be helpful
+  PCH_HEADERS <vector> <string> <fmt/format.h>
 )
+```
+
+```cmake
 # add your executables, libraries, etc. here:
 
 add_executable(myprogram main.cpp)

src/Doxygen.cmake

@@ -1,8 +1,50 @@
 # Enable doxygen doc builds of source
-function(enable_doxygen)
+function(enable_doxygen DOXYGEN_THEME)
+  # If not specified, use the top readme file as the first page
+  if((NOT DOXYGEN_USE_MDFILE_AS_MAINPAGE) AND EXISTS "${PROJECT_SOURCE_DIR}/README.md")
+    set(DOXYGEN_USE_MDFILE_AS_MAINPAGE "${PROJECT_SOURCE_DIR}/README.md")
+  endif()
+
+  # set better defaults for doxygen
   set(DOXYGEN_CALLER_GRAPH YES)
   set(DOXYGEN_CALL_GRAPH YES)
   set(DOXYGEN_EXTRACT_ALL YES)
-  find_package(Doxygen REQUIRED dot)
-  doxygen_add_docs(doxygen-docs ${PROJECT_SOURCE_DIR})
+  set(DOXYGEN_GENERATE_TREEVIEW YES)
+  # svg files are much smaller than jpeg and png, and yet they have higher quality
+  set(DOXYGEN_DOT_IMAGE_FORMAT svg)
+  set(DOXYGEN_DOT_TRANSPARENT YES)
+
+  # If not specified, exclude the vcpkg files and the files CMake downloads under _deps (like project_options)
+  if(NOT DOXYGEN_EXCLUDE_PATTERNS)
+    set(DOXYGEN_EXCLUDE_PATTERNS "${CMAKE_CURRENT_BINARY_DIR}/vcpkg_installed/*" "${CMAKE_CURRENT_BINARY_DIR}/_deps/*")
+  endif()
+
+  if("${DOXYGEN_THEME}" STREQUAL "")
+    set(DOXYGEN_THEME "awesome-sidebar")
+  endif()
+
+  if("${DOXYGEN_THEME}" STREQUAL "awesome" OR "${DOXYGEN_THEME}" STREQUAL "awesome-sidebar")
+    # use a modern doxygen theme
+    # https://github.com/jothepro/doxygen-awesome-css v1.6.1
+    FetchContent_Declare(_doxygen_theme
+                         URL https://github.com/jothepro/doxygen-awesome-css/archive/refs/tags/v1.6.1.zip)
+    FetchContent_MakeAvailable(_doxygen_theme)
+    if("${DOXYGEN_THEME}" STREQUAL "awesome" OR "${DOXYGEN_THEME}" STREQUAL "awesome-sidebar")
+      set(DOXYGEN_HTML_EXTRA_STYLESHEET "${_doxygen_theme_SOURCE_DIR}/doxygen-awesome.css")
+    endif()
+    if("${DOXYGEN_THEME}" STREQUAL "awesome-sidebar")
+      set(DOXYGEN_HTML_EXTRA_STYLESHEET ${DOXYGEN_HTML_EXTRA_STYLESHEET}
+                                        "${_doxygen_theme_SOURCE_DIR}/doxygen-awesome-sidebar-only.css")
+    endif()
+  else()
+    # use the original doxygen theme
+  endif()
+
+  # find doxygen and dot if available
+  find_package(Doxygen REQUIRED OPTIONAL_COMPONENTS dot)
+
+  # add doxygen-docs target
+  message(STATUS "Adding `doxygen-docs` target that builds the documentation.")
+  doxygen_add_docs(doxygen-docs ALL ${PROJECT_SOURCE_DIR}
+                   COMMENT "Generating documentation - entry file: ${CMAKE_CURRENT_BINARY_DIR}/html/index.html")
 endfunction()