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»). По умолчанию «Человечество».

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

Описание проекта, используемое, например, в начальном экране установочных файлов, созданных CPack для Windows. Если не задано, значение этой переменной берётся из файла, имя которого указано в 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 при необходимости.