From af293ff7c3847dae029d5e91a3ea1864466c9659 Mon Sep 17 00:00:00 2001 From: Robert Maynard Date: Thu, 15 Feb 2024 11:58:26 -0500 Subject: Help: Explicitly discourage absolute install destinations Document some of the problems caused by absolute install destinations. Encourage use of relative paths. --- Help/command/install.rst | 29 ++++++++++++++++------------- Modules/GNUInstallDirs.cmake | 20 +++++++++++++++----- 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 `` Specify the directory on disk to which a file will be installed. - Arguments can be relative or absolute paths. + ```` 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 ` installer - generators, it is preferable to use relative paths throughout. + As absolute paths do not work with the ``cmake --install`` command's + :option:`--prefix ` option, or with the + :manual:`cpack ` 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 ...`` 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_`` 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_``). - 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 ` option, or with the + :manual:`cpack ` 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_`` @@ -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 ` option, or with the + :manual:`cpack ` installer generators. + where ```` is one of: ``BINDIR`` -- cgit v0.12