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(PACKAGE_INFO <package-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 является относительным путем.

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

Изменено в версии 3.31: <dir> будет нормализован в соответствии с теми же правилами нормализации, что и команда cmake_path().

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.

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

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

В отличие от других аргументов DESTINATION для различных подкоманд install(), пути, указанные после INCLUDES DESTINATION, используются как есть. Они не нормализуются, и не предполагается, что они нормализованы, хотя рекомендуется указывать их в нормализованной форме (см. Нормализация).

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

Необязательный аргумент RENAME <name> используется для задания имени устанавливаемого файла, отличного от исходного имени файла. Переименование разрешено только при установке единственного файла командой.

Должен быть указан либо аргумент 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
LIBEXEC	${CMAKE_INSTALL_LIBEXECDIR}	libexec

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

Добавлен в версии 3.31: Аргумент TYPE теперь поддерживает тип LIBEXEC.

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
LIBEXEC	${CMAKE_INSTALL_LIBEXECDIR}	libexec

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

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

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

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

Добавлена в версии 3.31: Аргумент TYPE теперь поддерживает тип LIBEXEC.

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(PACKAGE_INFO <package-name> [...])

Добавлен в версии 3.31.

Примечание

Экспериментальная опция. Включена через CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_INFO.

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

install(PACKAGE_INFO <package-name> EXPORT <export-name>
        [APPENDIX <appendix-name>]
        [DESTINATION <dir>]
        [LOWER_CASE_FILE]
        [VERSION <version>
         [COMPAT_VERSION <version>]
         [VERSION_SCHEMA <string>]]
        [DEFAULT_TARGETS <target>...]
        [DEFAULT_CONFIGURATIONS <config>...]
        [PERMISSIONS <permission>...]
        [CONFIGURATIONS <config>...]
        [COMPONENT <component>]
        [EXCLUDE_FROM_ALL])

Форма PACKAGE_INFO генерирует и устанавливает файл Common Package Specification, описывающий установленные цели, чтобы их можно было использовать в другом проекте. Установки целей связаны с экспортом <export-name> с помощью опции EXPORT в сигнатуре install(TARGETS), описанной выше. В отличие от install(EXPORT), эта информация не выражена в коде CMake и может быть использована инструментами помимо CMake. При импорте в другой проект CMake импортированные цели будут иметь префикс <package-name>::. По умолчанию сгенерированный файл будет называться <package-name>[-<appendix-name>].cps. Если задано LOWER_CASE_FILE, имя пакета в системе (в имени файла и пункте назначения установки) сначала будет преобразовано в нижний регистр.

Если DESTINATION не указано, используется платформа-зависимый стандарт.

Если указано APPENDIX, вместо генерации файла спецификации верхнего уровня, указанные цели будут экспортированы как приложение к указанному пакету. Приложения могут использоваться для разделения менее часто используемых целей (вместе с их внешними зависимостями) от остальной части пакета. Это позволяет потребителям игнорировать транзитивные зависимости для целей, которые они не используют, и также позволяет одному логическому «пакету» состоять из артефактов, созданных несколькими деревьями сборки.

Приложениям запрещено изменять основные метаданные пакета; поэтому ни VERSION, ни COMPAT_VERSION, ни VERSION_SCHEMA, ни DEFAULT_TARGETS или DEFAULT_CONFIGURATIONS не могут быть указаны в сочетании с APPENDIX. Кроме того, настоятельно рекомендуется использовать LOWER_CASE_FILE согласованно между основным пакетом и любыми приложениями.

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.