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

Описание проекта, используемое, например, на экране ввода 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

Файл 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, 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 будет булевым переменной, которая включает очистку всех файлов (список файлов в 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

Добавлен в версии 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 при необходимости.