Repository files navigation

cmake-init is an opinionated CMake project initializer that generates CMakeprojects which are FetchContent ready, separate consumer and developer targets,provide install rules with proper relocatable CMake packages and use modernCMake (3.14+).

Please see thewiki for example outputs of cmake-init and other pragmaticexamples of functionality implemented for CMake, like package managers, fuzztesting, superbuilds, etc.

If you wish to contact me for anything CMake related, then you may find me inthe#cmake channel ofthe C++ Slack. If what you wish to know iscmake-init specific, then you may also ask questions in this repository'sDiscussions.

• Be simple to use
  The script allows you to just mash enter to get you a correctly set upproject for an executable. You want a header-only library? Chooseh whenprompted. Static/shared library? Just chooses when prompted. Simpleand correct!
• CreateFetchContent ready projects
  This is important, because in the near feature this might allow CMake toconsume other projects in a trivial fashion similar to other languages, e.g.in JavaScript's case (npm).
• Cleanly separate developer and consumer targets
  This ties into the previous point as well, but developers and consumers of aproject have different needs, and separating targets achieves that goal. Adeveloper should be able to run tests, add warning flags, run benchmarks,etc., while a consumer, such as a package maintainer, generally only wants tobuild the library or the executable itself, without having to patch around inthe CMake scripts. Show some love to your package maintainers!
• Use modern CMake (3.14+)
  There are too many outdated and plain wrong examples on the internet, it'stime to change that.
• Make usage of tools easy
  Code coverage (gcov), code linting and formatting (clang-format), staticanalysis (clang-tidy) and dynamic analysis (sanitizers, valgrind) are allvery helpful ways to guide the developer in creating better software, so theyshould be easy to use.

• Kenneth Hoste - How To Make Package Managers Cry
• Robert Schumacher - Don't package your libraries, write packagablelibraries! (Part 1)
• Robert Schumacher - Don't package your libraries, write packagablelibraries! (Part 2)
• Craig Scott - Deep CMake for Library Authors

• Cover every possible project structure
  Doing this is pointless as an init script, because there are far too manyways people have been building software, and if you have special needs, youought to already know CMake and you can set the project up yourself.
• Generate files and show tips for websites other than GitHub
  While I understand the people who are against GitHub (and by proxyMicrosoft), it's by far the most used website of its kind, the files andmessages specific to it are small in number, and they are easily adapted forany other service.

Make sure you have these programs installed:

• Python 3.8 or newer
• CMake 3.20 or newer (3.21 or newer for C17 or newer projects)
• git
• clang-tidy 18 (optional)
• cppcheck (optional)
• Doxygen < 1.9 (optional)
• LCOV (optional)
• clang-format 18 (optional)
• codespell (optional)
• Package managers: Conan or vcpkg (optional)

NOTE

Some of these tools can be used on Windows as well if you want to use VisualStudio, but you have to install these addins:

• https://clangpowertools.com/
• https://github.com/VioletGiraffe/cppcheck-vs-addin

This package is available for download fromPyPI. You can install thispackage usingpip:

pip install cmake-init

clang-tidy is a static analysis tool that helps you spot logical errors inyour code before it is compiled. This script gives you the option to inherittheclang-tidy preset in yourdev preset, enabling the CMake integrationfor this tool.

CI will always run clang-tidy for you, so it is entirely optional to installand use it locally, but it is recommended.

For Windows users, if you wish to use clang-tidy, then you must installNinja and set thegenerator field in yourdev preset toNinja. Thereason for this is that onlyMakefiles and Ninja are supported with CMakefor use with clang-tidy. For other generators, this feature is a no-op.

cppcheck is a static analysis tool similar to clang-tidy, however theoverlap in what they detect is minimal, so it's beneficial to use both of them.This script gives you the option to inherit thecppcheck preset in yourdevpreset, enabling the CMake integration for this tool.

CI will always run cppcheck for you, so it is entirely optional to install anduse it locally, but it is recommended.

For Windows users, if you wish to use cppcheck, then you must installNinja and set thegenerator field in yourdev preset toNinja. Thereason for this is that onlyMakefiles and Ninja are supported with CMakefor use with cppcheck. For other generators, this feature is a no-op.

Doxygen is a tool to generate documentation from annotated source code.In conjunction with it,m.css is used for presenting the generateddocumentation.

The generated projects will have adocs target in developer mode, which canbe used to build the documentation into the<binary-dir>/docs/html directory.

After Doxygen is installed, please make sure thedoxygen executable exists inthePATH, otherwise you might get confusing error messages.

This documentation can be deployed to GitHub Pages using thedocs job in thegenerated CI workflow. Follow the comments left in the job to enable this.

NOTE: m.css does not work with Doxygen >= 1.9. You can install 1.8.20 touse thedocs target. See issues#41 and#48.

LCOV is a tool to process coverage info generated by executables thatwere instrumented with GCC'sgcov. This coverage info can be used to see whatparts of the program were executed.

The generated projects will have acoverage target in developer mode if theENABLE_COVERAGE variable is enabled. The reason why a separate target is usedinstead of CTest's built-incoverage step is because it lacks necessarycustomization. This target should be run after the tests and by default it willgenerate a report at<binary-dir>/coverage.info and an HTML report at the<binary-dir>/coverage_html directory.

For Windows users, you may use a similar tool calledOpenCppCoverage,for which there is an example script in the generatedcmake directory. Thisscript is left as an example, because the Linux VM launches and runs faster inGitHub Actions and so it is used for coverage submission.

clang-format is part of the LLVM tool suite similar toclang-tidy. It's a code linter and code formatter, which can beused to enforce style guides.

Two targets are made available to check and fix code in developer mode usingtheformat-check andformat-fix targets respectively.

NOTE: the project generates files that are formatted according toclang-format 18. Newer or older versions may format the project differently.

codespell is a tool to find and fix spelling errors mainly in sourcecode.

Two targets are made available to check and fix spelling errors in developermode using thespell-check andspell-fix targets respectively.

The-p flag can be used to select a package manager for the project.Arguments for the flag can be:

• none: no package manager integration (default)
• conan:Conan integration
• vcpkg:vcpkg integration

When using a package manager, the following packages are used in the generatedproject:

• fmt for C++,json-c andhedley (exe only) for C projects
• Catch2 as a dev dependency for C++ and C projects

Make sure to read the generated HACKING document to see what needs to be doneto fetch dependencies.

• cmake-init [--c] <path>
  This command will create a CMake project at the provided location andaccording to the answers given to the prompts. You may pass the-s,-e or-h flags after to quickly create a shared library, executable or a headeronly library respectively. The--c switch will set the generated project'stype to C instead of C++.
• cmake-init --help
  Shows the help screen for more flags and switches.

cmake-init is Free Software: You can use, study, share and improve it at yourwill. Specifically you can redistribute and/or modify it under the terms of theGNU General Public License as published by the Free Software Foundation,either version 3 of the License, or (at your option) any later version.

The contents of the directorycmake-init/templates are licensed using theUnlicense license. See the license in that directory for further details.