Merge topic 'doc-install-relative-paths' into release-3.29

af293ff7c3 Help: Explicitly discourage absolute install destinations

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !9261

2 files changed, 31 insertions, 18 deletions

diff --git a/Help/command/install.rst b/Help/command/install.rst
index 0c2a32a..674b770 100644
--- a/Help/command/install.rst
+++ b/Help/command/install.rst
@@ -47,23 +47,26 @@ signatures that specify them.  The common options are:
 
 ``DESTINATION <dir>``
   Specify the directory on disk to which a file will be installed.
-  Arguments can be relative or absolute paths.
+  ``<dir>`` should be a relative path.  An absolute path is allowed,
+  but not recommended.
 
-  If a relative path is given it is interpreted relative to the value
+  When a relative path is given it is interpreted relative to the value
   of the :variable:`CMAKE_INSTALL_PREFIX` variable.
   The prefix can be relocated at install time using the ``DESTDIR``
   mechanism explained in the :variable:`CMAKE_INSTALL_PREFIX` variable
   documentation.
 
-  If an absolute path (with a leading slash or drive letter) is given
-  it is used verbatim.
-
-  As absolute paths are not supported by :manual:`cpack <cpack(1)>` installer
-  generators, it is preferable to use relative paths throughout.
+  As absolute paths do not work with the ``cmake --install`` command's
+  :option:`--prefix <cmake--install --prefix>` option, or with the
+  :manual:`cpack <cpack(1)>` installer generators, it is strongly recommended
+  to use relative paths throughout for best support by package maintainers.
   In particular, there is no need to make paths absolute by prepending
   :variable:`CMAKE_INSTALL_PREFIX`; this prefix is used by default if
   the DESTINATION is a relative path.
 
+  If an absolute path (with a leading slash or drive letter) is given
+  it is used verbatim.
+
 ``PERMISSIONS <permission>...``
   Specify permissions for installed files.  Valid permissions are
   ``OWNER_READ``, ``OWNER_WRITE``, ``OWNER_EXECUTE``, ``GROUP_READ``,
@@ -280,8 +283,8 @@ Signatures
   instead of being able to rely on the above (see next example below).
 
   To make packages compliant with distribution filesystem layout policies, if
-  projects must specify a ``DESTINATION``, it is recommended that they use a
-  path that begins with the appropriate :module:`GNUInstallDirs` variable.
+  projects must specify a ``DESTINATION``, it is strongly recommended that they use
+  a path that begins with the appropriate relative :module:`GNUInstallDirs` variable.
   This allows package maintainers to control the install destination by setting
   the appropriate cache variables.  The following example shows a static library
   being installed to the default destination provided by
@@ -572,8 +575,8 @@ Signatures
   ``DATA`` instead.
 
   To make packages compliant with distribution filesystem layout policies, if
-  projects must specify a ``DESTINATION``, it is recommended that they use a
-  path that begins with the appropriate :module:`GNUInstallDirs` variable.
+  projects must specify a ``DESTINATION``, it is strongly recommended that they use
+  a path that begins with the appropriate relative :module:`GNUInstallDirs` variable.
   This allows package maintainers to control the install destination by setting
   the appropriate cache variables.  The following example shows how to follow
   this advice while installing an image to a project-specific documentation
@@ -719,8 +722,8 @@ Signatures
   ``DATA`` instead.
 
   To make packages compliant with distribution filesystem layout policies, if
-  projects must specify a ``DESTINATION``, it is recommended that they use a
-  path that begins with the appropriate :module:`GNUInstallDirs` variable.
+  projects must specify a ``DESTINATION``, it is strongly recommended that they use
+  a path that begins with the appropriate relative :module:`GNUInstallDirs` variable.
   This allows package maintainers to control the install destination by setting
   the appropriate cache variables.
 
diff --git a/Modules/GNUInstallDirs.cmake b/Modules/GNUInstallDirs.cmake
index 9796854..ed34c4a 100644
--- a/Modules/GNUInstallDirs.cmake
+++ b/Modules/GNUInstallDirs.cmake
@@ -20,11 +20,16 @@ Inclusion of this module defines the following variables:
 ``CMAKE_INSTALL_<dir>``
 
   Destination for files of a given type.  This value may be passed to
-  the ``DESTINATION`` options of :command:`install` commands for the
-  corresponding file type.  It should typically be a path relative to
-  the installation prefix so that it can be converted to an absolute
-  path in a relocatable way (see ``CMAKE_INSTALL_FULL_<dir>``).
-  However, an absolute path is also allowed.
+  the ``DESTINATION`` options of  :command:`install` commands for the
+  corresponding file type.  It should be a path relative to the installation
+  prefix so that it can be converted to an absolute path in a relocatable way.
+
+  While absolute paths are allowed, they are not recommended as they
+  do not work with the ``cmake --install`` command's
+  :option:`--prefix <cmake--install --prefix>` option, or with the
+  :manual:`cpack <cpack(1)>` installer generators. In particular, there is no
+  need to make paths absolute by prepending :variable:`CMAKE_INSTALL_PREFIX`;
+  this prefix is used by default if the DESTINATION is a relative path.
 
 ``CMAKE_INSTALL_FULL_<dir>``
 
@@ -34,6 +39,11 @@ Inclusion of this module defines the following variables:
   :variable:`CMAKE_INSTALL_PREFIX` variable.  However, there are some
   `special cases`_ as documented below.
 
+  These variables shouldn't be used in :command:`install` commands
+  as they do not work with the ``cmake --install`` command's
+  :option:`--prefix <cmake--install --prefix>` option, or with the
+  :manual:`cpack <cpack(1)>` installer generators.
+
 where ``<dir>`` is one of:
 
 ``BINDIR``