CPack

Настройка генераторов для установочных файлов и исходных пакетов.

Введение

Модуль CPack генерирует файлы конфигурации CPackConfig.cmake и CPackSourceConfig.cmake. Они предназначены для последующего использования в программе cpack, где они управляют генерацией установочных и/или исходных пакетов.

В зависимости от генератора CMake, модуль CPack может также добавить две новые целевые задачи, package и package_source. Подробности см. в разделе «Целевые задачи упаковки» ниже.

Сгенерированные установочные файлы будут содержать все файлы, установленные с помощью команды CMake install() (и устаревшие команды install_files(), install_programs() и install_targets()). Обратите внимание, что параметр DESTINATION команды install() должен быть относительным путем; в противном случае установленные файлы игнорируются CPack.

Некоторые виды установочных файлов могут быть настроены так, чтобы пользователи могли выбирать отдельные компоненты приложения для установки. Дополнительные сведения см. в модуле CPackComponent.

Исходные пакеты (настраиваемые через CPackSourceConfig.cmake и генерируемые генератором CPack Archive Generator) будут содержать все исходные файлы в каталоге проекта, за исключением тех, которые указаны в CPACK_SOURCE_IGNORE_FILES.

Генераторы CPack

Переменная CPACK_GENERATOR имеет разное значение в разных контекстах. В файле CMakeLists.txt, CPACK_GENERATOR представляет собой список генераторов; а когда cpack выполняется без других аргументов, он итерируется по этому списку и создаёт один пакет для каждого генератора. В файле CPACK_PROJECT_CONFIG_FILE, CPACK_GENERATOR является строкой с именем одного генератора. Если вам нужна логика для управления другими настройками cpack для каждого генератора, то вам нужен CPACK_PROJECT_CONFIG_FILE. Если он установлен, то CPACK_PROJECT_CONFIG_FILE включается автоматически для каждого генератора. Он должен содержать только переопределения.

Вот как это работает:

• cpack выполняется
• он включает CPackConfig.cmake
• он итерируется по генераторам, указанным в опции командной строки -G, или, если такая опция не указана, по списку генераторов, заданному переменной CPACK_GENERATOR в файле CPackConfig.cmake.

• для каждого генератора

  • он устанавливает CPACK_GENERATOR на текущий генератор
  • он включает CPACK_PROJECT_CONFIG_FILE
  • он создаёт пакет для этого генератора

Это ключевой момент: Для каждого генератора, перечисленного в CPACK_GENERATOR в CPackConfig.cmake, cpack сбросит CPACK_GENERATOR внутренне на текущий используемый и затем включит CPACK_PROJECT_CONFIG_FILE.

Список доступных генераторов см. в cpack-generators(7).

Целевые задачи упаковки package и package_source

Если CMake запущен с генератором Makefile, Ninja или Xcode, то include(CPack) генерирует целевую задачу package. Это позволяет создавать установочный файл из CMake, Make или Ninja: вместо cpack, можно вызвать cmake --build . --target package или make package или ninja package. Генератор VS создаёт целевую задачу с заглавными буквами PACKAGE.

Если CMake запущен с генератором Makefile или Ninja, то include(CPack) также генерирует целевую задачу package_source. Чтобы создать исходный пакет, вместо cpack -G TGZ --config CPackSourceConfig.cmake можно вызвать cmake --build . --target package_source, make package_source, или ninja package_source.

Общие переменные для всех генераторов CPack

Перед включением этого модуля CPack в ваш CMakeLists.txt файл, можно установить различные переменные для настройки получившихся установочных файлов. Наиболее часто используемые переменные:

CPACK_PACKAGE_NAME

Имя пакета (или приложения). Если не указано, оно по умолчанию совпадает с именем проекта.

CPACK_PACKAGE_VENDOR

Имя поставщика пакета (например, «Kitware»). По умолчанию «Humanity».

CPACK_PACKAGE_DIRECTORY

Каталог, в котором CPack выполняет упаковку. Если не задан, он по умолчанию устанавливается в каталог сборки. Эта переменная может быть определена в файле конфигурации CPack или из опции командной строки cpack -B. Если она задана, опция командной строки переопределяет значение, найденное в файле конфигурации.

CPACK_PACKAGE_VERSION_MAJOR

Основная версия пакета. Эта переменная всегда задаётся, но её значение по умолчанию зависит от того, были ли детали версии переданы команде project() в файле CMakeLists.txt верхнего уровня. Если детали версии были переданы, значение по умолчанию будет CMAKE_PROJECT_VERSION_MAJOR. Если детали версии не были переданы, по умолчанию будет версия 0.1.1, что приведёт к тому, что значение по умолчанию для CPACK_PACKAGE_VERSION_MAJOR будет 0.

CPACK_PACKAGE_VERSION_MINOR

Дополнительная версия пакета. Значение по умолчанию определяется на основе того, были ли детали версии переданы команде project() в файле CMakeLists.txt верхнего уровня. Если детали версии были переданы, значение по умолчанию будет CMAKE_PROJECT_VERSION_MINOR, но если компонент дополнительной версии не был указан, то CPACK_PACKAGE_VERSION_MINOR останется не заданным. Если вообще не была передана версия проекта, по умолчанию будет версия 0.1.1, что приведёт к тому, что значение по умолчанию для CPACK_PACKAGE_VERSION_MINOR будет 1.

CPACK_PACKAGE_VERSION_PATCH

Версия исправления пакета. Значение по умолчанию определяется на основе того, были ли детали версии переданы команде project() в файле CMakeLists.txt верхнего уровня. Если детали версии были переданы, значение по умолчанию будет CMAKE_PROJECT_VERSION_PATCH, но если компонент версии исправления не был указан, то CPACK_PACKAGE_VERSION_PATCH останется не заданным. Если вообще не была передана версия проекта, по умолчанию будет версия 0.1.1, что приведёт к тому, что значение по умолчанию для CPACK_PACKAGE_VERSION_PATCH будет 1.

CPACK_PACKAGE_DESCRIPTION

Описание проекта, используемое, например, на начальном экране установщиков Windows, сгенерированных CPack. Если не задано, значение этой переменной берется из файла, указанного в CPACK_PACKAGE_DESCRIPTION_FILE.

CPACK_PACKAGE_DESCRIPTION_FILE

Текстовый файл, используемый для описания проекта, когда CPACK_PACKAGE_DESCRIPTION не задан явно. По умолчанию CPACK_PACKAGE_DESCRIPTION_FILE указывает на встроенный шаблонный файл Templates/CPack.GenericDescription.txt.

CPACK_PACKAGE_DESCRIPTION_SUMMARY

Краткое описание проекта (несколько слов). Если переменная CMAKE_PROJECT_DESCRIPTION установлена, она используется в качестве значения по умолчанию, иначе значение по умолчанию — строка, сгенерированная CMake на основе CMAKE_PROJECT_NAME.

CPACK_PACKAGE_HOMEPAGE_URL

URL домашней страницы проекта. Значение по умолчанию взято из переменной CMAKE_PROJECT_HOMEPAGE_URL, установленной командой верхнего уровня project(), иначе, если URL не был предоставлен команде project(), значение по умолчанию — пустая строка.

CPACK_PACKAGE_FILE_NAME

Имя файла пакета для генерации, без расширения. Например, cmake-2.6.1-Linux-i686. Значение по умолчанию:

${CPACK_PACKAGE_NAME}-${CPACK_PACKAGE_VERSION}-${CPACK_SYSTEM_NAME}

CPACK_PACKAGE_INSTALL_DIRECTORY

Директория установки на целевой системе. Может использоваться некоторыми генераторами CPack, такими как NSIS, для создания директории установки, например, “CMake 2.5” ниже директории установки. Все установленные элементы будут помещены в эту директорию.

CPACK_PACKAGE_ICON

Изображение бренда, которое будет отображаться внутри установщика (используется в графических установщиках).

CPACK_PACKAGE_CHECKSUM

Алгоритм, который будет использоваться для генерации дополнительного файла с контрольной суммой пакета. Имя выходного файла будет:

${CPACK_PACKAGE_FILE_NAME}.${CPACK_PACKAGE_CHECKSUM}

Поддерживаемые алгоритмы — те, которые перечислены командой string(<HASH>).

CPACK_PROJECT_CONFIG_FILE

Конфигурационный файл проекта CPack для CPack. Этот файл включается во время cpack, один раз на генератор после того, как CPack установит CPACK_GENERATOR на фактический используемый генератор. Это позволяет устанавливать переменные CPACK_* на этапе cpack, в зависимости от генератора.

CPACK_RESOURCE_FILE_LICENSE

Лицензия, которая будет встроена в установщик. Обычно отображается пользователю установщиком (часто с явной кнопкой «Принять» для графических установщиков) перед установкой. Этот файл лицензии НЕ добавляется к установленным файлам, но используется некоторыми генераторами CPack, например, NSIS. Если вы хотите установить файл лицензии (возможно, такой же, как этот) вместе с вашим проектом, вам необходимо добавить соответствующую команду CMake install() в ваш CMakeLists.txt.

CPACK_RESOURCE_FILE_README

Файл ReadMe, который будет встроен в установщик. Обычно подробно описывает назначение проекта во время установки. Данный файл не используется всеми генераторами CPack.

CPACK_RESOURCE_FILE_WELCOME

Файл приветствия, который будет встроен в установщик. Приветствует пользователей этого установщика. Обычно используется в графических установщиках Windows и Mac OS X.

CPACK_MONOLITHIC_INSTALL

Отключает механизм установки по компонентам. При установке, спецификация компонента игнорируется, и все установленные элементы помещаются в один пакет «MONOLITHIC». Некоторые генераторы CPack выполняют монолитную сборку по умолчанию и могут быть запрошены на выполнение компонентной сборки путем задания CPACK_<GENNAME>_COMPONENT_INSTALL в значение TRUE.

CPACK_GENERATOR

Список используемых генераторов CPack. Если не указан, CPack создаст набор опций, следующих шаблону именования CPACK_BINARY_<GENNAME> (например, CPACK_BINARY_NSIS). Это позволит пользователю включать/выключать отдельные генераторы. Если опция -G указана в командной строке команды cpack, она переопределит эту переменную и любые опции CPACK_BINARY_<GENNAME>.

CPACK_OUTPUT_CONFIG_FILE

Имя конфигурационного файла CPack бинарного файла. Этот файл — конфигурация CPack, сгенерированная модулем CPack для бинарных установщиков. По умолчанию CPackConfig.cmake.

CPACK_PACKAGE_EXECUTABLES

Список исполняемых файлов и соответствующих текстовых меток, используемых для создания ярлыков в меню «Пуск». Например, установка этого списка на ccmake;CMake создаст ярлык с именем «CMake», который будет запускать установленный исполняемый файл ccmake. Некоторые генераторы CPack (хотя бы NSIS, WIX и OSXX11) не используют его.

CPACK_STRIP_FILES

Список файлов для удаления. Начиная с CMake 2.6.0, CPACK_STRIP_FILES будет булевой переменной, которая включает удаление всех файлов (список файлов оценивается как TRUE в CMake, поэтому это изменение совместимо).

CPACK_VERBATIM_VARIABLES

Если установлено в значение TRUE, значения переменных с префиксом CPACK_ будут экранированы перед записью в конфигурационные файлы, чтобы программа cpack получила их точно так, как они были заданы. В противном случае символы, такие как кавычки и обратные слеши, могут привести к ошибкам анализа или изменить значение, полученное программой cpack. По умолчанию FALSE для обратной совместимости.

Переменные для генераторов пакетов исходных кодов

Следующие переменные CPack предназначены только для пакетов исходных кодов и не повлияют на бинарные пакеты:

CPACK_SOURCE_PACKAGE_FILE_NAME

Имя пакета исходных кодов. Например, cmake-2.6.1.

CPACK_SOURCE_STRIP_FILES

Список файлов в дереве исходных кодов, которые будут удалены. Начиная с CMake 2.6.0, CPACK_SOURCE_STRIP_FILES будет булевой переменной, которая включает удаление всех файлов (список файлов оценивается как TRUE в CMake, поэтому это изменение совместимо).

CPACK_SOURCE_GENERATOR

Список генераторов, используемых для пакетов исходных кодов. Как и с CPACK_GENERATOR, если это не указано, CPack создаст набор опций (например, CPACK_SOURCE_ZIP), позволяющий пользователям выбрать, какие пакеты будут сгенерированы.

CPACK_SOURCE_OUTPUT_CONFIG_FILE

Имя конфигурационного файла CPack для пакетов исходных кодов. Этот файл — конфигурация CPack, сгенерированная модулем CPack для установщиков исходных кодов. По умолчанию CPackSourceConfig.cmake.

CPACK_SOURCE_IGNORE_FILES

Шаблон файлов в дереве исходных кодов, которые не будут включены в пакет исходных кодов. Это список шаблонов регулярных выражений (которые должны быть корректно экранированы), например, /CVS/;/\\.svn/;\\.swp$;\\.#;/#;.*~;cscope.*.

Переменные для расширенного использования

Следующие переменные предназначены для расширенного использования CPack:

CPACK_CMAKE_GENERATOR

Какой генератор CMake следует использовать, если проект является проектом CMake. По умолчанию устанавливается значение CMAKE_GENERATOR. Немногие пользователи захотят изменить это значение.

CPACK_INSTALL_CMAKE_PROJECTS

Список из четырёх значений, определяющих, какой проект установить. Четыре значения: Директория сборки, Имя проекта, Компонент проекта, Директория. Если опущено, CPack создаст установщик, устанавливающий всё.

CPACK_SYSTEM_NAME

Имя системы, по умолчанию равно значению CMAKE_SYSTEM_NAME, за исключением Windows, где будет win32 или win64.

CPACK_PACKAGE_VERSION

Полная версия пакета, используемая внутри. По умолчанию, она строится из CPACK_PACKAGE_VERSION_MAJOR, CPACK_PACKAGE_VERSION_MINOR и CPACK_PACKAGE_VERSION_PATCH.

CPACK_TOPLEVEL_TAG

Директория для установленных файлов.

CPACK_INSTALL_COMMANDS

Дополнительные команды для установки компонентов. Переменная среды CMAKE_INSTALL_PREFIX устанавливается в временную директорию установки во время выполнения.

CPACK_INSTALL_SCRIPTS

Дополнительные скрипты CMake, выполняемые CPack во время локальной установки. Они выполняются перед установкой файлов для упаковки. Скрипты не вызываются при самостоятельной установке (например: make install). Для каждого скрипта будут установлены следующие переменные: CMAKE_CURRENT_SOURCE_DIR, CMAKE_CURRENT_BINARY_DIR и CMAKE_INSTALL_PREFIX (которая установлена в директорию временной установки). Сингулярная форма CMAKE_INSTALL_SCRIPT поддерживается как альтернативная переменная по историческим причинам, но её значение игнорируется, если установлено CMAKE_INSTALL_SCRIPTS, и будет выведено предупреждение.

См. также CPACK_PRE_BUILD_SCRIPTS и CPACK_POST_BUILD_SCRIPTS, которые можно использовать для указания скриптов, которые должны быть выполнены позже в процессе упаковки.

CPACK_PRE_BUILD_SCRIPTS

Список скриптов CMake, которые нужно выполнить после того, как CPack установил файлы, которые нужно упаковать в временную директорию, и перед созданием пакета(ов) из этих файлов. См. также CPACK_INSTALL_SCRIPTS и CPACK_POST_BUILD_SCRIPTS.

CPACK_POST_BUILD_SCRIPTS

Список скриптов CMake, которые нужно выполнить после того, как CPack создал результирующие пакеты и перед копированием их обратно в директорию сборки. См. также CPACK_INSTALL_SCRIPTS, CPACK_PRE_BUILD_SCRIPTS и CPACK_PACKAGE_FILES.

CPACK_PACKAGE_FILES

Список файлов пакета, созданных во временной директории, где каждый файл предоставлен в виде полного абсолютного пути. Эта переменная заполняется CPack непосредственно перед вызовом скриптов пост-сборки, перечисленных в CPACK_POST_BUILD_SCRIPTS. Это предпочтительный способ для скриптов пост-сборки узнать набор файлов пакета, над которыми нужно работать. Проекты не должны пытаться установить эту переменную самостоятельно.

CPACK_INSTALLED_DIRECTORIES

Дополнительные директории для установки.

CPACK_PACKAGE_INSTALL_REGISTRY_KEY

Ключ реестра, используемый при установке этого проекта. Используется только установщиками для Windows. Значение по умолчанию основано на директории установки.

CPACK_CREATE_DESKTOP_LINKS

Список создаваемых ярлыков на рабочем столе. Каждый ярлык на рабочем столе требует соответствующего ярлыка в меню Пуск, созданного с помощью CPACK_PACKAGE_EXECUTABLES.

CPACK_BINARY_<GENNAME>

Сгенерированные CPack опции для двоичных генераторов. Модуль CPack.cmake генерирует (если CPACK_GENERATOR не задан) набор опций CMake (см. команду CMake option()), которые затем могут быть использованы для выбора генератора(ов) CPack, используемого при построении целевого объекта package или при запуске cpack без опции -G.