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 по сравнению с предыдущим запуском может привести к непредвиденным результатам. Переход от режима без символических ссылок к режиму с символическими ссылками приведет к удалению любого предыдущего файла в целевом каталоге, но обратное неверно. После создания символической ссылки в целевом каталоге, даже если вы перейдете в режим без символических ссылок, символическая ссылка останется в целевом каталоге и не будет заменена фактическим файлом.