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

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

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

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

Проекты, желающие следовать общепринятой практике установки заголовков в подкаталог, специфичный для проекта, могут предпочесть использовать наборы файлов с соответствующими путями и базовыми каталогами. В противном случае, им необходимо указать 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 целевого объекта <targets> при экспорте командой 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 mySharedLib DLL будет установлен в <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 и BUNDLE CFBundles). Например, заголовки и библиотеки импорта, связанные с DLL, не устанавливаются. В случае библиотек FRAMEWORK, исполняемых файлов MACOSX_BUNDLE и BUNDLE CFBundles вся директория устанавливается.

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

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

Обратите внимание, что некоторые встроенные значения по умолчанию для типов используют каталог 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|...]]
        [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.

Форма 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 и компонент.

Сгенерированный скрипт установки вызывает 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.