Merge topic 'color-diagnostics'

6ab9fbd43b color: Add tests for CMAKE_COLOR_DIAGNOSTICS
78adb1b952 color: Add CMAKE_COLOR_DIAGNOSTICS environment variable
884d9de8b7 color: Introduce CMAKE_COLOR_DIAGNOSTICS variable

Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: buildbot <buildbot@kitware.com>
Acked-by: Frank Dana <ferdnyc@gmail.com>
Merge-request: !6990

5 files changed, 58 insertions, 0 deletions

diff --git a/Help/envvar/CMAKE_COLOR_DIAGNOSTICS.rst b/Help/envvar/CMAKE_COLOR_DIAGNOSTICS.rst
new file mode 100644
index 0000000..d3d0aa9
--- /dev/null
+++ b/Help/envvar/CMAKE_COLOR_DIAGNOSTICS.rst
@@ -0,0 +1,9 @@
+CMAKE_COLOR_DIAGNOSTICS
+-----------------------
+
+.. versionadded:: 3.24
+
+.. include:: ENV_VAR.txt
+
+Specifies a default value for the :variable:`CMAKE_COLOR_DIAGNOSTICS` variable
+when there is no explicit value given on the first run.
diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst
index 0799fdd..fc14262 100644
--- a/Help/manual/cmake-env-variables.7.rst
+++ b/Help/manual/cmake-env-variables.7.rst
@@ -31,6 +31,7 @@ Environment Variables that Control the Build
    /envvar/CMAKE_APPLE_SILICON_PROCESSOR
    /envvar/CMAKE_BUILD_PARALLEL_LEVEL
    /envvar/CMAKE_BUILD_TYPE
+   /envvar/CMAKE_COLOR_DIAGNOSTICS
    /envvar/CMAKE_CONFIGURATION_TYPES
    /envvar/CMAKE_CONFIG_TYPE
    /envvar/CMAKE_EXPORT_COMPILE_COMMANDS
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index ffebfff..f2fef54 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -172,6 +172,7 @@ Variables that Change Behavior
    /variable/CMAKE_CODEBLOCKS_COMPILER_ID
    /variable/CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES
    /variable/CMAKE_CODELITE_USE_TARGETS
+   /variable/CMAKE_COLOR_DIAGNOSTICS
    /variable/CMAKE_COLOR_MAKEFILE
    /variable/CMAKE_CONFIGURATION_TYPES
    /variable/CMAKE_DEPENDS_IN_PROJECT_ONLY
diff --git a/Help/release/dev/color-diagnostics.rst b/Help/release/dev/color-diagnostics.rst
new file mode 100644
index 0000000..8e0e225
--- /dev/null
+++ b/Help/release/dev/color-diagnostics.rst
@@ -0,0 +1,10 @@
+color-diagnostics
+-----------------
+
+* The :variable:`CMAKE_COLOR_DIAGNOSTICS` variable was added to control
+  color diagnostics generated by compilers.  This variable also controls
+  color buildsystem messages with :ref:`Makefile Generators`, replacing
+  :variable:`CMAKE_COLOR_MAKEFILE`.
+
+  The :envvar:`CMAKE_COLOR_DIAGNOSTICS` environment was added to set
+  a default value for :variable:`CMAKE_COLOR_DIAGNOSTICS`.
diff --git a/Help/variable/CMAKE_COLOR_DIAGNOSTICS.rst b/Help/variable/CMAKE_COLOR_DIAGNOSTICS.rst
new file mode 100644
index 0000000..a72c9e1
--- /dev/null
+++ b/Help/variable/CMAKE_COLOR_DIAGNOSTICS.rst
@@ -0,0 +1,37 @@
+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``).
+
+If the :envvar:`CMAKE_COLOR_DIAGNOSTICS` environment variable is set, its
+value is used.  Otherwise, ``CMAKE_COLOR_DIAGNOSTICS`` is not defined by
+default.