TsukiNi22/ai-utils / skills/cpp/cmake-style
cmake-style
VerifiedWrite or edit CMakeLists.txt in Tsukini's style (from libutils, context-forge, c2dmp-hsm) - fixed section order with '# =====' banners, TARGET variable, clang++ C++20, ccache, warnings, explicit SRC list with group comments, Debug/Asan/Optimized modes, release targets, exception header generation, GTest tests/, install + find_package config, CPack RPM/DEB with stable/pre channels, Makefile wrapper. Use whenever creating, editing or reviewing a CMakeLists.txt, a tests/CMakeLists.txt, a *Config.cmake.in or the CMake packaging of one of the user's projects.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.1 KB |
| requires.txt | markdown | 22 B |
| templates/Makefile | other | 515 B |
| templates/app/CMakeLists.txt | markdown | 6.5 KB |
| templates/check_files.shexecutable | script | 972 B |
| templates/lib/CMakeLists.txt | markdown | 7.8 KB |
| templates/lib/NAMEConfig.cmake.in | other | 1.2 KB |
| templates/tests/CMakeLists.txt | markdown | 1.2 KB |
SKILL.md
View on GitHub---
name: cmake-style
description: Write or edit CMakeLists.txt in Tsukini's style (from libutils, context-forge, c2dmp-hsm) - fixed section order with '# =====' banners, TARGET variable, clang++ C++20, ccache, warnings, explicit SRC list with group comments, Debug/Asan/Optimized modes, release targets, exception header generation, GTest tests/, install + find_package config, CPack RPM/DEB with stable/pre channels, Makefile wrapper. Use whenever creating, editing or reviewing a CMakeLists.txt, a tests/CMakeLists.txt, a *Config.cmake.in or the CMake packaging of one of the user's projects.
metadata:
summary: '`CMakeLists.txt` in my style: section order, explicit sources, Debug/Asan/Optimized modes, release targets, GTest tests, install + `find_package` config, CPack RPM/DEB stable/pre channels, with app/lib/tests templates.'
---
# Tsukini CMake style
`<name>` (a skill) = the folder of that skill: `~/.claude/skills/<name>` (setup.sh) or `${CLAUDE_SKILL_DIR}/../../*/<name>` (plugin of the marketplace).
**A new project**: the `CMakeLists.txt` of **cpp_project_template** (made by `cpp-project`) is the reference and is kept
as generated - one file for every kind (`<NAME>_KIND` binary / library / header-only, `<NAME>_PACKAGE_BIN` / `_LIB` /
`_DEV`, `<NAME>_SHARED_LIB`), `SRC` / `SRC_SHARED`, the `release` / `install_release` / `package_release` targets, CPack
with the `-op` / `-db` / `-as` variants and the `mingw64-` packages, the MinGW toolchain `cmake/toolchain/mingw-w64.cmake`.
The templates below are for an existing project or a CMake written by hand, in the same style.
Templates (copy, then replace `<name>` = target/package name, `<NAME>` = upper-case option prefix,
`<x.y.z>` = version, `<summary>` = package description, `<utils-version>` = minimal libutils version):
| Project kind | Files |
|---|---|
| executable (context-forge) | `templates/app/CMakeLists.txt` |
| installable library (libutils) | `templates/lib/CMakeLists.txt` + `templates/lib/NAMEConfig.cmake.in` -> `cmake/package/<name>Config.cmake.in` |
| header-only library (c2dmp-hsm) | `templates/lib/CMakeLists.txt` with the `src/nothing.cpp` trick (see below) |
| unit tests (GTest) | `templates/tests/CMakeLists.txt` -> `tests/CMakeLists.txt` |
| helpers | `templates/Makefile` (root), `templates/check_files.sh` -> `cmake/scripts/` |
Full real examples: `~/personal_delivery/cpp/libutils/CMakeLists.txt` (library + multi-component packages),
`~/personal_delivery/cpp/context-forge/CMakeLists.txt` (executable + plugins `.so`).
## File layout (always this order, omit the sections that don't apply)
```cmake
cmake_minimum_required(VERSION 3.20)
set(TARGET <name>)
set(CMAKE_CXX_COMPILER clang++)
project(${TARGET} VERSION <x.y.z> LANGUAGES CXX)
# =========================
# Options
# =========================
```
`set(CMAKE_CXX_COMPILER clang++)` goes **before `project()`**: the compiler is detected by `project()`, set after
it is ignored (or re-runs the configuration). Sections, each introduced by the 3-line banner (`# ` + 25 `=`), one empty line before the next banner:
1. `Options` - `option(<NAME>_STABLE_RELEASE "Channel as stable release" OFF)`, `option(BUILD_TESTS "Build unit tests" OFF)`, project specific `<NAME>_*`.
2. `Compilateur & Standard` (exact title) - C++20 required, no extensions, PIC, output dir for executables, global definitions.
3. `Requirement` - `find_package(...)` with a trailing comment saying why, `pkg_check_modules(... IMPORTED_TARGET ...)`, then the ccache block.
4. `Warnings` - `add_compile_options(-W -Wall -Wextra -Wpedantic -Wunused-parameter -Wshadow -Wuninitialized)` one flag per line.
5. `Sources` - explicit `set(SRC ...)` then `add_executable` / `add_library` right after the list.
6. Extra targets when needed (`Plugins`, `Compilation parameters` for `set_target_properties`).
7. `Special Targets` - `tests` subdirectory, generated exception header, aggregate custom targets.
8. `Release (build ...)` - `release`, `install_release`, `package_release` custom targets that re-configure and build every mode.
9. `Dependencies` - include dirs, `target_link_libraries`, `add_dependencies` (a `foreach(target ${PLUGINS})` for the extra targets).
10. `Includes` / `Headers configuration` (libraries) - `BUILD_INTERFACE`/`INSTALL_INTERFACE`, `configure_file` of `version.hpp.in`.
11. `Modes` - per configuration compile/link options (and the `OUTPUT_NAME` suffix of a library).
12. `Installation` - `include(GNUInstallDirs)`, `install(...)` with `COMPONENT`, export + package config for a library.
13. `Utils` - `get_unregistered_files` target.
14. `Package Building` - CPack RPM & DEB with the stable/pre channels, `include(CPack)` last line.
## Formatting
- Commands in lower case, 4 spaces, `if(...)` / `else()` / `endif()` / `foreach(...)` / `endforeach()` without
space and with empty `()` on the closers (the ccache `if (CCACHE_PROGRAM)` is the only legacy exception).
- One argument per line when a call has several arguments, closing `)` alone at column 0 (or at the
indentation of the call): `add_compile_options(`, `set(SRC`, `add_custom_command(`, `install(`.
Short calls stay on one line: `target_link_libraries(${TARGET} PRIVATE utils::utils)`.
- Keywords grouped as in the examples: `OUTPUT`, `COMMAND`, `WORKING_DIRECTORY`, `DEPENDS`, `COMMENT`, `VERBATIM`;
`set_target_properties(` then targets, `PROPERTIES` and the indented key/values.
- Variables `UPPER_SNAKE` (`SRC`, `SRC_<GROUP>`, `PLUGINS`, `CHANNEL`, `MIRROR_CHANNEL`), options prefixed by the
project in upper case (`UTILS_`, `CONTEXT_FORGE_`). Always `${TARGET}`, never the raw name, for the main target.
- Paths from `${CMAKE_SOURCE_DIR}`; sources relative to the root (`src/<project>/X.cpp`).
- Comments: `# Comment` trailing or above, short English (typos aside), commented alternatives kept
(`#add_library(${TARGET} SHARED ${SRC})`), `# =========================` banners only for sections.
- One empty line between blocks inside a section, none after the opening banner.
## Rules
- **Sources are listed explicitly** in `set(SRC ...)`, grouped by comments: `# Group` or `## Group`,
`SRC` = the executable only (its `main.cpp`) and `SRC_SHARED` = what the executable and the library share (the
library target `<name>_lib` is built from it, the executable links it) when a project has both (the template);
`## Group (sub-part: x)` for a sub-folder, one empty line between groups. Never `file(GLOB ...)` for the
sources (only for configs, with `CONFIGURE_DEPENDS`); the `get_unregistered_files` target lists the
`.cpp` missing from `SRC` / `SRC_SHARED`. To add a file: `python3 <cpp-class>/scripts/cmake_add.py CMakeLists.txt src/<path>/X.cpp`.
- Build types: `Debug` (`-g -ggdb3`), `Asan` (`-fsanitize=address -fno-omit-frame-pointer -g -ggdb3` + link option),
`Optimized` (`-O3 -ffast-math -funroll-loops -pipe -DNDEBUG`, `-march=native` only for a binary not distributed,
`-fno-plt` for a library), all through generator expressions `$<$<CONFIG:Debug>:...>`. No `Release` type:
the `release` custom target builds the modes.
- Library output names per mode: `OUTPUT_NAME "<name>$<$<CONFIG:Debug>:_debug>$<$<CONFIG:Asan>:_asan>"`.
- Executables are written at the root: `set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_SOURCE_DIR}) # TARGET destination`.
- Exception codes: JSON files in `cmake/config/exceptions/`, generated header with `add_custom_command` +
`add_custom_target(generated_<internal|external>_exception_header)` + `add_dependencies(${TARGET} ...)`
(internal = libutils itself, external = a project using libutils).
- libutils dependency: `find_package(utils <min version> CONFIG REQUIRED) # Check utils dependencies existance`
+ `utils::utils`; `<min version>` is `4.0.0` at least for a new project (libutils v4: no v3 compatibility names,
`SameMajorVersion`: a v3 requirement refuses an installed v4).
- Windows (libutils v4.1.0: packages `mingw64-libutils*` in the MinGW sysroot; `set(LIBUTILS_VERSION 4.1.0)` then for a
project built for Windows): the same CMake builds for Windows x86_64 with a MinGW toolchain (the template's
`cmake/toolchain/mingw-w64.cmake` copied into a project without one, `mingw64-cmake` on Fedora, else
`-DCMAKE_TOOLCHAIN_FILE=`; a source build of
`libutils-install windows` into a prefix: `+ -DCMAKE_FIND_ROOT_PATH=<prefix>`): its compiler wins over the
`clang++` set before `project()`, the executable is
`<name>.exe` (`.gitignore`: `/<name>.exe`, `/build-windows`); no Asan with MinGW (built like Debug); the `.exe`
linked `-static-libgcc -static-libstdc++ -static` (no MinGW runtime dll), `if(WIN32)` / `if(NOT WIN32)` for what
differs, CPack with the MinGW sysroot prefix (`cmake/package/CPackProjectConfig.cmake` of the template).
- Tests: `if(BUILD_TESTS)` -> `enable_testing()` + `add_subdirectory(tests)`; `tests/CMakeLists.txt` builds
`unit_tests` (GTest, `gtest_discover_tests`), links the library target when it exists, else reuses the parent
`SRC_SHARED` (or `SRC` without `main.cpp`); cross compiling: GTest by `FetchContent` when the sysroot has none,
`gtest_discover_tests(... DISCOVERY_MODE PRE_TEST)` (run under the emulator, `wine`).
- Header-only library: an `INTERFACE` library target (the template: `add_library(${TARGET_LIB} INTERFACE)`, only the
headers and the CMake config packaged); in an older CMake: `src/nothing.cpp` in `SRC` to keep a target, a `message(WARNING ...)` explaining that only
`--target install` is meaningful, and `target_include_directories(${TARGET} PUBLIC include)`.
- Library install: `install(TARGETS ... EXPORT ${TARGET}Targets ...)`, headers `install(DIRECTORY include/ ... PATTERN "*.in" EXCLUDE)`,
`install(EXPORT ... NAMESPACE ${TARGET}:: ...)`, `configure_package_config_file` + `write_basic_package_version_file`
(`SameMajorVersion`) so that `find_package(<name> <version> CONFIG REQUIRED)` works.
- Packages: `CPACK_GENERATOR "RPM;DEB"`, vendor/maintainer `TsukiNi22`, contact `xartania.contact@gmail.com`, MIT,
channel `-pre` unless `<NAME>_STABLE_RELEASE`, the stable package obsoletes/replaces the `-pre` one and both
conflict, release number `1` for stable / `${PACKAGE_RELEASE}` (CI run number) / `0`.
- New target / output written in the sources (executable at the root, plugin dir, generated file): update the
`.gitignore` with `python3 <cpp-project>/scripts/update_gitignore.py <root>`.
- Root `Makefile` wrapper (`all`, `clean`, `fclean`, `re`) calling CMake with `BUILD_DIR := build`.
## Checking (xstyle)
When `xstyle` is installed (`command -v xstyle`), check what was written or reviewed with it instead of re-reading the
rules by hand: `xstyle --rtk <files|dirs> [-r]` (**always `--rtk`**: compact output made for the assistant),
`xstyle --rtk --fix [CODES] <paths>` for the fixable ones (`-n` to preview), `-c CMAKE,G` for the rules of this
skill, `xstyle -x CODE` to explain one. Not installed: apply the rules by hand and say once that
`curl -fsSL https://tsukini22.github.io/my-universe/install.sh | bash -s` then `sudo dnf|apt|pacman install xstyle` (packages of [my-universe](https://tsukini22.github.io/my-universe/), sources: [TsukiNi22/xstyle](https://github.com/TsukiNi22/xstyle); no curl: `wget -qO-` instead of `curl -fsSL`) would check them. Its findings are heuristic: the local style of a file wins.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |