Composing CMake targets with recursive sources discovery

Template variables

Those are the variables you need to replace into your CMake once (and forger). They look like this - {{variable}}.

Building

1. Set the BUILD_TYPE env var to either Debug or Release. Run BUILD_TYPE=Debug in bash, $BUILD_TYPE = "Debug" in PowerShell.
2. At the root of the project (at the same level as CMakeLists.txt), run

cmake -S . -B build -DCMAKE_BUILD_TYPE=$BUILD_TYPE
cmake --build build --config $BUILD_TYPE

The build results (and CMake caches) will go into the build directory. Make sure to .gitignore it ;)!

⚠ Due to the nature of CMake's recursive capabilites, you need to re-run both commands whenever you modify a sources tree (add, delete, or move a file).

Code coverage

Code coverage is possible with lcov. To do so

1. CodeCoverage.cmake cmake module must be imported (just put it into .cmake folder if you're following the baseline).
2. A dedicated version of libraries must be built for coverage specifically.

Baseline

cmake_minimum_required(VERSION 3.15)

list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/.cmake")
Include(FetchContent)

project({{project_name}} VERSION 0.0.1)
set(CMAKE_CXX_STANDARD 17)
add_compile_definitions("$<$<CONFIG:DEBUG>:_DEBUG>")

find_program( LCOV_PATH  NAMES lcov lcov.bat lcov.exe lcov.perl)
if(LCOV_PATH)
	Include(CodeCoverage)
endif()

find_package(Threads)

SET (CMAKE_ENABLE_EXPORTS TRUE)

Variables:

• {{project_name}}: Project name

Contexpl:

• CMake modules loaded from .cmake subdirectory.
• If coverage tooling is installed, it is loaded, and CMake modules too.
• System-specific multithreading options are explored.

Library

file(GLOB_RECURSE {{lib_srcset}} "${PROJECT_SOURCE_DIR}/{{lib_srcset_location}}/*.hpp" "${PROJECT_SOURCE_DIR}/{{lib_srcset_location}}/*.cpp")
add_library({{lib_name}} STATIC ${{{lib_srcset}}})
include_directories({{lib_name}} ${PROJECT_SOURCE_DIR}/lib)
include_directories({{lib_name}} ${PROJECT_SOURCE_DIR}/{{lib_srcset_location}})
target_compile_options({{lib_name}} PRIVATE
	$<$<CXX_COMPILER_ID:MSVC>:/W4 /WX>
	$<$<NOT:$<CXX_COMPILER_ID:MSVC>>:-Wall -Wextra -Werror>
)
target_link_libraries({{lib_name}} ${CMAKE_THREAD_LIBS_INIT})

if(WIN32)
	target_link_libraries({{lib_name}} ws2_32 "$<$<CONFIG:DEBUG>:dbghelp>")
endif()

Variables:

• {{lib_name}}: Library name.
• {{lib_srcset}}: Name of the source-set (globally unique) for the library sources.
• {{lib_srcset_location}}: (Sub)Folder containing (recursively) library sources.

Contexpl:

• Static library added to CMake configuration.
• Sources explored recursively for .cpp and .hpp files.
• Library headers from lib project subdirectory made available.
• Compile with all warnings and errors, treat warnings as errors.
• Link to system multithreading lib.
• If on Windows, link to windows system, and in debug mode to windows debug utils.

Executable

file(GLOB_RECURSE {{exe_srcset}} "${PROJECT_SOURCE_DIR}/{{exe_srcset_location}}/*.hpp" "${PROJECT_SOURCE_DIR}/{{exe_srcset_location}}/*.cpp")

add_executable({{exe_name}} ${{{exe_srcset}}})
include_directories({{exe_name}} ${PROJECT_SOURCE_DIR}/lib)
include_directories({{exe_name}} ${PROJECT_SOURCE_DIR}/{{lib_srcset_location}})
include_directories({{exe_name}} ${PROJECT_SOURCE_DIR}/{{exe_srcset_location}})
target_compile_options({{exe_name}} PRIVATE
	$<$<CXX_COMPILER_ID:MSVC>:/W4 /WX>
	$<$<NOT:$<CXX_COMPILER_ID:MSVC>>:-Wall -Wextra -Werror>
)
target_link_libraries({{exe_name}} {{lib_name}})
set_property(TARGET {{exe_name}} PROPERTY POSITION_INDEPENDENT_CODE TRUE)

Variables:

• {{lib_name}}: Library name.
• {{lib_srcset_location}}: (Sub)Folder containing (recursively) library sources.
• {{exe_name}}: Executable name.
• {{exe_srcset}}: Name of the source-set (globally unique) for the exe sources.
• {{exe_srcset_location}}: (Sub)Folder containing (recursively) exe sources.

Contexpl:

• PIC/PIE executable added to CMake configuration.
• Sources explored recursively for .cpp and .hpp files.
• Library headers from lib project subdirectory made available.
• Compile with all warnings and errors, treat warnings as errors.
• Linked to principal library from the project.

Testing with Catch2

# Get Catch2
FetchContent_Declare(
  Catch2
  GIT_REPOSITORY https://github.com/catchorg/Catch2.git
  GIT_TAG        {{catch2_version}})
FetchContent_MakeAvailable(Catch2)
FetchContent_GetProperties(Catch2 SOURCE_DIR src_Catch2)
list(APPEND CMAKE_MODULE_PATH "${src_Catch2}/extras/")

set(CTEST_OUTPUT_ON_FAILURE 1)
include(CTest)
include(Catch)

# Initialize test target
file(GLOB_RECURSE {{tests_srcset}} "${PROJECT_SOURCE_DIR}/{{tests_srcset_location}}/*.hpp" "${PROJECT_SOURCE_DIR}/{{tests_srcset_location}}/*.cpp")
add_executable({{tests_name}} ${{{tests_srcset}}})
target_compile_options({{tests_name}} PRIVATE
	$<$<CXX_COMPILER_ID:MSVC>:/W4 /WX>
	$<$<NOT:$<CXX_COMPILER_ID:MSVC>>:-Wall -Wextra -Wno-unused -Wno-missing-field-initializers -Werror>
)
target_link_libraries({{tests_name}} Catch2::Catch2WithMain)
include_directories({{tests_name}} ${PROJECT_SOURCE_DIR}/lib)
include_directories({{tests_name}} ${PROJECT_SOURCE_DIR}/{{lib_srcset_location}})
include_directories({{tests_name}} ${PROJECT_SOURCE_DIR}/{{tests_srcset_location}})
if(LCOV_PATH)
  target_link_libraries({{tests_name}} {{lib_name_cov}})
	setup_target_for_coverage_lcov(
		NAME {{tests_name_cov}}
		EXECUTABLE {{tests_name}}
		BASE_DIRECTORY "${PROJECT_SOURCE_DIR}"
		EXCLUDE "lib/*"
	)
else()
  target_link_libraries({{tests_name}} {{lib_name}})
endif()
catch_discover_tests({{tests_name}})

Variables:

• {{catch2_version}}: Catch2 version.
• {{lib_name}}: Library (subject to testing) name.
• {{lib_name_cov}}: Library (subject to testing) name, built for code coverage.
• {{lib_srcset_location}}: (Sub)Folder containing (recursively) library sources.
• {{tests_name}}: Tests executable name.
• {{tests_name_cov}}: Tests executable name, with code coverage.
• {{tests_srcset}}: Name of the source-set (globally unique) for the tests sources.
• {{tests_srcset_location}}: (Sub)Folder containing (recursively) tests sources.

Contexpl:

• Catch2 framework fetched from git and loaded into CMake.
• CTest configured to crash on test failure.
• Testing executable powered by Catch2 added to CMake configuration.
• Sources explored recursively for .cpp and .hpp files.
• Library headers from lib project subdirectory made available.
• Compile with all warnings and errors, treat warnings as errors.
• Linked to library for testing.
• Coverage-enabled testing executable created if coverage is possible.

CUDA

For CUDA support, please refer to this amazing guide → https://cliutils.gitlab.io/modern-cmake/chapters/packages/CUDA.html