1 # Distributed under the OSI-approved BSD 3-Clause License. See accompanying
2 # file Copyright.txt or https://cmake.org/licensing for details.
4 #[=======================================================================[.rst:
8 Define GNU standard installation directories
10 Provides install directory variables as defined by the
11 `GNU Coding Standards`_.
13 .. _`GNU Coding Standards`: https://www.gnu.org/prep/standards/html_node/Directory-Variables.html
18 Inclusion of this module defines the following variables:
20 ``CMAKE_INSTALL_<dir>``
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 be a path relative to the installation
25 prefix so that it can be converted to an absolute path in a relocatable way.
27 While absolute paths are allowed, they are not recommended as they
28 do not work with the ``cmake --install`` command's
29 :option:`--prefix <cmake--install --prefix>` option, or with the
30 :manual:`cpack <cpack(1)>` installer generators. In particular, there is no
31 need to make paths absolute by prepending :variable:`CMAKE_INSTALL_PREFIX`;
32 this prefix is used by default if the DESTINATION is a relative path.
34 ``CMAKE_INSTALL_FULL_<dir>``
36 The absolute path generated from the corresponding ``CMAKE_INSTALL_<dir>``
37 value. If the value is not already an absolute path, an absolute path
38 is constructed typically by prepending the value of the
39 :variable:`CMAKE_INSTALL_PREFIX` variable. However, there are some
40 `special cases`_ as documented below.
42 These variables shouldn't be used in :command:`install` commands
43 as they do not work with the ``cmake --install`` command's
44 :option:`--prefix <cmake--install --prefix>` option, or with the
45 :manual:`cpack <cpack(1)>` installer generators.
47 where ``<dir>`` is one of:
50 user executables (``bin``)
52 system admin executables (``sbin``)
54 program executables (``libexec``)
56 read-only single-machine data (``etc``)
58 modifiable architecture-independent data (``com``)
60 modifiable single-machine data (``var``)
63 run-time variable data (``LOCALSTATEDIR/run``)
65 object code libraries (``lib`` or ``lib64``)
67 On Debian, this may be ``lib/<multiarch-tuple>`` when
68 :variable:`CMAKE_INSTALL_PREFIX` is ``/usr``.
70 C header files (``include``)
72 C header files for non-gcc (``/usr/include``)
74 read-only architecture-independent data root (``share``)
76 read-only architecture-independent data (``DATAROOTDIR``)
78 info documentation (``DATAROOTDIR/info``)
80 locale-dependent data (``DATAROOTDIR/locale``)
82 man documentation (``DATAROOTDIR/man``)
84 documentation root (``DATAROOTDIR/doc/PROJECT_NAME``)
86 If the includer does not define a value the above-shown default will be
87 used and the value will appear in the cache for editing by the user.
94 The following values of :variable:`CMAKE_INSTALL_PREFIX` are special:
98 For ``<dir>`` other than the ``SYSCONFDIR``, ``LOCALSTATEDIR`` and
99 ``RUNSTATEDIR``, the value of ``CMAKE_INSTALL_<dir>`` is prefixed
100 with ``usr/`` if it is not user-specified as an absolute path.
101 For example, the ``INCLUDEDIR`` value ``include`` becomes ``usr/include``.
102 This is required by the `GNU Coding Standards`_, which state:
104 When building the complete GNU system, the prefix will be empty
105 and ``/usr`` will be a symbolic link to ``/``.
109 For ``<dir>`` equal to ``SYSCONFDIR``, ``LOCALSTATEDIR`` or
110 ``RUNSTATEDIR``, the ``CMAKE_INSTALL_FULL_<dir>`` is computed by
111 prepending just ``/`` to the value of ``CMAKE_INSTALL_<dir>``
112 if it is not user-specified as an absolute path.
113 For example, the ``SYSCONFDIR`` value ``etc`` becomes ``/etc``.
114 This is required by the `GNU Coding Standards`_.
118 For ``<dir>`` equal to ``SYSCONFDIR``, ``LOCALSTATEDIR`` or
119 ``RUNSTATEDIR``, the ``CMAKE_INSTALL_FULL_<dir>`` is computed by
120 *appending* the prefix to the value of ``CMAKE_INSTALL_<dir>``
121 if it is not user-specified as an absolute path.
122 For example, the ``SYSCONFDIR`` value ``etc`` becomes ``/etc/opt/...``.
123 This is defined by the `Filesystem Hierarchy Standard`_.
125 This behavior does not apply to paths under ``/opt/homebrew/...``.
127 .. _`Filesystem Hierarchy Standard`: https://refspecs.linuxfoundation.org/FHS_3.0/fhs/index.html
132 .. command:: GNUInstallDirs_get_absolute_install_dir
136 GNUInstallDirs_get_absolute_install_dir(absvar var dirname)
138 .. versionadded:: 3.7
140 Set the given variable ``absvar`` to the absolute path contained
141 within the variable ``var``. This is to allow the computation of an
142 absolute path, accounting for all the special cases documented
143 above. While this macro is used to compute the various
144 ``CMAKE_INSTALL_FULL_<dir>`` variables, it is exposed publicly to
145 allow users who create additional path variables to also compute
146 absolute paths where necessary, using the same logic. ``dirname`` is
147 the directory name to get, e.g. ``BINDIR``.
149 .. versionchanged:: 3.20
150 Added the ``<dirname>`` parameter. Previous versions of CMake passed
151 this value through the variable ``${dir}``.
152 #]=======================================================================]
155 cmake_policy(SET CMP0054 NEW) # if() quoted variables not dereferenced
157 # Convert a cache variable to PATH type
159 macro(_GNUInstallDirs_cache_convert_to_path var description)
160 get_property(_GNUInstallDirs_cache_type CACHE ${var} PROPERTY TYPE)
161 if(_GNUInstallDirs_cache_type STREQUAL "UNINITIALIZED")
162 file(TO_CMAKE_PATH "${${var}}" _GNUInstallDirs_cmakepath)
163 set_property(CACHE ${var} PROPERTY TYPE PATH)
164 set_property(CACHE ${var} PROPERTY VALUE "${_GNUInstallDirs_cmakepath}")
165 set_property(CACHE ${var} PROPERTY HELPSTRING "${description}")
166 unset(_GNUInstallDirs_cmakepath)
168 unset(_GNUInstallDirs_cache_type)
171 # Create a cache variable with default for a path.
172 macro(_GNUInstallDirs_cache_path var default description)
173 if(NOT DEFINED ${var})
174 set(${var} "${default}" CACHE PATH "${description}")
176 _GNUInstallDirs_cache_convert_to_path("${var}" "${description}")
179 # Create a cache variable with not default for a path, with a fallback
180 # when unset; used for entries slaved to other entries such as
182 macro(_GNUInstallDirs_cache_path_fallback var default description)
184 set(${var} "" CACHE PATH "${description}")
185 set(${var} "${default}")
187 _GNUInstallDirs_cache_convert_to_path("${var}" "${description}")
190 # Installation directories
193 _GNUInstallDirs_cache_path(CMAKE_INSTALL_BINDIR "bin"
194 "User executables (bin)")
195 _GNUInstallDirs_cache_path(CMAKE_INSTALL_SBINDIR "sbin"
196 "System admin executables (sbin)")
197 _GNUInstallDirs_cache_path(CMAKE_INSTALL_LIBEXECDIR "libexec"
198 "Program executables (libexec)")
199 _GNUInstallDirs_cache_path(CMAKE_INSTALL_SYSCONFDIR "etc"
200 "Read-only single-machine data (etc)")
201 _GNUInstallDirs_cache_path(CMAKE_INSTALL_SHAREDSTATEDIR "com"
202 "Modifiable architecture-independent data (com)")
203 _GNUInstallDirs_cache_path(CMAKE_INSTALL_LOCALSTATEDIR "var"
204 "Modifiable single-machine data (var)")
206 # We check if the variable was manually set and not cached, in order to
207 # allow projects to set the values as normal variables before including
208 # GNUInstallDirs to avoid having the entries cached or user-editable. It
209 # replaces the "if(NOT DEFINED CMAKE_INSTALL_XXX)" checks in all the
211 # If CMAKE_INSTALL_LIBDIR is defined, if _libdir_set is false, then the
212 # variable is a normal one, otherwise it is a cache one.
213 get_property(_libdir_set CACHE CMAKE_INSTALL_LIBDIR PROPERTY TYPE SET)
214 if(NOT DEFINED CMAKE_INSTALL_LIBDIR OR (_libdir_set
215 AND DEFINED _GNUInstallDirs_LAST_CMAKE_INSTALL_PREFIX
216 AND NOT "${_GNUInstallDirs_LAST_CMAKE_INSTALL_PREFIX}" STREQUAL "${CMAKE_INSTALL_PREFIX}"))
217 # If CMAKE_INSTALL_LIBDIR is not defined, it is always executed.
219 # * if _libdir_set is false it is not executed (meaning that it is
220 # not a cache variable)
221 # * if _GNUInstallDirs_LAST_CMAKE_INSTALL_PREFIX is not defined it is
223 # * if _GNUInstallDirs_LAST_CMAKE_INSTALL_PREFIX and
224 # CMAKE_INSTALL_PREFIX are the same string it is not executed.
225 # _GNUInstallDirs_LAST_CMAKE_INSTALL_PREFIX is updated after the
226 # execution, of this part of code, therefore at the next inclusion
227 # of the file, CMAKE_INSTALL_LIBDIR is defined, and the 2 strings
228 # are equal, meaning that the if is not executed the code the
231 set(_LIBDIR_DEFAULT "lib")
232 # Override this default 'lib' with 'lib64' iff:
233 # - we are on Linux system but NOT cross-compiling
234 # - we are NOT on debian
235 # - we are NOT building for conda
236 # - we are on a 64 bits system
237 # reason is: amd64 ABI: https://github.com/hjl-tools/x86-psABI/wiki/X86-psABI
238 # For Debian with multiarch, use 'lib/${CMAKE_LIBRARY_ARCHITECTURE}' if
239 # CMAKE_LIBRARY_ARCHITECTURE is set (which contains e.g. "i386-linux-gnu"
240 # and CMAKE_INSTALL_PREFIX is "/usr"
241 # See http://wiki.debian.org/Multiarch
242 if(DEFINED _GNUInstallDirs_LAST_CMAKE_INSTALL_PREFIX)
243 set(__LAST_LIBDIR_DEFAULT "lib")
244 # __LAST_LIBDIR_DEFAULT is the default value that we compute from
245 # _GNUInstallDirs_LAST_CMAKE_INSTALL_PREFIX, not a cache entry for
246 # the value that was last used as the default.
247 # This value is used to figure out whether the user changed the
248 # CMAKE_INSTALL_LIBDIR value manually, or if the value was the
249 # default one. When CMAKE_INSTALL_PREFIX changes, the value is
250 # updated to the new default, unless the user explicitly changed it.
252 if (NOT DEFINED CMAKE_SYSTEM_NAME OR NOT DEFINED CMAKE_SIZEOF_VOID_P)
253 message(AUTHOR_WARNING
254 "Unable to determine default CMAKE_INSTALL_LIBDIR directory because no target architecture is known. "
255 "Please enable at least one language before including GNUInstallDirs.")
258 if(CMAKE_SYSTEM_NAME MATCHES "^(Linux|kFreeBSD|GNU)$"
259 AND NOT CMAKE_CROSSCOMPILING)
260 unset(__system_type_for_install)
261 if(DEFINED ENV{CONDA_BUILD} AND DEFINED ENV{PREFIX})
262 set(conda_prefix "$ENV{PREFIX}")
263 cmake_path(ABSOLUTE_PATH conda_prefix NORMALIZE)
264 if("${CMAKE_INSTALL_PREFIX}" STREQUAL conda_prefix)
265 set(__system_type_for_install "conda")
267 elseif(DEFINED ENV{CONDA_PREFIX})
268 set(conda_prefix "$ENV{CONDA_PREFIX}")
269 cmake_path(ABSOLUTE_PATH conda_prefix NORMALIZE)
270 if("${CMAKE_INSTALL_PREFIX}" STREQUAL conda_prefix AND
271 NOT ("${CMAKE_INSTALL_PREFIX}" MATCHES "^/usr/?$" OR
272 "${CMAKE_INSTALL_PREFIX}" MATCHES "^/usr/local/?$"))
273 set(__system_type_for_install "conda")
276 if(NOT __system_type_for_install)
277 if (EXISTS "/etc/alpine-release")
278 set(__system_type_for_install "alpine")
279 elseif (EXISTS "/etc/arch-release")
280 set(__system_type_for_install "arch linux")
281 elseif (EXISTS "/etc/debian_version")
282 set(__system_type_for_install "debian")
286 if(__system_type_for_install STREQUAL "debian")
287 if(CMAKE_LIBRARY_ARCHITECTURE)
288 if("${CMAKE_INSTALL_PREFIX}" MATCHES "^/usr/?$")
289 set(_LIBDIR_DEFAULT "lib/${CMAKE_LIBRARY_ARCHITECTURE}")
291 if(DEFINED _GNUInstallDirs_LAST_CMAKE_INSTALL_PREFIX
292 AND "${_GNUInstallDirs_LAST_CMAKE_INSTALL_PREFIX}" MATCHES "^/usr/?$")
293 set(__LAST_LIBDIR_DEFAULT "lib/${CMAKE_LIBRARY_ARCHITECTURE}")
296 elseif(NOT DEFINED __system_type_for_install)
297 # not debian, alpine, arch, or conda so rely on CMAKE_SIZEOF_VOID_P:
298 if("${CMAKE_SIZEOF_VOID_P}" EQUAL "8")
299 set(_LIBDIR_DEFAULT "lib64")
300 if(DEFINED _GNUInstallDirs_LAST_CMAKE_INSTALL_PREFIX)
301 set(__LAST_LIBDIR_DEFAULT "lib64")
306 unset(__system_type_for_install)
308 if(NOT DEFINED CMAKE_INSTALL_LIBDIR)
309 set(CMAKE_INSTALL_LIBDIR "${_LIBDIR_DEFAULT}" CACHE PATH "Object code libraries (${_LIBDIR_DEFAULT})")
310 elseif(DEFINED __LAST_LIBDIR_DEFAULT
311 AND "${__LAST_LIBDIR_DEFAULT}" STREQUAL "${CMAKE_INSTALL_LIBDIR}")
312 set_property(CACHE CMAKE_INSTALL_LIBDIR PROPERTY VALUE "${_LIBDIR_DEFAULT}")
315 _GNUInstallDirs_cache_convert_to_path(CMAKE_INSTALL_LIBDIR "Object code libraries (lib)")
318 set(_GNUInstallDirs_LAST_CMAKE_INSTALL_PREFIX "${CMAKE_INSTALL_PREFIX}" CACHE INTERNAL "CMAKE_INSTALL_PREFIX during last run")
320 unset(__LAST_LIBDIR_DEFAULT)
322 _GNUInstallDirs_cache_path(CMAKE_INSTALL_INCLUDEDIR "include"
323 "C header files (include)")
324 _GNUInstallDirs_cache_path(CMAKE_INSTALL_OLDINCLUDEDIR "/usr/include"
325 "C header files for non-gcc (/usr/include)")
326 _GNUInstallDirs_cache_path(CMAKE_INSTALL_DATAROOTDIR "share"
327 "Read-only architecture-independent data root (share)")
329 #-----------------------------------------------------------------------------
330 # Values whose defaults are relative to DATAROOTDIR. Store empty values in
331 # the cache and store the defaults in local variables if the cache values are
332 # not set explicitly. This auto-updates the defaults as DATAROOTDIR changes.
334 _GNUInstallDirs_cache_path_fallback(CMAKE_INSTALL_DATADIR "${CMAKE_INSTALL_DATAROOTDIR}"
335 "Read-only architecture-independent data (DATAROOTDIR)")
337 if(CMAKE_SYSTEM_NAME MATCHES "^(([^kF].*)?BSD|DragonFly)$")
338 _GNUInstallDirs_cache_path_fallback(CMAKE_INSTALL_INFODIR "info"
339 "Info documentation (info)")
341 _GNUInstallDirs_cache_path_fallback(CMAKE_INSTALL_INFODIR "${CMAKE_INSTALL_DATAROOTDIR}/info"
342 "Info documentation (DATAROOTDIR/info)")
345 if(CMAKE_SYSTEM_NAME MATCHES "^(([^k].*)?BSD|DragonFly)$" AND NOT CMAKE_SYSTEM_NAME MATCHES "^(FreeBSD)$")
346 _GNUInstallDirs_cache_path_fallback(CMAKE_INSTALL_MANDIR "man"
347 "Man documentation (man)")
349 _GNUInstallDirs_cache_path_fallback(CMAKE_INSTALL_MANDIR "${CMAKE_INSTALL_DATAROOTDIR}/man"
350 "Man documentation (DATAROOTDIR/man)")
353 _GNUInstallDirs_cache_path_fallback(CMAKE_INSTALL_LOCALEDIR "${CMAKE_INSTALL_DATAROOTDIR}/locale"
354 "Locale-dependent data (DATAROOTDIR/locale)")
355 _GNUInstallDirs_cache_path_fallback(CMAKE_INSTALL_DOCDIR "${CMAKE_INSTALL_DATAROOTDIR}/doc/${PROJECT_NAME}"
356 "Documentation root (DATAROOTDIR/doc/PROJECT_NAME)")
358 _GNUInstallDirs_cache_path_fallback(CMAKE_INSTALL_RUNSTATEDIR "${CMAKE_INSTALL_LOCALSTATEDIR}/run"
359 "Run-time variable data (LOCALSTATEDIR/run)")
361 #-----------------------------------------------------------------------------
365 CMAKE_INSTALL_SBINDIR
366 CMAKE_INSTALL_LIBEXECDIR
367 CMAKE_INSTALL_SYSCONFDIR
368 CMAKE_INSTALL_SHAREDSTATEDIR
369 CMAKE_INSTALL_LOCALSTATEDIR
370 CMAKE_INSTALL_RUNSTATEDIR
372 CMAKE_INSTALL_INCLUDEDIR
373 CMAKE_INSTALL_OLDINCLUDEDIR
374 CMAKE_INSTALL_DATAROOTDIR
375 CMAKE_INSTALL_DATADIR
376 CMAKE_INSTALL_INFODIR
377 CMAKE_INSTALL_LOCALEDIR
382 macro(GNUInstallDirs_get_absolute_install_dir absvar var)
383 set(GGAID_extra_args ${ARGN})
384 list(LENGTH GGAID_extra_args GGAID_extra_arg_count)
385 if(GGAID_extra_arg_count GREATER "0")
386 list(GET GGAID_extra_args 0 GGAID_dir)
388 # Historical behavior: use ${dir} from caller's scope
389 set(GGAID_dir "${dir}")
390 message(AUTHOR_WARNING
391 "GNUInstallDirs_get_absolute_install_dir called without third argument. "
392 "Using \${dir} from the caller's scope for compatibility with CMake 3.19 and below.")
395 if(NOT IS_ABSOLUTE "${${var}}")
396 # Handle special cases:
397 # - CMAKE_INSTALL_PREFIX == /
398 # - CMAKE_INSTALL_PREFIX == /usr
399 # - CMAKE_INSTALL_PREFIX == /opt/...
400 if("${CMAKE_INSTALL_PREFIX}" STREQUAL "/")
401 if("${GGAID_dir}" STREQUAL "SYSCONFDIR" OR "${GGAID_dir}" STREQUAL "LOCALSTATEDIR" OR "${GGAID_dir}" STREQUAL "RUNSTATEDIR")
402 set(${absvar} "/${${var}}")
404 if (NOT "${${var}}" MATCHES "^usr/")
405 set(${var} "usr/${${var}}")
407 set(${absvar} "/${${var}}")
409 elseif("${CMAKE_INSTALL_PREFIX}" MATCHES "^/usr/?$")
410 if("${GGAID_dir}" STREQUAL "SYSCONFDIR" OR "${GGAID_dir}" STREQUAL "LOCALSTATEDIR" OR "${GGAID_dir}" STREQUAL "RUNSTATEDIR")
411 set(${absvar} "/${${var}}")
413 set(${absvar} "${CMAKE_INSTALL_PREFIX}/${${var}}")
415 elseif("${CMAKE_INSTALL_PREFIX}" MATCHES "^/opt/" AND NOT "${CMAKE_INSTALL_PREFIX}" MATCHES "^/opt/homebrew/")
416 if("${GGAID_dir}" STREQUAL "SYSCONFDIR" OR "${GGAID_dir}" STREQUAL "LOCALSTATEDIR" OR "${GGAID_dir}" STREQUAL "RUNSTATEDIR")
417 set(${absvar} "/${${var}}${CMAKE_INSTALL_PREFIX}")
419 set(${absvar} "${CMAKE_INSTALL_PREFIX}/${${var}}")
422 set(${absvar} "${CMAKE_INSTALL_PREFIX}/${${var}}")
425 set(${absvar} "${${var}}")
429 unset(GGAID_extra_arg_count)
430 unset(GGAID_extra_args)
453 GNUInstallDirs_get_absolute_install_dir(CMAKE_INSTALL_FULL_${dir} CMAKE_INSTALL_${dir} ${dir})