C++ Project Template

This is a template for C++ projects. What you get:

• Use of modern CMake for building and compiling
• External libraries installed and managed by Vcpkg Package Manager:
  • JSON
  • spdlog
  • cxxopts
  • fmt
• Tooling: Automatically update submodules, CCache, and Sanitizers
• Code analysis with Cppcheck, Clang-Tidy, and Include what you use
• Unit testing with Googletest
• Code coverage reports, including automatic upload to Codecov
• Code documentation with Doxygen and Github Pages
• Continuous integration testing with Github Actions and pre-commit

Structure

├── CMakeLists.txt
├── cmake
│   ├── CMake modules
│   └── ...
├── docs
│   └── html/
├── external
│   ├── vcpkg/
│   └── CMakesLists.txt
├── include
│   ├── pch.h
│   └── ...
├── lib
│   └── ...
├── src
│   ├── Main.cpp
│   └── ...
└── test
    ├── CMakeLists.txt
    └── ...

Headers go in include/, source code in src/, and unit tests go in test/

Software Requirements

These can be installed with choco and pip on windows by running Install.bat (choco and pip must be installed manually)

• CMake v3.21+
• GNU Makefile
• MSVC 2017 (or higher), G++9 (or higher), or Clang++9 (or higher)
• Vcpkg (included as a submodule)
• (Optional) Tooling:
  • Ccache
• (Optional) Static analyzers:
  • Cppcheck
  • Clang-Tidy
  • Include what you use (this must be built manually, I think I successfully build it on windows with Clang)
• (Optional*, Clang compiler only) Code Coverage: llvm-profdata and llvm-cov (download with LLVM)
• (Optional*) Documentation: Doxygen and Graphviz

*It is not necessary to install the software for Code Coverage and Documentation locally as they can be built and automatically deployed by workflows

Additional setup

GitHub

• Allow template janitor workflow to complete, this will rename various placeholders in the CMake files to your new project name and also delete some files that you don't need
• Give your workflows write permission in Settings/Actions/General/Workflow permissions (documentation will fail to deploy to gh-pages unless this is done)
• Setup GitHub Pages

Local Machine

• Ensure all software is in your PATH environment variable (relaunch VSCode or cmd for the changes to be recognised)
• (Optional) If you're using the Clang compiler, add a variable called EXTERNAL_INCLUDE to your environment variables (system or user) and give it the paths to the various windows headers provided by Visual Studio. The reason the variable is called EXTERNAL_INCLUDE is because github workflows use this variable too. For instance the headers currently needed by this project:

C:\Program Files\Microsoft Visual Studio\2022\Preview\VC\Tools\MSVC\14.38.32919\include
C:\Program Files (x86)\Windows Kits\10\Include\10.0.22621.0\um
C:\Program Files (x86)\Windows Kits\10\Include\10.0.22621.0\shared
C:\Program Files (x86)\Windows Kits\10\Include\10.0.22621.0\ucrt
C:\Program Files (x86)\Windows Kits\10\Include\10.0.22621.0\winrt

• Modify "generator" in CMakeUserPresets.json to the generator you wish to use although this project is geared towards Ninja or Ninja-Multi-Config generators
• Modify CMAKE_C_COMPILER and CMAKE_CXX_COMPILER in CMakeUserPresets.json to the compiler you wish to use
• (Optional) Automate unit tests with git hooks (for example: pre-commit)
• (Optional) Install the various hooks listed in .pre-commit-config.yaml for use with pre-commit or delete the file if you don't intend to use it. Pre-commit can be automated with git hooks like ctest above

Building

First, clone this repo:

git clone --recursive https://github.com/<your github username>/<your repository name>

Now ideally use VSCode with CMake Tools which will read from CMakeUserPresets.json and give you a nice toolbar on the bottom of the VSCode window to switch between configurations. Alternatively you can build the project manually on the command line:

• Executable

cd build
cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_EXECUTABLE=ON ..
cmake --build . --config Release
cd bin
./<your project name>.exe

• Unit testing

cd build
cmake -DCMAKE_BUILD_TYPE=Debug ..
cmake --build . --config Debug --target unit_tests
ctest -C Debug -VV

• Code Coverage (Clang compiler only)

cd build
cmake -DCMAKE_BUILD_TYPE=Debug -DENABLE_CODE_COVERAGE=ON ..
cmake --build . --config Debug --target unit_tests

• Documentation

cd build
cmake -DCMAKE_BUILD_TYPE=Debug -DENABLE_DOXYGEN=ON ..
cmake --build . --config Debug --target doxygen

For more info about CMake see here.