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