{"id":15101493,"url":"https://github.com/thelartians/moderncppstarter","last_synced_at":"2025-05-13T22:10:47.940Z","repository":{"id":38379170,"uuid":"254842585","full_name":"TheLartians/ModernCppStarter","owner":"TheLartians","description":"🚀 Kick-start your C++! A template for modern C++ projects using CMake, CI, code coverage, clang-format, reproducible dependency management and much more.","archived":false,"fork":false,"pushed_at":"2025-03-12T18:31:16.000Z","size":361,"stargazers_count":4735,"open_issues_count":22,"forks_count":408,"subscribers_count":64,"default_branch":"master","last_synced_at":"2025-04-30T14:16:01.664Z","etag":null,"topics":["bootstrap","c","ccache","ci","clang-format","cmake","cmakelists","codecov","continuous-integration","coverage","cpp","dependency-manager","free","github-workflows","modern-cmake","modern-cmake-template","open-source","sanitizers","starter","template"],"latest_commit_sha":null,"homepage":"https://thelartians.github.io/ModernCppStarter","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/TheLartians.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":"2020-04-11T10:22:12.000Z","updated_at":"2025-04-30T08:41:27.000Z","dependencies_parsed_at":"2023-11-19T12:26:10.037Z","dependency_job_id":"a8552d92-15b4-4004-a8f8-9475f0f1df43","html_url":"https://github.com/TheLartians/ModernCppStarter","commit_stats":null,"previous_names":[],"tags_count":27,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheLartians%2FModernCppStarter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheLartians%2FModernCppStarter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheLartians%2FModernCppStarter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheLartians%2FModernCppStarter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TheLartians","download_url":"https://codeload.github.com/TheLartians/ModernCppStarter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254036842,"owners_count":22003654,"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":["bootstrap","c","ccache","ci","clang-format","cmake","cmakelists","codecov","continuous-integration","coverage","cpp","dependency-manager","free","github-workflows","modern-cmake","modern-cmake-template","open-source","sanitizers","starter","template"],"created_at":"2024-09-25T18:24:19.806Z","updated_at":"2025-05-13T22:10:47.904Z","avatar_url":"https://github.com/TheLartians.png","language":"CMake","readme":"[![Actions Status](https://github.com/TheLartians/ModernCppStarter/workflows/MacOS/badge.svg)](https://github.com/TheLartians/ModernCppStarter/actions)\n[![Actions Status](https://github.com/TheLartians/ModernCppStarter/workflows/Windows/badge.svg)](https://github.com/TheLartians/ModernCppStarter/actions)\n[![Actions Status](https://github.com/TheLartians/ModernCppStarter/workflows/Ubuntu/badge.svg)](https://github.com/TheLartians/ModernCppStarter/actions)\n[![Actions Status](https://github.com/TheLartians/ModernCppStarter/workflows/Style/badge.svg)](https://github.com/TheLartians/ModernCppStarter/actions)\n[![Actions Status](https://github.com/TheLartians/ModernCppStarter/workflows/Install/badge.svg)](https://github.com/TheLartians/ModernCppStarter/actions)\n[![codecov](https://codecov.io/gh/TheLartians/ModernCppStarter/branch/master/graph/badge.svg)](https://codecov.io/gh/TheLartians/ModernCppStarter)\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# ModernCppStarter\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 template 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- [Modern CMake practices](https://pabloariasal.github.io/2018/02/19/its-time-to-do-cmake-right/)\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/TheLartians/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- Support for [sanitizer tools, and more](#additional-tools)\n\n## Usage\n\n### Adjust the template to your needs\n\n- Use this repo [as a template](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-from-a-template).\n- Replace all occurrences of \"Greeter\" in the relevant CMakeLists.txt with the name of your project\n  - Capitalization matters here: `Greeter` means the name of the project, while `greeter` is used in file names.\n  - Remember to rename the `include/greeter` directory to use your project's lowercase name and update all relevant `#include`s accordingly.\n- Replace the source files with your own\n- For header-only libraries: see the comments in [CMakeLists.txt](CMakeLists.txt)\n- Add [your project's codecov token](https://docs.codecov.io/docs/quick-start) to your project's github secrets under `CODECOV_TOKEN`\n- Happy coding!\n\nEventually, you can remove any unused files, such as the standalone directory or irrelevant github workflows for your project.\nFeel free to replace the License with one suited for your project.\n\nTo cleanly separate the library and subproject code, the outer `CMakeList.txt` only defines the library itself while the tests and other subprojects are self-contained in their own directories. \nDuring development it is usually convenient to [build all subprojects at once](#build-everything-at-once).\n\n### Build and run the standalone target\n\nUse the following command to build and run the executable target.\n\n```bash\ncmake -S standalone -B build/standalone\ncmake --build build/standalone\n./build/standalone/Greeter --help\n```\n\n### Build and run test suite\n\nUse the following commands from the project's root directory to run the test suite.\n\n```bash\ncmake -S test -B build/test\ncmake --build build/test\nCTEST_OUTPUT_ON_FAILURE=1 cmake --build build/test --target test\n\n# or simply call the executable: \n./build/test/GreeterTests\n```\n\nTo collect code coverage information, run CMake with the `-DENABLE_TEST_COVERAGE=1` option.\n\n### Run clang-format\n\nUse the following commands from the project's root directory to check and fix C++ and CMake source style.\nThis requires _clang-format_, _cmake-format_ and _pyyaml_ to be installed on the current system.\n\n```bash\ncmake -S test -B build/test\n\n# view changes\ncmake --build build/test --target format\n\n# apply changes\ncmake --build build/test --target fix-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\npip install clang-format==14.0.6 cmake_format==0.6.11 pyyaml\n```\n\n### Build the documentation\n\nThe documentation is automatically built and [published](https://thelartians.github.io/ModernCppStarter) whenever a [GitHub Release](https://help.github.com/en/github/administering-a-repository/managing-releases-in-a-repository) is created.\nTo manually build documentation, call the following command.\n\n```bash\ncmake -S documentation -B build/doc\ncmake --build build/doc --target GenerateDocs\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 installed on your system.\n\n### Build everything at once\n\nThe project also includes an `all` directory that allows building all targets at the same time.\nThis is useful during development, as it exposes all subprojects to your IDE and avoids redundant builds of the library.\n\n```bash\ncmake -S all -B build\ncmake --build build\n\n# run tests\n./build/test/GreeterTests\n# format code\ncmake --build build --target fix-format\n# run standalone\n./build/standalone/Greeter --help\n# build docs\ncmake --build build --target GenerateDocs\n```\n\n### Additional tools\n\nThe test and standalone subprojects include the [tools.cmake](cmake/tools.cmake) file which is used to import additional tools on-demand through CMake configuration arguments.\nThe following are currently supported.\n\n#### Sanitizers\n\nSanitizers can be enabled by configuring CMake with `-DUSE_SANITIZER=\u003cAddress | Memory | MemoryWithOrigins | Undefined | Thread | Leak | 'Address;Undefined'\u003e`.\n\n#### Static Analyzers\n\nStatic Analyzers can be enabled by setting `-DUSE_STATIC_ANALYZER=\u003cclang-tidy | iwyu | cppcheck\u003e`, or a combination of those in quotation marks, separated by semicolons.\nBy default, analyzers will automatically find configuration files such as `.clang-format`.\nAdditional arguments can be passed to the analyzers by setting the `CLANG_TIDY_ARGS`, `IWYU_ARGS` or `CPPCHECK_ARGS` variables.\n\n#### Ccache\n\nCcache can be enabled by configuring with `-DUSE_CCACHE=\u003cON | OFF\u003e`.\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 based on the template.\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 template 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 template 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/TheLartians/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 template. 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- [**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- [**cpp-best-practices/gui_starter_template**](https://github.com/cpp-best-practices/gui_starter_template/): A popular C++ starter project, created in 2017.\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\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=TheLartians/ModernCppStarter,cpp-best-practices/gui_starter_template,filipdutescu/modern-cpp-template\u0026type=Date)](https://star-history.com/#TheLartians/ModernCppStarter\u0026cpp-best-practices/gui_starter_template\u0026filipdutescu/modern-cpp-template\u0026Date)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthelartians%2Fmoderncppstarter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthelartians%2Fmoderncppstarter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthelartians%2Fmoderncppstarter/lists"}