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

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

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.
• На 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>

Новое в версии 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 является ошибкой.

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

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

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

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

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