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|OBJECTS|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, OBJECTS, FRAMEWORK, и BUNDLE. Исполняемые файлы обрабатываются как RUNTIME цели, за исключением помеченных свойством MACOSX_BUNDLE — они обрабатываются как BUNDLE цели на ОС X. Статические библиотеки обрабатываются как ARCHIVE цели, за исключением помеченных свойством FRAMEWORK — они обрабатываются как FRAMEWORK цели на ОС X. Модульные библиотеки всегда обрабатываются как LIBRARY цели. На платформах, не поддерживающих DLL, динамические библиотеки обрабатываются как LIBRARY цели, за исключением помеченных свойством FRAMEWORK — они обрабатываются как FRAMEWORK цели на ОС X. На платформах, поддерживающих DLL, DLL-часть динамической библиотеки обрабатывается как RUNTIME цель, а соответствующая импортная библиотека — как ARCHIVE цель. Все системы на базе Windows, включая Cygwin, являются платформами DLL. Библиотеки объектов всегда обрабатываются как OBJECTS цели. Аргументы ARCHIVE, LIBRARY, RUNTIME, OBJECTS, и 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, mySharedLib DLL будет установлен в <prefix>/bin и /some/full/path, а его импортная библиотека — в <prefix>/lib/static и /some/full/path.

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