Merge topic 'cmake-install-doc'

a4f71b4ba8 Help: Document existence of cmake_install.cmake
fcf64866da Help: move DESTDIR into a separate page

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !1979

6 files changed, 53 insertions, 17 deletions

diff --git a/Help/command/install.rst b/Help/command/install.rst
index e9c185c..d3818d6 100644
--- a/Help/command/install.rst
+++ b/Help/command/install.rst
@@ -400,3 +400,26 @@ executable from the installation tree using the imported target name
   those generated by :command:`install_targets`,
   :command:`install_files`, and :command:`install_programs` commands
   is not defined.
+
+Generated Installation Script
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``install()`` command generates a file, ``cmake_install.cmake``, inside
+the build directory, which is used internally by the generated install target
+and by CPack. You can also invoke this script manually with ``cmake -P``. This
+script accepts several variables:
+
+``COMPONENT``
+  Set this variable to install only a single CPack component as opposed to all
+  of them. For example, if you only want to install the ``Development``
+  component, run ``cmake -DCOMPONENT=Development -P cmake_install.cmake``.
+
+``BUILD_TYPE``
+  Set this variable to change the build type if you are using a multi-config
+  generator. For example, to install with the ``Debug`` configuration, run
+  ``cmake -DBUILD_TYPE=Debug -P cmake_install.cmake``.
+
+``DESTDIR``
+  This is an environment variable rather than a CMake variable. It allows you
+  to change the installation prefix on UNIX systems. See :envvar:`DESTDIR` for
+  details.
diff --git a/Help/envvar/DESTDIR.rst b/Help/envvar/DESTDIR.rst
new file mode 100644
index 0000000..87f1115
--- /dev/null
+++ b/Help/envvar/DESTDIR.rst
@@ -0,0 +1,19 @@
+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:
+
+::
+
+ make DESTDIR=/home/john install
+
+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``.
+
+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.
diff --git a/Help/index.rst b/Help/index.rst
index 3dccdda..fa5273c 100644
--- a/Help/index.rst
+++ b/Help/index.rst
@@ -29,18 +29,18 @@ Reference Manuals
    /manual/cmake-commands.7
    /manual/cmake-compile-features.7
    /manual/cmake-developer.7
+   /manual/cmake-env-variables.7
    /manual/cmake-generator-expressions.7
    /manual/cmake-generators.7
    /manual/cmake-language.7
-   /manual/cmake-server.7
    /manual/cmake-modules.7
    /manual/cmake-packages.7
    /manual/cmake-policies.7
    /manual/cmake-properties.7
    /manual/cmake-qt.7
+   /manual/cmake-server.7
    /manual/cmake-toolchains.7
    /manual/cmake-variables.7
-   /manual/cmake-env-variables.7
 
 .. only:: html or text
 
diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst
index fed129e..2d8869f 100644
--- a/Help/manual/cmake-env-variables.7.rst
+++ b/Help/manual/cmake-env-variables.7.rst
@@ -16,6 +16,7 @@ Environment Variables that Control the Build
    /envvar/CMAKE_CONFIG_TYPE
    /envvar/CMAKE_MSVCIDE_RUN_PATH
    /envvar/CMAKE_OSX_ARCHITECTURES
+   /envvar/DESTDIR
    /envvar/LDFLAGS
    /envvar/MACOSX_DEPLOYMENT_TARGET
 
diff --git a/Help/release/dev/cmake-install-doc.rst b/Help/release/dev/cmake-install-doc.rst
new file mode 100644
index 0000000..028aa43
--- /dev/null
+++ b/Help/release/dev/cmake-install-doc.rst
@@ -0,0 +1,7 @@
+cmake-install-doc
+-----------------
+
+* The existence and functionality of the file
+  ``${CMAKE_BINARY_DIR}/cmake_install.cmake`` has now been documented in the
+  :command:`install` documentation so that external packaging software can take
+  advantage of CPack-style component installs.
diff --git a/Help/variable/CMAKE_INSTALL_PREFIX.rst b/Help/variable/CMAKE_INSTALL_PREFIX.rst
index 7bd87d6..02ba645 100644
--- a/Help/variable/CMAKE_INSTALL_PREFIX.rst
+++ b/Help/variable/CMAKE_INSTALL_PREFIX.rst
@@ -10,21 +10,7 @@ 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.  ``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:
-
-::
-
- make DESTDIR=/home/john install
-
-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``.
-
-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.
+whole installation. See :envvar:`DESTDIR` for more information.
 
 The installation prefix is also added to :variable:`CMAKE_SYSTEM_PREFIX_PATH`
 so that :command:`find_package`, :command:`find_program`,