Package: cmake-init
cmake-init- The missing CMake project initializercmake-initis an opinionated CMake project initializer that generates CMake
projects which are FetchContent ready, separate consumer and developer targets,
provide install rules with proper relocatable CMake packages and use modern
CMake (3.14+).Please see thewikifor example outputs of cmake-init and other pragmatic
examples of functionality implemented for CMake, like package managers, fuzz
testing, superbuilds, etc.VSCode integration with minimal configuration using presets:CLion integration with minimal configuration using presets:If you wish to contact me for anything CMake related, then you may find me in
the#cmakechannel ofthe C++ Slack. If what you wish to know is
cmake-init specific, then you may also ask questions in this repository'sDiscussions.GoalsBe simple to useThe script allows you to just mash enter to get you a correctly set up
project for an executable. You want a header-only library? Choosehwhen
prompted. Static/shared library? Just chooseswhen prompted. Simpleandcorrect!CreateFetchContentready projectsThis is important, because in the near feature this might allow CMake to
consume other projects in a trivial fashion similar to other languages, e.g.
in JavaScript's case (npm).Cleanly separate developer and consumer targetsThis ties into the previous point as well, but developers and consumers of a
project have different needs, and separating targets achieves that goal. A
developer should be able to run tests, add warning flags, run benchmarks,
etc., while a consumer, such as a package maintainer, generally only wants to
build the library or the executable itself, without having to patch around in
the 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's
time to change that.Make usage of tools easyCode coverage (gcov), code linting and formatting (clang-format), static
analysis (clang-tidy) and dynamic analysis (sanitizers, valgrind) are all
very helpful ways to guide the developer in creating better software, so they
should be easy to use.Relevant conference talksKenneth Hoste - How To Make Package Managers CryRobert Schumacher - Don't package your libraries, write packagable
libraries! (Part 1)Robert Schumacher - Don't package your libraries, write packagable
libraries! (Part 2)Craig Scott - Deep CMake for Library AuthorsNon-goalsCover every possible project structureDoing this is pointless as an init script, because there are far too many
ways people have been building software, and if you have special needs, you
ought to already know CMake and you can set the project up yourself.Generate files and show tips for websites other than GitHubWhile I understand the people who are against GitHub (and by proxy
Microsoft), it's by far the most used website of its kind, the files and
messages specific to it are small in number, and they are easily adapted for
any other service.InstallMake sure you have these programs installed:Python 3.8 or newerCMake 3.20 or newer (3.21 or newer for C17 or newer projects)gitclang-tidy 14(optional)cppcheck(optional)Doxygen < 1.9(optional)LCOV(optional)clang-format 14(optional)codespell(optional)Package managers: Conan or vcpkg (optional)NOTESome of these tools can be used on Windows as well if you want to use Visual
Studio, but you have to install these addins:https://clangpowertools.com/https://github.com/VioletGiraffe/cppcheck-vs-addinThis package is available for download fromPyPI. You can install this
package usingpip:pipinstallcmake-initclang-tidyclang-tidyis a static analysis tool that helps you spot logical errors in
your code before it is compiled. This script gives you the option to inherit
theclang-tidypreset in yourdevpreset, enabling the CMake integration
for this tool.CI will always run clang-tidy for you, so it is entirely optional to install
and use it locally, but it is recommended.For Windows users, if you wish to use clang-tidy, then you must installNinjaand set thegeneratorfield in yourdevpreset toNinja. The
reason for this is that onlyMakefiles and Ninjaare supported with CMake
for use with clang-tidy. For other generators, this feature is a no-op.cppcheckcppcheckis a static analysis tool similar to clang-tidy, however the
overlap in what they detect is minimal, so it's beneficial to use both of them.
This script gives you the option to inherit thecppcheckpreset in yourdevpreset, enabling the CMake integration for this tool.CI will always run cppcheck for you, so it is entirely optional to install and
use it locally, but it is recommended.For Windows users, if you wish to use cppcheck, then you must installNinjaand set thegeneratorfield in yourdevpreset toNinja. The
reason for this is that onlyMakefiles and Ninjaare supported with CMake
for use with cppcheck. For other generators, this feature is a no-op.DoxygenDoxygenis a tool to generate documentation from annotated source code.
In conjunction with it,m.cssis used for presenting the generated
documentation.The generated projects will have adocstarget in developer mode, which can
be used to build the documentation into the<binary-dir>/docs/htmldirectory.After Doxygen is installed, please make sure thedoxygenexecutable exists in
thePATH, otherwise you might get confusing error messages.This documentation can be deployed to GitHub Pages using thedocsjob in the
generated 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 to
use thedocstarget. See issues#41and#48.LCOVLCOVis a tool to process coverage info generated by executables that
were instrumented with GCC'sgcov. This coverage info can be used to see what
parts of the program were executed.The generated projects will have acoveragetarget in developer mode if theENABLE_COVERAGEvariable is enabled. The reason why a separate target is used
instead of CTest's built-incoveragestep is because it lacks necessary
customization. This target should be run after the tests and by default it will
generate a report at<binary-dir>/coverage.infoand an HTML report at the<binary-dir>/coverage_htmldirectory.For Windows users, you may use a similar tool calledOpenCppCoverage,
for which there is an example script in the generatedcmakedirectory. This
script is left as an example, because the Linux VM launches and runs faster in
GitHub Actions and so it is used for coverage submission.clang-formatclang-formatis part of the LLVM tool suite similar toclang-tidy. It's a code linter and code formatter, which can be
used to enforce style guides.Two targets are made available to check and fix code in developer mode using
theformat-checkandformat-fixtargets respectively.NOTE: the project generates files that are formatted according to
clang-format 14. Newer or older versions may format the project differently.codespellcodespellis a tool to find and fix spelling errors mainly in source
code.Two targets are made available to check and fix spelling errors in developer
mode using thespell-checkandspell-fixtargets respectively.Package managersThe-pflag can be used to select a package manager for the project.
Arguments for the flag can be:none: no package manager integration (default)conan:Conanintegrationvcpkg:vcpkgintegrationWhen using a package manager, the following packages are used in the generated
project:fmtfor C++,json-candhedley(exe only) for C projectsCatch2as a dev dependency for C++ and C projectsMake sure to read the generated HACKING document to see what needs to be done
to fetch dependencies.Usagecmake-init [--c] <path>This command will create a CMake project at the provided location and
according to the answers given to the prompts. You may pass the-s,-eor-hflags after to quickly create a shared library, executable or a header
only library respectively. The--cswitch will set the generated project's
type to C instead of C++.cmake-init --helpShows the help screen for more flags and switches.Licensingcmake-initis Free Software: You can use, study, share and improve it at your
will. Specifically you can redistribute and/or modify it under the terms of theGNU General Public Licenseas 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/templatesare licensed using theUnlicenselicense. See the license in that directory for further details.