Merge branch 'doc-CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT' into release

Help/manual/cmake-variables.7.rst

@@ -148,6 +148,7 @@ Variables that Change Behavior
    /variable/CMAKE_INSTALL_DEFAULT_COMPONENT_NAME
    /variable/CMAKE_INSTALL_MESSAGE
    /variable/CMAKE_INSTALL_PREFIX
+   /variable/CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT
    /variable/CMAKE_LIBRARY_PATH
    /variable/CMAKE_MFC_FLAG
    /variable/CMAKE_MODULE_PATH

Help/variable/CMAKE_INSTALL_PREFIX.rst

@@ -6,6 +6,8 @@ Install directory used by :command:`install`.
 If ``make install`` is invoked or ``INSTALL`` is built, this directory is
 prepended onto all install directories.  This variable defaults to
 ``/usr/local`` on UNIX and ``c:/Program Files/${PROJECT_NAME}`` on Windows.
+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

Help/variable/CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT.rst

+CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT
+-------------------------------------------
+
+CMake sets this variable to a ``TRUE`` value when the
+:variable:`CMAKE_INSTALL_PREFIX` has just been initialized to
+its default value, typically on the first run of CMake within
+a new build tree.  This can be used by project code to change
+the default without overriding a user-provided value:
+
+.. code-block:: cmake
+
+  if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
+    set(CMAKE_INSTALL_PREFIX "/my/default" CACHE PATH "..." FORCE)
+  endif()