1CMAKE_INSTALL_MODE 2------------------ 3 4.. versionadded:: 3.22 5 6.. include:: ENV_VAR.txt 7 8The ``CMAKE_INSTALL_MODE`` environment variable allows users to operate 9CMake in an alternate mode of :command:`file(INSTALL)` and :command:`install()`. 10 11The default behavior for an installation is to copy a source file from a 12source directory into a destination directory. This environment variable 13however allows the user to override this behavior, causing CMake to create 14symbolic links instead. 15 16Usage Scenarios 17^^^^^^^^^^^^^^^ 18 19Installing symbolic links rather than copying files can help in the following 20ways: 21 22* Conserving storage space because files do not have to be duplicated on disk. 23* Changes to the source of the symbolic link are seen at the install 24 destination without having to re-run the install step. 25* Editing through the link at the install destination will modify the source 26 of the link. This may be useful when dealing with CMake project hierarchies, 27 i.e. using :module:`ExternalProject` and consistent source navigation and 28 refactoring is desired across projects. 29 30Allowed Values 31^^^^^^^^^^^^^^ 32 33The following values are allowed for ``CMAKE_INSTALL_MODE``: 34 35``COPY``, empty or unset 36 Duplicate the file at its destination. This is the default behavior. 37 38``ABS_SYMLINK`` 39 Create an *absolute* symbolic link to the source file at the destination. 40 Halt with an error if the link cannot be created. 41 42``ABS_SYMLINK_OR_COPY`` 43 Like ``ABS_SYMLINK`` but fall back to silently copying if the symlink 44 couldn't be created. 45 46``REL_SYMLINK`` 47 Create a *relative* symbolic link to the source file at the destination. 48 Halt with an error if the link cannot be created. 49 50``REL_SYMLINK_OR_COPY`` 51 Like ``REL_SYMLINK`` but fall back to silently copying if the symlink 52 couldn't be created. 53 54``SYMLINK`` 55 Try as if through ``REL_SYMLINK`` and fall back to ``ABS_SYMLINK`` if the 56 referenced file cannot be expressed using a relative path. 57 Halt with an error if the link cannot be created. 58 59``SYMLINK_OR_COPY`` 60 Like ``SYMLINK`` but fall back to silently copying if the symlink couldn't 61 be created. 62 63.. note:: 64 A symbolic link consists of a reference file path rather than contents of its 65 own, hence there are two ways to express the relation, either by a *relative* 66 or an *absolute* path. 67 68When To Set The Environment Variable 69^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 70 71For the environment variable to take effect, it must be set during the correct 72build phase(s). 73 74* If the project calls :command:`file(INSTALL)` directly, the environment 75 variable must be set during the configuration phase. 76* In order to apply to :command:`install()`, the environment variable must be 77 set during installation. This could be during a build if using the 78 ``install`` or ``package`` build targets, or separate from the build when 79 invoking an install or running :manual:`cpack <cpack(1)>` from the command 80 line. 81* When using :module:`ExternalProject`, it might be required during the build 82 phase, since the external project's own configure, build and install steps 83 will execute during the main project's build phase. 84 85Given the above, it is recommended to set the environment variable consistently 86across all phases (configure, build and install). 87 88Caveats 89^^^^^^^ 90 91Use this environment variable with caution. The following highlights some 92points to be considered: 93 94* ``CMAKE_INSTALL_MODE`` only affects files, not directories. 95 96* Symbolic links are not available on all platforms. 97 98* The way this environment variable interacts with the install step of 99 :module:`ExternalProject` is more complex. For further details, see that 100 module's documentation. 101 102* A symbolic link ties the destination to the source in a persistent way. 103 Writing to either of the two affects both file system objects. 104 This is in contrast to normal install behavior which only copies files as 105 they were at the time the install was performed, with no enduring 106 relationship between the source and destination of the install. 107 108* Combining ``CMAKE_INSTALL_MODE`` with :prop_tgt:`IOS_INSTALL_COMBINED` is 109 not supported. 110 111* Changing ``CMAKE_INSTALL_MODE`` from what it was on a previous run can lead 112 to unexpected results. Moving from a non-symlinking mode to a symlinking 113 mode will discard any previous file at the destination, but the reverse is 114 not true. Once a symlink exists at the destination, even if you switch to a 115 non-symlink mode, the symlink will continue to exist at the destination and 116 will not be replaced by an actual file. 117