https://github.com/filipdutescu/modern-cpp-template
A template for modern C++ projects using CMake, Clang-Format, CI, unit testing and more, with support for downstream inclusion.
https://github.com/filipdutescu/modern-cpp-template
ccache ci clang-format cmake cmake-module cmake-template cmakelists code-coverage codecov continuous-integration cpp github-action github-actions google-test gtest open-source package-manager project-template static-analysis template
Last synced: 7 days ago
JSON representation
A template for modern C++ projects using CMake, Clang-Format, CI, unit testing and more, with support for downstream inclusion.
- Host: GitHub
- URL: https://github.com/filipdutescu/modern-cpp-template
- Owner: filipdutescu
- License: unlicense
- Created: 2020-05-03T11:51:22.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2024-03-16T21:36:14.000Z (about 1 year ago)
- Last Synced: 2025-03-31T16:09:56.085Z (14 days ago)
- Topics: ccache, ci, clang-format, cmake, cmake-module, cmake-template, cmakelists, code-coverage, codecov, continuous-integration, cpp, github-action, github-actions, google-test, gtest, open-source, package-manager, project-template, static-analysis, template
- Language: CMake
- Homepage:
- Size: 373 KB
- Stars: 1,791
- Watchers: 37
- Forks: 218
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-fancy-toolkit - modern-cpp系列, modern-cpp-template
README
[](https://github.com/filipdutescu/modern-cpp-template/actions)
[](https://github.com/filipdutescu/modern-cpp-template/actions)
[](https://github.com/filipdutescu/modern-cpp-template/actions)
[](https://codecov.io/gh/filipdutescu/modern-cpp-template)
[](https://github.com/filipdutescu/modern-cpp-template/releases)
# 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_DOXYGEN` option, 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_COVERAGE` option, 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](https://unlicense.org/),
* 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/](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](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html).*
### Installing
It is fairly easy to install the project, all you need to do is clone if from
[GitHub](https://github.com/filipdutescu/modern-cpp-template) or
[generate a new repository from it](https://github.com/filipdutescu/modern-cpp-template/generate)
(also on **GitHub**).
If you wish to clone the repository, rather than generate from it, you simply need
to run:
```bash
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`](.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
```cmake
project(
"Project"
VERSION 0.1.0
LANGUAGES CXX
)
```
to the ***exact name of your project***, i.e. using the previous name it will become:
```cmake
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:
```bash
cmake --build build --target install --config Release
# a more general syntax for that command is:
cmake --build --target install --config
```
## Building the project
To build the project, all you need to do, ***after correctly
[installing the project](README.md#Installing)***, is run a similar **CMake** routine
to the the one below:
```bash
mkdir build/ && cd build/
cmake .. -DCMAKE_INSTALL_PREFIX=/absolute/path/to/custom/install/directory
cmake --build . --target install
```
> ***Note:*** *The custom ``CMAKE_INSTALL_PREFIX`` can be omitted if you wish to
install in [the default install location](https://cmake.org/cmake/help/latest/module/GNUInstallDirs.html).*
More options that you can set for the project can be found in the
[`cmake/StandardSettings.cmake` file](cmake/StandardSettings.cmake). 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](cmake/Conan.cmake)).
## 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:
```bash
mkdir build/ && cd build/
cmake .. -D_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](https://github.com/google/googletest/)
for unit testing. Unit testing can be disabled in the options, by setting the
`ENABLE_UNIT_TESTING` (from
[cmake/StandardSettings.cmake](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:
```bash
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](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](http://semver.org/) for versioning. A list of
existing versions can be found in the
[project's releases](https://github.com/filipdutescu/modern-cpp-template/releases).
## Authors
* **Filip-Ioan Dutescu** - [@filipdutescu](https://github.com/filipdutescu)
## License
This project is licensed under the [Unlicense](https://unlicense.org/) - see the
[LICENSE](LICENSE) file for details