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