CMake/C++ template project

This CMake/C++ template project gives me a good starting point for f.e. GPU/Graphics programming. For everything close to hardware ... .

For the official docs follow this link.

About The Project • Getting Started • License • Literature

Table of Contents

1. About The Project
   • Key Features
   • Dependencies
   • Useful tools
2. Getting Started
   • Prerequisites
   • Installation
3. Tests
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgements
9. Literature

About The Project

This project is dedicated to compiling a comprehensive collection of best practices for C++ development using CMake. It serves as a definitive guide for starting new C++ projects, providing insights into optimal project setup, modern CMake techniques, and efficient workflows. The repository includes examples, templates, and detailed instructions to help developers of all levels adopt industry standards and improve their project configuration and build processes.

Frequently tested under

• windows server 2025 x64 Clang 20.1.0 and MSVC
• ubuntu 24.04 x64 Clang 18.1.3
• ubuntu 24.04 ARM Clang 18.1.3

Key Features

Category	Feature	Implement Status
Build System	CMake > 4.0	✔️
Performance	Performance Benchmark	✔️
Platform Support	Linux/Windows support	✔️
Compiler Support	Clang/GNU/MSVC support	✔️

Legend:

• ✔️ - completed
• 🔶 - in progress
• ❌ - not started

Dependencies

This enumeration also includes submodules.

• nlohmann_json
• SPDLOG
• gtest
• gbenchmark
• google fuzztest

Optional

• Rust
• corrision-rs
• cxx

Useful tools

• NSIS
• doxygen
• cppcheck
• cmake
• valgrind
• clangtidy
• visualstudio
• ClangPowerTools
• Codecov
• Ccache
• Sccache

Benchmarking

• gperftools

VSCode Extensions

• CMake format
• CMake tools
• CppTools

Getting Started

Specific version requirements

C++23 or higher required.
C17 or higher required.
CMake 4.0.0 or higher required.

Installation

1. Clone the repo

   git clone --recurse-submodules [email protected]:Kataglyphis/Kataglyphis-CMakeTemplate.git

   NOTE: In case you forgot the flag --recurse run the following command

   git submodule update --init --recursive
   

   afterwards.
2. Optional: Using the newest clang compiler. Install via apt. See here:
3. Optional: Run scripts/prepare_tooling.sh for preparing important dev tools.
4. Then build your solution with [CMAKE] (https://cmake.org/)
   Here the recommended way over command line after cloning the repo:
   

NOTE: Here we use CmakePresets to simplify things. Consider using it too or just build on a common way.

For now the features in Rust are experimental. If you want to use them install Rust and set RUST_FEATURES=ON on your CMake build.

(for clarity: Assumption you are in the dir you have cloned the repo into)

$ mkdir build ; cd build
# enlisting all available presets
$ cmake --list-presets=all ../
$ cmake --preset <configurePreset-name> ../
$ cmake --build --preset <buildPreset-name> .

Upgrades

Rusty things:

1. Do not forget to upgrade the cxxbridge from time to time:

cargo install cxxbridge-cmd

Tests

I have four tests suites.

1. Compilation Test Suite: This suite gets executed every compilation step. This ensures the very most important functionality is correct before every compilation.

2. Commit Test Suite: This gets executed on every push. More expensive tests are allowed :)

3. Perf test suite: It is all about measurements of performance. We are C++ tho!

4. Fuzz testing suite

Performance Tests

gperftools and pprof

Install deps

Linux only

1. Step:

sudo apt-get install google-perftools libgoogle-perftools-dev graphviz
####### only if go is not installed already 
wget https://go.dev/dl/go1.24.3.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.24.3.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin
source ~/.bashrc
# to see if everything works
go version
####### go on with this step if go already installed
go install github.com/google/pprof@latest  # if you want to use latest Go-based pprof
export PATH="$PATH:$HOME/go/bin"
source ~/.bashrc  # or source ~/.zshrc

2. Step: Run actual profiling and look into results:

LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libprofiler.so CPUPROFILE=profile.prof ./build/KataglyphisCppProject
pprof -http=:8080 ./build/KataglyphisCppProject profile.prof

valgrind

sudo apt install valgrind kcachegrind
# build in debug for readable information
valgrind --tool=callgrind ./build/KataglyphisCppProject

perf

sudo apt install linux-tools-$(uname -r)
perf record ./build/KataglyphisCppProject

Static Analyzers

clang --analyze --output-format html $(find Src -name '*.cpp' -o -name '*.cc')
scan-build cmake --build .
clang-tidy -p=./build/compile_commands.json  $(find Src -name '*.cpp' -o -name '*.cc')

Format cmake files

uv venv
source .venv/bin/activate
pip install -v -e .
cmake-format -c ./.cmake-format.yaml -i $(find cmake -name '*.cmake' -o -name 'CMakeLists.txt')

Format code files

clang-format -i $(find include -name "*.cpp" -or -name "*.h" -or -name "*.hpp")

Docs

Build the docs

uv venv
source .venv/bin/activate
pip install -r requirements.txt
cd docs 
make html

Roadmap

Upcoming :)

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Contact

Jonas Heinle - @Cataglyphis_ - [email protected]

jonasheinle.de

Acknowledgements

Literature

Some very helpful literature, tutorials, etc.

Rust

• rust-lang

CMake/C++

• Cpp best practices
• Integrate Rust into CMake projects
• corrision-rs
• cxx
• C++ Software Design by Klaus Iglberger