install

• Синопсис
• Введение
• Подписи

• Примеры

  • Пример: Установка целей с компонентами на артефакт
  • Пример: Установка целей в места назначения на конфигурацию
• Сгенерированный скрипт установки

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

Синопсис

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

Введение

Эта команда генерирует правила установки для проекта. Правила установки, заданные вызовами команды install() внутри директории исходного кода, выполняются в порядке следования во время установки.

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

DESTINATION <dir>

Укажите директорию на диске, в которую будет установлен файл. <dir> должна быть относительным путем. Разрешается абсолютный путь, но он не рекомендуется.

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

Поскольку абсолютные пути не работают с опцией --prefix команды cmake --install, или с установщиками генераторов cpack, настоятельно рекомендуется использовать относительные пути для наилучшей поддержки разработчиками пакетов. В частности, нет необходимости делать пути абсолютными, добавляя CMAKE_INSTALL_PREFIX; этот префикс используется по умолчанию, если DESTINATION — это относительный путь.

Если задан абсолютный путь (с ведущей косой чертой или буквой диска), он используется дословно.

PERMISSIONS <permission>...

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

Если эта опция используется несколько раз в одном вызове, её список разрешений накапливается. Если вызов install(TARGETS) использует аргументы <artifact-kind>, отдельный список разрешений накапливается для каждого вида артефакта.

CONFIGURATIONS <config>...

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

Если эта опция используется несколько раз в одном вызове, её список конфигураций накапливается. Если вызов install(TARGETS) использует аргументы <artifact-kind>, отдельный список конфигураций накапливается для каждого вида артефакта.

COMPONENT <component>

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

EXCLUDE_FROM_ALL

Новое в версии 3.6.

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

RENAME <name>

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

OPTIONAL

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

Подписи

install(TARGETS <target>... [...])

Установить целевой объект Выходные артефакты и связанные файлы:

install(TARGETS <target>... [EXPORT <export-name>]
        [RUNTIME_DEPENDENCIES <arg>...|RUNTIME_DEPENDENCY_SET <set-name>]
        [<artifact-option>...]
        [<artifact-kind> <artifact-option>...]...
        [INCLUDES DESTINATION [<dir> ...]]
        )

где группа <artifact-option>... может содержать:

[DESTINATION <dir>]
[PERMISSIONS <permission>...]
[CONFIGURATIONS <config>...]
[COMPONENT <component>]
[NAMELINK_COMPONENT <component>]
[OPTIONAL] [EXCLUDE_FROM_ALL]
[NAMELINK_ONLY|NAMELINK_SKIP]

Первая группа <artifact-option>... применяется к целевому объекту Выходные артефакты, для которого не определена отдельная группа в этом же вызове.

Каждая группа <artifact-kind> <artifact-option>... применяется к Выходным артефактам указанного типа артефакта:

ARCHIVE

Артефакты целевого объекта данного типа включают:

• Статические библиотеки (за исключением macOS, когда отмечены как FRAMEWORK, см. ниже);
• DLL-библиотеки импорта (на всех системах на базе Windows, включая Cygwin; у них расширение .lib, в отличие от библиотек .dll, которые идут в RUNTIME);
• На AIX, файл импорта линковщика, созданный для исполняемых файлов с включённым ENABLE_EXPORTS.
• На macOS, файл импорта линковщика, созданный для общих библиотек с включённым ENABLE_EXPORTS (за исключением случаев, когда отмечены как FRAMEWORK, см. ниже).

LIBRARY

Артефакты целевого объекта данного типа включают:

• Общие библиотеки, за исключением

  • DLL (они идут в RUNTIME, см. ниже),
  • на macOS, когда помечены как FRAMEWORK (см. ниже).

RUNTIME

Артефакты целевого объекта данного типа включают:

• Исполняемые файлы (за исключением macOS, когда отмечены как MACOSX_BUNDLE, см. BUNDLE ниже);
• DLL (на всех системах на базе Windows, включая Cygwin; обратите внимание, что сопровождающие библиотеки импорта относятся к типу ARCHIVE).

OBJECTS

Новое в версии 3.9.

Объектные файлы, связанные с библиотеками объектов.

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.

FILE_SET <set-name>

Новое в версии 3.23.

Наборы файлов определяются командой target_sources(FILE_SET). Если набор файлов <set-name> существует и имеет тип PUBLIC или INTERFACE, все файлы в наборе устанавливаются в указанное место назначения (см. ниже). Структура каталогов относительно базовых каталогов набора файлов сохраняется. Например, файл, добавленный в набор файлов как /blah/include/myproj/here.h с базовым каталогом /blah/include, будет установлен в myproj/here.h под местом назначения.

CXX_MODULES_BMI

Новое в версии 3.28.

Все файлы модулей из C++-модулей из PUBLIC источников в наборе файлов типа CXX_MODULES будут установлены в указанное DESTINATION. Все модули помещаются непосредственно в место назначения, так как структура каталогов не извлекается из имён модулей. Пустой DESTINATION может использоваться для подавления установки этих файлов (для использования в общем коде).

Для обычных исполняемых файлов, статических и общих библиотек, аргумент DESTINATION не требуется. Для этих типов целевых объектов, когда DESTINATION отсутствует, место назначения будет взято из соответствующей переменной из GNUInstallDirs или установлено по умолчанию, если эта переменная не определена. То же самое относится к наборам файлов, а также к общедоступным и закрытым заголовкам, связанным с установленными целевыми объектами через свойства целевых объектов PUBLIC_HEADER и PRIVATE_HEADER. Для модульных библиотек, пакетов Apple и фреймворков место назначения всегда должно быть указано. Для интерфейсных и объектных библиотек место назначения можно опустить, но они обрабатываются иначе (см. обсуждение этого вопроса в конце этого раздела).

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

В следующей таблице показаны типы целевых объектов, связанные переменные и встроенные значения по умолчанию, которые применяются, если место назначения не задано:

Тип целевого объекта	Переменная GNUInstallDirs	Встроенное значение по умолчанию
RUNTIME	${CMAKE_INSTALL_BINDIR}	bin
LIBRARY	${CMAKE_INSTALL_LIBDIR}	lib
ARCHIVE	${CMAKE_INSTALL_LIBDIR}	lib
PRIVATE_HEADER	${CMAKE_INSTALL_INCLUDEDIR}	include
PUBLIC_HEADER	${CMAKE_INSTALL_INCLUDEDIR}	include
FILE_SET (тип HEADERS)	${CMAKE_INSTALL_INCLUDEDIR}	include

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

Для обеспечения соответствия пакетов политикам расположения файлов системы распределения, если проекты должны указать DESTINATION, настоятельно рекомендуется использовать путь, начинающийся с соответствующей относительной переменной GNUInstallDirs. Это позволяет хранителям пакетов контролировать место установки, устанавливая соответствующие переменные кэша. Следующий пример демонстрирует установку статической библиотеки в место назначения по умолчанию, предоставляемое GNUInstallDirs, но с установкой заголовков в подкаталог, специфичный для проекта, без использования наборов файлов:

add_library(mylib STATIC ...)
set_target_properties(mylib PROPERTIES PUBLIC_HEADER mylib.h)
include(GNUInstallDirs)
install(TARGETS mylib
        PUBLIC_HEADER
          DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
)

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

NAMELINK_COMPONENT

Новое в версии 3.12.

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

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

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

Изменено в версии 3.27: Этот параметр также пригоден для блока ARCHIVE для управления файлом импорта компоновщика, создаваемым на macOS для общих библиотек с включенным ENABLE_EXPORTS.

См. Пример: Установка целей с компонентами для каждого артефакта для примера использования NAMELINK_COMPONENT.

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

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

NAMELINK_ONLY

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

Изменено в версии 3.27: Этот параметр также пригоден для блока ARCHIVE для управления файлом импорта компоновщика, создаваемым на macOS для общих библиотек с включенным ENABLE_EXPORTS.

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

NAMELINK_SKIP

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

Изменено в версии 3.27: Этот параметр также пригоден для блока ARCHIVE для управления файлом импорта компоновщика, создаваемым на macOS для общих библиотек с включенным ENABLE_EXPORTS.

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

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

EXPORT

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

Если используется EXPORT, а среди целей есть наборы файлов PUBLIC или INTERFACE, все они должны быть указаны с аргументами FILE_SET. Все наборы файлов PUBLIC или INTERFACE , связанные с целевым объектом, включаются в экспорт.

INCLUDES DESTINATION

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

RUNTIME_DEPENDENCY_SET <set-name>

Новое в версии 3.21.

Этот параметр добавляет все зависимости времени выполнения установленных исполняемых файлов, общих библиотек и модулей к указанному набору зависимостей времени выполнения. Этот набор затем может быть установлен с помощью команды install(RUNTIME_DEPENDENCY_SET).

Этот ключ и ключ RUNTIME_DEPENDENCIES взаимоисключающие.

RUNTIME_DEPENDENCIES <arg>...

Новое в версии 3.21.

Этот параметр устанавливает все зависимости времени выполнения установленных исполняемых файлов, общих библиотек и модулей вместе с самими целями. Используются аргументы RUNTIME, LIBRARY, FRAMEWORK, и универсальные аргументы для определения свойств (DESTINATION, COMPONENT, и т.д.) установки этих зависимостей.

RUNTIME_DEPENDENCIES семантически эквивалентно следующей паре вызовов:

install(TARGETS ... RUNTIME_DEPENDENCY_SET <set-name>)
install(RUNTIME_DEPENDENCY_SET <set-name> <arg>...)

где <set-name> будет случайным именем набора. <arg>... может содержать любые из следующих ключей, поддерживаемых командой install(RUNTIME_DEPENDENCY_SET):

• DIRECTORIES
• PRE_INCLUDE_REGEXES
• PRE_EXCLUDE_REGEXES
• POST_INCLUDE_REGEXES
• POST_EXCLUDE_REGEXES
• POST_INCLUDE_FILES
• POST_EXCLUDE_FILES

Ключи RUNTIME_DEPENDENCIES и RUNTIME_DEPENDENCY_SET взаимоисключающие.

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

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

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

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

install(IMPORTED_RUNTIME_ARTIFACTS <target>... [...])

Новое в версии 3.21.

Установка артефактов выполнения импортированных целей:

install(IMPORTED_RUNTIME_ARTIFACTS <target>...
        [RUNTIME_DEPENDENCY_SET <set-name>]
        [[LIBRARY|RUNTIME|FRAMEWORK|BUNDLE]
         [DESTINATION <dir>]
         [PERMISSIONS <permission>...]
         [CONFIGURATIONS <config>...]
         [COMPONENT <component>]
         [OPTIONAL] [EXCLUDE_FROM_ALL]
        ] [...]
        )

Форма IMPORTED_RUNTIME_ARTIFACTS задаёт правила для установки артефактов выполнения импортированных целей. Проекты могут делать это, если они хотят объединить внешние исполняемые файлы или модули в свою установку. Аргументы LIBRARY, RUNTIME, FRAMEWORK, и BUNDLE имеют такое же семантическое значение, как и в режиме ЦЕЛЕЙ. Устанавливаются только артефакты выполнения импортированных целей (кроме случаев с библиотеками FRAMEWORK, исполняемыми файлами MACOSX_BUNDLE, и CFBundles BUNDLE). Например, заголовки и библиотеки импорта, связанные с DLL, не устанавливаются. В случае с библиотеками FRAMEWORK, исполняемыми файлами MACOSX_BUNDLE и CFBundles BUNDLE устанавливается весь каталог.

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

install(FILES <file>... [...])

install(PROGRAMS <program>... [...])

Примечание

При установке заголовочных файлов рекомендуется использовать наборы файлов, определённые с помощью target_sources(FILE_SET). Наборы файлов связывают заголовки с целью, и они устанавливаются в качестве части цели.

Установка файлов или программ:

install(<FILES|PROGRAMS> <file>...
        TYPE <type> | DESTINATION <dir>
        [PERMISSIONS <permission>...]
        [CONFIGURATIONS <config>...]
        [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) для доступных выражений. Однако, если любой элемент начинается с генераторского выражения, он должен вычисляться в полный путь.

Должен быть указан либо аргумент TYPE, либо аргумент DESTINATION, но не оба. Аргумент TYPE указывает общий тип файла устанавливаемых файлов. Затем путь назначения будет автоматически установлен, взяв соответствующую переменную из GNUInstallDirs, или используя встроенное значение по умолчанию, если эта переменная не определена. В таблице ниже приведены поддерживаемые типы файлов и соответствующие переменные, а также встроенные значения по умолчанию.

Аргумент TYPE	Переменная GNUInstallDirs	Встроенное значение по умолчанию
BIN	${CMAKE_INSTALL_BINDIR}	bin
SBIN	${CMAKE_INSTALL_SBINDIR}	sbin
LIB	${CMAKE_INSTALL_LIBDIR}	lib
INCLUDE	${CMAKE_INSTALL_INCLUDEDIR}	include
SYSCONF	${CMAKE_INSTALL_SYSCONFDIR}	etc
SHAREDSTATE	${CMAKE_INSTALL_SHARESTATEDIR}	com
LOCALSTATE	${CMAKE_INSTALL_LOCALSTATEDIR}	var
RUNSTATE	${CMAKE_INSTALL_RUNSTATEDIR}	<LOCALSTATE dir>/run
DATA	${CMAKE_INSTALL_DATADIR}	<DATAROOT dir>
INFO	${CMAKE_INSTALL_INFODIR}	<DATAROOT dir>/info
LOCALE	${CMAKE_INSTALL_LOCALEDIR}	<DATAROOT dir>/locale
MAN	${CMAKE_INSTALL_MANDIR}	<DATAROOT dir>/man
DOC	${CMAKE_INSTALL_DOCDIR}	<DATAROOT dir>/doc

Проектам, желающим следовать общепринятой практике установки заголовков в подкаталоге проекта, нужно указать место назначения, а не полагаться на вышеперечисленное. Использование наборов файлов для заголовков вместо install(FILES) было бы ещё лучше (см. target_sources(FILE_SET)).

Обратите внимание, что некоторые встроенные значения по умолчанию для типов используют директорию DATAROOT в качестве префикса. Префикс DATAROOT рассчитывается аналогично типам, используя переменную CMAKE_INSTALL_DATAROOTDIR и встроенное значение по умолчанию share. Вы не можете использовать DATAROOT как параметр TYPE; пожалуйста, используйте DATA вместо этого.

Для обеспечения соответствия пакетов политикам расположения файлов системы распространения, если проекты должны указать DESTINATION, настоятельно рекомендуется использовать путь, начинающийся с соответствующей относительной переменной GNUInstallDirs. Это позволяет поддерживающим пакет специалистам управлять местом установки, установив соответствующие переменные кэша. Следующий пример демонстрирует, как последовать этому совету при установке изображения в подкаталог документации проекта:

include(GNUInstallDirs)
install(FILES logo.png
        DESTINATION ${CMAKE_INSTALL_DOCDIR}/myproj
)

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

Новое в версии 3.20: Переименование установки, заданное как аргумент RENAME, может использовать "генераторские выражения" с синтаксисом $<...>. См. руководство cmake-generator-expressions(7) для доступных выражений.

install(DIRECTORY <dir>... [...])

Примечание

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

Установить содержимое одного или нескольких каталогов:

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

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

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

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

install(DIRECTORY src/ DESTINATION doc/myproj
        FILES_MATCHING PATTERN "*.png")

извлечёт и установит изображения из дерева исходного кода.

Некоторые опции могут следовать за выражением PATTERN или REGEX, как описано в разделе string(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 будут исключены.

Должен быть указан либо TYPE, либо DESTINATION, но не оба. Аргумент TYPE указывает общий тип файла файлов в указанных каталогах, которые будут устанавливаться. Пункт назначения будет затем автоматически установлен, взяв соответствующую переменную из GNUInstallDirs, или используя встроенное значение по умолчанию, если эта переменная не определена. В таблице ниже представлены поддерживаемые типы файлов и соответствующие переменные и встроенные значения по умолчанию.

TYPE Аргумент	Переменная GNUInstallDirs	Встроенное значение по умолчанию
BIN	${CMAKE_INSTALL_BINDIR}	bin
SBIN	${CMAKE_INSTALL_SBINDIR}	sbin
LIB	${CMAKE_INSTALL_LIBDIR}	lib
INCLUDE	${CMAKE_INSTALL_INCLUDEDIR}	include
SYSCONF	${CMAKE_INSTALL_SYSCONFDIR}	etc
SHAREDSTATE	${CMAKE_INSTALL_SHARESTATEDIR}	com
LOCALSTATE	${CMAKE_INSTALL_LOCALSTATEDIR}	var
RUNSTATE	${CMAKE_INSTALL_RUNSTATEDIR}	<LOCALSTATE dir>/run
DATA	${CMAKE_INSTALL_DATADIR}	<DATAROOT dir>
INFO	${CMAKE_INSTALL_INFODIR}	<DATAROOT dir>/info
LOCALE	${CMAKE_INSTALL_LOCALEDIR}	<DATAROOT dir>/locale
MAN	${CMAKE_INSTALL_MANDIR}	<DATAROOT dir>/man
DOC	${CMAKE_INSTALL_DOCDIR}	<DATAROOT dir>/doc

Обратите внимание, что некоторые встроенные значения по умолчанию для типов используют каталог DATAROOT в качестве префикса. Префикс DATAROOT рассчитывается аналогично типам, с CMAKE_INSTALL_DATAROOTDIR в качестве переменной и share в качестве встроенного значения по умолчанию. Вы не можете использовать DATAROOT в качестве параметра TYPE; используйте DATA вместо этого.

Для обеспечения совместимости пакетов с политиками структуры файловой системы дистрибутива, если проекты должны указать DESTINATION, настоятельно рекомендуется использовать путь, начинающийся с соответствующей относительной переменной GNUInstallDirs. Это позволяет администраторам пакетов контролировать пункт назначения установки, устанавливая соответствующие переменные кэша.

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

Новое в версии 3.5: Список dirs... , переданных в DIRECTORY, также может использовать «генераторские выражения».

install(SCRIPT <file> [...])

install(CODE <code> [...])

Вызвать скрипты CMake или код во время установки:

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

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

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

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

Новое в версии 3.21: Когда указана опция ALL_COMPONENTS, код пользовательского скрипта установки будет выполняться для каждого компонента установки, специфичной для компонента. Эта опция несовместима с опцией COMPONENT.

Новое в версии 3.14: <file> или <code> могут использовать «генераторские выражения» с синтаксисом $<...> (в случае с <file>, это относится к их использованию в имени файла, а не к содержимому файла). См. руководство cmake-generator-expressions(7) для доступных выражений.

install(EXPORT <export-name> [...])

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

install(EXPORT <export-name> DESTINATION <dir>
        [NAMESPACE <namespace>] [FILE <name>.cmake]
        [PERMISSIONS <permission>...]
        [CONFIGURATIONS <config>...]
        [CXX_MODULES_DIRECTORY <directory>]
        [EXPORT_LINK_INTERFACE_LIBRARIES]
        [COMPONENT <component>]
        [EXCLUDE_FROM_ALL]
        [EXPORT_PACKAGE_DEPENDENCIES])
install(EXPORT_ANDROID_MK <export-name> DESTINATION <dir> [...])

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

Примечание

Установленный файл <export-name>.cmake может поставляться с дополнительными файлами <export-name>-*.cmake для каждой конфигурации, которые будут загружаться с помощью шаблонов. Не используйте имя экспорта, совпадающее с именем пакета в сочетании с установкой файла <package-name>-config.cmake, так как последний может быть неправильно сопоставлен шаблоном и загружен.

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

Новое в версии 3.7: В дополнение к файлам языка cmake, режим EXPORT_ANDROID_MK может использоваться для указания экспорта для системы сборки android ndk. Этот режим принимает те же опции, что и обычный режим экспорта. Android NDK поддерживает использование предварительно собранных библиотек, как статических, так и общих. Это позволяет cmake собирать библиотеки проекта и делать их доступными для системы сборки ndk с полным набором транзитивных зависимостей, флагов включения и определений, необходимых для использования библиотек.

CXX_MODULES_DIRECTORY

Новое в версии 3.28.

Указать подкаталог для хранения информации о модулях C++ для целевых объектов в наборе экспорта. Этот каталог будет заполнен файлами, которые добавляют необходимую информацию о свойствах целевых объектов в соответствующие целевые объекты. Обратите внимание, что без этой информации ни один из модулей C++, входящих в состав целевых объектов в наборе экспорта, не сможет быть импортирован в целевые объекты, которые их используют.

EXPORT_PACKAGE_DEPENDENCIES

Примечание

Экспериментально. Ограничено CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_DEPENDENCIES.

Указать, что вызовы find_dependency() должны быть экспортированы. Если этот аргумент указан, CMake анализирует все целевые объекты в наборе экспорта и собирает их зависимые целевые объекты для линковки. Если такие целевые объекты были найдены с помощью find_package() или имеют установленное свойство EXPORT_FIND_PACKAGE_NAME, и такая зависимость пакета не была отключена путём передачи ENABLED OFF в export(SETUP), то вызов find_dependency() записывается с именем пакета соответствующего целевого объекта, аргументом REQUIRED и любыми дополнительными аргументами, указанными в аргументе EXTRA_ARGS вызова export(SETUP). Любые зависимости пакетов, которые были указаны вручную путём передачи ENABLED ON в export(SETUP), также добавляются, даже если экспортируемые целевые объекты не зависят от каких-либо целевых объектов из них.

Вызовы find_dependency() записываются в следующем порядке:

1. Любые зависимости пакетов, перечисленные в export(SETUP), записываются в порядке их первоначального указания, независимо от того, содержат ли они зависимости INTERFACE экспортируемых целевых объектов.
2. Любые зависимости пакетов, содержащие зависимости INTERFACE для линковки экспортируемых целевых объектов и которые никогда не были указаны в export(SETUP), записываются в порядке их первого обнаружения.

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

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

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

install(RUNTIME_DEPENDENCY_SET <set-name> [...])

Новое в версии 3.21.

Устанавливает набор зависимостей времени выполнения:

install(RUNTIME_DEPENDENCY_SET <set-name>
        [[LIBRARY|RUNTIME|FRAMEWORK]
         [DESTINATION <dir>]
         [PERMISSIONS <permission>...]
         [CONFIGURATIONS <config>...]
         [COMPONENT <component>]
         [NAMELINK_COMPONENT <component>]
         [OPTIONAL] [EXCLUDE_FROM_ALL]
        ] [...]
        [PRE_INCLUDE_REGEXES <regex>...]
        [PRE_EXCLUDE_REGEXES <regex>...]
        [POST_INCLUDE_REGEXES <regex>...]
        [POST_EXCLUDE_REGEXES <regex>...]
        [POST_INCLUDE_FILES <file>...]
        [POST_EXCLUDE_FILES <file>...]
        [DIRECTORIES <dir>...]
        )

Устанавливает набор зависимостей времени выполнения, ранее созданный одной или несколькими командами install(TARGETS) или install(IMPORTED_RUNTIME_ARTIFACTS). Зависимости целевых объектов, принадлежащих набору зависимостей времени выполнения, устанавливаются в назначение RUNTIME и компонент на платформах DLL, и в назначение LIBRARY и компонент на платформах, не являющихся DLL. Фреймворки macOS устанавливаются в назначение FRAMEWORK и компонент. Целевые объекты, собранные в дереве сборки, никогда не будут установлены в качестве зависимостей времени выполнения, также как и их собственные зависимости, если сами целевые объекты не установлены с помощью install(TARGETS).

Сгенерированный скрипт установки вызывает file(GET_RUNTIME_DEPENDENCIES) для файлов дерева сборки, чтобы рассчитать зависимости времени выполнения. Файлы исполняемых файлов дерева сборки передаются как аргумент EXECUTABLES, файлы общих библиотек дерева сборки как аргумент LIBRARIES, а файлы модулей дерева сборки как аргумент MODULES. На macOS, если один из исполняемых файлов является MACOSX_BUNDLE, этот исполняемый файл передаётся как аргумент BUNDLE_EXECUTABLE. На macOS в наборе зависимостей времени выполнения может быть не более одного такого исполняемого файла-пакета. Свойство MACOSX_BUNDLE не имеет эффекта на других платформах. Обратите внимание, что file(GET_RUNTIME_DEPENDENCIES) поддерживает сборку зависимостей времени выполнения только для платформ Windows, Linux и macOS, поэтому install(RUNTIME_DEPENDENCY_SET) имеет такое же ограничение.

Следующие подаргументы передаются как соответствующие аргументы в file(GET_RUNTIME_DEPENDENCIES) (для тех, которые предоставляют непустой список каталогов, регулярных выражений или файлов). Все они поддерживают generator expressions.

• DIRECTORIES <dir>...
• PRE_INCLUDE_REGEXES <regex>...
• PRE_EXCLUDE_REGEXES <regex>...
• POST_INCLUDE_REGEXES <regex>...
• POST_EXCLUDE_REGEXES <regex>...
• POST_INCLUDE_FILES <file>...
• POST_EXCLUDE_FILES <file>...

Примеры

Пример: Установка целей с компонентами для каждого артефакта

Рассмотрим проект, который определяет цели с разными типами артефактов:

add_executable(myExe myExe.c)
add_library(myStaticLib STATIC myStaticLib.c)
target_sources(myStaticLib PUBLIC FILE_SET HEADERS FILES myStaticLib.h)
add_library(mySharedLib SHARED mySharedLib.c)
target_sources(mySharedLib PUBLIC FILE_SET HEADERS FILES mySharedLib.h)
set_property(TARGET mySharedLib PROPERTY SOVERSION 1)

Мы можем вызвать install(TARGETS) с аргументами <artifact-kind>, чтобы указать разные параметры для каждого типа артефакта:

install(TARGETS
          myExe
          mySharedLib
          myStaticLib
        RUNTIME           # Following options apply to runtime artifacts.
          COMPONENT Runtime
        LIBRARY           # Following options apply to library artifacts.
          COMPONENT Runtime
          NAMELINK_COMPONENT Development
        ARCHIVE           # Following options apply to archive artifacts.
          COMPONENT Development
          DESTINATION lib/static
        FILE_SET HEADERS  # Following options apply to file set HEADERS.
          COMPONENT Development
        )

Это будет:

• Установить myExe в <prefix>/bin, стандартное расположение артефакта RUNTIME, как часть компонента Runtime.

• На платформах, не использующих DLL:

  • Установить libmySharedLib.so.1 в <prefix>/lib, стандартное расположение артефакта LIBRARY, как часть компонента Runtime.
  • Установить libmySharedLib.so «namelink» (символическую ссылку) в <prefix>/lib, стандартное расположение артефакта LIBRARY, как часть компонента Development.

• На платформах, использующих DLL:

  • Установить mySharedLib.dll в <prefix>/bin, стандартное расположение артефакта RUNTIME, как часть компонента Runtime.
  • Установить mySharedLib.lib в <prefix>/lib/static, указанное расположение артефакта ARCHIVE, как часть компонента Development.
• Установить myStaticLib в <prefix>/lib/static, указанное расположение артефакта ARCHIVE, как часть компонента Development.
• Установить mySharedLib.h и myStaticLib.h в <prefix>/include, стандартное расположение набора файлов типа HEADERS, как часть компонента Development.

Пример: Установка целей в расположения, зависящие от конфигурации

Каждый вызов install(TARGETS) устанавливает заданный целевой артефакт вывода в не более чем одном DESTINATION, но само правило установки может быть отфильтровано параметром CONFIGURATIONS. Для установки в разное расположение для каждой конфигурации требуется по одному вызову для каждой конфигурации. Например, код:

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

установит myExe в <prefix>/Debug/bin в конфигурации Debug и в <prefix>/Release/bin в конфигурации Release.

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

Команда 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.