mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-05-01 03:29:18 -05:00
Code Issues Packages Projects Releases Wiki Activity

Help: Clarify CMAKE_INSTALL_MODE documentation

Browse Source 
Fixes: #22869
Co-Authored-By: Craig Scott <craig.scott@crascit.com>
This commit is contained in:
Felix Lelchuk
2021-11-18 04:01:10 +01:00
committed by Craig Scott
parent 699d4a98e2
commit 3caeee0c86
2 changed files with 84 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Help/envvar/CMAKE_INSTALL_MODE.rst
+68 -8
View File
@@ -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::
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.
.. note:: ``CMAKE_INSTALL_MODE`` only affects files, *not* directories.
When To Set The Environment Variable
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. note:: Symbolic links are not available on all platforms.
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.