install

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

Резюме

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

Введение

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

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

DESTINATION

Укажите каталог на диске, в который будет установлен файл. Аргументы могут быть относительными или абсолютными путями.

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

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

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

PERMISSIONS

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

Права, не имеющие смысла на определённых платформах, игнорируются на этих платформах.

CONFIGURATIONS

Укажите список конфигураций сборки, для которых применяется правило установки (Отладка, Релиз и т.д.). Обратите внимание, что значения, указанные для этого параметра, применяются только к параметрам, перечисленным ПОСЛЕ параметра CONFIGURATIONS. Например, чтобы задать отдельные пути установки для конфигураций Отладка и Релиз, сделайте следующее:

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

Обратите внимание, что CONFIGURATIONS указано ПЕРЕД RUNTIME DESTINATION.

COMPONENT

Укажите имя компонента установки, с которым ассоциировано правило установки, например Runtime или Development.

Во время установки, специфичной для компонента, будут выполняться только правила установки, ассоциированные с заданным именем компонента. Во время полной установки устанавливаются все компоненты, если не отмечено EXCLUDE_FROM_ALL.

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

EXCLUDE_FROM_ALL

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

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

RENAME

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

OPTIONAL

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

Установка целей

install(TARGETS targets... [EXPORT <export-name>]
        [RUNTIME_DEPENDENCIES args...|RUNTIME_DEPENDENCY_SET <set-name>]
        [[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE|
          PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE|FILE_SET <set-name>|CXX_MODULES_BMI]
         [DESTINATION <dir>]
         [PERMISSIONS permissions...]
         [CONFIGURATIONS [Debug|Release|...]]
         [COMPONENT <component>]
         [NAMELINK_COMPONENT <component>]
         [OPTIONAL] [EXCLUDE_FROM_ALL]
         [NAMELINK_ONLY|NAMELINK_SKIP]
        ] [...]
        [INCLUDES DESTINATION [<dir> ...]]
        )

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

ARCHIVE

Целевые артефакты этого типа включают:

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

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, так как связанные файлы устанавливаются в соответствующие места внутри папки framework. См. PUBLIC_HEADER для деталей.

PRIVATE_HEADER

Аналогично PUBLIC_HEADER, но для файлов PRIVATE_HEADER. См. PRIVATE_HEADER для деталей.

RESOURCE

Аналогично PUBLIC_HEADER и PRIVATE_HEADER, но для файлов RESOURCE. См. RESOURCE для деталей.

FILE_SET <set>

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

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

CXX_MODULES_BMI

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

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

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

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

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

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

Рассмотрим следующий пример:

install(TARGETS mylib
        LIBRARY
          COMPONENT Libraries
          NAMELINK_COMPONENT Development
        PUBLIC_HEADER
          COMPONENT Development
       )

В этом сценарии, если вы выберите установить только Development компонент, как заголовки, так и имя ссылки будут установлены без библиотеки. (Если вы также не установите Libraries компонент, имя ссылки станет висящей символической ссылкой, и у проектов, которые ссылаются на библиотеку, возникнут ошибки сборки.) Если вы установите только Libraries компонент, будет установлена только библиотека без заголовков и имени ссылки.

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

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

NAMELINK_ONLY

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

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

NAMELINK_SKIP

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

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

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

EXPORT

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

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

INCLUDES DESTINATION

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

RUNTIME_DEPENDENCY_SET

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

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

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

RUNTIME_DEPENDENCIES

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

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

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

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

где <set-name> будет случайно сгенерированным именем набора. В args... могут быть указаны любые из следующих ключевых слов, поддерживаемых командой 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 взаимоисключающие.

В одном вызове команды в форме TARGETS может быть указано один или несколько наборов свойств. Целевой объект может быть установлен более одного раза в разных местоположениях. Рассмотрим гипотетические целевые объекты myExe, mySharedLib, и myStaticLib. Код:

install(TARGETS myExe mySharedLib myStaticLib
        RUNTIME DESTINATION bin
        LIBRARY DESTINATION lib
        ARCHIVE DESTINATION lib/static)
install(TARGETS mySharedLib DESTINATION /some/full/path)

установит myExe в <prefix>/bin и myStaticLib в <prefix>/lib/static. На платформах, не использующих DLL, mySharedLib будет установлен в <prefix>/lib и /some/full/path. На платформах с DLL, DLL mySharedLib будет установлен в <prefix>/bin и /some/full/path, а его импортная библиотека — в <prefix>/lib/static и /some/full/path.

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

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

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

install(IMPORTED_RUNTIME_ARTIFACTS targets...
        [RUNTIME_DEPENDENCY_SET <set-name>]
        [[LIBRARY|RUNTIME|FRAMEWORK|BUNDLE]
         [DESTINATION <dir>]
         [PERMISSIONS permissions...]
         [CONFIGURATIONS [Debug|Release|...]]
         [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|PROGRAMS> files...
        TYPE <type> | DESTINATION <dir>
        [PERMISSIONS permissions...]
        [CONFIGURATIONS [Debug|Release|...]]
        [COMPONENT <component>]
        [RENAME <name>] [OPTIONAL] [EXCLUDE_FROM_ALL])

Форма FILES определяет правила установки файлов для проекта. Имена файлов, заданные как относительные пути, интерпретируются относительно текущего каталога исходных файлов. Файлы, установленные с помощью этой формы, по умолчанию получают разрешения OWNER_WRITE, OWNER_READ, GROUP_READ, и WORLD_READ , если не задан аргумент PERMISSIONS.

Форма PROGRAMS идентична форме FILES за исключением того, что по умолчанию установленные файлы также получают разрешения OWNER_EXECUTE, GROUP_EXECUTE, и WORLD_EXECUTE. Эта форма предназначена для установки программ, которые не являются целевыми объектами, таких как скрипты оболочки. Используйте форму TARGETS для установки целевых объектов, построенных в рамках проекта.

Список files... , переданный в FILES или PROGRAMS, может использовать «генераторные выражения» с синтаксисом $<...>. Обратитесь к cmake-generator-expressions(7) руководству за доступными выражениями. Однако, если какой-либо элемент начинается с генераторного выражения, он должен оцениваться в полный путь.

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

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

Установка каталогов

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

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

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

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

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

Кастомная логика установки

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

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

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

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

Установка экспортов

install(EXPORT <export-name> DESTINATION <dir>
        [NAMESPACE <namespace>] [FILE <name>.cmake]
        [PERMISSIONS permissions...]
        [CONFIGURATIONS [Debug|Release|...]
        [CXX_MODULES_DIRECTORY <directory>]
        [EXPORT_LINK_INTERFACE_LIBRARIES]
        [COMPONENT <component>]
        [EXCLUDE_FROM_ALL])
install(EXPORT_ANDROID_MK <export-name> DESTINATION <dir> [...])

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

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

CXX_MODULES_DIRECTORY

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

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

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

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

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

install(RUNTIME_DEPENDENCY_SET <set-name>
        [[LIBRARY|RUNTIME|FRAMEWORK]
         [DESTINATION <dir>]
         [PERMISSIONS permissions...]
         [CONFIGURATIONS [Debug|Release|...]]
         [COMPONENT <component>]
         [NAMELINK_COMPONENT <component>]
         [OPTIONAL] [EXCLUDE_FROM_ALL]
        ] [...]
        [PRE_INCLUDE_REGEXES regexes...]
        [PRE_EXCLUDE_REGEXES regexes...]
        [POST_INCLUDE_REGEXES regexes...]
        [POST_EXCLUDE_REGEXES regexes...]
        [POST_INCLUDE_FILES files...]
        [POST_EXCLUDE_FILES files...]
        [DIRECTORIES directories...]
        )

Устанавливает набор зависимостей времени выполнения, созданный ранее одной или несколькими командами 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 <directories>
• PRE_INCLUDE_REGEXES <regexes>
• PRE_EXCLUDE_REGEXES <regexes>
• POST_INCLUDE_REGEXES <regexes>
• POST_EXCLUDE_REGEXES <regexes>
• POST_INCLUDE_FILES <files>
• POST_EXCLUDE_FILES <files>

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

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