CPack

Настройка установщиков бинарных и исходных пакетов.

Введение

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

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

Сгенерированные установщики бинарных пакетов содержат всё, что было установлено с помощью команды CMake install() (и устаревшими командами install_files(), install_programs() и install_targets()). Для некоторых типов бинарных установщиков (включая графические установщики macOS и Windows) CPack генерирует установщики, позволяющие пользователям выбирать отдельные компоненты приложения для установки. Подробности см. в модуле CPackComponent.

Генераторы CPack

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

Дерево исходного кода CMake содержит файл CPACK_PROJECT_CONFIG_FILE. Пример см. в файле верхнего уровня CMakeCPackOptions.cmake.in.

Если задан, файл 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).

Целевые задачи пакетирования

Если 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 CPackConfig.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 будет булевой переменной, которая включает удаление всех файлов (список файлов в CMake оценивается как TRUE, поэтому это изменение совместимо).

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 будет булевой переменной, которая включает удаление всех файлов (список файлов в CMake оценивается как TRUE, поэтому это изменение совместимо).

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_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.