This is a CMake project template to get you started with modern C++ project. Works on Windows, Linux, and MacOS. This project aims to work seamlessly on major operating systems and without a lengthy setup process. Just install the dependencies through default package manager and you are good to go π!
This template comes with features that help you write bug/error prone code and make it easier to maintain and scale your project:
- Easy configuration using CMake Presets
- Address Sanitizer and Undefined Behavior Sanitizer enabled where possible
- Warnings as errors
- clang-tidy and cppcheck static analysis
- CPM for dependencies
- Code coverage with Codecov
- Continuous integration on three operating systems
The initial project includes:
- a basic CLI example
- examples for fuzz, unit, and constexpr testing
First, click the green Use this template
button near the top of this page.
This will take you to GitHub's
'Generate Repository'
page.
Fill in a repository name and short description,
and click 'Create repository from template'.
This will allow you to create a new repository in your GitHub account,
pre-populated with the contents of this project.
After creating the project please wait until the cleanup workflow has finished setting up your project and committed the changes.
Now you can clone the project locally and get to work!
git clone https://github.com/<user>/<your_new_repo>.git
To enable Codecov, you need to add
your Codecov token to the repository secrets as CODECOV_TOKEN
.
You may also want to create a badge for Codecov and add it to the README.
Before you start, we recommend you to install a package manager Chocolatey to install the dependencies. It makes installing tools like clang-tidy and cppcheck much easier.
- Install Visual Studio 2022 or Visual Studio Build Tools 2022
If you want to use Visual Studio as your IDE, install Visual Studio 2022. If you want to use other editors, install Visual Studio Build Tools 2022.
- Install using GUI Download the installer from Visual Studio 2022. Run the installer and select the "Desktop development with C++" workload. If you want to be able to compile with clang, search for "clang" in the individual components tab and install the "Clang compiler for Windows" component and "MSBuild Support for llvm toolset". You can change the configuration later from the installer.
Alternatively, you can use choco
to install Visual Studio / Visual Studio Build Tools 2022.
# Install Visual Studio Build Tools 2022
choco install visualstudio2022buildtools --package-parameters "--config path-to-this-project's-.vsconfig"
# Install Visual Studio 2022
choco install visualstudio2022community --package-parameters "--config path-to-this-project's-.vsconfig"
- Install
ccache
choco install ccache
- Install
cppcheck
choco install cppcheck
- Install
vswhere
choco install vswhere
sudo apt update
sudo apt install -y gcc g++ clang clang-tools clang-tidy llvm\
cmake ninja-build ccache cppcheck gcovr
brew install gcc llvm cmake ninja ccache cppcheck
Building is made easy with CMake Presets. You can configure and build the project with the following commands from the root of the project:
cmake --preset <preset_name>
cmake --build --preset build-<preset_name>
ctest --preset test-<preset_name>
<preset_name>
can be one of the following:
windows-msvc-debug
windows-msvc-release
unixlike-clang-debug
unixlike-clang-release
unixlike-gcc-debug
unixlike-gcc-release
Feel free to modify the presets to your liking in CMakePresets.json
.
This project uses 'actions/cache' to speed up the CI on GitHub actions. If you have trouble compiling solely in GitHub Actions, consider removing the cache and trying again. GitHub CLI is useful for this kind of operation.
The project supports MPI (Message Passing Interface) for distributed computing.
By default, MPI is disabled.
To enable MPI, you need to set "myproject_ENABLE_MPI": "ON"
in the CMakePresets.json
file.
In addition to enabling MPI,
you can also specify the number of nodes used when running ctest
by setting the "myproject_NPROC"
variable in the CMakePresets.json
file.
For example, to use 4 nodes, you would set "myproject_NPROC": 4
.
Please note that you need to have MPI installed on your system.
To disable MPI, you can set "myproject_ENABLE_MPI": "OFF"
in the CMakePresets.json
file.
The components to be installed to GitHub runners
are specified in a JSON file named oneapi_components.json
.
The project currently uses OneAPI to install
MPI binaries and library to the windows runners.
The oneapi_components.json
file is structured as follows:
{
"Windows": {
"basekit": {
"components": ["comp1", "comp2"]
},
"hpckit": {
"components": ["comp3", "comp4"]
}
}
}
In this file, you can specify the components you want to install for each kit. The components should be specified as an array of strings under the components key.
The list of component names is available at https://oneapi-src.github.io/oneapi-ci/.
If you have the installer at your hand,
you can run it with --list-components
to get the list of components the installer can install.
If you want to update the installer itself, change the URL in the workflow file.
Use options --trace
, --trace-source FILENAME
, -trace-expand
when configuring CMake project to debug CMakeLists.txt
clangd
looks for thecompile_commands.json
in the/build
directory. If you configure CMake with only the--preset
option,clangd
will not be able to find this file. Use-Bbuild
to build in thebuild
directory.- Testing framework heavily uses macros,
and is difficult to configure static analysis on the test files
(It checks the expanded
#define
and outputs errors). Therefore,cppcheck
andclang-tidy
has deliberately been turn off for testing targets. CMake 2.27 seems to support the featureSKIP_LINTING
which could help solve the issue in a more elegant way, but since cmake 2.27 is not widely distributed throughapt
, target compile properties has been modified intests/CMakeLists.txt
- Due to the issue where ubuntu-latest runners have an incompatible combination of clang and libstdc++ , the GitHub Actions installs newer versions of clang. When the issue is fixed, the code should compile without additional configuration to GitHub runners.
Open a new issue and we will help you out!