diff options
Diffstat (limited to 'Help/envvar')
| -rw-r--r-- | Help/envvar/CMAKE_INSTALL_MODE.rst | 80 |
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. |