Cancellar CMake framework

This repository provides helpers for setting up C++ projects using CMake in a quick and elegant way.

Howewer, it also makes several assumptions, and will report errors if those aren't met:

• At least CMake 3.16 is used
• The compiler is clang/clang++ (and NOT clang-cl)
• The generator is Ninja
• An out of source build is used

If a project mets these requirements this script allow a zero-configuration setup and offer:

• a sane default configuration (warnings as errors ; most warnings turned on, C++17, ...)
• no global-config-hell: can be used with any classic CMake code, runs fine alongside it
• support for easy configuration of some third parties
• a clang-tidy setup
• a clang-format setup and enforcement
• a standardese setup and automatic documentation generation as part of the build process (only on linux)
• an easy way to add new targets, files and tests
• a python script to make comman tasks even simpler
• environment checks (e.g. installed packages on ubuntu)

Setup:

• Add this as a submodule, for example in cmake/ccf
• Add that folder to the CMake module path
• include(ccf_init) at the start
• ccf_end() at the end

Unless otherwise specified, init will automatically add the following third parties:

• For every project:
  • spdlog
  • threads (threading flags)
  • backward-cpp for debug builds (automatic stack trace generation on linux)
• For every test project:
  • catch2
  • fakeit

During its run the script will check for several common configuration files to exists. If they don't it'll create them based on a template.

These files are:

• .gitignore
• .clang-format
• git hooks for clang-format
• .clang-tidy
• bt.py

Optional configuration

• ccf_cpp_extension("cxx") - reports error if a C++ file uses a different extension
• ccf_h_extension("hxx", "hpp") - reports error if a H file uses a non listed extension
• ccf_tidy_executable(...) - uses a custom tidy instead of the system one

Third party libraries:

For any supported third party in the 3rd-party forder, add: ccf_3p(<name> <TAG|COMMIT> <ref>) or ccf_3p(<name> DEFAULT)

Third party libraries usually expect the sources to be found under _3p/name, as a shallow submodule. It'll ensure that:

• this submodule exists
• that it points to the correct ref
• that the dependency is built with the correct settings if it isn't header only
• that the dependency exists as a CMake interface target

Build structure:

These scripts assume a simple module structure, where:

• generic folders are simply "namespaces" for executables/libraries
• folders containing targets follow the following structure:

 ns_folder\
   target_folder\
     include\
     internal_include\
     src\
     tests\
       test_executable_1\
         include\
         internal_include\
         src\
         CMakeLists.txt
       test_executable_2\
         ...
       test_library_1\
         include\
         internal_include\
         src\
         CMakeLists.txt
     CMakeLists.txt
   CMakeLists.txt

Adding new targets (full automatic)

• Call ccf_add_all(NAMESPACE) in the main CMakeLists
• Create a subdirectory for a namespace: a_ns
• Create a subdirectory for an executable: a_ns/target_folder
• (Re)run CMake
• Use the newly created executable scaffold in a_ns/target_folder

Adding new targets (manual listing)

• Create the target's directory
• Add the add_subdirectory entry to the parent directory
• Add the ccf_ns/ccf_target call to the CMakeLists.txt in the new directory
• Re-run CMake/Ninja: directories / minimal source files created

Adding tests

• Add a folder inside tests
• Re-run CMake/Ninja: minimal files created

CMakeLists in ns_folder

ccf_ns()
ccf_add_all(TARGET)

(created automatically)

CMakeLists in target_folder

ccf_ns()
ccf_target(EXECUTABLE) # or STATIC_LIBRARY/DYNAMIC_LIBRARY
#ccf_depends(some-other-target)

(created automatically with EXECUTABLE, without comments)

The build relies on GLOB_RECURSE and CONFIGURE_DEPENDS, nothing else has to be specified. The alternative was to add a sanity check to ccf_end to check that there are no missing undocumented files - and then this makes more sense.

Executables assume that the main.cpp or main.cxx file contains the main function of the program, and that it doesn't contain anything else - it is only a starting point. This is to support writing tests against executables: an executable is an object library containing everything but the main, and an executable target using both. Tests use the object library.

CMakeLists in a test folder

ccf_ns()
ccf_target(EXECUTABLE) # or STATIC_LIBRARY/DYNAMIC_LIBRARY
ccf_test()
#ccf_test(additional_test_name param1 param2 param3)
ccf_depends(catch2)
ccf_depends(parent-target)

(created automacitally with EXECUTABLE, without comments)