# 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 Debian, this may be `lib/<multiarch-tuple>` when `CMAKE_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 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`.

## 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

- The `install()` command.