cth cmake

This is an opinionated cross-platform c++ cmake utility library to enable quicker and safer use of cmake.

VERY PRE ALPHA CURRENTLY, DONT EXPECT BACKWARDS COMPATIBILITY

Quick Start

Requirements (guide):

• cmake 4+
• vcpkg
• VCPKG_ROOT must be defined

overview

cth_assertions

Simple assertions that every language should have:

• cth_assert_true / cth_assert_false: check boolean conditions and fail configuration when the condition is (not) met.
• cth_assert_[_not]_cmd: verify a CMake command/function is (not) present and fail on mismatch.
• cth_assert_[_not]_target: assert a CMake target does (not) exists in the current scope.
• cth_assert_[_not]_empty: assert a string value is (not) empty.
• cth_assert_program: locate an external program (supports find_program args) and export <PROG>_PROGRAM to the parent scope (fails if not found).
• cth_assert_file: assert that a particular file exists and is not a directory.

cth_target_utilities

To help you set up targets and dependencies quicker:

• cth_glob: generic recursive glob for specified file patterns/masks and append results to a variable.
• cth_glob_cpp: recursive glob for common C++ source/header/file-set extensions and append results to a variable.
• cth_glob_cppm: recursive glob for C++ module interface files (.cppm).
• cth_add_resources: add a POST_BUILD step to copy resource directories next to a target's binary.
• cth_target_alias_any: alias the first existing target of several candidates (e.g. hv / hv_static depending on the linkage).
• cth_target_add_modules: add C++ module files to a target with PUBLIC/PRIVATE visibility.
• cth_target_enable_sanitizers: enable Address/Undefined sanitizers for specified targets/configurations.
• cth_target_enable_build_cache: enable per-target build-cache integration (installation)
• cth_add_clang_format_target: create a "format" target that runs clang-format on specified source files
• cth_target_attach_link_dependency: attach external shared libraries to a target as linked imported targets.
• cth_target_attach_copy_dependency: attach files that must ship next to consuming executables, structure-preserved, propagated through the link chain.
• cth_target_copy_dependencies: copy runtime dependencies and attached copy dependencies to the target's output directory post-build.

cth_install_utilities

Ever wanted to create a cmake installable package?
Now made easy, just build the <main-component>_package target and you are good to go:

• cth_pkg_target_add_modules: add C++ module file-sets to a target (via cth_target_add_modules) and register it for installation.
• cth_pkg_target_find_package: wrap find_package and record the dependency for generated package config files.
• cth_pkg_add_find_modules: register Find<Package>.cmake modules for dependencies without a CMake package, installed with the package and used by its config.
• cth_pkg_target_include_directories: configure target include directories with appropriate install interfaces.
• cth_create_package: finalize export sets, generate config/version files, and create the package target.

This has naming implications, subcomponents should be named <main-component>_<subcomponent> to be installable via <main-component>::<subcomponent>.

This will create additional cmake target.

cth_setup_utilities

this is more or less for me, very handy but no backwards compatibility guaranteed

• cth_set_compiler_specifics: apply compiler-specific common flags (MSVC vs others).
• cth_set_latest_c_cpp_standard (macro): prefer the newest supported C/C++ standard and set related policy/flags.
• cth_add_subdirectory: add a subdirectory behind an option (default ON, OFF or a variable like WIN32), a parent project turns parts of a library off with set(<option> OFF).

cth_tool_utilities

• cth_enable_build_cache: enable BuildCache globally by setting C/C++ compiler launcher variables. (installation)
• cth_find_program: locate an external program and export path to parent scope.
• cth_find_clang_format: locate clang-format executable and export path to parent scope.

toolchain.cmake

• (toolchain configuration): contains the project's recommended toolchain preset for CMake.

quick start

1. install the requirements (guide below)

2. add as submodule (recommended) or clone normally:

   • add as submodule:

     • git submodule add https://github.com/codethinki/cth_cmake.git lib/cth_cmake/
     • git submodule update --init --recursive

   • or git clone https://github.com/codethinki/cth_cmake

3. add to your cmake preset

   //CMakePresets.txt
   {
       //...
       "configurePresets": [
               //...
               {
                   "name": "cth_cmake",
                   "hidden": true,
                   "cacheVariables": {
                                   //replace with <path_to_clone> if you dont use submodule
                       "CMAKE_TOOLCHAIN_FILE": "${sourceDir}/lib/cth_cmake/toolchain.cmake"
                   }
               },
               //...    
       ]
   }

4. let used presets inherit from this

   //...
       "configurePresets": [
               //...
               {
                   "name": "<your_preset>",
                   "inherits": [
                       "cth_cmake",
                       //...
                   ]
               },
               //...
       ]

5. enjoy :)

dependencies & installation

Required (kinda)

• vcpkg

  1. install vcpkg
  2. open your repo in the terminal
  3. vcpkg new --application (add local manifest)
  4. add packages via: vcpkg add port <your_package_here>

  altho i strongly advise against it, you can disable automatic vcpkg integration with CTH_DISABLE_VCPKG_INTEGRATION

Optional

• BuildCache:
  • Windows:
    1. install scoop (windows only)
    2. scoop bucket add extras
    3. scoop install BuildCache
  • Linux (arch)
    1. install via the AUR (buildcache-git) or via pacman if on cachyos