cmake-init - The missing CMake project initializer

cmake-init is 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 the wiki for 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 #cmake channel of the C++ Slack. If what you wish to know is
cmake-init specific, then you may also ask questions in this repository’s
Discussions.

Goals

• Be simple to use
  The script allows you to just mash enter to get you a correctly set up
  project for an executable. You want a header-only library? Choose h when
  prompted. Static/shared library? Just choose s when prompted. Simple
  and correct!
• Create FetchContent ready projects
  This 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 targets
  This 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 easy
  Code 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 talks

• Kenneth Hoste - How To Make Package Managers Cry
• Robert 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 Authors

Non-goals

• Cover every possible project structure
  Doing 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 GitHub
  While 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.

Install

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 Visual
Studio, but you have to install these addins:

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

This package is available for download from PyPI. You can install this
package using pip:

pip install cmake-init

clang-tidy

clang-tidy is 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
the clang-tidy preset in your dev preset, 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 install
Ninja and set the generator field in your dev preset to Ninja. The
reason for this is that only Makefiles and Ninja are supported with CMake
for use with clang-tidy. For other generators, this feature is a no-op.

cppcheck

cppcheck is 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 the cppcheck preset in your dev
preset, 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 install
Ninja and set the generator field in your dev preset to Ninja. The
reason for this is that only Makefiles and Ninja are supported with CMake
for use with cppcheck. For other generators, this feature is a no-op.

Doxygen

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

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

After Doxygen is installed, please make sure the doxygen executable exists in
the PATH, otherwise you might get confusing error messages.

This documentation can be deployed to GitHub Pages using the docs job 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 the docs target. See issues #41 and #48.

LCOV

LCOV is a tool to process coverage info generated by executables that
were instrumented with GCC’s gcov. This coverage info can be used to see what
parts of the program were executed.

The generated projects will have a coverage target in developer mode if the
ENABLE_COVERAGE variable is enabled. The reason why a separate target is used
instead of CTest’s built-in coverage step 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.info and an HTML report at the
<binary-dir>/coverage_html directory.

For Windows users, you may use a similar tool called OpenCppCoverage,
for which there is an example script in the generated cmake directory. 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-format

clang-format is part of the LLVM tool suite similar to
clang-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
the format-check and format-fix targets respectively.

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

codespell

codespell is 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 the spell-check and spell-fix targets respectively.

Package managers

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 generated
project:

• fmt for C++, json-c and hedley (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 done
to fetch dependencies.

Usage

• cmake-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, -e or
  -h flags after to quickly create a shared library, executable or a header
  only library respectively. The --c switch will set the generated project’s
  type to C instead of C++.
• cmake-init --help
  Shows the help screen for more flags and switches.

Licensing

cmake-init is 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 the
GNU 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 directory cmake-init/templates are licensed using the
Unlicense license. See the license in that directory for further details.