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

CPACK_OUTPUT_CONFIG_FILE

Имя файла конфигурации бинарной программы CPack. Этот файл — конфигурация CPack, сгенерированная модулем CPack для бинарных установщиков. По умолчанию CPackConfig.cmake.

CPACK_PACKAGE_EXECUTABLES

Список исполняемых файлов и соответствующих текстовых меток, используемых для создания ярлыков в меню «Пуск». Например, задав этот список ccmake;CMake, будет создан ярлык «CMake», который запустит установленный исполняемый файл ccmake. Не все генераторы CPack его используют (по крайней мере, NSIS, WIX и OSXX11 нет).

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.