CPack

Этот модуль настраивает генераторы двоичных установщиков и исходных пакетов.

Загрузите этот модуль в проекте CMake с помощью:

include(CPack)

Введение

Модуль CPack создает файлы конфигурации CPackConfig.cmake и CPackSourceConfig.cmake. Они предназначены для использования при последующем запуске программы cpack, которая использует их для управления созданием установщиков и/или исходных пакетов.

В зависимости от генератора CMake модуль CPack также может добавлять две новые цели сборки: package и package_source. Подробности см. в разделе цели упаковки ниже.

Создаваемые двоичные установщики будут содержать все файлы, установленные с помощью команды install() CMake (а также устаревших команд 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 и 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 или с помощью параметра командной строки -B программы cpack. Если параметр командной строки задан, он переопределяет значение из файла конфигурации.

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>).

Изменено в версии 4.2: Переменная принимает список алгоритмов.

CPACK_PROJECT_CONFIG_FILE

Файл конфигурации проекта CPack, используемый во время выполнения CPack. Этот файл подключается во время выполнения cpack один раз для каждого генератора после того, как CPack присвоит CPACK_GENERATOR значение фактически используемого генератора. Это позволяет задавать значения переменных CPACK_* во время выполнения cpack отдельно для каждого генератора.

CPACK_RESOURCE_FILE_LICENSE

Лицензия, встраиваемая в установщик. Обычно установщик показывает ее пользователю перед установкой (часто с отдельной кнопкой "Accept" в установщиках с графическим интерфейсом). Этот файл лицензии НЕ добавляется к устанавливаемым файлам, но используется некоторыми генераторами 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

Отключает механизм установки на основе компонентов. Если переменная задана, спецификация компонентов игнорируется, а все устанавливаемые элементы помещаются в один пакет "MONOLITHIC". Некоторые генераторы CPack по умолчанию создают монолитные пакеты; чтобы использовать упаковку по компонентам, для CPACK_<GENNAME>_COMPONENT_INSTALL можно задать значение TRUE.

CPACK_GENERATOR

Список используемых генераторов CPack. Если список не задан, CPack создаст набор параметров по шаблону именования CPACK_BINARY_<GENNAME> (например, CPACK_BINARY_NSIS), позволяющих пользователю включать и отключать отдельные генераторы. Если в командной строке cpack задан параметр -G, он переопределит эту переменную и все параметры 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 будет логической переменной, включающей обработку всех файлов (в CMake список файлов интерпретируется как TRUE, поэтому это изменение обратно совместимо).

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_COMPRESSION_LEVEL

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

Выбор уровня сжатия, если он применим, например при сжатии пакета установщика.

Некоторые методы сжатия, используемые генераторами CPack, например Debian или Archive, позволяют выбирать разные уровни сжатия. Допустимые значения находятся в диапазоне от 0 до 9. При выборе метода сжатия zstd можно задать уровень сжатия от 0 до 19, за исключением формата архива zip.

По умолчанию для CPACK_COMPRESSION_LEVEL задано значение 0, которое выбирает уровень сжатия по умолчанию. Его автоматически выбирает библиотека для работы с архивами, а не непосредственно CMake. Уровень сжатия по умолчанию может различаться в зависимости от формата архива, платформы и других факторов.

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

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