GNUInstallDirs: Add notice about --prefix option

When setting the installation prefix at the installation phase
(`cmake --install`) using the `--prefix` option, the GNU special cases
aren't applicable. This also adds a small clarification when to use the
`--prefix` option at the installation phase.

Briefly mentioned also the CMake presets installDir field,
the CPACK_PACKAGING_INSTALL_PREFIX variable, and the $<INSTALL_PREFIX>
generator expression so user has a better overview.

Fixes #27343
Fixes #26338

Help/manual/cmake-presets.7.rst

@@ -285,8 +285,11 @@ that may contain the following fields:
   preset is ``hidden``). In version ``3`` or above, this field may be
   omitted.
 
+.. _`CMakePresets installDir`:
+
 ``installDir``
-  An optional string representing the path to the installation directory.
+  An optional string representing the path to the installation directory,
+  which will be used as the :variable:`CMAKE_INSTALL_PREFIX` variable.
   This field supports `macro expansion`_. If a relative path is specified,
   it is calculated relative to the source directory. This is allowed in
   preset files specifying version ``3`` or above.

Help/manual/cmake.1.rst

@@ -919,7 +919,23 @@ The options are:
 
 .. option:: --prefix <prefix>
 
-  Override the installation prefix, :variable:`CMAKE_INSTALL_PREFIX`.
+  Specifies an alternative installation prefix, temporarily replacing the
+  value of the :variable:`CMAKE_INSTALL_PREFIX` variable at the installation
+  phase.
+
+  The main purpose of this option is to allow installation to occur in an
+  arbitrary location.  This is commonly used in certain installation and
+  packaging workflows.  It is analogous to selecting the installation
+  directory during the installation phase.  For example, on Windows, where
+  a user may choose the destination folder for the project.
+
+  .. note::
+
+    When the project is using the :module:`GNUInstallDirs` module, there are
+    some :ref:`special cases <GNUInstallDirs special cases>` that are
+    evaluated based on the value of the :variable:`CMAKE_INSTALL_PREFIX`
+    variable during the configuration phase.  The results persist even if an
+    alternative prefix is used during installation.
 
 .. option:: --strip
 

Help/manual/presets/schema.json

@@ -572,7 +572,7 @@
           },
           "installDir": {
             "type": "string",
-            "description": "An optional string representing the path to the installation directory. This field supports macro expansion. If a relative path is specified, it is calculated relative to the source directory."
+            "description": "An optional string representing the path to the installation directory, which will be used as the CMAKE_INSTALL_PREFIX variable. This field supports macro expansion. If a relative path is specified, it is calculated relative to the source directory."
           }
         }
       }

Help/variable/CMAKE_INSTALL_PREFIX.rst

@@ -45,3 +45,21 @@ option:
 .. code-block:: shell
 
   cmake --install . --prefix /my/install/prefix
+
+.. note::
+
+  When the project is using the :module:`GNUInstallDirs` module, there are
+  some :ref:`special cases <GNUInstallDirs special cases>` that are
+  evaluated based on the value of the :variable:`CMAKE_INSTALL_PREFIX`
+  variable during the configuration phase.  The results persist even
+  if an alternative :option:`--prefix <cmake--install --prefix>` option
+  is used during installation.
+
+See Also
+^^^^^^^^
+
+* The :option:`--install-prefix <cmake --install-prefix>` option.
+* The :genex:`$<INSTALL_PREFIX>` generator expression.
+* The :ref:`installDir <CMakePresets installDir>` field in CMake configure
+  presets.
+* The :variable:`CPACK_PACKAGING_INSTALL_PREFIX` variable.

Modules/GNUInstallDirs.cmake

@@ -86,6 +86,15 @@ where ``<dir>`` is one of:
 
   On Debian, this may be ``lib/<multiarch-tuple>`` when
   :variable:`CMAKE_INSTALL_PREFIX` is ``/usr``.
+
+  .. note::
+
+    When an alternative installation prefix is specified with the
+    :option:`--prefix <cmake--install --prefix>` option at install time,
+    the special case with multi-architecture tuple is evaluated based on
+    the configuration-time :variable:`CMAKE_INSTALL_PREFIX`, not on the
+    alternative prefix value.
+
 ``INCLUDEDIR``
   C header files (``include``)
 ``OLDINCLUDEDIR``
@@ -174,6 +183,13 @@ The following values of :variable:`CMAKE_INSTALL_PREFIX` are special:
     absolute paths ``/etc/opt/...``, ``/var/opt/...`` and
     ``/var/run/opt/...`` respectively. See policy :policy:`CMP0192`.
 
+.. note::
+
+  When an alternative installation prefix is specified with the
+  :option:`--prefix <cmake--install --prefix>` option at install time,
+  these special cases are evaluated based on the configuration-time
+  :variable:`CMAKE_INSTALL_PREFIX`, not on the alternative prefix value.
+
 .. _`Filesystem Hierarchy Standard`: https://refspecs.linuxfoundation.org/FHS_3.0/fhs/index.html
 
 Commands