{"id":16109877,"url":"https://github.com/clausklein/moderncmakestarter","last_synced_at":"2025-04-10T03:33:17.400Z","repository":{"id":42448805,"uuid":"475839221","full_name":"ClausKlein/ModernCmakeStarter","owner":"ClausKlein","description":"Modern CMake Starter Project","archived":false,"fork":false,"pushed_at":"2025-02-14T12:30:01.000Z","size":159,"stargazers_count":5,"open_issues_count":2,"forks_count":2,"subscribers_count":4,"default_branch":"develop","last_synced_at":"2025-03-24T04:50:52.524Z","etag":null,"topics":["cmake","conan-packages","cpp","template","travis-ci"],"latest_commit_sha":null,"homepage":"","language":"CMake","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ClausKlein.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-03-30T11:02:27.000Z","updated_at":"2025-03-21T08:31:17.000Z","dependencies_parsed_at":"2025-02-14T13:24:54.625Z","dependency_job_id":"30408cb4-8dc0-4adb-a65c-cac65e4d3f1a","html_url":"https://github.com/ClausKlein/ModernCmakeStarter","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":"ClausKlein/ModernCppStarter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClausKlein%2FModernCmakeStarter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClausKlein%2FModernCmakeStarter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClausKlein%2FModernCmakeStarter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClausKlein%2FModernCmakeStarter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ClausKlein","download_url":"https://codeload.github.com/ClausKlein/ModernCmakeStarter/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248151115,"owners_count":21056027,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cmake","conan-packages","cpp","template","travis-ci"],"created_at":"2024-10-09T19:34:48.254Z","updated_at":"2025-04-10T03:33:17.375Z","avatar_url":"https://github.com/ClausKlein.png","language":"CMake","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![MacOS](https://github.com/ClausKlein/ModernCmakeStarter/actions/workflows/macos.yml/badge.svg)](https://github.com/ClausKlein/ModernCmakeStarter/actions/workflows/macos.yml)\n[![Install](https://github.com/ClausKlein/ModernCmakeStarter/actions/workflows/install.yml/badge.svg)](https://github.com/ClausKlein/ModernCmakeStarter/actions/workflows/install.yml)\n[![Ubuntu](https://github.com/ClausKlein/ModernCmakeStarter/actions/workflows/ubuntu.yml/badge.svg)](https://github.com/ClausKlein/ModernCmakeStarter/actions/workflows/ubuntu.yml)\n[![Windows](https://github.com/ClausKlein/ModernCmakeStarter/actions/workflows/windows.yml/badge.svg)](https://github.com/ClausKlein/ModernCmakeStarter/actions/workflows/windows.yml)\n[![Standalone](https://github.com/ClausKlein/ModernCmakeStarter/actions/workflows/standalone.yml/badge.svg)](https://github.com/ClausKlein/ModernCmakeStarter/actions/workflows/standalone.yml)\n[![Style](https://github.com/ClausKlein/ModernCmakeStarter/actions/workflows/style.yml/badge.svg)](https://github.com/ClausKlein/ModernCmakeStarter/actions/workflows/style.yml)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://repository-images.githubusercontent.com/254842585/4dfa7580-7ffb-11ea-99d0-46b8fe2f4170\" height=\"175\" width=\"auto\" /\u003e\n\u003c/p\u003e\n\n# ModernCmakeStarter\n\nSetting 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 continuous integration.\nThis project is the result of learnings from many previous projects and should help reduce the work required to setup up a modern C++ project.\n\n## Features\n\n- [How to Use CMake Without the Agonizing Pain](https://alexreinking.com/blog/how-to-use-cmake-without-the-agonizing-pain-part-1.html) Note the Resources sections!\n- [Modern CMake practices](https://pabloariasal.github.io/2018/02/19/its-time-to-do-cmake-right/) Noteable if you want to use project without CMake config package exports\n- Suited for single header libraries and projects of any scale\n- Clean separation of library and executable code\n- Integrated test suite\n- Continuous integration via [GitHub Actions](https://help.github.com/en/actions/)\n- Code coverage via [codecov](https://codecov.io)\n- Code formatting enforced by [clang-format](https://clang.llvm.org/docs/ClangFormat.html) and [cmake-format](https://github.com/cheshirekow/cmake_format) via [Format.cmake](https://github.com/TheLartians/Format.cmake)\n- Reproducible dependency management via [CPM.cmake](https://github.com/cpm-cmake/CPM.cmake)\n- Installable target with automatic versioning information and header generation via [PackageProject.cmake](https://github.com/TheLartians/PackageProject.cmake)\n- Automatic [documentation](https://thelartians.github.io/ModernCppStarter) and deployment with [Doxygen](https://www.doxygen.nl) and [GitHub Pages](https://pages.github.com)\n- Configurable support for [sanitizer tools, and more](#additional-tools)\n- [CMake presets](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html)\n- Supports [CMake Workflow Presets](https://cmake.org/cmake/help/v3.25/manual/cmake-presets.7.html#id10)\n\n### New Features added\n\nAlternatively you may use the [flexible project options](https://github.com/aminya/project_options#readme). It provides different CMake functions such:\n\n- `project_options()`\n- `dynamic_project_options()`\n- [Build a project with presets](https://cmake.org/cmake/help/latest/manual/cmake.1.html#build-a-project)\n\n## Usage\n\n### Important note\n\n**To cleanly separate the library and subprojects code, the outer\n[CMakeLists.txt](CMakeLists.txt) only defines the library itself while the\ntests and other subprojects are self-contained in their own directories.**\n\nDuring development it is usually convenient to [build all subprojects at\nonce](#build-everything-at-once).\n\nA [./GNUmakefile](./GNUmakefile) encapsulates the most common tasks. Where this\nis not feasible the underlying CMake commands are shown as an alternative.\n\n#### This project lives on this directory tree:\n\n```bash\ntree -d -L 3\n.\n├── all\n├── cmake\n├── documentation\n│   └── pages\n├── include\n│   └── greeter\n├── source\n├── standalone\n│   └── source\n└── test\n    └── source\n\n11 directories\n```\n\n#### The CMake workflows presets creates this directory tree:\n\n```bash\ntree -d -L 2 build stagedir\nbuild\n├── all\n│   ├── CMakeFiles\n│   ├── CPM_modules\n│   ├── Testing\n│   ├── _deps\n│   ├── bin\n│   ├── documentation\n│   ├── standalone\n│   └── test\n├── doc\n│   ├── CMakeFiles\n│   ├── CPM_modules\n│   ├── __pycache__\n│   ├── _deps\n│   └── doxygen\n├── standalone\n│   ├── CMakeFiles\n│   ├── CPM_modules\n│   ├── Testing\n│   ├── _CPack_Packages\n│   ├── _deps\n│   └── bin\n├── test\n│   ├── CMakeFiles\n│   ├── CPM_modules\n│   ├── Testing\n│   ├── _deps\n│   └── bin\n└── user\n    ├── CMakeFiles\n    ├── CPM_modules\n    ├── PackageProjectInclude\n    ├── _CPack_Packages\n    └── _deps\nstagedir\n├── bin\n├── include\n│   ├── fmt\n│   └── greeter\n└── lib\n    ├── cmake\n    ├── greeter\n    └── pkgconfig\n\n44 directories\n```\n\n### Build and install the Release library and its dependencies only\n\nsee [./CMakeLists.txt](./CMakeLists.txt)\nand [./CMakePresets.json](./CMakePresets.json)\n\n**This `CMakeList.txt` project file is intended to be used as a subproject with\n`CPMAddPackage()` only!**\n\nUse the following command to install the **Release** library without test:\n\n```bash\nmake install\n\n## This is equivalent to call:\n# cmake --workflow --preset default --fresh\n\n# the build/user is the CMake binary tree\n```\n\nThe installed CMake export config package is:\n\n```bash\ntree stagedir/lib/cmake/greeter\n\nstagedir/lib/cmake/greeter\n├── greeterConfig.cmake\n├── greeterConfigVersion.cmake\n├── greeterTargets-release.cmake\n└── greeterTargets.cmake\n\n0 directories, 4 files\n```\n\n### Build, test, and install the standalone Release targets and its dependencies\n\nsee [standalone/CMakeLists.txt](standalone/CMakeLists.txt)\nand [standalone/CMakePresets.json](standalone/CMakePresets.json)\n\nUse the following command to build, test, and install the **Release**\nexecutable target:\n\n```bash\nmake standalone\n\n## This is equivalent to call:\n# cmake --workflow --preset default --fresh\n# cd test \u0026\u0026 cmake --workflow --preset default --fresh\n# cd standalone \u0026\u0026 cmake --workflow --preset default --fresh\n\n# to directly call the executable use:\n./build/standalone/greeter --help\n```\n\n### Build and test the installed Release version of the libray\n\nsee [test/CMakeLists.txt](test/CMakeLists.txt)\nand [test/CMakePresets.json](test/CMakePresets.json)\n\nUse the following commands to run the **Release** test suite at once:\n\n```bash\ncd test \u0026\u0026 cmake --workflow --preset=default\n```\n\n### Build and test a Debug build with CMake and generate a test coverage report with gcovr\n\nsee [all/CMakeLists.txt](all/CMakeLists.txt)\nand [all/CMakePresets.json](all/CMakePresets.json)\n\nUse the following command to run the **Debug** test suite at once:\n\n```bash\nmake gcov\n\n## This is equivalent to call:\n# cd all \u0026\u0026 cmake --preset default\n# cmake --build build/all --target all\n# cmake --build build/all --target test\n# gcovr build/all\n\n# to directly call the executable use:\n./build/test/GreeterTestsD\n```\n\n### Run clang-format\n\nUse the following command from the project's root directory to check and fix\nC++ and CMake source style.  This requires _clang-format_, _cmake-format_ and\n_pyyaml_ to be installed on the current system.\n\n```bash\nmake format\n\n## This is equivalent to call:\n# cd all \u0026\u0026 cmake --preset default\n# cmake --build build/all --target format\n\n### you may check it manually this way:\n# cmake --build build/all --target check-format\n```\n\nSee [Format.cmake](https://github.com/TheLartians/Format.cmake) for details.\nThese dependencies can be easily installed using pip.\n\n```bash\npip3 install -r requirements.txt\n```\n\n### Build the documentation\n\nsee [documentation/CMakeLists.txt](documentation/CMakeLists.txt)\n\nTo manually build documentation, call the following commands.\n\n```bash\ncmake -S documentation -B build/doc\ncmake --build build/doc --target GenerateDocs\n\n# view the docs\nopen build/doc/doxygen/html/index.html\n```\n\nTo build the documentation locally, you will need _Doxygen_, jinja2 and Pygments\ninstalled on your system.\n\n## Build everything at once\n\n**Note: This workflow is for developers only and their targets must not be installed!**\n\nThe project also includes an `all` directory that allows building all **Debug**\ntargets at the same time.  This is useful during development, as it exposes all\nsubprojects to your IDE and avoids redundant builds of the library.\n\n```bash\nmake all\n# cd all \u0026\u0026 cmake --workflow --preset=default\n\n# to run-clang-tidy on all sources:\nmake check\n# cd all \u0026\u0026 cmake --preset default\n# run-clang-tidy -p build/all source */source\n\n# too you generate the documentation\ncmake --build build/all --target GenerateDocs\n```\n\n### Additional tools\n\nThe all subprojects include additional tools on-demand through CMake configuration presets.\n\n#### Sanitizers\n\nSanitizers can be enabled by configuring with \n\n```bash\nmake setup\ncd build/all \u0026\u0026 ccmake .\n```\n\n#### Static Analyzers\n\nStatic Analyzers are enabled by default for developers at the all subdirectory\n\nBy default, analyzers will automatically find configuration files such as `.clang-format`.\n\n#### Ccache\n\nCcache is enabled as long it is found.\n\n## FAQ\n\n\u003e Can I use this for header-only libraries?\n\nYes, however you will need to change the library type to an `INTERFACE` library as documented in the [CMakeLists.txt](CMakeLists.txt).\nSee [here](https://github.com/TheLartians/StaticTypeInfo) for an example header-only library project.\n\n\u003e I don't need a standalone target / documentation. How can I get rid of it?\n\nSimply remove the standalone / documentation directory and according github workflow file.\n\n\u003e Can I build the standalone and tests at the same time? / How can I tell my IDE about all subprojects?\n\nTo keep the project modular, all subprojects derived from the library have been separated into their own CMake modules.\nThis approach makes it trivial for third-party projects to re-use the projects library code.\nTo allow IDEs to see the full scope of the project, the project includes the `all` directory that will create a single build for all subprojects.\nUse this as the main directory for best IDE support.\n\n\u003e I see you are using `GLOB` to add source files in CMakeLists.txt. Isn't that evil?\n\nGlob is considered bad because any changes to the source file structure [might not be automatically caught](https://cmake.org/cmake/help/latest/command/file.html#filesystem) by CMake's builders and you will need to manually invoke CMake on changes.\n  I personally prefer the `GLOB` solution for its simplicity, but feel free to change it to explicitly listing sources.\n\n\u003e I want create additional targets that depend on my library. Should I modify the main CMakeLists to include them?\n\nAvoid including derived projects from the libraries CMakeLists (even though it is a common sight in the C++ world), as this effectively inverts the dependency tree and makes the build system hard to reason about.\nInstead, create a new directory or project with a CMakeLists that adds the library as a dependency (e.g. like the [standalone](standalone/CMakeLists.txt) directory).\nDepending type it might make sense move these components into a separate repositories and reference a specific commit or version of the library.\nThis has the advantage that individual libraries and components can be improved and updated independently.\n\n\u003e You recommend to add external dependencies using CPM.cmake. Will this force users of my library to use CPM.cmake as well?\n\n[CPM.cmake](https://github.com/cpm-cmake/CPM.cmake) should be invisible to library users as it's a self-contained CMake Script.\nIf problems do arise, users can always opt-out by defining the CMake or env variable [`CPM_USE_LOCAL_PACKAGES`](https://github.com/cpm-cmake/CPM.cmake#options), which will override all calls to `CPMAddPackage` with the according `find_package` call.\nThis should also enable users to use the project with their favorite external C++ dependency manager, such as vcpkg or Conan.\n\n\u003e Can I configure and build my project offline?\n\nNo internet connection is required for building the project, however when using CPM missing dependencies are downloaded at configure time.\nTo avoid redundant downloads, it's highly recommended to set a CPM.cmake cache directory, e.g.: `export CPM_SOURCE_CACHE=$HOME/.cache/CPM`.\nThis will enable shallow clones and allow offline configurations dependencies are already available in the cache.\n\n\u003e Can I use CPack to create a package installer for my project?\n\nAs there are a lot of possible options and configurations, this is not (yet) in the scope of this project. See the [CPack documentation](https://cmake.org/cmake/help/latest/module/CPack.html) for more information on setting up CPack installers.\n\n\u003e This is too much, I just want to play with C++ code and test some libraries.\n\nPerhaps the [MiniCppStarter](https://github.com/TheLartians/MiniCppStarter) is something for you!\n\n## Related projects and alternatives\n\n- [**cmake-init - The missing CMake project initializer**](https://github.com/friendlyanon/cmake-init#readme)\n- [**cpp-best-practices cpp_starter_project**](https://github.com/cpp-best-practices/cpp_starter_project#readme): A popular C++ starter project\n- [**ModernCppStarter \u0026 PVS-Studio Static Code Analyzer**](https://github.com/viva64/pvs-studio-cmake-examples/tree/master/modern-cpp-starter): Official instructions on how to use the ModernCppStarter with the PVS-Studio Static Code Analyzer.\n- [**filipdutescu/modern-cpp-template**](https://github.com/filipdutescu/modern-cpp-template): A recent starter using a more traditional approach for CMake structure and dependency management.\n- [**vector-of-bool/pitchfork**](https://github.com/vector-of-bool/pitchfork/): Pitchfork is a Set of C++ Project Conventions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclausklein%2Fmoderncmakestarter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclausklein%2Fmoderncmakestarter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclausklein%2Fmoderncmakestarter/lists"}