color: Introduce CMAKE_COLOR_DIAGNOSTICS variable

Add a variable to control both makefile color messages and compiler
color diagnostics.

Fixes: #15502

1 files changed, 35 insertions, 0 deletions

diff --git a/Help/variable/CMAKE_COLOR_DIAGNOSTICS.rst b/Help/variable/CMAKE_COLOR_DIAGNOSTICS.rst
new file mode 100644
index 0000000..805467a
--- /dev/null
+++ b/Help/variable/CMAKE_COLOR_DIAGNOSTICS.rst
@@ -0,0 +1,35 @@
+CMAKE_COLOR_DIAGNOSTICS
+-----------------------
+
+.. versionadded:: 3.24
+
+Enable color diagnostics throughout.
+
+This variable uses three states: ``ON``, ``OFF`` and not defined.
+
+When not defined:
+
+* :ref:`Makefile Generators` initialize the :variable:`CMAKE_COLOR_MAKEFILE`
+  variable to ``ON``.  It controls color buildsystem messages.
+
+* GNU/Clang compilers are not invoked with any color diagnostics flag.
+
+When ``ON``:
+
+* :ref:`Makefile Generators` produce color buildsystem messages by default.
+  :variable:`CMAKE_COLOR_MAKEFILE` is not initialized, but may be
+  explicitly set to ``OFF`` to disable color buildsystem messages.
+
+* GNU/Clang compilers are invoked with a flag enabling color diagnostics
+  (``-fcolor-diagnostics``).
+
+When ``OFF``:
+
+* :ref:`Makefile Generators` do not produce color buildsystem messages by
+  default.  :variable:`CMAKE_COLOR_MAKEFILE` is not initialized, but may be
+  explicitly set to ``ON`` to enable color buildsystem messages.
+
+* GNU/Clang compilers are invoked with a flag disabling color diagnostics
+  (``-fno-color-diagnostics``).
+
+``CMAKE_COLOR_DIAGNOSTICS`` is not defined by default.