install: Add CMAKE_INSTALL_MESSAGE variable (#13761)

Create a variable to allow users to control which installation
messages are printed.  In particular, provide a "LAZY" setting
that prints "Installing" messages but not "Up-to-date" messages.
This is desirable for incremental re-installations.

Suggested-by: J Decker <d3ck0r@gmail.com>

1 files changed, 30 insertions, 0 deletions

diff --git a/Help/variable/CMAKE_INSTALL_MESSAGE.rst b/Help/variable/CMAKE_INSTALL_MESSAGE.rst
new file mode 100644
index 0000000..304df26
--- /dev/null
+++ b/Help/variable/CMAKE_INSTALL_MESSAGE.rst
@@ -0,0 +1,30 @@
+CMAKE_INSTALL_MESSAGE
+---------------------
+
+Specify verbosity of installation script code generated by the
+:command:`install` command (using the :command:`file(INSTALL)` command).
+For paths that are newly installed or updated, installation
+may print lines like::
+
+  -- Installing: /some/destination/path
+
+For paths that are already up to date, installation may print
+lines like::
+
+  -- Up-to-date: /some/destination/path
+
+The ``CMAKE_INSTALL_MESSAGE`` variable may be set to control
+which messages are printed:
+
+``ALWAYS``
+  Print both ``Installing`` and ``Up-to-date`` messages.
+
+``LAZY``
+  Print ``Installing`` but not ``Up-to-date`` messages.
+
+``NEVER``
+  Print neither ``Installing`` nor ``Up-to-date`` messages.
+
+Other values have undefined behavior and may not be diagnosed.
+
+If this variable is not set, the default behavior is ``ALWAYS``.