install

• Введение
• Установка целевых объектов
• Установка файлов
• Установка каталогов
• Пользовательская логика установки
• Установка экспортов

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

Введение

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

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

DESTINATION

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

PERMISSIONS

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

CONFIGURATIONS

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

COMPONENT

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

RENAME

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

OPTIONAL

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

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

Установка целевых объектов

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

Форма TARGETS задаёт правила для установки целевых объектов из проекта. Существует пять типов файлов целевых объектов, которые могут быть установлены: ARCHIVE, LIBRARY, RUNTIME, FRAMEWORK, и BUNDLE. Исполняемые файлы обрабатываются как целевые объекты типа RUNTIME, за исключением тех, которые помечены свойством MACOSX_BUNDLE, которые обрабатываются как целевые объекты типа BUNDLE на ОС X. Статические библиотеки всегда обрабатываются как целевые объекты типа ARCHIVE. Библиотеки модулей всегда обрабатываются как целевые объекты типа LIBRARY. На платформах, не поддерживающих DLL, общие библиотеки обрабатываются как целевые объекты типа LIBRARY, за исключением тех, которые помечены свойством FRAMEWORK, которые обрабатываются как целевые объекты типа FRAMEWORK на ОС X. На платформах DLL, DLL-часть общей библиотеки обрабатывается как целевой объект типа RUNTIME, а соответствующая импортная библиотека обрабатывается как целевой объект типа ARCHIVE. Все платформы на базе Windows, включая Cygwin, являются платформами DLL. Аргументы ARCHIVE, LIBRARY, RUNTIME, и FRAMEWORK изменяют тип целевого объекта, к которому применяются последующие свойства. Если ничего не указано, свойства установки применяются ко всем типам целевых объектов. Если указан только один тип, то будут установлены только целевые объекты этого типа (что может быть использовано для установки только DLL или только импортной библиотеки).

Аргументы PRIVATE_HEADER, PUBLIC_HEADER, и RESOURCE заставляют последующие свойства применяться к установке файлов, связанных с целевым объектом общей библиотеки FRAMEWORK на платформах, не являющихся платформами Apple. Правила, определённые этими аргументами, игнорируются на платформах Apple, поскольку связанные файлы устанавливаются в соответствующие места внутри папки фреймворка. Смотрите документацию свойств целевого объекта PRIVATE_HEADER, PUBLIC_HEADER, и RESOURCE для получения подробностей.

Можно указать либо NAMELINK_ONLY, либо NAMELINK_SKIP в качестве опции LIBRARY. На некоторых платформах у версиированной общей библиотеки есть символическая ссылка, например:

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

где lib<name>.so.1 — имя библиотеки, а lib<name>.so — «имя ссылки», позволяющая линковщику найти библиотеку, когда задано -l<name>. Опция NAMELINK_ONLY вызывает установку только ссылки при установке целевого объекта библиотеки. Опция NAMELINK_SKIP вызывает установку файлов библиотеки, отличных от ссылки. Если ни одна опция не указана, обе части устанавливаются. На платформах, где версиярованные общие библиотеки не имеют ссылок или когда библиотека не версияруется, опция NAMELINK_SKIP устанавливает библиотеку, а опция NAMELINK_ONLY ничего не устанавливает. Смотрите свойства целевого объекта VERSION и SOVERSION для получения подробностей о создании версиярованных общих библиотек.

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

В одном вызове формы 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 связывает установленные файлы целевого объекта с экспортом, называемым <export-name>. Она должна появляться до опций RUNTIME, LIBRARY, или ARCHIVE. Для фактической установки файла экспорта используйте команду install(EXPORT), документированную ниже.

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

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

Установка файлов

install(<FILES|PROGRAMS> files... DESTINATION <dir>
        [PERMISSIONS permissions...]
        [CONFIGURATIONS [Debug|Release|...]]
        [COMPONENT <component>]
        [RENAME <name>] [OPTIONAL])

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

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

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

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

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

Параметр MESSAGE_NEVER отключает вывод состояния установки файлов.

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

install(DIRECTORY src/ DESTINATION include/myproj
        FILES_MATCHING PATTERN "*.h")

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

Некоторые параметры могут следовать за выражением PATTERN или 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 будут исключены.

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

Логика пользовательской установки

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

Форма 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>])

Форма 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 не соответствует значению, заданному для целей, связанных с <export-name>, поведение не определено. Если цель библиотеки включена в экспорт, но цель, к которой она ссылается, не включена, поведение не определено.

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

install(TARGETS myexe EXPORT myproj DESTINATION bin)
install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj)

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