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

Новое в версии 3.21: Официальные двоичные файлы CMake, доступные на cmake.org , теперь поставляются с liblzma , который поддерживает параллельное сжатие. Более старые версии этого не поддерживали.

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

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