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». Во время установки, специфичной для компонента, будут выполнены только правила установки, связанные с заданным именем компонента. Во время полной установки устанавливаются все компоненты, если они не помечены как EXCLUDE_FROM_ALL. Если COMPONENT не указано, создаётся компонент по умолчанию «Unspecified». Имя компонента по умолчанию можно контролировать с помощью переменной CMAKE_INSTALL_DEFAULT_COMPONENT_NAME.

EXCLUDE_FROM_ALL

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

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] [EXCLUDE_FROM_ALL]
         [NAMELINK_ONLY|NAMELINK_SKIP]
        ] [...]
        [INCLUDES DESTINATION [<dir> ...]]
        )

Формат TARGETS определяет правила для установки целевых объектов из проекта. Существует пять типов файлов целевых объектов, которые могут быть установлены: ARCHIVE, LIBRARY, RUNTIME, FRAMEWORK, и BUNDLE. Исполняемые файлы рассматриваются как целевые объекты типа RUNTIME, за исключением тех, которые помечены свойством MACOSX_BUNDLE, которые рассматриваются как целевые объекты типа BUNDLE на платформе OS X. Статические библиотеки всегда рассматриваются как целевые объекты типа ARCHIVE. Модульные библиотеки всегда рассматриваются как целевые объекты типа LIBRARY. На платформах, не поддерживающих DLL, динамические библиотеки рассматриваются как целевые объекты типа LIBRARY, за исключением тех, которые помечены свойством FRAMEWORK, которые рассматриваются как целевые объекты типа FRAMEWORK на платформе OS 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.

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

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

Указанный для установки 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>] [EXCLUDE_FROM_ALL]
        [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>] [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])

Форма 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, как если бы цель была построена в своём собственном дереве.