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_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. Если вы хотите использовать символы UTF-8, файл должен быть закодирован в UTF-8 BOM. Если вы хотите установить файл лицензии (может быть таким же, как этот) вместе с вашим проектом, вы должны добавить соответствующую команду CMake install() в свой CMakeLists.txt.

CPACK_RESOURCE_FILE_README

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

CPACK_RESOURCE_FILE_WELCOME

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

CPACK_MONOLITHIC_INSTALL

Отключает механизм установки по компонентам. При установке эта опция игнорируется, и все установленные элементы помещаются в один пакет «МОНОЛИТНЫЙ». Некоторые генераторы 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, Inno Setup и 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.

CPACK_READELF_EXECUTABLE

Добавлено в версии 3.25.

Укажите путь к исполняемому файлу readelf используемому CPack. Значение по умолчанию будет взято из переменной CMAKE_READELF , если она установлена, что может быть выполнено внутренним модулем CMake. Если CMAKE_READELF не установлена, CPack будет использовать find_program() для определения пути к readelf при необходимости.

CPACK_OBJCOPY_EXECUTABLE

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

Укажите путь к исполняемому файлу objcopy, используемому утилитой CPack. Значение по умолчанию будет взято из переменной CMAKE_OBJCOPY, если она задана и была инициализирована внутренним модулем CMake. Если CMAKE_OBJCOPY не задано, CPack воспользуется find_program(), чтобы определить путь к исполняемому файлу objcopy при необходимости.

CPACK_OBJDUMP_EXECUTABLE

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

Укажите путь к исполняемому файлу objdump, используемому утилитой CPack. Значение по умолчанию будет взято из переменной CMAKE_OBJDUMP, если она задана и была инициализирована внутренним модулем CMake. Если CMAKE_OBJDUMP не задано, CPack воспользуется find_program(), чтобы определить путь к исполняемому файлу objdump при необходимости.