Modern C++ Template
A quick C++ template for modern CMake projects, aimed to be an easy to use starting point.
This is my personal take on such a type of template, thus I might not use the best practices or you might disagree with how I do things. Any and all feedback is greatly appreciated!
Features
-
Modern CMake configuration and project, which, to the best of my knowledge, uses the best practices,
-
An example of a Clang-Format config, inspired from the base Google model, with minor tweaks. This is aimed only as a starting point, as coding style is a subjective matter, everyone is free to either delete it (for the LLVM default) or supply their own alternative,
-
Static analyzers integration, with Clang-Tidy and Cppcheck, the former being the default option,
-
Doxygen support, through the
ENABLE_DOXYGENoption, which you can enable if you wish to use it, -
Unit testing support, through GoogleTest (with an option to enable GoogleMock) or Catch2,
-
Code coverage, enabled by using the
ENABLE_CODE_COVERAGEoption, through Codecov CI integration, -
Package manager support, with Conan and Vcpkg, through their respective options
-
CI workflows for Windows, Linux and MacOS using GitHub Actions, making use of the caching features, to ensure minimum run time,
-
.md templates for: README, Contributing Guideliness, Issues and Pull Requests,
-
Permissive license to allow you to integrate it as easily as possible. The template is licensed under the Unlicense,
-
Options to build as a header-only library or executable, not just a static or shared library.
-
Ccache integration, for speeding up rebuild times
Getting Started
These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.
Prerequisites
This project is meant to be only a template, thus versions of the software used can be change to better suit the needs of the developer(s). If you wish to use the template as-is, meaning using the versions recommended here, then you will need:
-
CMake v3.15+ - found at https://cmake.org/
-
C++ Compiler - needs to support at least the C++17 standard, i.e. MSVC, GCC, Clang
Note: You also need to be able to provide CMake a supported generator.
Installing
It is fairly easy to install the project, all you need to do is clone if from GitHub or generate a new repository from it (also on GitHub).
If you wish to clone the repository, rather than generate from it, you simply need to run:
git clone https://github.com/filipdutescu/modern-cpp-template/
After finishing getting a copy of the project, with any of the methods above, create a new folder in the include/ folder, with the name of your project. Edit cmake/SourcesAndHeaders.cmake to add your files.
You will also need to rename the cmake/ProjectConfig.cmake.in file to start with the exact name of your project. Such as cmake/MyNewProjectConfig.cmake.in. You should also make the same changes in the GitHub workflows provided, notably .github/workflows/ubuntu.yml, in which you should replace the CMake option -DProject_ENABLE_CODE_COVERAGE=1 to -DMyNewProject_ENABLE_CODE_COVERAGE=1.
Finally, change "Project" from CMakeLists.txt, from
project(
"Project"
VERSION 0.1.0
LANGUAGES CXX
)
to the exact name of your project, i.e. using the previous name it will become:
project(
MyNewProject
VERSION 0.1.0
LANGUAGES CXX
)
To install an already built project, you need to run the install target with CMake. For example:
cmake --build build --target install --config Release
# a more general syntax for that command is:
cmake --build <build_directory> --target install --config <desired_config>
Building the project
To build the project, all you need to do, after correctly installing the project, is run a similar CMake routine to the the one below:
mkdir build/ && cd build/
cmake .. -DCMAKE_INSTALL_PREFIX=/absolute/path/to/custom/install/directory
cmake --build . --target install
Note: The custom
CMAKE_INSTALL_PREFIXcan be omitted if you wish to install in the default install location.
More options that you can set for the project can be found in the cmake/StandardSettings.cmake file. For certain options additional configuration may be needed in their respective *.cmake files (i.e. Conan needs the CONAN_REQUIRES and might need the CONAN_OPTIONS to be setup for it work correctly; the two are set in the cmake/Conan.cmake file).
Generating the documentation
In order to generate documentation for the project, you need to configure the build to use Doxygen. This is easily done, by modifying the workflow shown above as follows:
mkdir build/ && cd build/
cmake .. -D<project_name>_ENABLE_DOXYGEN=1 -DCMAKE_INSTALL_PREFIX=/absolute/path/to/custom/install/directory
cmake --build . --target doxygen-docs
Note: This will generate a
docs/directory in the project's root directory.
Running the tests
By default, the template uses Google Test for unit testing. Unit testing can be disabled in the options, by setting the ENABLE_UNIT_TESTING (from cmake/StandardSettings.cmake) to be false. To run the tests, simply use CTest, from the build directory, passing the desire configuration for which to run tests for. An example of this procedure is:
cd build # if not in the build directory already
ctest -C Release # or `ctest -C Debug` or any other configuration you wish to test
# you can also run tests with the `-VV` flag for a more verbose output (i.e.
#GoogleTest output as well)
End to end tests
If applicable, should be presented here.
Coding style tests
If applicable, should be presented here.
Contributing
Please read CONTRIBUTING.md for details on our how you can become a contributor and the process for submitting pull requests to us.
Versioning
This project makes use of SemVer for versioning. A list of existing versions can be found in the project's releases.
Authors
- Filip-Ioan Dutescu - @filipdutescu
License
This project is licensed under the Unlicense - see the LICENSE file for details
![[BUG] msvc runtime library not setup at all.](https://avatars.githubusercontent.com/u/10578713?v=4)
![[FEATURE] Release workflow for github](https://avatars.githubusercontent.com/u/841681?v=4)
![[FEATURE] Control which changes trigger github actions](https://avatars.githubusercontent.com/u/3843619?v=4)
![[BUG] cmake fails when Project_BUILD_EXECUTABLE is true](https://avatars.githubusercontent.com/u/70304?v=4)
![[BUG] CMakeLists.txt source files and header files do not print as list](https://avatars.githubusercontent.com/u/56540191?v=4)
![[BUG] Conan not working ootb](https://avatars.githubusercontent.com/u/23345084?v=4)
![[FEATURE] Use pip to install CMake in Dockerfile](https://avatars.githubusercontent.com/u/2142684?v=4)
![[BUG] Error linking to Conan-installed Boost](https://avatars.githubusercontent.com/u/1579723?v=4)
![Not printing the header files with BUILD_HEADERS_ONLY [BUG]](https://avatars.githubusercontent.com/u/18662314?v=4)
![[FEATURE] add .cmake-format config file and use cmake-format please](https://avatars.githubusercontent.com/u/1833050?v=4)
![[BUG] The unit test module failed to compile](https://avatars.githubusercontent.com/u/26534856?v=4)
![[BUG] Gmock target not found](https://avatars.githubusercontent.com/u/76056900?v=4)
2.3k Jan 6, 2023
17 Nov 22, 2020
3.1k Jan 1, 2023
50 Dec 28, 2022
1 Oct 11, 2021
36 Dec 26, 2022
36 Dec 28, 2022
8 Apr 5, 2022
521 Jan 3, 2023
2 May 16, 2022
180 Sep 21, 2022
163 Dec 5, 2022
11 Oct 23, 2022
990 Dec 17, 2022
22 Feb 17, 2022
276 Jan 3, 2023
14 Dec 16, 2022
39 Oct 2, 2022
1.1k Dec 26, 2022