Tutorial: Describe install prefix

Give a brief overview of what the install prefix is and the various
ways it can be set.
This commit is contained in:
Tyler Yankee
2026-05-14 18:11:41 -04:00
parent fdc4511f18
commit 653356bed0

View File

@@ -66,6 +66,27 @@ to unless instructed to do otherwise. For example, ``RUNTIME`` will be installed
to the location named by :module:`CMAKE_INSTALL_BINDIR <GNUInstallDirs>`, if to the location named by :module:`CMAKE_INSTALL_BINDIR <GNUInstallDirs>`, if
the variable is available, otherwise they default to ``bin``. the variable is available, otherwise they default to ``bin``.
Just like we use :option:`cmake -B` to control what build directory will be
used by CMake, we have a variety of options for telling CMake where to install
things. This location is generally referred to as the install prefix. To
set this at configure time, so that every :option:`cmake --install` performed
using that build tree defaults to a given prefix, we can use any of:
* the :option:`cmake --install-prefix` option;
* the :ref:`installDir <CMakePresets installDir>` field in CMake presets; or
* the :variable:`CMAKE_INSTALL_PREFIX` variable.
.. note::
We have discouraged setting ``CMAKE_`` variables inside the project. Setting
:variable:`CMAKE_INSTALL_PREFIX` is *particularly* bad practice without very
good reasoning for doing so, since it prevents users from ever overriding it.
When providing a default, projects should check
:variable:`CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT`.
Alternatively, we can use the
:option:`cmake --install --prefix <cmake--install --prefix>` option to set the
install prefix for a single install invocation.
The full list of artifact kind default destinations is described in the The full list of artifact kind default destinations is described in the
following table. following table.
@@ -140,6 +161,8 @@ Helpful Resources
----------------- -----------------
* :command:`install` * :command:`install`
* :option:`cmake --install-prefix`
* :option:`cmake --install --prefix <cmake--install --prefix>`
Files to Edit Files to Edit
------------- -------------