C++ Experiments CMake Template

The C++ Experiments CMake Template is a project template for modern C++ projects with the CMake build system and Visual Studio Code as a development environment.

The default setting is the C++23 standard.

Components

1. C++ Compiler

GCC and CLang are supported in current versions with sufficient C++23 support. Testing is carried out with GCC 14 and CLang 18.

2. LTO Support

If the installed compiler/linker supports LTO, this is activated by default.

Disable with ENABLE_LTO=OFF.

3. ccache/sccache Support

If the programs ccache or sccache are installed and found by CMake, these compiler caches are used for build and linking.

Disable with ENABLE_CCACHE=OFF.

4. Compiler Warnings

Very strict compiler warnings in order to create error-free, secure and multiplatform-compatible code.

With the CMake option ENABLE_WARNINGS_AS_ERRORS these warnings can also be degraded to errors.
So set ENABLE_WARNINGS_AS_ERRORS=ON.

To disable all the compiler warnings setup set ENABLE_WARNINGS=OFF.

5. Code Checks

Provided the tools are installed in the development environment, they are used to check the created source code.
Build targets are also available in CMake.

• clang-tidy (Disable with ENABLE_CLANG_TIDY=OFF)
• cppchecker (Disable with ENABLE_CPPCHECK=OFF)
• flawfinder (Disable with ENABLE_FLAWFINDER=OFF)

6. Sanitizer Compile Options

The following sanitizer options are optionally available for compiling:

• ENABLE_SANITIZE_ADDR "Enable address sanitize."
• ENABLE_SANITIZE_UNDEF "Enable undefined sanitize."
• ENABLE_SANITIZE_LEAK "Enable leak sanitize."
• ENABLE_SANITIZE_THREAD "Enable thread sanitize."

7. CPM CMake Package Manager

With CPM, external dependencies for the project can be added very easily during the build process.

8. Doxygen Code Documentation

If installed on the system, the code documentation tool Doxygen is activated and provides the build target docs for the creation of HTML documentation in the docs subfolder.
The theme doxygen-awesome-css is used.
The files in the doxygen folder can be edited for customisation.

Disable with ENABLE_DOXYGEN=OFF.

9. CTest and Catch2 Testing

Tests are using CTest of CMake.

It can be disabled by setting BUILD_TESTING=OFF.

Catch2 is installed automatically (can be deactivated) and can be used for unit tests.
Optionally, any other tool can be installed, e.g. with CPM.

Disable with ENABLE_CATCH2_TEST=OFF.

9. Code Coverage of Tests

Code coverage report in tests can be enabled with ENABLE_COVERAGE=ON.

The external tool gcovr is required for this to work. Any version >= 5.0 should do.

To run the coverage report the CMake_ target coverage is to be used.
The compilation and linking is done with special flags and additional lib. So this should be only enabled to generate a report.

A textual report is in the console output and the Cobertura XML format in saved in build/gcov/cobertura-coverage.xml.

Optional configuration can be done in file gcovr.cfg.

With GaelGirodon/ci-badges-action GitHub Workflow Action a badge can be created like in this template.

10. GitHub Workflow

There is provided the safe-cplusplus-build.yml workflow for GitHub.
It does source and safety checks provided by the multiple CMake targets created by helper functions of this template.
After build of Debug and Release config the tests are running.
On any failure the workflow fails.

Organisation of the Project Structure

There are the subfolders apps, include, src and tests.

apps is intended for the sources of applications
include is the base of the usual include files
src is for shared source components for building objects or libraries. tests is the subfolder for unit tests

These folders contain CMakeLists.txt files, each of which automatically involve further CMakeLists.txt files in deeper subfolders and thus a tree structure can be created very easily.

Based on the existing example code in the folders, it should be comprehensable how you can adapt the structure for your own project.

The include folder is added to the default includes of compiler.

custom_target Magic

The provided CMakeLists.txt in subfolders of the template project contains the usage of CMake helper functions out of cmake/custom_target.cmake.

So for apps this might look like:

include(custom_target)

set(TARGET_NAME env_crashloop)
create_executable(${TARGET_NAME} env_crashloop.cpp)
target_link_libraries(${TARGET_NAME} PRIVATE -lpthread)

The create_executable(${TARGET_NAME} <source files...>) make the required CMake setup to compile the code like intended and provides useful CMake targets.
Afterwards you can call any CMake function on the target which makes sense for your project.

The example libraries in src are using a quite simple CMakeLists.txt with comparable purpose:

include(custom_target)

set(TARGET_NAME liba)
create_library(${TARGET_NAME} lib.cpp)

For unit tests using CTest like in the sample bare_test:

include(custom_target)

if(BUILD_TESTING)
  set(TEST_NAME bare_test)
  create_test(${TEST_NAME})
  add_test(NAME ${TEST_NAME} COMMAND ${TEST_NAME})
  # target_link_libraries(${TEST_NAME} PRIVATE liba)
endif()

There you have to call at least add_test() provided by CMake.

For unit tests with the Catch2 framework like in catch2_a_test:

include(custom_target)

if(ENABLE_CATCH2_TEST)
  set(TEST_NAME sum_tests)
  create_test(${TEST_NAME})
  target_link_libraries(${TEST_NAME} PRIVATE liba)
endif()

Here the addition of tests for CTest is handled by Catch2 and you must not call add_test() yourself.

License

BSD 1-Clause License

Copyright (c) 2024 Markus Kolb All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.