mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-01-11 00:11:07 -06:00
Code Issues Packages Projects Releases Wiki Activity

GNUInstallDirs: Add notice about --prefix option

Browse Source 
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
This commit is contained in:
Peter Kokot
2025-10-28 21:11:14 +01:00
parent 59534983c9
commit 35b1250b0a
5 changed files with 56 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
Help/manual/cmake-presets.7.rst
View File

@@ -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.

18
Help/manual/cmake.1.rst
View File

@@ -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

2
Help/manual/presets/schema.json
View File

@@ -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."
}
}
}

18
Help/variable/CMAKE_INSTALL_PREFIX.rst
View File

@@ -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.

16
Modules/GNUInstallDirs.cmake
View File

@@ -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