GNUInstallDirs¶
This module defines the installation directory variables according to the GNU Coding Standards and provides a command to compute installation-related absolute paths.
Load this module in a CMake project with:
include(GNUInstallDirs)
Result Variables¶
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 ofinstall()
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. However, there are some special cases as documented below.While absolute paths are allowed, they are not recommended as they do not work with the
cmake --install
command's--prefix
option, or with thecpack
installer generators. In particular, there is no need to make paths absolute by prependingCMAKE_INSTALL_PREFIX
; this prefix is used by default if the DESTINATION is a relative path.CMAKE_INSTALL_FULL_<dir>
The absolute path generated from the corresponding
CMAKE_INSTALL_<dir>
value. If the value is not already an absolute path, an absolute path is constructed typically by prepending the value of theCMAKE_INSTALL_PREFIX
variable, except in special cases as documented below.These variables shouldn't be used in
install()
commands as they do not work with thecmake --install
command's--prefix
option, or with thecpack
installer generators.
where <dir>
is one of:
BINDIR
user executables (
bin
)SBINDIR
system admin executables (
sbin
)LIBEXECDIR
program executables (
libexec
)SYSCONFDIR
read-only single-machine data (
etc
)Changed in version 4.1: If the
CMAKE_INSTALL_PREFIX
falls into the special cases, the default paths for are the absolute path variants as described there. See policyCMP0192
.SHAREDSTATEDIR
modifiable architecture-independent data (
com
)LOCALSTATEDIR
modifiable single-machine data (
var
)Changed in version 4.1: If the
CMAKE_INSTALL_PREFIX
falls into the special cases, the default paths for are the absolute path variants as described there. See policyCMP0192
.RUNSTATEDIR
run-time variable data (
LOCALSTATEDIR/run
)Added in version 3.9.
Changed in version 4.1: If the
CMAKE_INSTALL_PREFIX
falls into the special cases, the default paths for are the absolute path variants as described there. See policyCMP0192
.LIBDIR
object code libraries (
lib
orlib64
)On Debian, this may be
lib/<multiarch-tuple>
whenCMAKE_INSTALL_PREFIX
is/usr
.INCLUDEDIR
C header files (
include
)OLDINCLUDEDIR
C header files for non-gcc (
/usr/include
)DATAROOTDIR
read-only architecture-independent data root (
share
)DATADIR
read-only architecture-independent data (
DATAROOTDIR
)INFODIR
info documentation (
DATAROOTDIR/info
)LOCALEDIR
locale-dependent data (
DATAROOTDIR/locale
)MANDIR
man documentation (
DATAROOTDIR/man
)DOCDIR
documentation root (
DATAROOTDIR/doc/PROJECT_NAME
)
If the includer does not define a value the above-shown default will be used and the value will appear in the cache for editing by the user.
If a default value for the CMAKE_INSTALL_<dir>
is used and the
CMAKE_INSTALL_PREFIX
is changed, the new default value will
be used calculated on the new CMAKE_INSTALL_PREFIX
value.
Using --prefix
in cmake --install
will not alter these values.
Special Cases¶
Added in version 3.4.
The following values of CMAKE_INSTALL_PREFIX
are special:
/
For
<dir>
other than theSYSCONFDIR
,LOCALSTATEDIR
andRUNSTATEDIR
, the value ofCMAKE_INSTALL_<dir>
is prefixed withusr/
if it is not user-specified as an absolute path. For example, theINCLUDEDIR
valueinclude
becomesusr/include
. This is required by the GNU Coding Standards, which state:When building the complete GNU system, the prefix will be empty and
/usr
will be a symbolic link to/
.Changed in version 4.1: The
CMAKE_INSTALL_<dir>
variables are cached with theusr/
prefix. See policyCMP0193
.
/usr
For
<dir>
equal toSYSCONFDIR
,LOCALSTATEDIR
orRUNSTATEDIR
, theCMAKE_INSTALL_FULL_<dir>
is computed by prepending just/
to the value ofCMAKE_INSTALL_<dir>
if it is not already an absolute path. For example, theSYSCONFDIR
valueetc
becomes/etc
. This is required by the GNU Coding Standards.Changed in version 4.1: The default values of
CMAKE_INSTALL_<dir>
for<dir>
equal toSYSCONFDIR
,LOCALSTATEDIR
andRUNSTATEDIR
are the absolute paths/etc
,/var
and/var/run
respectively. See policyCMP0192
.
/opt/...
For
<dir>
equal toSYSCONFDIR
,LOCALSTATEDIR
orRUNSTATEDIR
, theCMAKE_INSTALL_FULL_<dir>
is computed by appending the prefix to the value ofCMAKE_INSTALL_<dir>
if it is not already an absolute path. For example, theSYSCONFDIR
valueetc
becomes/etc/opt/...
. This is defined by the Filesystem Hierarchy Standard.This behavior does not apply to paths under
/opt/homebrew/...
.Changed in version 4.1: The default values of
CMAKE_INSTALL_<dir>
for<dir>
equal toSYSCONFDIR
,LOCALSTATEDIR
andRUNSTATEDIR
are the absolute paths/etc/opt/...
,/var/opt/...
and/var/run/opt/...
respectively. See policyCMP0192
.
Commands¶
This module provides the following command:
- GNUInstallDirs_get_absolute_install_dir¶
Added in version 3.7.
Computes an absolute installation path from a given relative path:
GNUInstallDirs_get_absolute_install_dir(<result-var> <input-var> <dir>)
This command takes the value from the variable
<input-var>
and computes its absolute path according to GNU standard installation directories. If the input path is relative, it is prepended withCMAKE_INSTALL_PREFIX
and may be adjusted for the special cases described above.The arguments are:
<result-var>
Name of the variable in which to store the computed absolute path.
<input-var>
Name of the variable containing the path that will be used to compute its associated absolute installation path.
Changed in version 4.1: This variable is no longer altered. See policy
CMP0193
. In previous CMake versions, this command modified the<input-var>
variable value based on the special cases.<dir>
Added in version 3.20.
The directory type name, e.g.,
SYSCONFDIR
,LOCALSTATEDIR
,RUNSTATEDIR
, etc. This argument determines whether special cases apply when computing the absolute path.Changed in version 3.20: Before the
<dir>
argument was introduced, the directory type could be specified by setting thedir
variable prior to calling this command. As of CMake 3.20, if the<dir>
argument is provided explicitly, thedir
variable is ignored.
While this command is used internally by this module to compute the
CMAKE_INSTALL_FULL_<dir>
variables, it is also exposed publicly for users to create additional custom installation path variables and compute absolute paths where necessary, using the same logic.
See Also¶
The
install()
command.