Spec-Zone.ru › CMake 3.28

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() в каталоге исходных файлов, выполняются в порядке следования во время установки.

Изменено в версии 3.14: Правила установки в подкаталогах, добавленных вызовами команды add_subdirectory(), чередуются с правилами в родительском каталоге для выполнения в объявленном порядке (см. политику CMP0082).

Изменено в версии 3.22: Переменная среды CMAKE_INSTALL_MODE может переопределить поведение по умолчанию копирования install().

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

DESTINATION <dir>

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

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

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

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

PERMISSIONS <permission>...

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

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

CONFIGURATIONS <config>...

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

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

COMPONENT <component>

Укажите имя компонента установки, с которым связано правило установки, например, Runtime или Development. Во время установки, специфичной для компонента, будут выполняться только правила установки, связанные с данным именем компонента. Во время полной установки все компоненты устанавливаются, если не помечены как EXCLUDE_FROM_ALL. Если COMPONENT не указано, создаётся компонент по умолчанию «Unspecified». Имя компонента по умолчанию может быть изменено с помощью переменной CMAKE_INSTALL_DEFAULT_COMPONENT_NAME.

EXCLUDE_FROM_ALL

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

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

RENAME <name>

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

OPTIONAL

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

Новое в версии 3.1: Подписи команд, устанавливающие файлы, могут выводить сообщения во время установки. Используйте переменную CMAKE_INSTALL_MESSAGE, чтобы управлять выводом сообщений.

Новое в версии 3.11: Многие варианты install() подписей неявно создают каталоги, содержащие установленные файлы. Если CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS установлено, эти каталоги будут созданы с указанными разрешениями. В противном случае они будут созданы в соответствии с правилами uname на платформах Unix-подобных системах. Платформы Windows не затронуты.

Подписи

install(TARGETS <target>... [...])

Установить целевой объект Результаты построения и связанные файлы:

install(TARGETS <target>... [EXPORT <export-name>]
        [RUNTIME_DEPENDENCIES <arg>...|RUNTIME_DEPENDENCY_SET <set-name>]
        [<artifact-option>...]
        [<artifact-kind> <artifact-option>...]...
        [INCLUDES DESTINATION [<dir> ...]]
        )

где группа <artifact-option>... может содержать:

[DESTINATION <dir>]
[PERMISSIONS <permission>...]
[CONFIGURATIONS <config>...]
[COMPONENT <component>]
[NAMELINK_COMPONENT <component>]
[OPTIONAL] [EXCLUDE_FROM_ALL]
[NAMELINK_ONLY|NAMELINK_SKIP]

Первая группа <artifact-option>... относится к целевым объектам Результаты построения, которым не назначена отдельная группа позже в том же вызове.

Каждая группа <artifact-kind> <artifact-option>... относится к Результатам построения указанного типа артефакта:

ARCHIVE

К целевым артефактам этого типа относятся:

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

К целевым артефактам этого типа относятся:

  • Динамические библиотеки, за исключением

    • DLL (они попадают в RUNTIME, см. ниже),
    • на macOS, если помечены как FRAMEWORK (см. ниже).
RUNTIME

К целевым артефактам этого типа относятся:

  • Исполняемые файлы (кроме macOS, если помечены как MACOSX_BUNDLE, см. BUNDLE ниже);
  • DLL (на всех системах на базе Windows, включая Cygwin; обратите внимание, что сопровождающие импортирующие библиотеки относятся к типу ARCHIVE).
OBJECTS

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

Объектные файлы, связанные с библиотеками объектов.

FRAMEWORK

Как статические, так и динамические библиотеки, помеченные свойством FRAMEWORK, рассматриваются как FRAMEWORK целевые объекты на macOS.

BUNDLE

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

PUBLIC_HEADER

Любые файлы PUBLIC_HEADER, связанные с библиотекой, устанавливаются в назначенный каталог, указанный аргументом PUBLIC_HEADER на платформах, не являющихся Apple. Правила, определенные этим аргументом, игнорируются для библиотек FRAMEWORK на платформах Apple, так как связанные файлы устанавливаются в соответствующие расположения внутри папки фреймворка. Подробнее см. PUBLIC_HEADER.

PRIVATE_HEADER

Аналогично PUBLIC_HEADER, но для файлов PRIVATE_HEADER. Подробнее см. PRIVATE_HEADER.

RESOURCE

Аналогично PUBLIC_HEADER и PRIVATE_HEADER, но для файлов RESOURCE. Подробнее см. RESOURCE.

FILE_SET <set-name>

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

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

CXX_MODULES_BMI

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

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

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

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

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

Тип целевого объекта

Переменная GNUInstallDirs

Значение по умолчанию

RUNTIME

${CMAKE_INSTALL_BINDIR}

bin

LIBRARY

${CMAKE_INSTALL_LIBDIR}

lib

ARCHIVE

${CMAKE_INSTALL_LIBDIR}

lib

PRIVATE_HEADER

${CMAKE_INSTALL_INCLUDEDIR}

include

PUBLIC_HEADER

${CMAKE_INSTALL_INCLUDEDIR}

include

FILE_SET (тип HEADERS)

${CMAKE_INSTALL_INCLUDEDIR}

include

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

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

add_library(mylib STATIC ...)
set_target_properties(mylib PROPERTIES PUBLIC_HEADER mylib.h)
include(GNUInstallDirs)
install(TARGETS mylib
        PUBLIC_HEADER
          DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
)

Помимо общих параметров, перечисленных выше, каждый целевой объект может принимать следующие дополнительные аргументы:

NAMELINK_COMPONENT

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

На некоторых платформах версия библиотеки с общим использованием имеет символическую ссылку, например:

lib<name>.so -> lib<name>.so.1

где lib<name>.so.1 — имя soname библиотеки, а lib<name>.so — «имя ссылки», позволяющее компоновщикам находить библиотеку, когда ей передано -l<name>. Параметр NAMELINK_COMPONENT аналогичен параметру COMPONENT, но он изменяет компонент установки имени ссылки для библиотеки с общим использованием, если она генерируется. Если не указано, он по умолчанию принимает значение COMPONENT. Использование этого параметра вне блока LIBRARY является ошибкой.

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

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

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

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

NAMELINK_ONLY

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

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

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

NAMELINK_SKIP

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

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

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

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

EXPORT

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

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

INCLUDES DESTINATION

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

RUNTIME_DEPENDENCY_SET <set-name>

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

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

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

RUNTIME_DEPENDENCIES <arg>...

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

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

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

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

где <set-name> — случайное имя набора. <arg>... может включать любые из следующих ключевых слов, поддерживаемых командой install(RUNTIME_DEPENDENCY_SET):

  • DIRECTORIES
  • PRE_INCLUDE_REGEXES
  • PRE_EXCLUDE_REGEXES
  • POST_INCLUDE_REGEXES
  • POST_EXCLUDE_REGEXES
  • POST_INCLUDE_FILES
  • POST_EXCLUDE_FILES

Ключевые слова RUNTIME_DEPENDENCIES и RUNTIME_DEPENDENCY_SET взаимоисключающие.

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

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

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

Новое в версии 3.13:install(TARGETS) может устанавливать цели, созданные в других каталогах. При использовании таких правил установки между каталогами выполнение make install (или аналогичного) из подкаталога не гарантирует, что цели из других каталогов являются актуальными. Можно использовать target_link_libraries() или add_dependencies(), чтобы гарантировать, что такие цели из других каталогов будут построены до запуска правил установки для подкаталога.

install(IMPORTED_RUNTIME_ARTIFACTS <target>... [...])

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

Установить исполняемые файлы импортированных целей:

install(IMPORTED_RUNTIME_ARTIFACTS <target>...
        [RUNTIME_DEPENDENCY_SET <set-name>]
        [[LIBRARY|RUNTIME|FRAMEWORK|BUNDLE]
         [DESTINATION <dir>]
         [PERMISSIONS <permission>...]
         [CONFIGURATIONS <config>...]
         [COMPONENT <component>]
         [OPTIONAL] [EXCLUDE_FROM_ALL]
        ] [...]
        )

Форма IMPORTED_RUNTIME_ARTIFACTS определяет правила для установки исполняемых файлов импортированных целей. Проекты могут это делать, если они хотят объединить внешние исполняемые файлы или модули в свою установку. Аргументы LIBRARY, RUNTIME, FRAMEWORK, и BUNDLE имеют те же семантику, что и в режиме TARGETS. Устанавливаются только исполняемые файлы импортированных целей (за исключением библиотек FRAMEWORK, исполняемых файлов MACOSX_BUNDLE и CFBundles BUNDLE). Например, заголовки и библиотеки импорта, связанные с DLL, не устанавливаются. В случае библиотек FRAMEWORK, исполняемых файлов MACOSX_BUNDLE и CFBundles BUNDLE устанавливается весь каталог.

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

install(FILES <file>... [...])
install(PROGRAMS <program>... [...])

Примечание

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

Установить файлы или программы:

install(<FILES|PROGRAMS> <file>...
        TYPE <type> | DESTINATION <dir>
        [PERMISSIONS <permission>...]
        [CONFIGURATIONS <config>...]
        [COMPONENT <component>]
        [RENAME <name>] [OPTIONAL] [EXCLUDE_FROM_ALL])

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

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

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

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

Аргумент TYPE

Переменная GNUInstallDirs

Встроенное значение по умолчанию

BIN

${CMAKE_INSTALL_BINDIR}

bin

SBIN

${CMAKE_INSTALL_SBINDIR}

sbin

LIB

${CMAKE_INSTALL_LIBDIR}

lib

INCLUDE

${CMAKE_INSTALL_INCLUDEDIR}

include

SYSCONF

${CMAKE_INSTALL_SYSCONFDIR}

etc

SHAREDSTATE

${CMAKE_INSTALL_SHARESTATEDIR}

com

LOCALSTATE

${CMAKE_INSTALL_LOCALSTATEDIR}

var

RUNSTATE

${CMAKE_INSTALL_RUNSTATEDIR}

<LOCALSTATE dir>/run

DATA

${CMAKE_INSTALL_DATADIR}

<DATAROOT dir>

INFO

${CMAKE_INSTALL_INFODIR}

<DATAROOT dir>/info

LOCALE

${CMAKE_INSTALL_LOCALEDIR}

<DATAROOT dir>/locale

MAN

${CMAKE_INSTALL_MANDIR}

<DATAROOT dir>/man

DOC

${CMAKE_INSTALL_DOCDIR}

<DATAROOT dir>/doc

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

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

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

include(GNUInstallDirs)
install(FILES logo.png
        DESTINATION ${CMAKE_INSTALL_DOCDIR}/myproj
)

Новое в версии 3.4: Путь установки, заданный как аргумент DESTINATION, может использовать "генераторные выражения" с синтаксисом $<...>. См. руководство по cmake-generator-expressions(7).

Новое в версии 3.20: Переименование при установке, заданное как аргумент RENAME, может использовать "генераторные выражения" с синтаксисом $<...>. См. руководство по cmake-generator-expressions(7).

install(DIRECTORY <dir>... [...])

Примечание

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

Установить содержимое одного или нескольких каталогов:

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

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

Введено в версии 3.1: Опция MESSAGE_NEVER отключает вывод статуса установки файлов.

Установку каталогов можно контролировать с высокой точностью, используя опции PATTERN или REGEX. Эти опции «сопоставления» задают шаблон сопоставления или регулярное выражение для сопоставления каталогов или файлов, встречающихся внутри входных каталогов. Они могут использоваться для применения определённых опций (см. ниже) к подмножеству встреченных файлов и каталогов. Полный путь к каждому входному файлу или каталогу (с обратными слэшами) сопоставляется с выражением. PATTERN будет соответствовать только полным именам файлов: часть полного пути, соответствующая шаблону, должна быть в конце имени файла и предшествовать слэшу. REGEX будет соответствовать любой части полного пути, но может использовать / и $ для имитации поведения PATTERN. По умолчанию все файлы и каталоги устанавливаются независимо от того, соответствуют ли они шаблону или нет. Опция FILES_MATCHING может быть задана перед первой опцией сопоставления, чтобы отключить установку файлов (но не каталогов), не соответствующих ни одному из выражений. Например, код

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

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

Некоторые опции могут следовать за выражением PATTERN или REGEX, как описано в string(REGEX), и применяются только к файлам или каталогам, соответствующим им. Опция EXCLUDE пропустит соответствующий файл или каталог. Опция PERMISSIONS переопределяет настройку разрешений для соответствующего файла или каталога. Например, код

install(DIRECTORY icons scripts/ DESTINATION share/myproj
        PATTERN "CVS" EXCLUDE
        PATTERN "scripts/*"
        PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ
                    GROUP_EXECUTE GROUP_READ)

установит каталог icons в share/myproj/icons и каталог scripts в share/myproj. Иконки получат стандартные разрешения на доступ к файлам, скриптам будут заданы определённые разрешения, а любые каталоги CVS будут исключены.

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

TYPE Аргумент

Переменная GNUInstallDirs

Встроенное значение по умолчанию

BIN

${CMAKE_INSTALL_BINDIR}

bin

SBIN

${CMAKE_INSTALL_SBINDIR}

sbin

LIB

${CMAKE_INSTALL_LIBDIR}

lib

INCLUDE

${CMAKE_INSTALL_INCLUDEDIR}

include

SYSCONF

${CMAKE_INSTALL_SYSCONFDIR}

etc

SHAREDSTATE

${CMAKE_INSTALL_SHARESTATEDIR}

com

LOCALSTATE

${CMAKE_INSTALL_LOCALSTATEDIR}

var

RUNSTATE

${CMAKE_INSTALL_RUNSTATEDIR}

<LOCALSTATE dir>/run

DATA

${CMAKE_INSTALL_DATADIR}

<DATAROOT dir>

INFO

${CMAKE_INSTALL_INFODIR}

<DATAROOT dir>/info

LOCALE

${CMAKE_INSTALL_LOCALEDIR}

<DATAROOT dir>/locale

MAN

${CMAKE_INSTALL_MANDIR}

<DATAROOT dir>/man

DOC

${CMAKE_INSTALL_DOCDIR}

<DATAROOT dir>/doc

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

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

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

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

install(SCRIPT <file> [...])
install(CODE <code> [...])

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

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

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

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

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

Введено в версии 3.21: Когда указана опция ALL_COMPONENTS, код пользовательского скрипта установки будет выполняться для каждого компонента установки, специфичной для компонента. Эта опция является взаимоисключающей с опцией COMPONENT.

Введено в версии 3.14: <file> или <code> могут использовать «генераторские выражения» с синтаксисом $<...> (в случае <file>, это относится к их использованию в имени файла, а не в содержимом файла). Обратитесь к руководству cmake-generator-expressions(7) для доступных выражений.

install(EXPORT <export-name> [...])

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

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

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

Примечание

Установленный файл <export-name>.cmake может содержать дополнительные файлы <export-name>-*.cmake для каждой конфигурации, которые должны загружаться с помощью подстановки по образцу. Не используйте имя экспорта, совпадающее с именем пакета в сочетании с установкой файла <package-name>-config.cmake, в противном случае последний может быть неверно сопоставлен шаблоном и загружен.

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

Новое в версии 3.7: Помимо файлов CMake, режим EXPORT_ANDROID_MK может быть использован для указания экспорта для системы сборки Android NDK. Этот режим принимает те же опции, что и обычный режим экспорта. Android NDK поддерживает использование предварительно скомпилированных библиотек, как статических, так и динамических. Это позволяет CMake собирать библиотеки проекта и предоставлять их системе сборки NDK с полным набором транзитивных зависимостей, флагами включения и необходимыми определениями для использования библиотек.

CXX_MODULES_DIRECTORY

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

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

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

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_targets() и свойства целей PRE_INSTALL_SCRIPT и POST_INSTALL_SCRIPT. Она также заменяет формы FILES команд install_files() и install_programs(). Порядок обработки этих правил установки по отношению к тем, которые сгенерированы командами install_targets(), install_files() и install_programs(), не определен.

install(RUNTIME_DEPENDENCY_SET <set-name> [...])

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

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

install(RUNTIME_DEPENDENCY_SET <set-name>
        [[LIBRARY|RUNTIME|FRAMEWORK]
         [DESTINATION <dir>]
         [PERMISSIONS <permission>...]
         [CONFIGURATIONS <config>...]
         [COMPONENT <component>]
         [NAMELINK_COMPONENT <component>]
         [OPTIONAL] [EXCLUDE_FROM_ALL]
        ] [...]
        [PRE_INCLUDE_REGEXES <regex>...]
        [PRE_EXCLUDE_REGEXES <regex>...]
        [POST_INCLUDE_REGEXES <regex>...]
        [POST_EXCLUDE_REGEXES <regex>...]
        [POST_INCLUDE_FILES <file>...]
        [POST_EXCLUDE_FILES <file>...]
        [DIRECTORIES <dir>...]
        )

Устанавливает набор зависимостей выполнения, предварительно созданный одной или несколькими командами install(TARGETS) или install(IMPORTED_RUNTIME_ARTIFACTS). Зависимости целей, входящих в набор зависимостей выполнения, устанавливаются в место назначения RUNTIME и компоненте на платформах DLL и в место назначения LIBRARY и компоненте на платформах, не использующих DLL. Фреймворки macOS устанавливаются в место назначения FRAMEWORK и компоненте. Цели, созданные в дереве сборки, никогда не будут установлены как зависимости выполнения, а также их зависимости, если сами цели не установлены с помощью install(TARGETS).

Сгенерированный скрипт установки вызывает file(GET_RUNTIME_DEPENDENCIES) для файлов дерева сборки, чтобы рассчитать зависимости выполнения. Файлы исполняемых файлов дерева сборки передаются как аргумент EXECUTABLES, файлы динамических библиотек дерева сборки как аргумент LIBRARIES, а модули дерева сборки как аргумент MODULES. В macOS, если один из исполняемых файлов является MACOSX_BUNDLE, этот исполняемый файл передаётся в качестве аргумента BUNDLE_EXECUTABLE. На macOS может быть максимум один такой исполняемый файл-сборка в наборе зависимостей выполнения. Свойство MACOSX_BUNDLE не имеет эффекта на других платформах. Обратите внимание, что file(GET_RUNTIME_DEPENDENCIES) поддерживает сбор зависимостей выполнения только для платформ Windows, Linux и macOS, поэтому install(RUNTIME_DEPENDENCY_SET) имеет то же ограничение.

Следующие подаргументы передаются как соответствующие аргументы в file(GET_RUNTIME_DEPENDENCIES) (для тех, которые предоставляют список каталогов, регулярных выражений или файлов, не являющихся пустыми). Все они поддерживают generator expressions.

  • DIRECTORIES <dir>...
  • PRE_INCLUDE_REGEXES <regex>...
  • PRE_EXCLUDE_REGEXES <regex>...
  • POST_INCLUDE_REGEXES <regex>...
  • POST_EXCLUDE_REGEXES <regex>...
  • POST_INCLUDE_FILES <file>...
  • POST_EXCLUDE_FILES <file>...

Примеры

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

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

add_executable(myExe myExe.c)
add_library(myStaticLib STATIC myStaticLib.c)
target_sources(myStaticLib PUBLIC FILE_SET HEADERS FILES myStaticLib.h)
add_library(mySharedLib SHARED mySharedLib.c)
target_sources(mySharedLib PUBLIC FILE_SET HEADERS FILES mySharedLib.h)
set_property(TARGET mySharedLib PROPERTY SOVERSION 1)

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

install(TARGETS
          myExe
          mySharedLib
          myStaticLib
        RUNTIME           # Following options apply to runtime artifacts.
          COMPONENT Runtime
        LIBRARY           # Following options apply to library artifacts.
          COMPONENT Runtime
          NAMELINK_COMPONENT Development
        ARCHIVE           # Following options apply to archive artifacts.
          COMPONENT Development
          DESTINATION lib/static
        FILE_SET HEADERS  # Following options apply to file set HEADERS.
          COMPONENT Development
        )

Это приведет к:

  • Установите myExe в <prefix>/bin, по умолчанию место назначения артефакта RUNTIME, в качестве части компонента Runtime.

  • На платформах без DLL:

    • Установите libmySharedLib.so.1 в <prefix>/lib, по умолчанию место назначения артефакта LIBRARY, в качестве части компонента Runtime.
    • Установите libmySharedLib.so "namelink" (символическую ссылку) в <prefix>/lib, по умолчанию место назначения артефакта LIBRARY, в качестве части компонента Development.

  • На платформах с DLL:

    • Установите mySharedLib.dll в <prefix>/bin, по умолчанию место назначения артефакта RUNTIME, в качестве части компонента Runtime.
    • Установите mySharedLib.lib в <prefix>/lib/static, указанное место назначения артефакта ARCHIVE, в качестве части компонента Development.
  • Установите myStaticLib в <prefix>/lib/static, указанное место назначения артефакта ARCHIVE, в качестве части компонента Development.
  • Установите mySharedLib.h и myStaticLib.h в <prefix>/include, по умолчанию место назначения набора файлов типа HEADERS, в качестве части компонента Development.

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

Каждый вызов install(TARGETS) устанавливает заданную цель выходной артефакт в самое большее одно DESTINATION, но само правило установки может быть отфильтровано опцией CONFIGURATIONS. Для установки в разное место назначения для каждой конфигурации требуется один вызов на конфигурацию. Например, код:

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

установит myExe в <prefix>/Debug/bin в конфигурации Debug и в <prefix>/Release/bin в конфигурации Release.

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

Примечание

Использование этой функции не рекомендуется. Пожалуйста, рассмотрите использование cmake --install вместо неё.

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

© 2000–2024 Kitware, Inc. and Contributors
Licensed under the BSD 3-clause License.
https://cmake.org/cmake/help/v3.28/command/install.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API