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 и macOS.

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

New in version 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

New in version 3.19.

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

CPACK_POST_BUILD_SCRIPTS

New in version 3.19.

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

CPACK_PACKAGE_FILES

New in version 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

New in version 3.25.

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

CPACK_OBJCOPY_EXECUTABLE

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

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

CPACK_OBJDUMP_EXECUTABLE

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

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