Help: Add documentation and release notes for install

This change adds documentation for the new DESTINATION behavior of
the install() command.

2 files changed, 121 insertions, 4 deletions

diff --git a/Help/command/install.rst b/Help/command/install.rst
index 4966df4..55c8485 100644
--- a/Help/command/install.rst
+++ b/Help/command/install.rst
@@ -9,8 +9,8 @@ Synopsis
 .. parsed-literal::
 
   install(`TARGETS`_ <target>... [...])
-  install({`FILES`_ | `PROGRAMS`_} <file>... DESTINATION <dir> [...])
-  install(`DIRECTORY`_ <dir>... DESTINATION <dir> [...])
+  install({`FILES`_ | `PROGRAMS`_} <file>... [DESTINATION <dir>] [...])
+  install(`DIRECTORY`_ <dir>... [DESTINATION <dir>] [...])
   install(`SCRIPT`_ <file> [...])
   install(`CODE`_ <code> [...])
   install(`EXPORT`_ <export-name> DESTINATION <dir> [...])
@@ -172,6 +172,29 @@ installation properties apply to all target types. If only one is given then
 only targets of that type will be installed (which can be used to install
 just a DLL or just an import library.)
 
+For some target types, the ``DESTINATION`` argument is optional. If no
+``DESTINATION`` argument is specified for these target types, the destination
+will default to either the appropriate variable from :module:`GNUInstallDirs`
+(if it is defined) or a built-in default (if the variable is not defined.) These
+defaults are outlined below:
+
+================== =============================== ======================
+   Target Type         GNUInstallDirs Variable        Built-In Default
+================== =============================== ======================
+``RUNTIME``        ``${CMAKE_INSTALL_BINDIR}``     ``bin``
+``LIBRARY``        ``${CMAKE_INSTALL_LIBDIR}``     ``lib``
+``ARCHIVE``        ``${CMAKE_INSTALL_LIBDIR}``     ``lib``
+``PRIVATE_HEADER`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include``
+``PUBLIC_HEADER``  ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include``
+================== =============================== ======================
+
+To make your package compliant with distribution filesystem layout policies, it
+is not recommended that you specify a ``DESTINATION`` for a target unless it
+must be installed in a nonstandard location. That way, package maintainers can
+control the install destination by setting the appropriate cache variables. In
+any case, it is recommended that you use the :module:`GNUInstallDirs` variables
+in your ``DESTINATION`` arguments whenever possible.
+
 In addition to the common options listed above, each target can accept
 the following additional arguments:
 
@@ -307,7 +330,7 @@ Installing Files
 
 .. code-block:: cmake
 
-  install(<FILES|PROGRAMS> files... DESTINATION <dir>
+  install(<FILES|PROGRAMS> files... [DESTINATION <dir> | TYPE <type>]
           [PERMISSIONS permissions...]
           [CONFIGURATIONS [Debug|Release|...]]
           [COMPONENT <component>]
@@ -331,6 +354,47 @@ 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.
 
+Instead of specifying ``DESTINATION``, you may specify a generic file type
+via the ``TYPE`` argument as listed below. If a type is selected and no
+destination is specified, the destination will default to either the
+appropriate variable from :module:`GNUInstallDirs` (if it is defined) or a
+built-in default (if the variable is not defined.) These defaults are outlined
+below:
+
+======================= ================================== =========================
+   ``TYPE`` Argument         GNUInstallDirs Variable           Built-In Default
+======================= ================================== =========================
+``BIN``                 ``${CMAKE_INSTALL_BINDIR}``        ``bin``
+``SBIN``                ``${CMAKE_INSTALL_SBINDIR}``       ``sbin``
+``LIB``                 ``${CMAKE_INSTALL_LIBDIR}``        ``lib``
+``INCLUDE``             ``${CMAKE_INSTALL_INCLUDEDIR}``    ``include``
+``SYSCONF``             ``${CMAKE_INSTALL_SYSCONFDIR}``    ``etc``
+``SHAREDSTATE``         ``${CMAKE_INSTALL_SHARESTATEDIR}`` ``com``
+``LOCALSTATE``          ``${CMAKE_INSTALL_LOCALSTATEDIR}`` ``var``
+``RUNSTATE``            ``${CMAKE_INSTALL_RUNSTATEDIR}``   ``<LOCALSTATE dir>/run``
+``DATA``                ``${CMAKE_INSTALL_DATADIR}``       ``<DATAROOT dir>``
+``INFO``                ``${CMAKE_INSTALL_INFODIR}``       ``<DATAROOT dir>/info``
+``LOCALE``              ``${CMAKE_INSTALL_LOCALEDIR}``     ``<DATAROOT dir>/locale``
+``MAN``                 ``${CMAKE_INSTALL_MANDIR}``        ``<DATAROOT dir>/man``
+``DOC``                 ``${CMAKE_INSTALL_DOCDIR}``        ``<DATAROOT dir>/doc``
+======================= ================================== =========================
+
+It is an error to use ``TYPE`` and ``DESTINATION`` arguments together.
+
+Note that some of the types' built-in defaults use the ``DATAROOT`` directory as
+a prefix. The ``DATAROOT`` prefix is calculated similarly to the types, with
+``CMAKE_INSTALL_DATAROOTDIR`` as the variable and ``share`` as the built-in
+default. You cannot use ``DATAROOT`` as a ``TYPE`` parameter; please use
+``DATA`` instead.
+
+To make your package compliant with distribution filesystem layout policies, it
+is recommended that you specify one of the above generic file types, rather than
+a ``DESTINATION`` argument, unless the files must be installed in a nonstandard
+location. That way, package maintainers can control the install destination by
+setting the appropriate cache variables. In any case, it is recommended that you
+use the :module:`GNUInstallDirs` variables in your ``DESTINATION`` arguments
+whenever possible.
+
 The install destination given to the files install ``DESTINATION`` may
 use "generator expressions" with the syntax ``$<...>``.  See the
 :manual:`cmake-generator-expressions(7)` manual for available expressions.
@@ -342,7 +406,7 @@ Installing Directories
 
 .. code-block:: cmake
 
-  install(DIRECTORY dirs... DESTINATION <dir>
+  install(DIRECTORY dirs... [DESTINATION <dir> | TYPE <type>]
           [FILE_PERMISSIONS permissions...]
           [DIRECTORY_PERMISSIONS permissions...]
           [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER]
@@ -413,6 +477,47 @@ 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.
 
+Instead of specifying ``DESTINATION``, you may specify a generic file type
+via the ``TYPE`` argument as listed below. If a type is selected and no
+destination is specified, the destination will default to either the
+appropriate variable from :module:`GNUInstallDirs` (if it is defined) or a
+built-in default (if the variable is not defined.) These defaults are outlined
+below:
+
+======================= ================================== =========================
+   ``TYPE`` Argument         GNUInstallDirs Variable           Built-In Default
+======================= ================================== =========================
+``BIN``                 ``${CMAKE_INSTALL_BINDIR}``        ``bin``
+``SBIN``                ``${CMAKE_INSTALL_SBINDIR}``       ``sbin``
+``LIB``                 ``${CMAKE_INSTALL_LIBDIR}``        ``lib``
+``INCLUDE``             ``${CMAKE_INSTALL_INCLUDEDIR}``    ``include``
+``SYSCONF``             ``${CMAKE_INSTALL_SYSCONFDIR}``    ``etc``
+``SHAREDSTATE``         ``${CMAKE_INSTALL_SHARESTATEDIR}`` ``com``
+``LOCALSTATE``          ``${CMAKE_INSTALL_LOCALSTATEDIR}`` ``var``
+``RUNSTATE``            ``${CMAKE_INSTALL_RUNSTATEDIR}``   ``<LOCALSTATE dir>/run``
+``DATA``                ``${CMAKE_INSTALL_DATADIR}``       ``<DATAROOT dir>``
+``INFO``                ``${CMAKE_INSTALL_INFODIR}``       ``<DATAROOT dir>/info``
+``LOCALE``              ``${CMAKE_INSTALL_LOCALEDIR}``     ``<DATAROOT dir>/locale``
+``MAN``                 ``${CMAKE_INSTALL_MANDIR}``        ``<DATAROOT dir>/man``
+``DOC``                 ``${CMAKE_INSTALL_DOCDIR}``        ``<DATAROOT dir>/doc``
+======================= ================================== =========================
+
+It is an error to use ``TYPE`` and ``DESTINATION`` arguments together.
+
+Note that some of the types' built-in defaults use the ``DATAROOT`` directory as
+a prefix. The ``DATAROOT`` prefix is calculated similarly to the types, with
+``CMAKE_INSTALL_DATAROOTDIR`` as the variable and ``share`` as the built-in
+default. You cannot use ``DATAROOT`` as a ``TYPE`` parameter; please use
+``DATA`` instead.
+
+To make your package compliant with distribution filesystem layout policies, it
+is recommended that you specify one of the above generic file types, rather than
+a ``DESTINATION`` argument, unless the files must be installed in a nonstandard
+location. That way, package maintainers can control the install destination by
+setting the appropriate cache variables. In any case, it is recommended that you
+use the :module:`GNUInstallDirs` variables in your ``DESTINATION`` arguments
+whenever possible.
+
 The list of ``dirs...`` given to ``DIRECTORY`` and the install destination
 given to the directory install ``DESTINATION`` may use "generator expressions"
 with the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
diff --git a/Help/release/dev/install-defaults.rst b/Help/release/dev/install-defaults.rst
new file mode 100644
index 0000000..4f31b7e
--- /dev/null
+++ b/Help/release/dev/install-defaults.rst
@@ -0,0 +1,12 @@
+install-defaults
+----------------
+
+* The ``TARGETS`` variant of the :command:`install` command learned how to
+  install to an appropriate default directory for a given target type, based
+  on variables from the :module:`GNUInstallDirs` module and built-in defaults,
+  in lieu of a ``DESTINATION`` argument.
+* The ``FILES`` and ``DIRECTORY`` variants of the :command:`install` command
+  learned a new set of parameters for installing files as a file type, setting
+  the destination based on the appropriate variables from
+  :module:`GNUInstallDirs` and built-in defaults, in lieu of a ``DESTINATION``
+  argument.