Help: Clarify roles of DESTDIR and CMAKE_INSTALL_PREFIX

2 files changed, 30 insertions, 11 deletions

diff --git a/Help/envvar/DESTDIR.rst b/Help/envvar/DESTDIR.rst
index d2144ae..94cae4a 100644
--- a/Help/envvar/DESTDIR.rst
+++ b/Help/envvar/DESTDIR.rst
@@ -5,17 +5,26 @@ DESTDIR
 
 On UNIX one can use the ``DESTDIR`` mechanism in order to relocate the
 whole installation.  ``DESTDIR`` means DESTination DIRectory.  It is
-commonly used by makefile users in order to install software at
-non-default location.  It is usually invoked like this:
+commonly used by packagers to install software in a staging directory.
 
-::
+For example, running
 
- make DESTDIR=/home/john install
+.. code-block:: shell
 
-which will install the concerned software using the installation
-prefix, e.g.  ``/usr/local`` prepended with the ``DESTDIR`` value which
-finally gives ``/home/john/usr/local``.
+  make DESTDIR=/package/stage install
 
-WARNING: ``DESTDIR`` may not be used on Windows because installation
-prefix usually contains a drive letter like in ``C:/Program Files``
-which cannot be prepended with some other prefix.
+will install the software using the installation prefix, e.g. ``/usr/local``,
+prepended with the ``DESTDIR`` value which gives ``/package/stage/usr/local``.
+The packaging tool may then construct the package from the content of the
+``/package/stage`` directory.
+
+See the :variable:`CMAKE_INSTALL_PREFIX` variable to control the
+installation prefix when configuring a build tree.  Or, when using
+the :manual:`cmake(1)` command-line tool's ``--install`` mode,
+one may specify a different prefix using the ``--prefix`` option.
+
+.. note::
+
+  ``DESTDIR`` may not be used on Windows because installation
+  prefix usually contains a drive letter like in ``C:/Program Files``
+  which cannot be prepended with some other prefix.
diff --git a/Help/variable/CMAKE_INSTALL_PREFIX.rst b/Help/variable/CMAKE_INSTALL_PREFIX.rst
index 02ba645..b92d3ef 100644
--- a/Help/variable/CMAKE_INSTALL_PREFIX.rst
+++ b/Help/variable/CMAKE_INSTALL_PREFIX.rst
@@ -10,7 +10,8 @@ See :variable:`CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT` for how a
 project might choose its own default.
 
 On UNIX one can use the ``DESTDIR`` mechanism in order to relocate the
-whole installation. See :envvar:`DESTDIR` for more information.
+whole installation to a staging area.  See the :envvar:`DESTDIR` environment
+variable for more information.
 
 The installation prefix is also added to :variable:`CMAKE_SYSTEM_PREFIX_PATH`
 so that :command:`find_package`, :command:`find_program`,
@@ -21,3 +22,12 @@ will search the prefix for other software.
 
   Use the :module:`GNUInstallDirs` module to provide GNU-style
   options for the layout of directories within the installation.
+
+The ``CMAKE_INSTALL_PREFIX`` may be defined when configuring a build tree
+to set its installation prefix.  Or, when using the :manual:`cmake(1)`
+command-line tool's ``--install`` mode, one may specify a different prefix
+using the ``--prefix`` option:
+
+.. code-block:: shell
+
+  cmake --install . --prefix /my/install/prefix