CMAKE-DIAGNOSTICS(7)

🎀 NAME 🎀

cmake-diagnostics — the CMake Diagnostics Reference, bestie 💅 (this one's from the CMake manual, and it's lowkey one of the most useful pages nobody reads)

---

✨ INTRODUCTION ✨

Added in version 4.4.

Okay so picture this: CMake Diagnostics are the whole mechanism CMake uses to categorize and present certain advisory info about your project's configuration and about generating its build system. Think of them as the build-system equivalent of compiler warnings — same energy, different layer 🫶.

They give you feedback on potential issues across several categories:

• Issues that may impact the success of the build 💀
• Issues that may impact the correctness of the build 🔥
• Issues that may impact the correctness of the project packaging 🎁
• Issues that may impact the ability of the project to be built with newer versions of dependencies 🦋
• Issues that may impact the ability of the project to be built with newer versions of CMake ⭐

---

🧚 CONTROLLING DIAGNOSTICS 🧚

Every diagnostic category has an associated action that gets taken when that diagnostic is triggered. Most categories will warn by default. The available actions are all described in the cmake_diagnostic() command documentation 👑

CMake keeps a diagnostic state stack that's basically the policy state's cousin. The initial state of the stack is decided by four factors, listed here in order of precedence (top wins):

• The default action associated with the diagnostic 🌸
• The action associated with the diagnostic that's stored in the CMake variable cache — this is what persists the initial state between CMake runs 💾
• The warnings and errors fields of CMake Presets (see cmake-presets(7)) 📋
• The -W[no-][error=] command line arguments ⌨️

Note: because command line arguments operate both recursively and in the order specified, some combinations of diagnostic arguments may result in later arguments completely overwriting the action of earlier arguments. For example, -Wno-child -Wparent will result in the child warning being enabled, because -Wparent promotes both parent and child to at least WARN severity. CMake presets are evaluated in order from most ancestral to least ancestral 🙈

During script execution, you can use the cmake_diagnostic() command to query or alter the state, or to perform limited stack manipulations 🛠️

When a diagnostic is issued at configure time (or during script execution, when CMake is running in script mode), the current diagnostic state controls the action. Diagnostics issued at generate time, or outside of the configuration and generation phases, have to make use of recorded state information instead. CMake strives to preserve that info in a way that matches the recorded state to the state as of the CMake command which ultimately causes a diagnostic to be issued — but ngl, CMake may sometimes fall back to the state when processing of a subdirectory completed, or even the root state 😭. That may limit the ability of the cmake_diagnostic() command to control such diagnostics, especially if it's called from a function or an included file. This is especially the case for diagnostics that aren't directly coupled to a CMake command 💀

---

👑 DIAGNOSTIC CATEGORIES 👑

The following categories are defined:

🌈 CMD_AUTHOR 🌈

Added in version 4.4.

• Command Line — -W[no-][error=]author
• Presets — warnings.author, errors.author
• Default — Warn

Warns you about a build system's incorrect use of CMake, or of a CMake interface provided by a dependency. This is the category triggered by message(AUTHOR_WARNING). It's also the ancestor of many other diagnostic categories 👑

The most important aspect of this category is that it represents issues with a project's build system which typically require alteration to that same build system. Translation: users who are simply trying to build a project they got from somewhere else will typically not be interested in these warnings — except maybe to report them to the project's developer(s) 📨

🦋 CMD_DEPRECATED 🦋

Added in version 4.4.

• Command Line — -W[no-][error=]deprecated
• Presets — warnings.deprecated, errors.deprecated
• Default — Warn
• Parent — CMD_AUTHOR

Warns you about use of a deprecated function or package. This is the category triggered by message(DEPRECATION) 🫠

Note: if CMP0218 is not set to NEW, then message(DEPRECATION) invocations — along with builtin deprecation messages that existed prior to CMake 4.4 — will ignore this diagnostic state and will instead use the CMAKE_WARN_DEPRECATED and CMAKE_ERROR_DEPRECATED variables to decide the severity of deprecation messages 👀

🧪 CMD_EXPERIMENTAL 🧪

Added in version 4.4.

• Command Line — -W[no-][error=]experimental
• Presets — warnings.experimental, errors.experimental
• Default — Warn
• Parent — CMD_AUTHOR

Warns if a build system uses an experimental feature, or if CMake detects that the gate variable for an experimental feature is set to an unrecognized value 🔬

🍓 CMD_INSTALL_ABSOLUTE_DESTINATION 🍓

Added in version 4.4.

• Command Line — -W[no-][error=]install-absolute-destination
• Presets — warnings.installAbsoluteDestination, errors.installAbsoluteDestination
• Default — Ignore
• Parent — CMD_AUTHOR

Warns when an install() command specifies an absolute DESTINATION path. Absolute destinations are typically undesirable because they prevent the installation prefix from being overridden at install time 😤

⚖️ CMD_POLICY ⚖️

Added in version 4.4.

• Command Line — -W[no-][error=]policy
• Presets — warnings.policy, errors.policy
• Default — Warn
• Parent — CMD_AUTHOR

Warns if a build system potentially depends on the OLD behavior of a CMake Policy. See the cmake_policy() command for more details. Heads up: setting a policy to OLD will also disable warnings for that specific policy 🔇

🫥 CMD_UNINITIALIZED 🫥

Added in version 4.4.

• Command Line — -W[no-][error=]uninitialized
• Presets — warnings.uninitialized, errors.uninitialized
• Default — Ignore

Warns if an uninitialized variable is dereferenced. Ghost variable behavior, we don't love it 👻

🗑️ CMD_UNUSED_CLI 🗑️

Added in version 4.4.

• Command Line — -W[no-][error=]unused-cli
• Presets — warnings.unusedCli, errors.unusedCli
• Default — Ignore

Warns about variables that are declared on the command line, but not used 🥲

This diagnostic is issued outside of the configuration / generation phases. So even though the action of this warning category can be queried as usual, the cmake_diagnostic() command is unable to affect the action of this diagnostic. It's giving "you can look but you can't touch" energy 💅

---

📜 Copyright 📜

2000-2026 Kitware, Inc. and Contributors

---

And that's the whole page, bestie — you ate that 🫶✨ Version 4.4.5, dated Oct 28, 2026, and if you need to find it again the manual name is literally CMAKE-DIAGNOSTICS(7). Slay 💖