Help: Clarify CMAKE_INSTALL_MODE documentation

Fixes: #22869
Co-Authored-By: Craig Scott <craig.scott@crascit.com>

1 files changed, 70 insertions, 10 deletions

diff --git a/Help/envvar/CMAKE_INSTALL_MODE.rst b/Help/envvar/CMAKE_INSTALL_MODE.rst
index be617cc..4549ea1 100644
--- a/Help/envvar/CMAKE_INSTALL_MODE.rst
+++ b/Help/envvar/CMAKE_INSTALL_MODE.rst
@@ -13,9 +13,22 @@ source directory into a destination directory. This environment variable
 however allows the user to override this behavior, causing CMake to create
 symbolic links instead.
 
-.. note::
-  A symbolic link consists of a reference file path rather than contents of its own,
-  hence there are two ways to express the relation, either by a relative or an absolute path.
+Usage Scenarios
+^^^^^^^^^^^^^^^
+
+Installing symbolic links rather than copying files can help in the following
+ways:
+
+* Conserving storage space because files do not have to be duplicated on disk.
+* Changes to the source of the symbolic link are seen at the install
+  destination without having to re-run the install step.
+* Editing through the link at the install destination will modify the source
+  of the link. This may be useful when dealing with CMake project hierarchies,
+  i.e. using :module:`ExternalProject` and consistent source navigation and
+  refactoring is desired across projects.
+
+Allowed Values
+^^^^^^^^^^^^^^
 
 The following values are allowed for ``CMAKE_INSTALL_MODE``:
 
@@ -47,10 +60,57 @@ The following values are allowed for ``CMAKE_INSTALL_MODE``:
   Like ``SYMLINK`` but fall back to silently copying if the symlink couldn't
   be created.
 
-Installing symbolic links rather than copying files can help conserve storage space because files do
-not have to be duplicated on disk. However, modifications applied to the source immediately affects
-the symbolic link and vice versa. *Use with caution*.
-
-.. note:: ``CMAKE_INSTALL_MODE`` only affects files, *not* directories.
-
-.. note:: Symbolic links are not available on all platforms.
+.. note::
+  A symbolic link consists of a reference file path rather than contents of its
+  own, hence there are two ways to express the relation, either by a *relative*
+  or an *absolute* path.
+
+When To Set The Environment Variable
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For the environment variable to take effect, it must be set during the correct
+build phase(s).
+
+* If the project calls :command:`file(INSTALL)` directly, the environment
+  variable must be set during the configuration phase.
+* In order to apply to :command:`install()`, the environment variable must be
+  set during installation.  This could be during a build if using the
+  ``install`` or ``package`` build targets, or separate from the build when
+  invoking an install or running :manual:`cpack <cpack(1)>` from the command
+  line.
+* When using :module:`ExternalProject`, it might be required during the build
+  phase, since the external project's own configure, build and install steps
+  will execute during the main project's build phase.
+
+Given the above, it is recommended to set the environment variable consistently
+across all phases (configure, build and install).
+
+Caveats
+^^^^^^^
+
+Use this environment variable with caution. The following highlights some
+points to be considered:
+
+* ``CMAKE_INSTALL_MODE`` only affects files, not directories.
+
+* Symbolic links are not available on all platforms.
+
+* The way this environment variable interacts with the install step of
+  :module:`ExternalProject` is more complex. For further details, see that
+  module's documentation.
+
+* A symbolic link ties the destination to the source in a persistent way.
+  Writing to either of the two affects both file system objects.
+  This is in contrast to normal install behavior which only copies files as
+  they were at the time the install was performed, with no enduring
+  relationship between the source and destination of the install.
+
+* Combining ``CMAKE_INSTALL_MODE`` with :prop_tgt:`IOS_INSTALL_COMBINED` is
+  not supported.
+
+* Changing ``CMAKE_INSTALL_MODE`` from what it was on a previous run can lead
+  to unexpected results.  Moving from a non-symlinking mode to a symlinking
+  mode will discard any previous file at the destination, but the reverse is
+  not true.  Once a symlink exists at the destination, even if you switch to a
+  non-symlink mode, the symlink will continue to exist at the destination and
+  will not be replaced by an actual file.