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(SBOM <sbom-name> [...])

Введение

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

Общие параметры

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

DESTINATION <dir>

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

Добавлено в версии 4.4: Диагностику CMD_INSTALL_ABSOLUTE_DESTINATION можно включить, чтобы выдавать предупреждение или ошибку при указании абсолютного пути назначения.

Если задан относительный путь, он интерпретируется относительно значения переменной 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>...

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

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

COMPONENT <component>

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

Компоненты установки можно использовать с параметром --component команды cmake --install и с модулем CPackComponent. Глобальная цель list_install_components содержит список всех доступных компонентов.

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, в macOS рассматриваются как целевые объекты FRAMEWORK.

BUNDLE

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

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, все файлы типа HEADERS из этого набора устанавливаются в указанное место назначения (см. ниже). Для файлов других типов место назначения по умолчанию не задано, поэтому для каждого FILE_SET необходимо указать параметр DESTINATION. Структура каталогов относительно базовых каталогов набора файлов сохраняется. Например, файл, добавленный в набор файлов как /blah/include/myproj/here.h с базовым каталогом /blah/include, будет установлен в myproj/here.h внутри места назначения.

CXX_MODULES_BMI

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

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

Для обычных исполняемых файлов, статических и динамических библиотек аргумент DESTINATION не требуется. Если для этих типов целей параметр DESTINATION опущен, место назначения по умолчанию берётся из соответствующей переменной модуля GNUInstallDirs либо задаётся встроенным значением по умолчанию, если эта переменная не определена. То же относится к наборам файлов типа HEADERS, а также к общедоступным и закрытым заголовочным файлам, связанным с устанавливаемыми целями через целевые свойства 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 — это soname библиотеки, а lib<name>.so — «namelink», позволяющая компоновщикам найти библиотеку при указании -l<name>. Параметр NAMELINK_COMPONENT аналогичен параметру COMPONENT, но изменяет компонент установки namelink динамической библиотеки, если такая ссылка создаётся. Если параметр не указан, по умолчанию используется значение COMPONENT. Использовать этот параметр вне блока LIBRARY нельзя.

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

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

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

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

NAMELINK_ONLY

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

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

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

NAMELINK_SKIP

Аналогично NAMELINK_ONLY, но с противоположным эффектом: при установке целевой библиотеки устанавливаются файлы библиотеки, отличные от namelink. Если не заданы ни 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 или PROGRAMS, можно использовать «генераторные выражения» с синтаксисом $<...>. Доступные выражения описаны в руководстве cmake-generator-expressions(7). Однако если какой-либо элемент начинается с генераторного выражения, оно должно вычисляться в полный путь.

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

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

Аргумент 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 <dir>...
        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]
        [<match-rule> <match-option>...]...
        )

Форма DIRECTORY устанавливает содержимое одного или нескольких каталогов в указанное место назначения. Структура каталогов копируется в место назначения без изменений.

Необходимо указать либо TYPE, либо DESTINATION, но не оба аргумента одновременно. Если права не заданы, файлам назначаются права по умолчанию, указанные в форме команды FILES, а каталогам — права по умолчанию, указанные в форме команды PROGRAMS.

Доступны следующие параметры:

<dir>...

Список устанавливаемых каталогов.

Последний компонент имени каждого каталога добавляется к каталогу назначения, но этого можно избежать, добавив завершающий символ косой черты, поскольку в таком случае последний компонент будет пустым. Имена каталогов, заданные относительными путями, интерпретируются относительно текущего исходного каталога. Если имена исходных каталогов не заданы, каталог назначения будет создан, но в него ничего не будет установлено.

Добавлено в версии 3.5: В списке исходных каталогов <dir>... можно использовать «генераторные выражения» с синтаксисом $<...>. Доступные выражения описаны в руководстве cmake-generator-expressions(7).

TYPE <type>

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

Аргумент 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.

Добавлено в версии 3.31: Тип LIBEXEC.

DESTINATION <dir>

Каталог назначения, описанный в разделе общие параметры.

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

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

FILE_PERMISSIONS <permission>...

Задаёт права для файлов в месте назначения; названия <permission> описаны в разделе общие параметры.

DIRECTORY_PERMISSIONS <permission>...

Задаёт права для каталогов в месте назначения; названия <permission> описаны в разделе общие параметры.

USE_SOURCE_PERMISSIONS

Если этот параметр задан, а FILE_PERMISSIONS — нет, права для файлов будут скопированы из структуры исходных каталогов.

MESSAGE_NEVER

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

Отключает вывод состояния установки файлов.

FILES_MATCHING

Этот параметр можно указать перед первым <match-rule>, чтобы отключить установку файлов (но не каталогов), не соответствующих ни одному выражению. Например, следующий код

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

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

<match-rule> <match-option>...

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

Полный путь к каждому входному файлу или каталогу, с прямыми косыми чертами, можно сопоставить с помощью <match-rule>:

PATTERN <pattern>

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

REGEX <regex>

Сопоставляет любую часть полного пути к файлу с помощью регулярного выражения. Для ограничения сопоставления концом пути можно использовать / и $.

За каждым <match-rule> могут следовать аргументы <match-option>. Параметры сопоставления применяются к файлам или каталогам, соответствующим правилу. Доступны следующие параметры сопоставления:

EXCLUDE

Исключает соответствующий файл или каталог из установки.

PERMISSIONS <permission>...

Переопределяет настройку прав для соответствующего файла или каталога.

Например, следующий код

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 будут исключены.

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> [...])

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

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

install(PACKAGE_INFO <package-name> EXPORT <export-name>
        [PROJECT <project-name>|NO_PROJECT_METADATA]
        [APPENDIX <appendix-name>]
        [DESTINATION <dir>]
        [LOWER_CASE_FILE]
        [VERSION <version>
         [COMPAT_VERSION <version>]
         [VERSION_SCHEMA <string>]]
        [DEFAULT_TARGETS <target>...]
        [DEFAULT_CONFIGURATIONS <config>...]
        [LICENSE <license-string>]
        [DEFAULT_LICENSE <license-string>]
        [DESCRIPTION <description-string>]
        [HOMEPAGE_URL <url-string>]
        [PERMISSIONS <permission>...]
        [CONFIGURATIONS <config>...]
        [CXX_MODULES_DIRECTORY <directory>]
        [COMPONENT <component>]
        [EXCLUDE_FROM_ALL])

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

Если DESTINATION не указан, используется платформозависимое значение по умолчанию.

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

VERSION <version>

Версия пакета. <version> должен соответствовать указанной схеме. Подробнее о том, как используется версия пакета при запросе пакета потребителями, см. в разделе Выбор версии (CPS).

COMPAT_VERSION <version>

Самая ранняя версия, с которой пакет обеспечивает совместимость.

Если не указано, COMPAT_VERSION неявно считается равным VERSION пакета, то есть обратная совместимость не обеспечивается.

VERSION_SCHEMA <schema>

Схема, которой следуют номера версий пакета (как VERSION, так и COMPAT_VERSION). Если этот параметр не указан, в файл .cps схема не записывается, однако спецификация CPS указывает, что в таких случаях предполагается схема simple. Подробнее см. в разделе version_schema, где также приведен список официально поддерживаемых схем. Учтите, что спецификация может включать схемы, не поддерживаемые CMake. Список схем, поддерживаемых командой find_package(), см. в разделе Выбор версии (CPS).

DEFAULT_TARGETS <target>...

Цели, используемые, если потребитель запрашивает связывание с именем пакета, а не с отдельными компонентами.

DEFAULT_CONFIGURATIONS <config>...

Упорядоченный список конфигураций, которым потребителям следует отдавать предпочтение, если точное соответствие или сопоставление конфигурации потребителя с доступными конфигурациями пакета отсутствует. Если список не указан, CMake будет использовать доступные конфигурации пакета в неопределенном порядке.

LICENSE <license-string>

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

System Package Data Exchange (SPDX) выражение лицензии, описывающее лицензии проекта в целом, включая документацию, ресурсы и другие материалы, распространяемые вместе с проектом, помимо программных артефактов. Список часто используемых лицензий и их идентификаторов см. в списке лицензий SPDX.

Лицензия отдельных компонентов берется из свойства SPDX_LICENSE соответствующих целей.

DEFAULT_LICENSE <license-string>

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

System Package Data Exchange (SPDX) выражение лицензии, описывающее лицензии компонентов, для которых лицензии не указаны иным образом.

DESCRIPTION <description-string>

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

Информационное описание проекта. Рекомендуется, чтобы это описание было относительно коротким — обычно не более нескольких слов.

HOMEPAGE_URL <url-string>

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

Информационный канонический URL-адрес домашней страницы проекта.

По умолчанию, если указанное <package-name> совпадает с текущим значением CMake PROJECT_NAME, метаданные пакета наследуются от проекта. Параметр PROJECT <project-name> можно использовать, чтобы указать другой проект, от которого следует наследовать метаданные. Если указан параметр NO_PROJECT_METADATA, автоматическое наследование метаданных пакета отключается. В любом случае значения метаданных, указанные в команде install, имеют приоритет.

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

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

Примечание

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

Примечание

Это рекомендуемый способ создания информации о пакетах Common Package Specification для проекта. Для дистрибьюторов, чьим пользователям может потребоваться информация о пакетах CPS, изменение файлов сборки проекта может быть непрактичным; в таком случае переменную CMAKE_INSTALL_EXPORTS_AS_PACKAGE_INFO можно использовать для создания файлов .cps из вызовов install(EXPORT). Сведения об использовании и ограничениях см. в документации переменной.

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, а на платформах без DLL — в место назначения LIBRARY и компонент. Фреймворки 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>...

install(SBOM <sbom-name> [...])

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

Примечание

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

Устанавливает ведомость программных материалов («SBOM»), описывающую проект:

install(SBOM <sbom-name> EXPORTS <export-names>...
        [PROJECT <project-name>|NO_PROJECT_METADATA]
        [DESTINATION <dir>]
        [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
        [LICENSE <license-string>]
        [DESCRIPTION <description-string>]
        [HOMEPAGE_URL <url-string>]
        [PACKAGE_URL <url-string>]
        [FORMAT <string>])

Форма SBOM создает файл ведомости программных материалов («SBOM») для указанного проекта и устанавливает его вместе с проектом. Ведомость программных материалов — это машиночитаемое описание целей проекта, связанных библиотек и связанных с ними метаданных, например версий и сведений о лицензиях. В настоящее время CMake создает файлы SBOM в соответствии со спецификацией System Package Data Exchange 3.0 в представлении JSON-LD, выбранном параметром FORMAT; интерфейс при этом разработан с учетом поддержки дополнительных форматов SBOM и версий схем в будущих выпусках CMake.

Установки целей связываются с каждым набором экспортов <export-names> в списке EXPORTS с помощью параметра EXPORTS сигнатуры install(TARGETS), описанной выше. Одна ведомость SBOM может охватывать несколько наборов экспортов; цели из всех перечисленных экспортов объединяются в один документ. Если DESTINATION не указан, используется платформозависимое значение по умолчанию.

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

VERSION <version>

Версия пакета, заданная последовательностью неотрицательных целочисленных компонентов, то есть <major>[.<minor>[.<patch>[.<tweak>]]]. Подробнее см. в документации project(VERSION).

FORMAT <string>

Формат экспорта SBOM, который должен быть выражением вида <format>[-<version>][+<representation>]. В настоящее время CMake поддерживает сериализацию JSON-LD для System Package Data Exchange v3.0.1 (spdx или spdx-3.0.1+json); этот формат также используется по умолчанию, если FORMAT не указан.

HOMEPAGE_URL <url-string>

Информационный канонический URL-адрес домашней страницы проекта.

PACKAGE_URL <url-string>

Информационный канонический URL-адрес пакета проекта.

LICENSE <license-string>

System Package Data Exchange (SPDX) выражение лицензии, описывающее лицензии проекта в целом, включая документацию, ресурсы и другие материалы, распространяемые вместе с проектом, помимо программных артефактов. Список часто используемых лицензий и их идентификаторов см. в списке лицензий SPDX.

Лицензия отдельных компонентов берется из свойства SPDX_LICENSE соответствующих целей.

DESCRIPTION <description-string>

Информационное описание проекта. Рекомендуется, чтобы это описание было относительно коротким — обычно не более нескольких слов.

По умолчанию, если указанное <sbom-name> совпадает с текущим значением CMake PROJECT_NAME, метаданные SBOM наследуются от проекта. Параметр PROJECT <project-name> можно использовать, чтобы указать другой проект, от которого следует наследовать метаданные. Если указан параметр NO_PROJECT_METADATA, автоматическое наследование метаданных SBOM отключается. В любом случае значения метаданных, указанные в команде install, имеют приоритет.

Обратите внимание, что для целей, в свойствах LINK_LIBRARIES или INTERFACE_LINK_LIBRARIES которых содержатся генераторные выражения, создать файл SBOM нельзя, если только эти выражения не защищены с помощью LINK_ONLY.

Примеры

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

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

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.