Modules/GNUInstallDirs.cmake

   1 # Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
   2 # file Copyright.txt or https://cmake.org/licensing for details.
   3
   4 #[=======================================================================[.rst:
   5 GNUInstallDirs
   6 --------------
   7
   8 Define GNU standard installation directories
   9
  10 Provides install directory variables as defined by the
  11 `GNU Coding Standards`_.
  12
  13 .. _`GNU Coding Standards`: https://www.gnu.org/prep/standards/html_node/Directory-Variables.html
  14
  15 Result Variables
  16 ^^^^^^^^^^^^^^^^
  17
  18 Inclusion of this module defines the following variables:
  19
  20 ``CMAKE_INSTALL_<dir>``
  21
  22   Destination for files of a given type.  This value may be passed to
  23   the ``DESTINATION`` options of :command:`install` commands for the
  24   corresponding file type.  It should typically be a path relative to
  25   the installation prefix so that it can be converted to an absolute
  26   path in a relocatable way (see ``CMAKE_INSTALL_FULL_<dir>``).
  27   However, an absolute path is also allowed.
  28
  29 ``CMAKE_INSTALL_FULL_<dir>``
  30
  31   The absolute path generated from the corresponding ``CMAKE_INSTALL_<dir>``
  32   value.  If the value is not already an absolute path, an absolute path
  33   is constructed typically by prepending the value of the
  34   :variable:`CMAKE_INSTALL_PREFIX` variable.  However, there are some
  35   `special cases`_ as documented below.
  36
  37 where ``<dir>`` is one of:
  38
  39 ``BINDIR``
  40   user executables (``bin``)
  41 ``SBINDIR``
  42   system admin executables (``sbin``)
  43 ``LIBEXECDIR``
  44   program executables (``libexec``)
  45 ``SYSCONFDIR``
  46   read-only single-machine data (``etc``)
  47 ``SHAREDSTATEDIR``
  48   modifiable architecture-independent data (``com``)
  49 ``LOCALSTATEDIR``
  50   modifiable single-machine data (``var``)
  51 ``RUNSTATEDIR``
  52   .. versionadded:: 3.9
  53     run-time variable data (``LOCALSTATEDIR/run``)
  54 ``LIBDIR``
  55   object code libraries (``lib`` or ``lib64``
  56   or ``lib/<multiarch-tuple>`` on Debian)
  57 ``INCLUDEDIR``
  58   C header files (``include``)
  59 ``OLDINCLUDEDIR``
  60   C header files for non-gcc (``/usr/include``)
  61 ``DATAROOTDIR``
  62   read-only architecture-independent data root (``share``)
  63 ``DATADIR``
  64   read-only architecture-independent data (``DATAROOTDIR``)
  65 ``INFODIR``
  66   info documentation (``DATAROOTDIR/info``)
  67 ``LOCALEDIR``
  68   locale-dependent data (``DATAROOTDIR/locale``)
  69 ``MANDIR``
  70   man documentation (``DATAROOTDIR/man``)
  71 ``DOCDIR``
  72   documentation root (``DATAROOTDIR/doc/PROJECT_NAME``)
  73
  74 If the includer does not define a value the above-shown default will be
  75 used and the value will appear in the cache for editing by the user.
  76
  77 Special Cases
  78 ^^^^^^^^^^^^^
  79
  80 .. versionadded:: 3.4
  81
  82 The following values of :variable:`CMAKE_INSTALL_PREFIX` are special:
  83
  84 ``/``
  85
  86   For ``<dir>`` other than the ``SYSCONFDIR``, ``LOCALSTATEDIR`` and
  87   ``RUNSTATEDIR``, the value of ``CMAKE_INSTALL_<dir>`` is prefixed
  88   with ``usr/`` if it is not user-specified as an absolute path.
  89   For example, the ``INCLUDEDIR`` value ``include`` becomes ``usr/include``.
  90   This is required by the `GNU Coding Standards`_, which state:
  91
  92     When building the complete GNU system, the prefix will be empty
  93     and ``/usr`` will be a symbolic link to ``/``.
  94
  95 ``/usr``
  96
  97   For ``<dir>`` equal to ``SYSCONFDIR``, ``LOCALSTATEDIR`` or
  98   ``RUNSTATEDIR``, the ``CMAKE_INSTALL_FULL_<dir>`` is computed by
  99   prepending just ``/`` to the value of ``CMAKE_INSTALL_<dir>``
 100   if it is not user-specified as an absolute path.
 101   For example, the ``SYSCONFDIR`` value ``etc`` becomes ``/etc``.
 102   This is required by the `GNU Coding Standards`_.
 103
 104 ``/opt/...``
 105
 106   For ``<dir>`` equal to ``SYSCONFDIR``, ``LOCALSTATEDIR`` or
 107   ``RUNSTATEDIR``, the ``CMAKE_INSTALL_FULL_<dir>`` is computed by
 108   *appending* the prefix to the value of ``CMAKE_INSTALL_<dir>``
 109   if it is not user-specified as an absolute path.
 110   For example, the ``SYSCONFDIR`` value ``etc`` becomes ``/etc/opt/...``.
 111   This is defined by the `Filesystem Hierarchy Standard`_.
 112
 113 .. _`Filesystem Hierarchy Standard`: https://refspecs.linuxfoundation.org/FHS_3.0/fhs/index.html
 114
 115 Macros
 116 ^^^^^^
 117
 118 .. command:: GNUInstallDirs_get_absolute_install_dir
 119
 120   ::
 121
 122     GNUInstallDirs_get_absolute_install_dir(absvar var dirname)
 123
 124   .. versionadded:: 3.7
 125
 126   Set the given variable ``absvar`` to the absolute path contained
 127   within the variable ``var``.  This is to allow the computation of an
 128   absolute path, accounting for all the special cases documented
 129   above.  While this macro is used to compute the various
 130   ``CMAKE_INSTALL_FULL_<dir>`` variables, it is exposed publicly to
 131   allow users who create additional path variables to also compute
 132   absolute paths where necessary, using the same logic.  ``dirname`` is
 133   the directory name to get, e.g. ``BINDIR``.
 134
 135   .. versionchanged:: 3.20
 136     Added the ``<dirname>`` parameter.  Previous versions of CMake passed
 137     this value through the variable ``${dir}``.
 138 #]=======================================================================]
 139
 140 cmake_policy(PUSH)
 141 cmake_policy(SET CMP0054 NEW) # if() quoted variables not dereferenced
 142
 143 # Convert a cache variable to PATH type
 144
 145 macro(_GNUInstallDirs_cache_convert_to_path var description)
 146   get_property(_GNUInstallDirs_cache_type CACHE ${var} PROPERTY TYPE)
 147   if(_GNUInstallDirs_cache_type STREQUAL "UNINITIALIZED")
 148     file(TO_CMAKE_PATH "${${var}}" _GNUInstallDirs_cmakepath)
 149     set_property(CACHE ${var} PROPERTY TYPE PATH)
 150     set_property(CACHE ${var} PROPERTY VALUE "${_GNUInstallDirs_cmakepath}")
 151     set_property(CACHE ${var} PROPERTY HELPSTRING "${description}")
 152     unset(_GNUInstallDirs_cmakepath)
 153   endif()
 154   unset(_GNUInstallDirs_cache_type)
 155 endmacro()
 156
 157 # Create a cache variable with default for a path.
 158 macro(_GNUInstallDirs_cache_path var default description)
 159   if(NOT DEFINED ${var})
 160     set(${var} "${default}" CACHE PATH "${description}")
 161   endif()
 162   _GNUInstallDirs_cache_convert_to_path("${var}" "${description}")
 163 endmacro()
 164
 165 # Create a cache variable with not default for a path, with a fallback
 166 # when unset; used for entries slaved to other entries such as
 167 # DATAROOTDIR.
 168 macro(_GNUInstallDirs_cache_path_fallback var default description)
 169   if(NOT ${var})
 170     set(${var} "" CACHE PATH "${description}")
 171     set(${var} "${default}")
 172   endif()
 173   _GNUInstallDirs_cache_convert_to_path("${var}" "${description}")
 174 endmacro()
 175
 176 # Installation directories
 177 #
 178
 179 _GNUInstallDirs_cache_path(CMAKE_INSTALL_BINDIR "bin"
 180   "User executables (bin)")
 181 _GNUInstallDirs_cache_path(CMAKE_INSTALL_SBINDIR "sbin"
 182   "System admin executables (sbin)")
 183 _GNUInstallDirs_cache_path(CMAKE_INSTALL_SYSCONFDIR "etc"
 184   "Read-only single-machine data (etc)")
 185 _GNUInstallDirs_cache_path(CMAKE_INSTALL_SHAREDSTATEDIR "com"
 186   "Modifiable architecture-independent data (com)")
 187 _GNUInstallDirs_cache_path(CMAKE_INSTALL_LOCALSTATEDIR "var"
 188   "Modifiable single-machine data (var)")
 189
 190 # We check if the variable was manually set and not cached, in order to
 191 # allow projects to set the values as normal variables before including
 192 # GNUInstallDirs to avoid having the entries cached or user-editable. It
 193 # replaces the "if(NOT DEFINED CMAKE_INSTALL_XXX)" checks in all the
 194 # other cases.
 195 # If CMAKE_INSTALL_LIBDIR is defined, if _libdir_set is false, then the
 196 # variable is a normal one, otherwise it is a cache one.
 197 get_property(_libdir_set CACHE CMAKE_INSTALL_LIBDIR PROPERTY TYPE SET)
 198 if(NOT DEFINED CMAKE_INSTALL_LIBDIR OR (_libdir_set
 199     AND DEFINED _GNUInstallDirs_LAST_CMAKE_INSTALL_PREFIX
 200     AND NOT "${_GNUInstallDirs_LAST_CMAKE_INSTALL_PREFIX}" STREQUAL "${CMAKE_INSTALL_PREFIX}"))
 201   # If CMAKE_INSTALL_LIBDIR is not defined, it is always executed.
 202   # Otherwise:
 203   #  * if _libdir_set is false it is not executed (meaning that it is
 204   #    not a cache variable)
 205   #  * if _GNUInstallDirs_LAST_CMAKE_INSTALL_PREFIX is not defined it is
 206   #    not executed
 207   #  * if _GNUInstallDirs_LAST_CMAKE_INSTALL_PREFIX and
 208   #    CMAKE_INSTALL_PREFIX are the same string it is not executed.
 209   #    _GNUInstallDirs_LAST_CMAKE_INSTALL_PREFIX is updated after the
 210   #    execution, of this part of code, therefore at the next inclusion
 211   #    of the file, CMAKE_INSTALL_LIBDIR is defined, and the 2 strings
 212   #    are equal, meaning that the if is not executed the code the
 213   #    second time.
 214
 215   set(_LIBDIR_DEFAULT "lib")
 216   # Override this default 'lib' with 'lib64' iff:
 217   #  - we are on Linux system but NOT cross-compiling
 218   #  - we are NOT on debian
 219   #  - we are on a 64 bits system
 220   # reason is: amd64 ABI: https://github.com/hjl-tools/x86-psABI/wiki/X86-psABI
 221   # For Debian with multiarch, use 'lib/${CMAKE_LIBRARY_ARCHITECTURE}' if
 222   # CMAKE_LIBRARY_ARCHITECTURE is set (which contains e.g. "i386-linux-gnu"
 223   # and CMAKE_INSTALL_PREFIX is "/usr"
 224   # See http://wiki.debian.org/Multiarch
 225   if(DEFINED _GNUInstallDirs_LAST_CMAKE_INSTALL_PREFIX)
 226     set(__LAST_LIBDIR_DEFAULT "lib")
 227     # __LAST_LIBDIR_DEFAULT is the default value that we compute from
 228     # _GNUInstallDirs_LAST_CMAKE_INSTALL_PREFIX, not a cache entry for
 229     # the value that was last used as the default.
 230     # This value is used to figure out whether the user changed the
 231     # CMAKE_INSTALL_LIBDIR value manually, or if the value was the
 232     # default one. When CMAKE_INSTALL_PREFIX changes, the value is
 233     # updated to the new default, unless the user explicitly changed it.
 234   endif()
 235   if (NOT DEFINED CMAKE_SYSTEM_NAME OR NOT DEFINED CMAKE_SIZEOF_VOID_P)
 236     message(AUTHOR_WARNING
 237       "Unable to determine default CMAKE_INSTALL_LIBDIR directory because no target architecture is known. "
 238       "Please enable at least one language before including GNUInstallDirs.")
 239   endif()
 240   if(CMAKE_SYSTEM_NAME MATCHES "^(Linux|kFreeBSD|GNU)$"
 241       AND NOT CMAKE_CROSSCOMPILING
 242       AND NOT EXISTS "/etc/alpine-release"
 243       AND NOT EXISTS "/etc/arch-release")
 244     if (EXISTS "/etc/debian_version") # is this a debian system ?
 245       if(CMAKE_LIBRARY_ARCHITECTURE)
 246         if("${CMAKE_INSTALL_PREFIX}" MATCHES "^/usr/?$")
 247           set(_LIBDIR_DEFAULT "lib/${CMAKE_LIBRARY_ARCHITECTURE}")
 248         endif()
 249         if(DEFINED _GNUInstallDirs_LAST_CMAKE_INSTALL_PREFIX
 250             AND "${_GNUInstallDirs_LAST_CMAKE_INSTALL_PREFIX}" MATCHES "^/usr/?$")
 251           set(__LAST_LIBDIR_DEFAULT "lib/${CMAKE_LIBRARY_ARCHITECTURE}")
 252         endif()
 253       endif()
 254     else() # not debian, rely on CMAKE_SIZEOF_VOID_P:
 255       if("${CMAKE_SIZEOF_VOID_P}" EQUAL "8")
 256         set(_LIBDIR_DEFAULT "lib64")
 257         if(DEFINED _GNUInstallDirs_LAST_CMAKE_INSTALL_PREFIX)
 258           set(__LAST_LIBDIR_DEFAULT "lib64")
 259         endif()
 260       endif()
 261     endif()
 262   endif()
 263   if(NOT DEFINED CMAKE_INSTALL_LIBDIR)
 264     set(CMAKE_INSTALL_LIBDIR "${_LIBDIR_DEFAULT}" CACHE PATH "Object code libraries (${_LIBDIR_DEFAULT})")
 265   elseif(DEFINED __LAST_LIBDIR_DEFAULT
 266       AND "${__LAST_LIBDIR_DEFAULT}" STREQUAL "${CMAKE_INSTALL_LIBDIR}")
 267     set_property(CACHE CMAKE_INSTALL_LIBDIR PROPERTY VALUE "${_LIBDIR_DEFAULT}")
 268   endif()
 269 endif()
 270 _GNUInstallDirs_cache_convert_to_path(CMAKE_INSTALL_LIBDIR "Object code libraries (lib)")
 271
 272 # Save for next run
 273 set(_GNUInstallDirs_LAST_CMAKE_INSTALL_PREFIX "${CMAKE_INSTALL_PREFIX}" CACHE INTERNAL "CMAKE_INSTALL_PREFIX during last run")
 274 unset(_libdir_set)
 275 unset(__LAST_LIBDIR_DEFAULT)
 276
 277 if(CMAKE_SYSTEM_NAME MATCHES "^(Linux|kFreeBSD|GNU)$"
 278     AND NOT CMAKE_CROSSCOMPILING
 279     AND NOT EXISTS "/etc/arch-release"
 280     AND EXISTS "/etc/debian_version" # is this a debian system ?
 281     AND "${CMAKE_INSTALL_PREFIX}" MATCHES "^/usr/?$")
 282   # see https://refspecs.linuxfoundation.org/FHS_3.0/fhs-3.0.html#usrlibexec
 283   # and https://www.debian.org/doc/debian-policy/ch-opersys#file-system-structure (section 9.1.1 bullet point 4)
 284   _GNUInstallDirs_cache_path(CMAKE_INSTALL_LIBEXECDIR "${CMAKE_INSTALL_LIBDIR}"
 285     "Program executables (${CMAKE_INSTALL_LIBDIR})")
 286 else()
 287   _GNUInstallDirs_cache_path(CMAKE_INSTALL_LIBEXECDIR "libexec"
 288     "Program executables (libexec)")
 289 endif()
 290 _GNUInstallDirs_cache_path(CMAKE_INSTALL_INCLUDEDIR "include"
 291   "C header files (include)")
 292 _GNUInstallDirs_cache_path(CMAKE_INSTALL_OLDINCLUDEDIR "/usr/include"
 293   "C header files for non-gcc (/usr/include)")
 294 _GNUInstallDirs_cache_path(CMAKE_INSTALL_DATAROOTDIR "share"
 295   "Read-only architecture-independent data root (share)")
 296
 297 #-----------------------------------------------------------------------------
 298 # Values whose defaults are relative to DATAROOTDIR.  Store empty values in
 299 # the cache and store the defaults in local variables if the cache values are
 300 # not set explicitly.  This auto-updates the defaults as DATAROOTDIR changes.
 301
 302 _GNUInstallDirs_cache_path_fallback(CMAKE_INSTALL_DATADIR "${CMAKE_INSTALL_DATAROOTDIR}"
 303   "Read-only architecture-independent data (DATAROOTDIR)")
 304
 305 if(CMAKE_SYSTEM_NAME MATCHES "^(([^kF].*)?BSD|DragonFly)$")
 306   _GNUInstallDirs_cache_path_fallback(CMAKE_INSTALL_INFODIR "info"
 307     "Info documentation (info)")
 308 else()
 309   _GNUInstallDirs_cache_path_fallback(CMAKE_INSTALL_INFODIR "${CMAKE_INSTALL_DATAROOTDIR}/info"
 310     "Info documentation (DATAROOTDIR/info)")
 311 endif()
 312
 313 if(CMAKE_SYSTEM_NAME MATCHES "^(([^k].*)?BSD|DragonFly)$")
 314   _GNUInstallDirs_cache_path_fallback(CMAKE_INSTALL_MANDIR "man"
 315     "Man documentation (man)")
 316 else()
 317   _GNUInstallDirs_cache_path_fallback(CMAKE_INSTALL_MANDIR "${CMAKE_INSTALL_DATAROOTDIR}/man"
 318     "Man documentation (DATAROOTDIR/man)")
 319 endif()
 320
 321 _GNUInstallDirs_cache_path_fallback(CMAKE_INSTALL_LOCALEDIR "${CMAKE_INSTALL_DATAROOTDIR}/locale"
 322   "Locale-dependent data (DATAROOTDIR/locale)")
 323 _GNUInstallDirs_cache_path_fallback(CMAKE_INSTALL_DOCDIR "${CMAKE_INSTALL_DATAROOTDIR}/doc/${PROJECT_NAME}"
 324   "Documentation root (DATAROOTDIR/doc/PROJECT_NAME)")
 325
 326 _GNUInstallDirs_cache_path_fallback(CMAKE_INSTALL_RUNSTATEDIR "${CMAKE_INSTALL_LOCALSTATEDIR}/run"
 327   "Run-time variable data (LOCALSTATEDIR/run)")
 328
 329 #-----------------------------------------------------------------------------
 330
 331 mark_as_advanced(
 332   CMAKE_INSTALL_BINDIR
 333   CMAKE_INSTALL_SBINDIR
 334   CMAKE_INSTALL_LIBEXECDIR
 335   CMAKE_INSTALL_SYSCONFDIR
 336   CMAKE_INSTALL_SHAREDSTATEDIR
 337   CMAKE_INSTALL_LOCALSTATEDIR
 338   CMAKE_INSTALL_RUNSTATEDIR
 339   CMAKE_INSTALL_LIBDIR
 340   CMAKE_INSTALL_INCLUDEDIR
 341   CMAKE_INSTALL_OLDINCLUDEDIR
 342   CMAKE_INSTALL_DATAROOTDIR
 343   CMAKE_INSTALL_DATADIR
 344   CMAKE_INSTALL_INFODIR
 345   CMAKE_INSTALL_LOCALEDIR
 346   CMAKE_INSTALL_MANDIR
 347   CMAKE_INSTALL_DOCDIR
 348   )
 349
 350 macro(GNUInstallDirs_get_absolute_install_dir absvar var)
 351   set(GGAID_extra_args ${ARGN})
 352   list(LENGTH GGAID_extra_args GGAID_extra_arg_count)
 353   if(GGAID_extra_arg_count GREATER "0")
 354     list(GET GGAID_extra_args 0 GGAID_dir)
 355   else()
 356     # Historical behavior: use ${dir} from caller's scope
 357     set(GGAID_dir "${dir}")
 358     message(AUTHOR_WARNING
 359       "GNUInstallDirs_get_absolute_install_dir called without third argument. "
 360       "Using \${dir} from the caller's scope for compatibility with CMake 3.19 and below.")
 361   endif()
 362
 363   if(NOT IS_ABSOLUTE "${${var}}")
 364     # Handle special cases:
 365     # - CMAKE_INSTALL_PREFIX == /
 366     # - CMAKE_INSTALL_PREFIX == /usr
 367     # - CMAKE_INSTALL_PREFIX == /opt/...
 368     if("${CMAKE_INSTALL_PREFIX}" STREQUAL "/")
 369       if("${GGAID_dir}" STREQUAL "SYSCONFDIR" OR "${GGAID_dir}" STREQUAL "LOCALSTATEDIR" OR "${GGAID_dir}" STREQUAL "RUNSTATEDIR")
 370         set(${absvar} "/${${var}}")
 371       else()
 372         if (NOT "${${var}}" MATCHES "^usr/")
 373           set(${var} "usr/${${var}}")
 374         endif()
 375         set(${absvar} "/${${var}}")
 376       endif()
 377     elseif("${CMAKE_INSTALL_PREFIX}" MATCHES "^/usr/?$")
 378       if("${GGAID_dir}" STREQUAL "SYSCONFDIR" OR "${GGAID_dir}" STREQUAL "LOCALSTATEDIR" OR "${GGAID_dir}" STREQUAL "RUNSTATEDIR")
 379         set(${absvar} "/${${var}}")
 380       else()
 381         set(${absvar} "${CMAKE_INSTALL_PREFIX}/${${var}}")
 382       endif()
 383     elseif("${CMAKE_INSTALL_PREFIX}" MATCHES "^/opt/.*")
 384       if("${GGAID_dir}" STREQUAL "SYSCONFDIR" OR "${GGAID_dir}" STREQUAL "LOCALSTATEDIR" OR "${GGAID_dir}" STREQUAL "RUNSTATEDIR")
 385         set(${absvar} "/${${var}}${CMAKE_INSTALL_PREFIX}")
 386       else()
 387         set(${absvar} "${CMAKE_INSTALL_PREFIX}/${${var}}")
 388       endif()
 389     else()
 390       set(${absvar} "${CMAKE_INSTALL_PREFIX}/${${var}}")
 391     endif()
 392   else()
 393     set(${absvar} "${${var}}")
 394   endif()
 395
 396   unset(GGAID_dir)
 397   unset(GGAID_extra_arg_count)
 398   unset(GGAID_extra_args)
 399 endmacro()
 400
 401 # Result directories
 402 #
 403 foreach(dir
 404     BINDIR
 405     SBINDIR
 406     LIBEXECDIR
 407     SYSCONFDIR
 408     SHAREDSTATEDIR
 409     LOCALSTATEDIR
 410     RUNSTATEDIR
 411     LIBDIR
 412     INCLUDEDIR
 413     OLDINCLUDEDIR
 414     DATAROOTDIR
 415     DATADIR
 416     INFODIR
 417     LOCALEDIR
 418     MANDIR
 419     DOCDIR
 420     )
 421   GNUInstallDirs_get_absolute_install_dir(CMAKE_INSTALL_FULL_${dir} CMAKE_INSTALL_${dir} ${dir})
 422 endforeach()
 423
 424 cmake_policy(POP)