mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-01-11 16:32:14 -06:00
Code Issues Packages Projects Releases Wiki Activity

Help: Explicitly discourage absolute install destinations

Browse Source 
Document some of the problems caused by absolute install destinations.
Encourage use of relative paths.
This commit is contained in:
Robert Maynard
2024-02-15 11:58:26 -05:00
committed by Brad King
parent cbc4afccc1
commit af293ff7c3
2 changed files with 31 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
Help/command/install.rst
View File

@@ -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.

20
Modules/GNUInstallDirs.cmake
View File

@@ -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``