New in version 3.22.
This is a CMake Environment Variable. Its initial value is taken from the calling process environment.
The default behavior for an installation is to copy a source file from a source directory into a destination directory. This environment variable however allows the user to override this behavior, causing CMake to create symbolic links instead.
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
ExternalProjectand consistent source navigation and refactoring is desired across projects.
The following values are allowed for
COPY, empty or unset
Duplicate the file at its destination. This is the default behavior.
Create an absolute symbolic link to the source file at the destination. Halt with an error if the link cannot be created.
ABS_SYMLINKbut fall back to silently copying if the symlink couldn't be created.
Create a relative symbolic link to the source file at the destination. Halt with an error if the link cannot be created.
REL_SYMLINKbut fall back to silently copying if the symlink couldn't be created.
Try as if through
REL_SYMLINKand fall back to
ABS_SYMLINKif the referenced file cannot be expressed using a relative path. Halt with an error if the link cannot be created.
SYMLINKbut fall back to silently copying if the symlink couldn't be created.
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
file(INSTALL)directly, the environment variable must be set during the configuration phase.
In order to apply to
install(), the environment variable must be set during installation. This could be during a build if using the
packagebuild targets, or separate from the build when invoking an install or running
cpackfrom the command line.
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).
Use this environment variable with caution. The following highlights some points to be considered:
CMAKE_INSTALL_MODEonly affects files, not directories.
Symbolic links are not available on all platforms.
The way this environment variable interacts with the install step of
ExternalProjectis 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.
IOS_INSTALL_COMBINEDis not supported.
CMAKE_INSTALL_MODEfrom 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.