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, вам понадобится файл 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

Новое в версии 3.7.

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

${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

Новое в версии 3.4.

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

CPACK_THREADS

Новое в версии 3.20.

Количество потоков для использования при выполнении параллельных операций, таких как сжатие архива установщика.

Некоторые методы сжатия, используемые генераторами CPack, такие как Debian или Archive, могут использовать несколько ядер процессора для ускорения сжатия. CPACK_THREADS можно установить в положительное целое число, чтобы указать количество потоков, используемых для сжатия. Если он установлен в 0, CPack установит его так, чтобы использовались все доступные ядра процессора. По умолчанию CPACK_THREADS устанавливается в 1.

В настоящее время только сжатие xz может использовать несколько ядер. Другие методы сжатия игнорируют это значение и используют только один поток.

Примечание

Официальные двоичные файлы CMake, доступные на cmake.org поставляются с liblzma которая не поддерживает параллельное сжатие.

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

Следующие переменные 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

Новое в версии 3.16.

Дополнительные скрипты 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

Новое в версии 3.19.

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

CPACK_POST_BUILD_SCRIPTS

Новое в версии 3.19.

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

CPACK_PACKAGE_FILES

Новое в версии 3.19.

Список файлов пакета, созданных во временной директории, каждый файл предоставлен в виде полного абсолютного пути. Эта переменная заполняется 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.