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(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 в OS X (см. FRAMEWORK ниже). Для платформ DLL (все системы на базе Windows, включая Cygwin), библиотека импорта DLL рассматривается как ARCHIVE цель.

LIBRARY

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

RUNTIME

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

OBJECTS

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

FRAMEWORK

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

BUNDLE

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

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 — имя библиотеки, а lib<name>.so — «имя ссылки», позволяющее компоновщикам найти библиотеку при указании -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, имеет неопределённое поведение.

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