install

• Введение
• Установка целевых объектов
• Установка файлов
• Установка директорий
• Пользовательская логика установки
• Установка экспортов

Укажите правила для выполнения во время установки.

Введение

Эта команда генерирует правила установки для проекта. Правила, заданные вызовами этой команды в каталоге исходных файлов, выполняются в порядке их задания во время установки. Порядок выполнения между каталогами не определён.

Существует несколько сигнатур для этой команды. Некоторые из них определяют параметры установки для файлов и целевых объектов. Общие для нескольких сигнатур параметры описаны здесь, но они действительны только для сигнатур, которые их указывают. Общие параметры:

DESTINATION

Укажите каталог на диске, в который будет установлен файл. Если указан полный путь (с ведущим слэшем или буквой диска), он используется напрямую. Если указан относительный путь, он интерпретируется относительно значения переменной CMAKE_INSTALL_PREFIX. Префикс может быть перемещён во время установки с помощью механизма DESTDIR, описанного в документации переменной CMAKE_INSTALL_PREFIX.

PERMISSIONS

Укажите разрешения для установленных файлов. Допустимые разрешения: OWNER_READ, OWNER_WRITE, OWNER_EXECUTE, GROUP_READ, GROUP_WRITE, GROUP_EXECUTE, WORLD_READ, WORLD_WRITE, WORLD_EXECUTE, SETUID, и SETGID. Разрешения, не имеющие смысла на определённых платформах, игнорируются на этих платформах.

CONFIGURATIONS

Укажите список конфигураций сборки, к которым относится правило установки (Отладка, Релиз и т. д.).

COMPONENT

Укажите имя компонента установки, с которым связано правило установки, например, «runtime» или «development». Во время установки, специфичной для компонента, будут выполняться только правила установки, связанные с заданным именем компонента. Во время полной установки все компоненты устанавливаются, если не помечены с помощью EXCLUDE_FROM_ALL. Если COMPONENT не указан, создаётся компонент по умолчанию «Unspecified». Имя компонента по умолчанию может быть изменено с помощью переменной CMAKE_INSTALL_DEFAULT_COMPONENT_NAME.

EXCLUDE_FROM_ALL

Укажите, что файл исключается из полной установки и устанавливается только в рамках установки, специфичной для компонента.

RENAME

Укажите имя установленного файла, которое может отличаться от исходного файла. Переименование разрешено только при установке одного файла командой.

OPTIONAL

Укажите, что отсутствие файла для установки не является ошибкой.

Сигнатуры команд, устанавливающие файлы, могут выводить сообщения во время установки. Используйте переменную CMAKE_INSTALL_MESSAGE для управления выводом сообщений.

Установка целевых объектов

install(TARGETS targets... [EXPORT <export-name>]
        [[ARCHIVE|LIBRARY|RUNTIME|FRAMEWORK|BUNDLE|
          PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE]
         [DESTINATION <dir>]
         [PERMISSIONS permissions...]
         [CONFIGURATIONS [Debug|Release|...]]
         [COMPONENT <component>]
         [OPTIONAL] [EXCLUDE_FROM_ALL]
         [NAMELINK_ONLY|NAMELINK_SKIP]
        ] [...]
        [INCLUDES DESTINATION [<dir> ...]]
        )

Форма TARGETS задаёт правила для установки целевых объектов из проекта. Существует пять типов файлов целевых объектов, которые могут быть установлены: ARCHIVE, LIBRARY, RUNTIME, FRAMEWORK, и BUNDLE. Исполняемые файлы рассматриваются как RUNTIME целевые объекты, за исключением случаев, когда для них установлено свойство MACOSX_BUNDLE, и тогда они рассматриваются как BUNDLE целевые объекты на платформах OS X. Статические библиотеки всегда рассматриваются как ARCHIVE целевые объекты. Модульные библиотеки всегда рассматриваются как LIBRARY целевые объекты. На платформах, не использующих DLL, общие библиотеки рассматриваются как LIBRARY целевые объекты, за исключением случаев, когда для них установлено свойство FRAMEWORK, и тогда они рассматриваются как FRAMEWORK целевые объекты на платформах OS X. На платформах DLL, DLL-часть общей библиотеки рассматривается как RUNTIME целевой объект, а соответствующая импортная библиотека – как ARCHIVE целевой объект. Все платформы, основанные на Windows, включая Cygwin, являются платформами DLL. Аргументы ARCHIVE, LIBRARY, RUNTIME, и FRAMEWORK изменяют тип целевого объекта, к которому относятся последующие свойства. Если ни один из них не указан, свойства установки применяются ко всем типам целевых объектов. Если указан только один, устанавливаются только целевые объекты этого типа (что может быть использовано для установки только DLL или только импортной библиотеки).

Аргументы PRIVATE_HEADER, PUBLIC_HEADER, и RESOURCE приводят к тому, что последующие свойства применяются к установке файлов, связанных с FRAMEWORK общей библиотекой целевого объекта, на платформах, не являющихся Apple. Правила, заданные этими аргументами, игнорируются на платформах Apple, потому что связанные файлы устанавливаются в соответствующие места внутри каталога фреймворка. Смотрите документацию свойств целевых объектов PRIVATE_HEADER, PUBLIC_HEADER, и RESOURCE для получения подробной информации.

Можно указать либо NAMELINK_ONLY, либо NAMELINK_SKIP в качестве опции LIBRARY. На некоторых платформах у версионированной общей библиотеки есть символическая ссылка, например:

lib<name>.so -> lib<name>.so.1

где lib<name>.so.1 – имя библиотеки, а lib<name>.so – «имя ссылки», позволяющее линковщикам найти библиотеку, когда она задаётся в -l<name>. Опция NAMELINK_ONLY вызывает установку только ссылки по имени, когда устанавливается целевой объект библиотеки. Опция NAMELINK_SKIP вызывает установку файлов библиотеки, кроме ссылки по имени, когда устанавливается целевой объект библиотеки. Если ни одна из опций не указана, устанавливаются обе части. На платформах, где версионированные общие библиотеки не имеют ссылок по имени или когда библиотека не версионирована, опция NAMELINK_SKIP устанавливает библиотеку, а опция NAMELINK_ONLY ничего не устанавливает. Смотрите свойства целевого объекта VERSION и SOVERSION для получения подробной информации о создании версионированных общих библиотек.

INCLUDES DESTINATION указывает список каталогов, которые будут добавлены в свойство INTERFACE_INCLUDE_DIRECTORIES целевого объекта <targets> при экспорте командой install(EXPORT). Если указан относительный путь, он рассматривается как относительный к $<INSTALL_PREFIX>. Это независимо от остальных групп аргументов и фактически ничего не устанавливает.

В одном вызове формы TARGETS этой команды можно указать одну или несколько групп свойств. Целевой объект может быть установлен более одного раза в разных местах. Рассмотрим гипотетические целевые объекты myExe, mySharedLib, и myStaticLib. Код:

install(TARGETS myExe mySharedLib myStaticLib
        RUNTIME DESTINATION bin
        LIBRARY DESTINATION lib
        ARCHIVE DESTINATION lib/static)
install(TARGETS mySharedLib DESTINATION /some/full/path)

установит myExe в <prefix>/bin и myStaticLib в <prefix>/lib/static. На платформах, не использующих DLL, mySharedLib будет установлен в <prefix>/lib и /some/full/path. На платформах DLL, DLL-часть mySharedLib будет установлена в <prefix>/bin и /some/full/path, а соответствующая импортная библиотека – в <prefix>/lib/static и /some/full/path.

Опция EXPORT связывает установленные файлы целевого объекта с экспортом, называемым <export-name>. Она должна стоять перед опциями RUNTIME, LIBRARY, или ARCHIVE. Для фактической установки файла экспорта вызовите install(EXPORT), документацию которого см. ниже.

Установка целевого объекта со свойством целевого объекта EXCLUDE_FROM_ALL, установленным в TRUE, имеет неопределённое поведение.

Место назначения установки, заданное для целевого объекта установки DESTINATION, может использовать «генераторные выражения» со синтаксисом $<...>. Смотрите руководство cmake-generator-expressions(7) для доступных выражений.

Установка файлов

install(<FILES|PROGRAMS> files... DESTINATION <dir>
        [PERMISSIONS permissions...]
        [CONFIGURATIONS [Debug|Release|...]]
        [COMPONENT <component>]
        [RENAME <name>] [OPTIONAL] [EXCLUDE_FROM_ALL])

Форма FILES задаёт правила для установки файлов для проекта. Имена файлов, заданные как относительные пути, интерпретируются относительно текущего каталога исходных файлов. Файлы, установленные с помощью этой формы, по умолчанию получают разрешения OWNER_WRITE, OWNER_READ, GROUP_READ, и WORLD_READ, если не указан аргумент PERMISSIONS.

Форма PROGRAMS идентична форме FILES, за исключением того, что по умолчанию разрешения установленного файла также включают OWNER_EXECUTE, GROUP_EXECUTE, и WORLD_EXECUTE. Эта форма предназначена для установки программ, которые не являются целевыми объектами, таких как скрипты оболочки. Используйте форму TARGETS для установки целевых объектов, скомпилированных в проекте.

Список files... для FILES или PROGRAMS может использовать «генераторные выражения» с синтаксисом $<...>. Смотрите руководство cmake-generator-expressions(7) для доступных выражений. Однако, если любой элемент начинается с генераторного выражения, он должен оцениваться как полный путь.

Указанное место установки файлов install DESTINATION может использовать «генераторные выражения» со синтаксисом $<...>. См. руководство cmake-generator-expressions(7) для доступных выражений.

Установка каталогов

install(DIRECTORY dirs... DESTINATION <dir>
        [FILE_PERMISSIONS permissions...]
        [DIRECTORY_PERMISSIONS permissions...]
        [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER]
        [CONFIGURATIONS [Debug|Release|...]]
        [COMPONENT <component>] [EXCLUDE_FROM_ALL]
        [FILES_MATCHING]
        [[PATTERN <pattern> | REGEX <regex>]
         [EXCLUDE] [PERMISSIONS permissions...]] [...])

Форма DIRECTORY устанавливает содержимое одного или нескольких каталогов в заданном месте назначения. Структура каталогов копируется дословно в место назначения. Последний компонент каждого имени каталога добавляется к каталогу назначения, но можно использовать обратный слэш для предотвращения этого, так как это оставляет последний компонент пустым. Имена каталогов, заданные как относительные пути, интерпретируются относительно текущего каталога исходников. Если имена входных каталогов не указаны, каталог назначения будет создан, но ничего в него установлено не будет. Опции FILE_PERMISSIONS и DIRECTORY_PERMISSIONS задают разрешения, предоставляемые файлам и каталогам в месте назначения. Если USE_SOURCE_PERMISSIONS указана, а FILE_PERMISSIONS нет, права доступа к файлам будут скопированы из структуры исходного каталога. Если разрешения не указаны, файлам будут предоставлены значения по умолчанию, указанные в форме FILES команды, а каталогам — значения по умолчанию, указанные в форме PROGRAMS команды.

Опция MESSAGE_NEVER отключает вывод статуса установки файлов.

Установка каталогов может быть настроена с высокой точностью с помощью опций PATTERN или REGEX. Эти опции «сопоставления» задают шаблон поиска или регулярное выражение для сопоставления каталогов или файлов, встречающихся в исходных каталогах. Они могут использоваться для применения определенных опций (см. ниже) к подмножеству файлов и каталогов. Полный путь к каждому входному файлу или каталогу (с помощью косых черт) сопоставляется с выражением. PATTERN будет сопоставлять только полные имена файлов: часть полного пути, соответствующая шаблону, должна находиться в конце имени файла и предшествовать косой чертой. REGEX будет сопоставлять любую часть полного пути, но может использовать / и $ для имитации поведения PATTERN. По умолчанию все файлы и каталоги устанавливаются независимо от того, соответствуют ли они шаблону или нет. Опция FILES_MATCHING может быть задана перед первой опцией сопоставления для отключения установки файлов (но не каталогов), не соответствующих ни одному выражению. Например, код

install(DIRECTORY src/ DESTINATION include/myproj
        FILES_MATCHING PATTERN "*.h")

извлечет и установит заголовочные файлы из дерева исходного кода.

Некоторые опции могут следовать за выражением PATTERN или REGEX и применяться только к файлам или каталогам, соответствующим им. Опция EXCLUDE пропустит соответствующий файл или каталог. Опция PERMISSIONS переопределяет настройки разрешений для соответствующего файла или каталога. Например, код

install(DIRECTORY icons scripts/ DESTINATION share/myproj
        PATTERN "CVS" EXCLUDE
        PATTERN "scripts/*"
        PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ
                    GROUP_EXECUTE GROUP_READ)

установит каталог icons в share/myproj/icons и каталог scripts в share/myproj. Иконки получат значения разрешений по умолчанию, скриптам будут предоставлены определенные разрешения, а любые каталоги CVS будут исключены.

Список dirs..., заданный для DIRECTORY, и место назначения, заданное для установки каталога DESTINATION, могут использовать «генераторные выражения» со синтаксисом $<...>. См. руководство cmake-generator-expressions(7) для доступных выражений.

Пользовательская логика установки

install([[SCRIPT <file>] [CODE <code>]]
        [COMPONENT <component>] [EXCLUDE_FROM_ALL] [...])

Форма SCRIPT вызовет указанные файлы сценариев CMake во время установки. Если имя файла сценария является относительным путем, оно будет интерпретироваться относительно текущего каталога исходников. Форма CODE вызовет заданный код CMake во время установки. Код задается как единственный аргумент в двойных кавычках. Например, код

install(CODE "MESSAGE(\"Sample install message.\")")

выведет сообщение во время установки.

Установка экспортов

install(EXPORT <export-name> DESTINATION <dir>
        [NAMESPACE <namespace>] [[FILE <name>.cmake]|
        [EXPORT_ANDROID_MK <name>.mk]]
        [PERMISSIONS permissions...]
        [CONFIGURATIONS [Debug|Release|...]]
        [EXPORT_LINK_INTERFACE_LIBRARIES]
        [COMPONENT <component>]
        [EXCLUDE_FROM_ALL])

Форма EXPORT генерирует и устанавливает файл CMake, содержащий код для импорта целей из дерева установки в другой проект. Установки целевых объектов связаны с экспортом <export-name> с помощью опции EXPORT подписи install(TARGETS) команды, описанной выше. Опция NAMESPACE добавит префикс <namespace> к именам целей при их записи в файл импорта. По умолчанию сгенерированный файл будет называться <export-name>.cmake, но опция FILE может использоваться для задания другого имени. Значение, заданное для опции FILE, должно быть именем файла с расширением .cmake. Если указана опция CONFIGURATIONS, файл будет установлен только при установке одной из перечисленных конфигураций. Кроме того, сгенерированный файл импорта будет ссылаться только на соответствующие конфигурации целей. Ключевое слово EXPORT_LINK_INTERFACE_LIBRARIES, если оно присутствует, приводит к экспорту содержимого свойств, соответствующих (IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?, когда политика CMP0022 установлена в NEW. Если указана опция COMPONENT, которая не соответствует заданной для целей, связанных с <export-name>, поведение не определено. Если целевой объект библиотеки включен в экспорт, но целевой объект, к которому он ссылается, не включен, поведение не определено.

Помимо файлов CMake, опция EXPORT_ANDROID_MK может использоваться для задания экспорта для системы сборки Android NDK. Android NDK поддерживает использование предварительно скомпилированных библиотек, как статических, так и динамических. Это позволяет CMake компилировать библиотеки проекта и предоставлять их системе сборки NDK, включая зависимые библиотеки, флаги включения и определения, необходимые для использования библиотек.

Форма EXPORT полезна для того, чтобы внешние проекты могли использовать цели, скомпилированные и установленные текущим проектом. Например, код

install(TARGETS myexe EXPORT myproj DESTINATION bin)
install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj)
install(EXPORT_ANDROID_MK myexp DESTINATION share/ndk-modules)

установит исполняемый файл myexe в <prefix>/bin и код для его импорта в файлы <prefix>/lib/myproj/myproj.cmake и <prefix>/lib/share/ndk-modules/Android.mk. Внешний проект может загрузить этот файл с помощью команды include и обратиться к исполняемому файлу myexe из дерева установки, используя имя импортированной цели mp_myexe, как если бы цель была скомпилирована в собственном дереве.