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 of 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. 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 the cpack installer generators. In particular, there is no need to make paths absolute by prepending CMAKE_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 the CMAKE_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 the cmake --install command's --prefix option, or with the cpack 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 policy CMP0192.

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 policy CMP0192.

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 policy CMP0192.

LIBDIR

object code libraries (lib or lib64)

On Linux, when not cross-compiling, the default is the distro's arch-specific library directory, such as lib or lib64. On Debian, this may be lib/<multiarch-tuple> when CMAKE_INSTALL_PREFIX is /usr. When cross-compiling, the default is lib.

In projects that enable no languages, e.g., project(... LANGUAGES NONE), no target architecture information is available, so the default is lib.

Note

When an alternative installation prefix is specified with the --prefix option at install time, the special case with multi-architecture tuple is evaluated based on the configuration-time CMAKE_INSTALL_PREFIX, not on the alternative prefix value.

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)

The DATADIR and DATAROOTDIR are treated separately so that DATADIR can be customized for project-specific data files, while DATAROOTDIR remains unchanged for standard architecture-independent locations INFODIR, LOCALEDIR, MANDIR, and DOCDIR.

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 the SYSCONFDIR, LOCALSTATEDIR and RUNSTATEDIR, the value of CMAKE_INSTALL_<dir> is prefixed with usr/ if it is not user-specified as an absolute path. For example, the INCLUDEDIR value include becomes usr/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 the usr/ prefix. See policy CMP0193.

/usr

For <dir> equal to SYSCONFDIR, LOCALSTATEDIR or RUNSTATEDIR, the CMAKE_INSTALL_FULL_<dir> is computed by prepending just / to the value of CMAKE_INSTALL_<dir> if it is not already an absolute path. For example, the SYSCONFDIR value etc 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 to SYSCONFDIR, LOCALSTATEDIR and RUNSTATEDIR are the absolute paths /etc, /var and /var/run respectively. See policy CMP0192.

/opt/...

For <dir> equal to SYSCONFDIR, LOCALSTATEDIR or RUNSTATEDIR, the CMAKE_INSTALL_FULL_<dir> is computed by appending the prefix to the value of CMAKE_INSTALL_<dir> if it is not already an absolute path. For example, the SYSCONFDIR value etc 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 to SYSCONFDIR, LOCALSTATEDIR and RUNSTATEDIR are the absolute paths /etc/opt/..., /var/opt/... and /var/run/opt/... respectively. See policy CMP0192.

Note

When an alternative installation prefix is specified with the --prefix option at install time, these special cases are evaluated based on the configuration-time CMAKE_INSTALL_PREFIX, not on the alternative prefix value.

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 with CMAKE_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 the dir variable prior to calling this command. As of CMake 3.20, if the <dir> argument is provided explicitly, the dir 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