install

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

Синопсис

install(TARGETS <target>... [...])
install({FILES | PROGRAMS} <file>... DESTINATION <dir> [...])
install(DIRECTORY <dir>... DESTINATION <dir> [...])
install(SCRIPT <file> [...])
install(CODE <code> [...])
install(EXPORT <export-name> DESTINATION <dir> [...])

Введение

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

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

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

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

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() неявно создают директории, содержащие устанавливаемые файлы. Если установлена переменная CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS, эти директории будут созданы с указанными правами доступа. В противном случае они будут созданы в соответствии с правилами uname на платформах, подобных Unix. Платформы Windows не затронуты.

Установка целей

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>]
         [NAMELINK_COMPONENT <component>]
         [OPTIONAL] [EXCLUDE_FROM_ALL]
         [NAMELINK_ONLY|NAMELINK_SKIP]
        ] [...]
        [INCLUDES DESTINATION [<dir> ...]]
        )

Формат TARGETS задаёт правила установки целей из проекта. Существует несколько типов файлов целей, которые могут быть установлены:

ARCHIVE

Статические библиотеки обрабатываются как ARCHIVE цели, за исключением тех, которые помечены свойством FRAMEWORK на macOS (см. FRAMEWORK ниже). Для платформ DLL (все системы на базе Windows, включая Cygwin), DLL-импортная библиотека обрабатывается как ARCHIVE цель.

LIBRARY

Модульные библиотеки всегда обрабатываются как LIBRARY цели. Для платформ, не являющихся DLL, общие библиотеки обрабатываются как LIBRARY цели, за исключением тех, которые помечены свойством FRAMEWORK на macOS (см. FRAMEWORK ниже).

RUNTIME

Исполняемые файлы обрабатываются как RUNTIME объекты, за исключением тех, которые помечены свойством MACOSX_BUNDLE на macOS (см. BUNDLE ниже). Для платформ DLL (все системы на базе Windows, включая Cygwin), DLL-часть общей библиотеки обрабатывается как RUNTIME цель.

OBJECTS

Библиотеки объектов (простая группа файлов объектов) всегда обрабатываются как OBJECTS цели.

FRAMEWORK

Статические и общие библиотеки, помеченные свойством FRAMEWORK, обрабатываются как FRAMEWORK цели на macOS.

BUNDLE

Исполняемые файлы, помеченные свойством MACOSX_BUNDLE, обрабатываются как BUNDLE цели на macOS.

PUBLIC_HEADER

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

PRIVATE_HEADER

Аналогично PUBLIC_HEADER, но для файлов PRIVATE_HEADER. Подробности см. в PRIVATE_HEADER.

RESOURCE

Аналогично PUBLIC_HEADER и PRIVATE_HEADER, но для файлов RESOURCE. Подробности см. в RESOURCE.

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

В дополнение к общим параметрам, перечисленным выше, каждая цель может принимать следующие дополнительные аргументы:

NAMELINK_COMPONENT

На некоторых платформах версия библиотеки общего использования имеет символическую ссылку, например:

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

где lib<name>.so.1 — soname библиотеки, а lib<name>.so — «namelink», позволяющий линковщику найти библиотеку, когда ей передаётся -l<name>. Параметр NAMELINK_COMPONENT аналогичен параметру COMPONENT, но он изменяет компонент установки имени ссылки общей библиотеки, если она генерируется. Если не указано, он по умолчанию равен значению COMPONENT. Использование этого параметра вне блока LIBRARY является ошибкой.

Рассмотрим следующий пример:

install(TARGETS mylib
        LIBRARY
          DESTINATION lib
          COMPONENT Libraries
          NAMELINK_COMPONENT Development
        PUBLIC_HEADER
          DESTINATION include
          COMPONENT Development
       )

В этом случае, если вы выберете установку только компонента Development, будут установлены заголовки и имя ссылки без библиотеки. (Если вы также не установите компонент Libraries, имя ссылки станет висящей символической ссылкой, и проекты, которые ссылаются на библиотеку, будут иметь ошибки сборки.) Если вы установите только компонент Libraries, будет установлена только библиотека без заголовков и имени ссылки.

Этот параметр обычно используется для систем управления пакетами, которые имеют отдельные пакеты выполнения и разработки. Например, в системах Debian библиотека должна находиться в пакете выполнения, а заголовки и имя ссылки — в пакете разработки.

См. свойства целей VERSION и SOVERSION для получения подробной информации о создании версии библиотек общего использования.

NAMELINK_ONLY

Этот параметр вызывает установку только имени ссылки, когда устанавливается библиотечная цель. На платформах, где версии библиотек общего использования не имеют имен ссылок или когда библиотека не имеет версий, параметр NAMELINK_ONLY ничего не устанавливает. Использование этого параметра вне блока LIBRARY является ошибкой.

При задании NAMELINK_ONLY, можно использовать либо NAMELINK_COMPONENT, либо COMPONENT, но COMPONENT обычно предпочтительнее.

NAMELINK_SKIP

Аналогично NAMELINK_ONLY, но имеет обратный эффект: вызывает установку файлов библиотеки, отличных от имени ссылки, при установке библиотечной цели. Когда ни NAMELINK_ONLY, ни NAMELINK_SKIP не заданы, устанавливаются обе части. На платформах, где версии библиотек общего использования не имеют символических ссылок или когда библиотека не имеет версии, NAMELINK_SKIP устанавливает библиотеку. Использование этого параметра вне блока LIBRARY является ошибкой.

Если указан NAMELINK_SKIP, NAMELINK_COMPONENT не имеет эффекта. Не рекомендуется использовать NAMELINK_SKIP в сочетании с NAMELINK_COMPONENT.

Команда install(TARGETS) также может принимать следующие параметры на верхнем уровне:

EXPORT

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

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 mySharedLib DLL будет установлен в <prefix>/bin и /some/full/path, а его библиотека импорта — в <prefix>/lib/static и /some/full/path.

Библиотеки интерфейса могут быть указаны среди устанавливаемых целевых объектов. Они не устанавливают какие-либо артефакты, но будут включены в ассоциированный EXPORT. Если указаны Библиотеки объектов, но не указано назначение для файлов объектов, они будут экспортированы как Библиотеки интерфейса. Это достаточно для удовлетворения требований транзитивной зависимости других целевых объектов, которые ссылаются на библиотеки объектов в своей реализации.

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

install(TARGETS) может устанавливать целевые объекты, созданные в других каталогах. При использовании таких правил установки между каталогами, выполнение make install (или аналогичных команд) из подкаталога не гарантирует, что целевые объекты из других каталогов будут обновлены. Вы можете использовать target_link_libraries() или add_dependencies(), чтобы убедиться, что такие целевые объекты из других каталогов скомпилированы перед выполнением правил установки, специфичных для подкаталога.

Назначение установки целевого объекта 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) для доступных выражений. Однако, если любой элемент начинается с генераторского выражения, он должен быть полным путём.

Назначение установки файлов 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 устанавливает содержимое одного или нескольких каталогов в указанное расположение. Структура каталогов копируется точно в место назначения. Последний компонент каждого имени каталога добавляется к каталогу назначения, но trailing slash можно использовать, чтобы этого избежать, так как это оставляет последний компонент пустым. Имена каталогов, заданные как относительные пути, интерпретируются относительно текущего каталога исходных файлов. Если не указано ни одного имени входного каталога, каталог назначения будет создан, но ничего не будет установлено в него. Параметры 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]|
        [PERMISSIONS permissions...]
        [CONFIGURATIONS [Debug|Release|...]]
        [EXPORT_LINK_INTERFACE_LIBRARIES]
        [COMPONENT <component>]
        [EXCLUDE_FROM_ALL])
install(EXPORT_ANDROID_MK <export-name> DESTINATION <dir> [...])

Форма 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, перечисленный <component> неявно зависит от всех компонентов, упомянутых в наборе экспорта. Экспортированный <name>.cmake файл потребует наличия каждого экспортированного компонента для корректной сборки зависимых проектов. Например, проект может определить компоненты Runtime и Development, при этом общие библиотеки будут помещены в компонент Runtime, а статические библиотеки и заголовки — в компонент Development. Набор экспорта также обычно является частью компонента Development, но он будет экспортировать цели как из компонента Runtime, так и из компонента Development. Следовательно, компонент Runtime необходимо установить, если установлен компонент Development, но не наоборот. Если компонент Development установлен без компонента Runtime, зависимые проекты, пытающиеся связаться с ним, получат ошибки сборки. Упаковщики пакетов, такие как APT и RPM, обычно обрабатывают это, указав компонент Runtime как зависимость компонента Development в метаданных пакета, гарантируя, что библиотека всегда устанавливается, если присутствуют заголовки и файл экспорта CMake.

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

Скрипт сгенерированной установки

Команда install() генерирует файл cmake_install.cmake внутри каталога сборки, который используется внутренне сгенерированной целью установки и CPack. Вы также можете вызвать этот скрипт вручную с помощью cmake -P. Этот скрипт принимает несколько переменных:

COMPONENT

Установите эту переменную, чтобы установить только один компонент CPack, а не все. Например, если вы хотите установить только компонент Development, запустите cmake -DCOMPONENT=Development -P cmake_install.cmake.

BUILD_TYPE

Установите эту переменную, чтобы изменить тип сборки, если вы используете генератор с несколькими конфигурациями. Например, чтобы установить с конфигурацией Debug, запустите cmake -DBUILD_TYPE=Debug -P cmake_install.cmake.

DESTDIR

Это переменная окружения, а не переменная CMake. Она позволяет изменить префикс установки в системах UNIX. См. DESTDIR для получения подробностей.