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_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 — нет).

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 можно установить, чтобы указать, сколько потоков будет использоваться для сжатия.

Можно использовать положительное целое число для указания точного желаемого количества потоков.

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

При задании 0 CPack попытается использовать все доступные ядра процессора.

По умолчанию CPACK_THREADS установлено в 1.

Следующие методы сжатия могут использовать несколько ядер:

xz

Поддерживается, если CMake скомпилирован с liblzma , который поддерживает параллельное сжатие.

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

zstd

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

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

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

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

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