CMAKE_INSTALL_MODE

Это переменная среды CMake Переменная среды. Её начальное значение берётся из переменной окружения вызывающего процесса.

Переменная окружения CMAKE_INSTALL_MODE позволяет пользователям управлять CMake в альтернативном режиме file(INSTALL) и install().

По умолчанию установка копирует исходный файл из исходного каталога в целевой каталог. Данная переменная позволяет переопределить это поведение, заставив CMake создавать символические ссылки вместо этого.

Сценарии использования

Установка символических ссылок вместо копирования файлов может помочь в следующих случаях:

• Экономия дискового пространства, так как файлы не нужно дублировать.
• Изменения исходного файла символической ссылки отображаются в целевом каталоге без повторного выполнения шага установки.
• Редактирование через ссылку в целевом каталоге изменит исходный файл ссылки. Это может быть полезно при работе с иерархией проекта CMake, например, при использовании ExternalProject, и желательно сохранение согласованного навигации по исходным файлам и рефакторинга между проектами.

Допустимые значения

Для CMAKE_INSTALL_MODE допустимы следующие значения:

COPY, empty or unset

Дублировать файл в целевой каталог. Это поведение по умолчанию.

ABS_SYMLINK

Создать абсолютную символическую ссылку на исходный файл в целевом каталоге. Остановиться с ошибкой, если ссылка не может быть создана.

ABS_SYMLINK_OR_COPY

Как ABS_SYMLINK, но перейти к тихому копированию, если символическая ссылка не может быть создана.

REL_SYMLINK

Создать относительную символическую ссылку на исходный файл в целевом каталоге. Остановиться с ошибкой, если ссылка не может быть создана.

REL_SYMLINK_OR_COPY

Как REL_SYMLINK, но перейти к тихому копированию, если символическая ссылка не может быть создана.

SYMLINK

Попытаться так, как будто через REL_SYMLINK, и перейти к ABS_SYMLINK, если файл, на который ссылаются, не может быть выражен с помощью относительного пути. Остановиться с ошибкой, если ссылка не может быть создана.

SYMLINK_OR_COPY

Как SYMLINK, но перейти к тихому копированию, если символическая ссылка не может быть создана.

Когда нужно задавать переменную среды

Для того, чтобы переменная среды вступила в силу, её нужно задать на соответствующей стадии сборки.

• Если проект вызывает file(INSTALL) напрямую, переменная среды должна быть задана на стадии конфигурации.
• Чтобы применить это к install(), переменная среды должна быть задана во время установки. Это может быть во время сборки, если используются цели сборки install или package, или отдельно от сборки при вызове установки или запуске cpack из командной строки.
• При использовании ExternalProject, это может потребоваться на стадии сборки, так как собственные шаги конфигурации, сборки и установки внешнего проекта будут выполняться на стадии сборки основного проекта.

В связи с этим рекомендуется устанавливать переменную среды последовательно на всех этапах (конфигурация, сборка и установка).

Ограничения

Используйте эту переменную среды с осторожностью. Ниже приведены некоторые моменты, которые следует учитывать:

• CMAKE_INSTALL_MODE влияет только на файлы, а не каталоги.
• Символические ссылки недоступны на всех платформах.
• Способ взаимодействия этой переменной среды с этапом установки ExternalProject более сложный. Подробности см. в документации по этому модулю.
• Символическая ссылка связывает место назначения с исходником постоянным образом. Запись в любой из двух объектов влияет на оба объекта файловой системы. Это отличается от обычного поведения установки, которое копирует файлы только в момент выполнения установки, без сохранения отношений между источником и местом назначения установки.
• Сочетание CMAKE_INSTALL_MODE с IOS_INSTALL_COMBINED не поддерживается.
• Изменение значения CMAKE_INSTALL_MODE по сравнению с предыдущей выполнением может привести к непредсказуемым результатам. Переход от режима без символических ссылок к режиму с символическими ссылками отбросит любой предыдущий файл в месте назначения, но обратное неверно. Если символическая ссылка существует в месте назначения, даже если вы переключаетесь на режим без символических ссылок, символическая ссылка останется в месте назначения и не будет заменена фактическим файлом.