Merge topic 'cxx-checks-tolerate-unused-arguments'
[kiteware-cmake.git] / Modules / GNUInstallDirs.cmake
blobed34c4a919d2fdab845e7558fed5253626af3068
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:
5 GNUInstallDirs
6 --------------
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
15 Result Variables
16 ^^^^^^^^^^^^^^^^
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:
49 ``BINDIR``
50   user executables (``bin``)
51 ``SBINDIR``
52   system admin executables (``sbin``)
53 ``LIBEXECDIR``
54   program executables (``libexec``)
55 ``SYSCONFDIR``
56   read-only single-machine data (``etc``)
57 ``SHAREDSTATEDIR``
58   modifiable architecture-independent data (``com``)
59 ``LOCALSTATEDIR``
60   modifiable single-machine data (``var``)
61 ``RUNSTATEDIR``
62   .. versionadded:: 3.9
63     run-time variable data (``LOCALSTATEDIR/run``)
64 ``LIBDIR``
65   object code libraries (``lib`` or ``lib64``)
67   On Debian, this may be ``lib/<multiarch-tuple>`` when
68   :variable:`CMAKE_INSTALL_PREFIX` is ``/usr``.
69 ``INCLUDEDIR``
70   C header files (``include``)
71 ``OLDINCLUDEDIR``
72   C header files for non-gcc (``/usr/include``)
73 ``DATAROOTDIR``
74   read-only architecture-independent data root (``share``)
75 ``DATADIR``
76   read-only architecture-independent data (``DATAROOTDIR``)
77 ``INFODIR``
78   info documentation (``DATAROOTDIR/info``)
79 ``LOCALEDIR``
80   locale-dependent data (``DATAROOTDIR/locale``)
81 ``MANDIR``
82   man documentation (``DATAROOTDIR/man``)
83 ``DOCDIR``
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.
89 Special Cases
90 ^^^^^^^^^^^^^
92 .. versionadded:: 3.4
94 The following values of :variable:`CMAKE_INSTALL_PREFIX` are special:
96 ``/``
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 ``/``.
107 ``/usr``
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`_.
116 ``/opt/...``
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
129 Macros
130 ^^^^^^
132 .. command:: GNUInstallDirs_get_absolute_install_dir
134   ::
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 #]=======================================================================]
154 cmake_policy(PUSH)
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)
167   endif()
168   unset(_GNUInstallDirs_cache_type)
169 endmacro()
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}")
175   endif()
176   _GNUInstallDirs_cache_convert_to_path("${var}" "${description}")
177 endmacro()
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
181 # DATAROOTDIR.
182 macro(_GNUInstallDirs_cache_path_fallback var default description)
183   if(NOT ${var})
184     set(${var} "" CACHE PATH "${description}")
185     set(${var} "${default}")
186   endif()
187   _GNUInstallDirs_cache_convert_to_path("${var}" "${description}")
188 endmacro()
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
210 # other cases.
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.
218   # Otherwise:
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
222   #    not executed
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
229   #    second time.
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.
251   endif()
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.")
256   endif()
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")
266       endif()
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")
274       endif()
275     endif()
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")
283       endif()
284     endif()
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}")
290         endif()
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}")
294         endif()
295       endif()
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")
302         endif()
303       endif()
304     endif()
305   endif()
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}")
313   endif()
314 endif()
315 _GNUInstallDirs_cache_convert_to_path(CMAKE_INSTALL_LIBDIR "Object code libraries (lib)")
317 # Save for next run
318 set(_GNUInstallDirs_LAST_CMAKE_INSTALL_PREFIX "${CMAKE_INSTALL_PREFIX}" CACHE INTERNAL "CMAKE_INSTALL_PREFIX during last run")
319 unset(_libdir_set)
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)")
340 else()
341   _GNUInstallDirs_cache_path_fallback(CMAKE_INSTALL_INFODIR "${CMAKE_INSTALL_DATAROOTDIR}/info"
342     "Info documentation (DATAROOTDIR/info)")
343 endif()
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)")
348 else()
349   _GNUInstallDirs_cache_path_fallback(CMAKE_INSTALL_MANDIR "${CMAKE_INSTALL_DATAROOTDIR}/man"
350     "Man documentation (DATAROOTDIR/man)")
351 endif()
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 #-----------------------------------------------------------------------------
363 mark_as_advanced(
364   CMAKE_INSTALL_BINDIR
365   CMAKE_INSTALL_SBINDIR
366   CMAKE_INSTALL_LIBEXECDIR
367   CMAKE_INSTALL_SYSCONFDIR
368   CMAKE_INSTALL_SHAREDSTATEDIR
369   CMAKE_INSTALL_LOCALSTATEDIR
370   CMAKE_INSTALL_RUNSTATEDIR
371   CMAKE_INSTALL_LIBDIR
372   CMAKE_INSTALL_INCLUDEDIR
373   CMAKE_INSTALL_OLDINCLUDEDIR
374   CMAKE_INSTALL_DATAROOTDIR
375   CMAKE_INSTALL_DATADIR
376   CMAKE_INSTALL_INFODIR
377   CMAKE_INSTALL_LOCALEDIR
378   CMAKE_INSTALL_MANDIR
379   CMAKE_INSTALL_DOCDIR
380   )
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)
387   else()
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.")
393   endif()
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}}")
403       else()
404         if (NOT "${${var}}" MATCHES "^usr/")
405           set(${var} "usr/${${var}}")
406         endif()
407         set(${absvar} "/${${var}}")
408       endif()
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}}")
412       else()
413         set(${absvar} "${CMAKE_INSTALL_PREFIX}/${${var}}")
414       endif()
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}")
418       else()
419         set(${absvar} "${CMAKE_INSTALL_PREFIX}/${${var}}")
420       endif()
421     else()
422       set(${absvar} "${CMAKE_INSTALL_PREFIX}/${${var}}")
423     endif()
424   else()
425     set(${absvar} "${${var}}")
426   endif()
428   unset(GGAID_dir)
429   unset(GGAID_extra_arg_count)
430   unset(GGAID_extra_args)
431 endmacro()
433 # Result directories
435 foreach(dir
436     BINDIR
437     SBINDIR
438     LIBEXECDIR
439     SYSCONFDIR
440     SHAREDSTATEDIR
441     LOCALSTATEDIR
442     RUNSTATEDIR
443     LIBDIR
444     INCLUDEDIR
445     OLDINCLUDEDIR
446     DATAROOTDIR
447     DATADIR
448     INFODIR
449     LOCALEDIR
450     MANDIR
451     DOCDIR
452     )
453   GNUInstallDirs_get_absolute_install_dir(CMAKE_INSTALL_FULL_${dir} CMAKE_INSTALL_${dir} ${dir})
454 endforeach()
456 cmake_policy(POP)