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>...

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

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