GNUInstallDirs: Change special path defaults to absolute

Add policy `CMP0192` for compatibility.

Closes: #25852
Signed-off-by: Cristian Le <git@lecris.dev>

Help/manual/cmake-policies.7.rst

@@ -98,6 +98,7 @@ Policies Introduced by CMake 4.1
 .. toctree::
    :maxdepth: 1
 
+   CMP0192: GNUInstallDirs uses absolute SYSCONFDIR, LOCALSTATEDIR, and RUNSTATEDIR in special prefixes. </policy/CMP0192>
    CMP0191: The FindCABLE module is removed. </policy/CMP0191>
    CMP0190: FindPython enforce consistency in cross-compiling mode. </policy/CMP0190>
    CMP0189: TARGET_PROPERTY evaluates LINK_LIBRARIES properties transitively. </policy/CMP0189>

Help/policy/CMP0192.rst

@@ -0,0 +1,41 @@
+CMP0192
+-------
+
+.. versionadded:: 4.1
+
+:module:`GNUInstallDirs` uses absolute ``SYSCONFDIR``, ``LOCALSTATEDIR``,
+and ``RUNSTATEDIR`` in special prefixes.
+
+The :module:`GNUInstallDirs` module documents
+:ref:`special cases <GNUInstallDirs special cases>`
+for ``SYSCONFDIR``, ``LOCALSTATEDIR``, and ``RUNSTATEDIR``.
+When :variable:`CMAKE_INSTALL_PREFIX` is a special prefix, e.g., ``/usr``,
+the absolute paths for these directories may be outside the prefix, e.g.,
+``/etc``, ``/var``, and ``/var/run``.
+
+In CMake 4.0 and below, the default values for the ``CMAKE_INSTALL_<dir>``
+variables, for ``<dir>`` equal to ``SYSCONFDIR``, ``LOCALSTATEDIR``, and
+``RUNSTATEDIR``, always used relative paths (``etc``, ``var``, ``var/run``),
+and the special cases were implemented only when computing absolute paths
+for the ``CMAKE_INSTALL_FULL_<dir>`` variables.
+CMake 4.1 and above prefer to default ``CMAKE_INSTALL_<dir>`` variables to
+absolute paths, for ``<dir>`` equal to ``SYSCONFDIR``, ``LOCALSTATEDIR``,
+and ``RUNSTATEDIR``, when :variable:`CMAKE_INSTALL_PREFIX` is a special
+prefix.  This policy provides compatibility for projects that have not
+been updated to expect this behavior.
+
+The ``OLD`` behavior for this policy is to default ``CMAKE_INSTALL_<dir>``
+variables to relative paths.  The ``NEW`` behavior for this policy is to
+default ``CMAKE_INSTALL_<dir>`` variables to absolute paths, for ``<dir>``
+equal to ``SYSCONFDIR``, ``LOCALSTATEDIR``, and ``RUNSTATEDIR``, when
+:variable:`CMAKE_INSTALL_PREFIX` is a special prefix.
+
+This policy takes effect at the first call of ``include(GNUInstallDirs)``.
+Subsequent calls of ``include(GNUInstallDirs)`` reuse cached
+``CMAKE_INSTALL_<dir>`` values from the first call.
+
+.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 4.1
+.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
+.. include:: STANDARD_ADVICE.txt
+
+.. include:: DEPRECATED.txt

Help/release/dev/GNUInstallDirs-special-cases.rst

@@ -0,0 +1,7 @@
+GNUInstallDirs-special-cases
+----------------------------
+
+* The :module:`GNUInstallDirs` module now prefers to default
+  ``SYSCONFDIR``, ``LOCALSTATEDIR``, and ``RUNSTATEDIR`` to
+  absolute paths when installing to special prefixes.
+  See policy :policy:`CMP0192`.

Modules/GNUInstallDirs.cmake

@@ -23,6 +23,7 @@ Inclusion of this module defines the following variables:
   the ``DESTINATION`` options of  :command:`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
@@ -36,8 +37,8 @@ Inclusion of this module defines the following variables:
   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
-  :variable:`CMAKE_INSTALL_PREFIX` variable.  However, there are some
-  `special cases`_ as documented below.
+  :variable:`CMAKE_INSTALL_PREFIX` variable, except in `special cases`_
+  as documented below.
 
   These variables shouldn't be used in :command:`install` commands
   as they do not work with the ``cmake --install`` command's
@@ -54,13 +55,29 @@ where ``<dir>`` is one of:
   program executables (``libexec``)
 ``SYSCONFDIR``
   read-only single-machine data (``etc``)
+
+  .. versionchanged:: 4.1
+    If the :variable:`CMAKE_INSTALL_PREFIX` falls into the
+    `special cases`_,  the default paths for are the absolute
+    path variants as described there. See policy :policy:`CMP0192`.
 ``SHAREDSTATEDIR``
   modifiable architecture-independent data (``com``)
 ``LOCALSTATEDIR``
   modifiable single-machine data (``var``)
+
+  .. versionchanged:: 4.1
+    If the :variable:`CMAKE_INSTALL_PREFIX` falls into the
+    `special cases`_,  the default paths for are the absolute
+    path variants as described there. See policy :policy:`CMP0192`.
 ``RUNSTATEDIR``
+  run-time variable data (``LOCALSTATEDIR/run``)
+
   .. versionadded:: 3.9
-    run-time variable data (``LOCALSTATEDIR/run``)
+
+  .. versionchanged:: 4.1
+    If the :variable:`CMAKE_INSTALL_PREFIX` falls into the
+    `special cases`_,  the default paths for are the absolute
+    path variants as described there. See policy :policy:`CMP0192`.
 ``LIBDIR``
   object code libraries (``lib`` or ``lib64``)
 
@@ -86,6 +103,14 @@ where ``<dir>`` is one of:
 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
+:variable:`CMAKE_INSTALL_PREFIX` is changed, the new default value will
+be used calculated on the new :variable:`CMAKE_INSTALL_PREFIX` value.
+Using :option:`--prefix <cmake--install --prefix>` in ``cmake --install``
+will not alter these values.
+
+.. _`GNUInstallDirs special cases`:
+
 Special Cases
 ^^^^^^^^^^^^^
 
@@ -109,21 +134,33 @@ The following values of :variable:`CMAKE_INSTALL_PREFIX` are special:
   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 user-specified as an absolute path.
+  if it is not already an absolute path.
   For example, the ``SYSCONFDIR`` value ``etc`` becomes ``/etc``.
   This is required by the `GNU Coding Standards`_.
 
+  .. versionchanged:: 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 :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 user-specified as an absolute path.
+  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/...``.
 
+  .. versionchanged:: 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 :policy:`CMP0192`.
+
 .. _`Filesystem Hierarchy Standard`: https://refspecs.linuxfoundation.org/FHS_3.0/fhs/index.html
 
 Macros
@@ -153,6 +190,11 @@ Macros
 
 cmake_policy(SET CMP0140 NEW)
 
+# Note that even though we read the policy every time this file is `include`
+# only the first occurrence has effect because it is used for the initialization
+# of cache variables
+cmake_policy(GET CMP0192 _GNUInstallDirs_CMP0192)
+
 # Convert a cache variable to PATH type
 
 function(_GNUInstallDirs_cache_convert_to_path var description)
@@ -339,6 +381,38 @@ function(_GNUInstallDirs_LIBDIR_get_default out_var install_prefix)
   return(PROPAGATE ${out_var})
 endfunction()
 
+function(_GNUInstallDirs_SYSCONFDIR_get_default out_var install_prefix)
+  if(_GNUInstallDirs_CMP0192 STREQUAL "NEW")
+    _GNUInstallDirs_special_absolute(${out_var}
+      "${_GNUInstallDirs_SYSCONFDIR_DEFAULT}" "${install_prefix}")
+  endif()
+  cmake_path(NORMAL_PATH ${out_var})
+  return(PROPAGATE ${out_var})
+endfunction()
+function(_GNUInstallDirs_LOCALSTATEDIR_get_default out_var install_prefix)
+  if(_GNUInstallDirs_CMP0192 STREQUAL "NEW")
+    _GNUInstallDirs_special_absolute(${out_var}
+      "${_GNUInstallDirs_LOCALSTATEDIR_DEFAULT}" "${install_prefix}")
+  endif()
+  cmake_path(NORMAL_PATH ${out_var})
+  return(PROPAGATE ${out_var})
+endfunction()
+
+# Depends on current CMAKE_INSTALL_LOCALSTATEDIR value
+function(_GNUInstallDirs_RUNSTATEDIR_get_default out_var install_prefix)
+  set(${out_var} "${_GNUInstallDirs_RUNSTATEDIR_DEFAULT}")
+  if(_GNUInstallDirs_CMP0192 STREQUAL "NEW")
+    # In the /opt/ case we want the install_prefix to be appended as
+    # LOCALSTATEDIR/run/PREFIX
+    if(install_prefix MATCHES "^/opt/" AND NOT install_prefix MATCHES "^/opt/homebrew/")
+        string(REPLACE "${install_prefix}" "/run${install_prefix}"
+          ${out_var} "${CMAKE_INSTALL_LOCALSTATEDIR}"
+        )
+    endif()
+  endif()
+  return(PROPAGATE ${out_var})
+endfunction()
+
 _GNUInstallDirs_cache_path(BINDIR
   "User executables")
 _GNUInstallDirs_cache_path(SBINDIR
@@ -514,3 +588,5 @@ foreach(dir
     )
   GNUInstallDirs_get_absolute_install_dir(CMAKE_INSTALL_FULL_${dir} CMAKE_INSTALL_${dir} ${dir})
 endforeach()
+
+unset(_GNUInstallDirs_CMP0192)

Source/cmPolicies.h

@@ -570,7 +570,11 @@ class cmMakefile;
   SELECT(POLICY, CMP0190,                                                     \
          "FindPython enforce consistency in cross-compiling mode.", 4, 1, 0,  \
          WARN)                                                                \
-  SELECT(POLICY, CMP0191, "The FindCABLE module is removed.", 4, 1, 0, WARN)
+  SELECT(POLICY, CMP0191, "The FindCABLE module is removed.", 4, 1, 0, WARN)  \
+  SELECT(POLICY, CMP0192,                                                     \
+         "GNUInstallDirs uses absolute SYSCONFDIR, LOCALSTATEDIR, and "       \
+         "RUNSTATEDIR in special prefixes.",                                  \
+         4, 1, 0, WARN)
 
 #define CM_SELECT_ID(F, A1, A2, A3, A4, A5, A6) F(A1)
 #define CM_FOR_EACH_POLICY_ID(POLICY)                                         \

Tests/RunCMake/GNUInstallDirs/CMakeLists.txt

@@ -1,3 +1,4 @@
 cmake_minimum_required(VERSION 3.10)
+cmake_policy(SET CMP0192 NEW)
 project(${RunCMake_TEST} NONE)
 include(${RunCMake_TEST}.cmake)

Tests/RunCMake/GNUInstallDirs/GetAbs-stderr.txt

@@ -6,7 +6,7 @@ CMake Warning \(dev\) at [^
   below.
 Call Stack \(most recent call first\):
   GetAbs.cmake:10 \(GNUInstallDirs_get_absolute_install_dir\)
-  CMakeLists.txt:3 \(include\)
+  CMakeLists.txt:4 \(include\)
 This warning is for project developers.  Use -Wno-dev to suppress it.
 +
 PROJ2_FULL_BINDIR='/usr/bin'$

Tests/RunCMake/GNUInstallDirs/Opt-BSD-stderr.txt

@@ -7,12 +7,12 @@ CMAKE_INSTALL_INFODIR='info'
 CMAKE_INSTALL_LIBDIR='(lib|lib64)'
 CMAKE_INSTALL_LIBEXECDIR='libexec'
 CMAKE_INSTALL_LOCALEDIR='share/locale'
-CMAKE_INSTALL_LOCALSTATEDIR='var'
-CMAKE_INSTALL_RUNSTATEDIR='var/run'
+CMAKE_INSTALL_LOCALSTATEDIR='/var/opt/Opt'
+CMAKE_INSTALL_RUNSTATEDIR='/var/run/opt/Opt'
 CMAKE_INSTALL_MANDIR='man'
 CMAKE_INSTALL_SBINDIR='sbin'
 CMAKE_INSTALL_SHAREDSTATEDIR='com'
-CMAKE_INSTALL_SYSCONFDIR='etc'
+CMAKE_INSTALL_SYSCONFDIR='/etc/opt/Opt'
 CMAKE_INSTALL_FULL_BINDIR='/opt/Opt/bin'
 CMAKE_INSTALL_FULL_DATADIR='/opt/Opt/share'
 CMAKE_INSTALL_FULL_DATAROOTDIR='/opt/Opt/share'

Tests/RunCMake/GNUInstallDirs/Opt-Debian-stderr.txt

@@ -7,12 +7,12 @@ CMAKE_INSTALL_INFODIR='share/info'
 CMAKE_INSTALL_LIBDIR='lib'
 CMAKE_INSTALL_LIBEXECDIR='libexec'
 CMAKE_INSTALL_LOCALEDIR='share/locale'
-CMAKE_INSTALL_LOCALSTATEDIR='var'
-CMAKE_INSTALL_RUNSTATEDIR='var/run'
+CMAKE_INSTALL_LOCALSTATEDIR='/var/opt/Opt'
+CMAKE_INSTALL_RUNSTATEDIR='/var/run/opt/Opt'
 CMAKE_INSTALL_MANDIR='share/man'
 CMAKE_INSTALL_SBINDIR='sbin'
 CMAKE_INSTALL_SHAREDSTATEDIR='com'
-CMAKE_INSTALL_SYSCONFDIR='etc'
+CMAKE_INSTALL_SYSCONFDIR='/etc/opt/Opt'
 CMAKE_INSTALL_FULL_BINDIR='/opt/Opt/bin'
 CMAKE_INSTALL_FULL_DATADIR='/opt/Opt/share'
 CMAKE_INSTALL_FULL_DATAROOTDIR='/opt/Opt/share'

Tests/RunCMake/GNUInstallDirs/Opt-FreeBSD-stderr.txt

@@ -7,12 +7,12 @@ CMAKE_INSTALL_INFODIR='share/info'
 CMAKE_INSTALL_LIBDIR='(lib|lib64)'
 CMAKE_INSTALL_LIBEXECDIR='libexec'
 CMAKE_INSTALL_LOCALEDIR='share/locale'
-CMAKE_INSTALL_LOCALSTATEDIR='var'
-CMAKE_INSTALL_RUNSTATEDIR='var/run'
+CMAKE_INSTALL_LOCALSTATEDIR='/var/opt/Opt'
+CMAKE_INSTALL_RUNSTATEDIR='/var/run/opt/Opt'
 CMAKE_INSTALL_MANDIR='share/man'
 CMAKE_INSTALL_SBINDIR='sbin'
 CMAKE_INSTALL_SHAREDSTATEDIR='com'
-CMAKE_INSTALL_SYSCONFDIR='etc'
+CMAKE_INSTALL_SYSCONFDIR='/etc/opt/Opt'
 CMAKE_INSTALL_FULL_BINDIR='/opt/Opt/bin'
 CMAKE_INSTALL_FULL_DATADIR='/opt/Opt/share'
 CMAKE_INSTALL_FULL_DATAROOTDIR='/opt/Opt/share'

Tests/RunCMake/GNUInstallDirs/Opt-stderr.txt

@@ -7,12 +7,12 @@ CMAKE_INSTALL_INFODIR='share/info'
 CMAKE_INSTALL_LIBDIR='(lib|lib64)'
 CMAKE_INSTALL_LIBEXECDIR='libexec'
 CMAKE_INSTALL_LOCALEDIR='share/locale'
-CMAKE_INSTALL_LOCALSTATEDIR='var'
-CMAKE_INSTALL_RUNSTATEDIR='var/run'
+CMAKE_INSTALL_LOCALSTATEDIR='/var/opt/Opt'
+CMAKE_INSTALL_RUNSTATEDIR='/var/run/opt/Opt'
 CMAKE_INSTALL_MANDIR='share/man'
 CMAKE_INSTALL_SBINDIR='sbin'
 CMAKE_INSTALL_SHAREDSTATEDIR='com'
-CMAKE_INSTALL_SYSCONFDIR='etc'
+CMAKE_INSTALL_SYSCONFDIR='/etc/opt/Opt'
 CMAKE_INSTALL_FULL_BINDIR='/opt/Opt/bin'
 CMAKE_INSTALL_FULL_DATADIR='/opt/Opt/share'
 CMAKE_INSTALL_FULL_DATAROOTDIR='/opt/Opt/share'

Tests/RunCMake/GNUInstallDirs/Usr-BSD-stderr.txt

@@ -7,12 +7,12 @@ CMAKE_INSTALL_INFODIR='info'
 CMAKE_INSTALL_LIBDIR='(lib|lib64|lib/arch)'
 CMAKE_INSTALL_LIBEXECDIR='libexec'
 CMAKE_INSTALL_LOCALEDIR='share/locale'
-CMAKE_INSTALL_LOCALSTATEDIR='var'
-CMAKE_INSTALL_RUNSTATEDIR='var/run'
+CMAKE_INSTALL_LOCALSTATEDIR='/var'
+CMAKE_INSTALL_RUNSTATEDIR='/var/run'
 CMAKE_INSTALL_MANDIR='man'
 CMAKE_INSTALL_SBINDIR='sbin'
 CMAKE_INSTALL_SHAREDSTATEDIR='com'
-CMAKE_INSTALL_SYSCONFDIR='etc'
+CMAKE_INSTALL_SYSCONFDIR='/etc'
 CMAKE_INSTALL_FULL_BINDIR='/usr/bin'
 CMAKE_INSTALL_FULL_DATADIR='/usr/share'
 CMAKE_INSTALL_FULL_DATAROOTDIR='/usr/share'

Tests/RunCMake/GNUInstallDirs/Usr-Debian-stderr.txt

@@ -7,12 +7,12 @@ CMAKE_INSTALL_INFODIR='share/info'
 CMAKE_INSTALL_LIBDIR='lib/arch'
 CMAKE_INSTALL_LIBEXECDIR='libexec'
 CMAKE_INSTALL_LOCALEDIR='share/locale'
-CMAKE_INSTALL_LOCALSTATEDIR='var'
-CMAKE_INSTALL_RUNSTATEDIR='var/run'
+CMAKE_INSTALL_LOCALSTATEDIR='/var'
+CMAKE_INSTALL_RUNSTATEDIR='/var/run'
 CMAKE_INSTALL_MANDIR='share/man'
 CMAKE_INSTALL_SBINDIR='sbin'
 CMAKE_INSTALL_SHAREDSTATEDIR='com'
-CMAKE_INSTALL_SYSCONFDIR='etc'
+CMAKE_INSTALL_SYSCONFDIR='/etc'
 CMAKE_INSTALL_FULL_BINDIR='/usr/bin'
 CMAKE_INSTALL_FULL_DATADIR='/usr/share'
 CMAKE_INSTALL_FULL_DATAROOTDIR='/usr/share'

Tests/RunCMake/GNUInstallDirs/Usr-FreeBSD-stderr.txt

@@ -7,12 +7,12 @@ CMAKE_INSTALL_INFODIR='share/info'
 CMAKE_INSTALL_LIBDIR='(lib|lib64|lib/arch)'
 CMAKE_INSTALL_LIBEXECDIR='libexec'
 CMAKE_INSTALL_LOCALEDIR='share/locale'
-CMAKE_INSTALL_LOCALSTATEDIR='var'
-CMAKE_INSTALL_RUNSTATEDIR='var/run'
+CMAKE_INSTALL_LOCALSTATEDIR='/var'
+CMAKE_INSTALL_RUNSTATEDIR='/var/run'
 CMAKE_INSTALL_MANDIR='share/man'
 CMAKE_INSTALL_SBINDIR='sbin'
 CMAKE_INSTALL_SHAREDSTATEDIR='com'
-CMAKE_INSTALL_SYSCONFDIR='etc'
+CMAKE_INSTALL_SYSCONFDIR='/etc'
 CMAKE_INSTALL_FULL_BINDIR='/usr/bin'
 CMAKE_INSTALL_FULL_DATADIR='/usr/share'
 CMAKE_INSTALL_FULL_DATAROOTDIR='/usr/share'

Tests/RunCMake/GNUInstallDirs/Usr-stderr.txt

@@ -7,12 +7,12 @@ CMAKE_INSTALL_INFODIR='share/info'
 CMAKE_INSTALL_LIBDIR='(lib|lib64|lib/arch)'
 CMAKE_INSTALL_LIBEXECDIR='libexec'
 CMAKE_INSTALL_LOCALEDIR='share/locale'
-CMAKE_INSTALL_LOCALSTATEDIR='var'
-CMAKE_INSTALL_RUNSTATEDIR='var/run'
+CMAKE_INSTALL_LOCALSTATEDIR='/var'
+CMAKE_INSTALL_RUNSTATEDIR='/var/run'
 CMAKE_INSTALL_MANDIR='share/man'
 CMAKE_INSTALL_SBINDIR='sbin'
 CMAKE_INSTALL_SHAREDSTATEDIR='com'
-CMAKE_INSTALL_SYSCONFDIR='etc'
+CMAKE_INSTALL_SYSCONFDIR='/etc'
 CMAKE_INSTALL_FULL_BINDIR='/usr/bin'
 CMAKE_INSTALL_FULL_DATADIR='/usr/share'
 CMAKE_INSTALL_FULL_DATAROOTDIR='/usr/share'