Scroll to navigation

CMAKE-DIAGNOSTICS(7) CMake CMAKE-DIAGNOSTICS(7)

NAME

cmake-diagnostics - CMake Diagnostics Reference

INTRODUCTION

Added in version 4.4.

CMake Diagnostics are the mechanism by which CMake categorizes and presents certain advisory information about a project's configuration and the generation of its build system. These diagnostics can be seen as the build system equivalent of compiler warnings. Diagnostics provide feedback on potential issues in 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

Each diagnostic category has an associated action to be taken when that diagnostic is triggered. Most categories will warn by default. The available actions are described in the cmake_diagnostic() <#command:cmake_diagnostic> command documentation.

CMake maintains a diagnostic state stack that is similar to the policy state. The initial state of the stack is determined by four factors, which are, in order of precedence:

  • The default action associated with the diagnostic.
  • The action associated with the diagnostic stored in the CMake variable cache, which is used to persist the initial state between CMake runs.
  • The warnings <#cmakepresets-configurepresets-warnings> and errors <#cmakepresets-configurepresets-errors> fields of CMake Presets <#manual:cmake-presets(7)>.
  • The -W[no-][error=] <#cmdoption-cmake-W> 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, the cmake_diagnostic() <#command:cmake_diagnostic> command can be used 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 must make use of recorded state information. While CMake strives to preserve this information in a way that matches the recorded state to the state as of the CMake command which ultimately causes a diagnostic to be issued, CMake may sometimes fall back to the state when processing of a subdirectory completed, or even the root state. This may limit the ability of the cmake_diagnostic() <#command:cmake_diagnostic> command to control such diagnostics, especially if called from a function or included file. This is especially the case for diagnostics that are not directly coupled to a CMake command.

DIAGNOSTIC CATEGORIES

The following categories are defined:

CMD_AUTHOR

Added in version 4.4.

-W[no-][error=]author <#cmdoption-cmake-W>
warnings.author <#cmakepresets-configurepresets-warnings-author>, errors.author <#cmakepresets-configurepresets-errors-author>
Warn

Warn 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) <#command:message>. It is 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 the same. This is to say that users simply trying to build a project obtained elsewhere will typically not be interested in these warnings, except to perhaps report them to the project's developer(s).

CMD_DEPRECATED

Added in version 4.4.

-W[no-][error=]deprecated <#cmdoption-cmake-W>
warnings.deprecated <#cmakepresets-configurepresets-warnings-deprecated>, errors.deprecated <#cmakepresets-configurepresets-errors-deprecated>
Warn
CMD_AUTHOR <#diagnostic:CMD_AUTHOR>

Warn about use of a deprecated function or package. This is the category triggered by message(DEPRECATION) <#command:message>.

Note:

If CMP0218 <#policy:CMP0218> is not set to NEW, message(DEPRECATION) <#command:message> 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 <#variable:CMAKE_WARN_DEPRECATED> and CMAKE_ERROR_DEPRECATED <#variable:CMAKE_ERROR_DEPRECATED> variables to determine the severity of deprecation messages.


CMD_EXPERIMENTAL

Added in version 4.4.

-W[no-][error=]experimental <#cmdoption-cmake-W>
warnings.experimental <#cmakepresets-configurepresets-warnings-experimental>, errors.experimental <#cmakepresets-configurepresets-errors-experimental>
Warn
CMD_AUTHOR <#diagnostic:CMD_AUTHOR>

Warn 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.

-W[no-][error=]install-absolute-destination <#cmdoption-cmake-W>
warnings.installAbsoluteDestination <#cmakepresets-configurepresets-warnings-installabsolutedestination>, errors.installAbsoluteDestination <#cmakepresets-configurepresets-errors-installabsolutedestination>
Ignore
CMD_AUTHOR <#diagnostic:CMD_AUTHOR>

Warn when an install() <#command: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.

-W[no-][error=]policy <#cmdoption-cmake-W>
warnings.policy <#cmakepresets-configurepresets-warnings-policy>, errors.policy <#cmakepresets-configurepresets-errors-policy>
Warn
CMD_AUTHOR <#diagnostic:CMD_AUTHOR>

Warn if a build system potentially depends on the OLD behavior of a CMake Policy. See the cmake_policy() <#command:cmake_policy> command for more details. Setting a policy to OLD will also disable warnings for that specific policy.

CMD_UNINITIALIZED

Added in version 4.4.

-W[no-][error=]uninitialized <#cmdoption-cmake-W>
warnings.uninitialized <#cmakepresets-configurepresets-warnings-uninitialized>, errors.uninitialized <#cmakepresets-configurepresets-errors-uninitialized>
Ignore

Warn if an uninitialized variable is dereferenced.

CMD_UNUSED_CLI

Added in version 4.4.

-W[no-][error=]unused-cli <#cmdoption-cmake-W>
warnings.unusedCli <#cmakepresets-configurepresets-warnings-unusedcli>, errors.unusedCli <#cmakepresets-configurepresets-errors-unusedcli>
Ignore

Warn about variables that are declared on the command line, but not used.

This diagnostic is issued outside of the configuration / generation phases. Accordingly, while the action of this warning category can be queried as usual, the cmake_diagnostic() <#command:cmake_diagnostic> command is unable to affect the action of this diagnostic.

Copyright

2000-2026 Kitware, Inc. and Contributors

July 11, 2026 4.4.0