Merge topic 'install-messages'

d19b64d6 install(DIRECTORY): Add MESSAGE_NEVER option to avoid output (#13761)
c9568de5 install: Add CMAKE_INSTALL_MESSAGE variable (#13761)
ec7cf7ea install: Thread message level setting through internal API
abebcd23 file(INSTALL): Add undocumented options to control output verbosity
464567a5 file(INSTALL): Report existing DIRECTORY as Up-to-date
f701b0b7 file(INSTALL): Do not pre-create DESTINATION for DIRECTORY
f0a01962 cmInstallTargetGenerator: Drop default constructor arguments
67815894 Help: Add install() command document section headers

5 files changed, 65 insertions, 7 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 47108f0..4c52abf 100644
--- a/Help/command/install.rst
+++ b/Help/command/install.rst
@@ -1,8 +1,15 @@
 install
 -------
 
+.. only:: html
+
+   .. contents::
+
 Specify rules to run at install time.
 
+Introduction
+^^^^^^^^^^^^
+
 This command generates installation rules for a project.  Rules
 specified by calls to this command within a source directory are
 executed in order during installation.  The order across directories
@@ -52,7 +59,12 @@ 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
+^^^^^^^^^^^^^^^^^^
 
 ::
 
@@ -147,7 +159,8 @@ file itself, call ``install(EXPORT)``, documented below.
 Installing a target with the :prop_tgt:`EXCLUDE_FROM_ALL` target property
 set to ``TRUE`` has undefined behavior.
 
-------------------------------------------------------------------------------
+Installing Files
+^^^^^^^^^^^^^^^^
 
 ::
 
@@ -175,14 +188,15 @@ The list of ``files...`` given to ``FILES`` or ``PROGRAMS`` may use
 However, if any item begins in a generator expression it must evaluate
 to a full path.
 
-------------------------------------------------------------------------------
+Installing Directories
+^^^^^^^^^^^^^^^^^^^^^^
 
 ::
 
   install(DIRECTORY dirs... DESTINATION <dir>
           [FILE_PERMISSIONS permissions...]
           [DIRECTORY_PERMISSIONS permissions...]
-          [USE_SOURCE_PERMISSIONS] [OPTIONAL]
+          [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER]
           [CONFIGURATIONS [Debug|Release|...]]
           [COMPONENT <component>] [FILES_MATCHING]
           [[PATTERN <pattern> | REGEX <regex>]
@@ -205,6 +219,8 @@ permissions specified in the ``FILES`` form of the command, and the
 directories will be given the default permissions specified in the
 ``PROGRAMS`` form of the command.
 
+The ``MESSAGE_NEVER`` option disables file installation status output.
+
 Installation of directories may be controlled with fine granularity
 using the ``PATTERN`` or ``REGEX`` options.  These "match" options specify a
 globbing pattern or regular expression to match directories or files
@@ -247,7 +263,8 @@ will install the ``icons`` directory to ``share/myproj/icons`` and the
 file permissions, the scripts will be given specific permissions, and any
 ``CVS`` directories will be excluded.
 
-------------------------------------------------------------------------------
+Custom Installation Logic
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
 ::
 
@@ -266,7 +283,8 @@ example, the code
 
 will print a message during installation.
 
-------------------------------------------------------------------------------
+Installing Exports
+^^^^^^^^^^^^^^^^^^
 
 ::
 
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..e023ef7
--- /dev/null
+++ b/Help/release/dev/install-messages.rst
@@ -0,0 +1,8 @@
+install-messages
+----------------
+
+* The :command:`install` command learned a ``MESSAGE_NEVER`` option
+  to avoid output during installation.
+
+* 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``.