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 цели, за исключением тех, которые помечены свойством FRAMEWORK, которые рассматриваются как FRAMEWORK цели на OS X. Модульные библиотеки всегда рассматриваются как 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 для подробностей.

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

Назначение установки, переданное файлам install 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]|
        [EXPORT_ANDROID_MK <name>.mk]]
        [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>, поведение не определено. Если в экспорт включена библиотечная цель, но цель, к которой она ссылается, не включена, поведение не определено.

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

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

install(TARGETS myexe EXPORT myproj DESTINATION bin)
install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj)
install(EXPORT_ANDROID_MK myexp DESTINATION share/ndk-modules)

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