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