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 объекты на OS X. Статические библиотеки рассматриваются как целевые объекты ARCHIVE, за исключением тех, которые помечены свойством FRAMEWORK, которые рассматриваются как FRAMEWORK объекты на OS X. Библиотеки модулей всегда рассматриваются как целевые объекты LIBRARY. На платформах, не поддерживающих DLL, общие библиотеки рассматриваются как целевые объекты LIBRARY, за исключением тех, которые помечены свойством FRAMEWORK, которые рассматриваются как FRAMEWORK объекты на OS 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, DLL mySharedLib будет установлен в <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) для доступных выражений. Однако, если какой-либо элемент начинается с генераторного выражения, он должен оцениваться как полный путь.

Указанный для установки файлов 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, как будто целевой объект был скомпилирован в своём собственном дереве.