From 653356bed0e5f80a20b3401ca9e9d576ed2d9689 Mon Sep 17 00:00:00 2001 From: Tyler Yankee Date: Thu, 14 May 2026 18:11:41 -0400 Subject: [PATCH] Tutorial: Describe install prefix Give a brief overview of what the install prefix is and the various ways it can be set. --- .../Installation Commands and Concepts.rst | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/Help/guide/tutorial/Installation Commands and Concepts.rst b/Help/guide/tutorial/Installation Commands and Concepts.rst index 8d797b2c22..914b65b8a4 100644 --- a/Help/guide/tutorial/Installation Commands and Concepts.rst +++ b/Help/guide/tutorial/Installation Commands and Concepts.rst @@ -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 `, if 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 ` 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 ` option to set the +install prefix for a single install invocation. + The full list of artifact kind default destinations is described in the following table. @@ -140,6 +161,8 @@ Helpful Resources ----------------- * :command:`install` +* :option:`cmake --install-prefix` +* :option:`cmake --install --prefix ` Files to Edit -------------