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>

5 files changed, 42 insertions, 1 deletions

diff --git a/Help/command/file.rst b/Help/command/file.rst
index 869350a..58e3a26 100644
--- a/Help/command/file.rst
+++ b/Help/command/file.rst
@@ -298,6 +298,7 @@ See the :command:`install(DIRECTORY)` command for documentation of
 permissions, ``PATTERN``, ``REGEX``, and ``EXCLUDE`` options.
 
 The ``INSTALL`` signature differs slightly from ``COPY``: it prints
-status messages, and ``NO_SOURCE_PERMISSIONS`` is default.
+status messages (subject to the :variable:`CMAKE_INSTALL_MESSAGE` variable),
+and ``NO_SOURCE_PERMISSIONS`` is default.
 Installation scripts generated by the :command:`install` command
 use this signature (with some undocumented options for internal use).
diff --git a/Help/command/install.rst b/Help/command/install.rst
index 462a8a9..00f722b 100644
--- a/Help/command/install.rst
+++ b/Help/command/install.rst
@@ -59,6 +59,10 @@ signatures that specify them.  The common options are:
   Specify that it is not an error if the file to be installed does
   not exist.
 
+Command signatures that install files may print messages during
+installation.  Use the :variable:`CMAKE_INSTALL_MESSAGE` variable
+to control which messages are printed.
+
 Installing Targets
 ^^^^^^^^^^^^^^^^^^
 
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index df434c5..0e4c4a0 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -128,6 +128,7 @@ Variables that Change Behavior
    /variable/CMAKE_INCLUDE_DIRECTORIES_BEFORE
    /variable/CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE
    /variable/CMAKE_INSTALL_DEFAULT_COMPONENT_NAME
+   /variable/CMAKE_INSTALL_MESSAGE
    /variable/CMAKE_INSTALL_PREFIX
    /variable/CMAKE_LIBRARY_PATH
    /variable/CMAKE_MFC_FLAG
diff --git a/Help/release/dev/install-messages.rst b/Help/release/dev/install-messages.rst
new file mode 100644
index 0000000..c8aa456
--- /dev/null
+++ b/Help/release/dev/install-messages.rst
@@ -0,0 +1,5 @@
+install-messages
+----------------
+
+* The :variable:`CMAKE_INSTALL_MESSAGE` variable was introduced to
+  optionally reduce output installation.
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``.