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

Укажите список конфигураций сборки, для которых применяется правило установки (Отладка, Релиз и т. д.). Обратите внимание, что значения, указанные для этого параметра, применяются только к параметрам, перечисленным ПОСЛЕ параметра CONFIGURATIONS. Например, чтобы задать отдельные пути установки для конфигураций Отладка и Релиз, выполните следующее:

install(TARGETS target
        CONFIGURATIONS Debug
        RUNTIME DESTINATION Debug/bin)
install(TARGETS target
        CONFIGURATIONS Release
        RUNTIME DESTINATION Release/bin)

Обратите внимание, что CONFIGURATIONS предшествует RUNTIME DESTINATION.

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|OBJECTS|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, OBJECTS, FRAMEWORK, и BUNDLE. Исполняемые файлы обрабатываются как целевые объекты RUNTIME, за исключением тех, которые помечены свойством MACOSX_BUNDLE, которые обрабатываются как целевые объекты BUNDLE на платформе OS X. Статические библиотеки обрабатываются как целевые объекты ARCHIVE, за исключением тех, которые помечены свойством FRAMEWORK, которые обрабатываются как целевые объекты FRAMEWORK на платформе OS X. Модульные библиотеки всегда обрабатываются как целевые объекты LIBRARY. Для платформ, не использующих DLL, динамические библиотеки обрабатываются как целевые объекты LIBRARY, за исключением тех, которые помечены свойством FRAMEWORK, которые обрабатываются как целевые объекты FRAMEWORK на платформе OS X. Для платформ DLL, часть DLL динамической библиотеки обрабатывается как целевой объект RUNTIME, а соответствующая библиотека импорта обрабатывается как целевой объект ARCHIVE. Все системы на базе Windows, включая Cygwin, являются платформами DLL. Библиотеки объектов всегда обрабатываются как целевые объекты OBJECTS. Аргументы ARCHIVE, LIBRARY, RUNTIME, OBJECTS, и 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, или OBJECTS. Чтобы фактически установить сам файл экспорта, вызовите 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 и установленное расположение, заданное для директории install 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, как если бы целевой элемент был построен в своём собственном дереве.