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