Setting up a new C++ project usually requires a significant amount of preparation and boilerplate code, even more so for modern C++ projects with tests, executables and contiguous integration. This template is the result of learnings from many previous projects and should help reduce the work required to setup up a modern C++ project.
- Modern CMake practices
- Suited for single header libraries and projects of any scale
- Separation into library and executable code
- Integrated test suite
- Continuous integration via GitHub Actions
- Code coverage via codecov
- Code formatting enforced by clang-format via Format.cmake
- Reproducible dependency management via CPM.cmake
- Installable target with versioning information via PackageProject.cmake
- Use this repo as a template and replace all occurrences of "Greeter" in the relevant CMakeLists.txt with the name of your project
- Replace the source files with your own
- For single-header libraries: see the comments in CMakeLists.txt
- Add your project's codecov token to your project's github secrets under
CODECOV_TOKEN
- Happy coding!
Eventually, you can remove any unused files, such as the standalone directory or irrelevant github workflows for your project.
Use the following command to build and run the executable target.
cmake -Hstandalone -Bbuild/standalone
cmake --build build/standalone
./build/standalone/Greeter --help
Use the following commands from the project's root directory to run the test suite.
cmake -Htest -Bbuild/test
cmake --build build/test
CTEST_OUTPUT_ON_FAILURE=1 cmake --build build/test --target test
# or simply call the executable:
./build/test/GreeterTests
To collect code coverage information, run CMake with the -DENABLE_TEST_COVERAGE=1
option.
Use the following commands from the project's root directory to run clang-format (must be installed on the host system).
cmake -Htest -Bbuild/test
# view changes
cmake --build build/test --target format
# apply changes
cmake --build build/test --target fix-format
See Format.cmake for more options.
-
Can I use this for header-only libraries?
Yes, however you will need to change the library type to an
INTERFACE
library as documented in the CMakeLists.txt. -
I see you are using
GLOB
to add source files in CMakeLists.txt. Isn't that evil?Glob is considered bad because any changes to the source file structure might not be automatically caught by CMake's builders and you will need to manually invoke CMake on changes. I personally prefer the
GLOB
solution for its simplicity, but feel free to change it to explicitly listing sources. -
I'm adding external dependencies to my project using CPM. Will this force users to use CPM as well?
CPM.cmake should be invisible for your library users as it's a self-contained CMake Script. If problems do arise, they can always opt-out by defining
CPM_USE_LOCAL_PACKAGES
, which will override all calls toCPMAddPackage
withfind_package
. If you concerned about this, you should prefer usingCPMFindPackage
instead ofCPMAddPackage
, as then CPM will try to usefind_package
to add packages whenever possible.CPMFindPackage
approach should also be compatible with any common C++ package manager without modifications, however at the cost of reproducible builds. For more information, see the CPM.cmake documentation. -
Can I configure and build my project offline?
Using CPM, all missing dependencies are downloaded at configure time. To avoid redundant downloads, it's recommended to set a CPM cache directory, e.g.:
export CPM_SOURCE_CACHE=$HOME/.cache/CPM
. This will also allow offline configurations if all dependencies are present. No internet connection is required for building. -
Can I use CPack to create a package installer for my project?
As there are a lot of possible options and configurations, this is not (yet) in the scope of this template. See the CPack documentation for more information on setting up CPack installers.
- Script to automatically adjust the template for new projects