CPack

Настройка генераторов для установочных пакетов бинарных файлов и исходных кодов.

Введение

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

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

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

Алгоритм, который будет использоваться для генерации дополнительного файла с контрольной суммой пакета. Имя выходного файла будет:

${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 и OSXX11 не используют).

CPACK_STRIP_FILES

Список файлов, подлежащих удалению. Начиная с CMake 2.6.0, CPACK_STRIP_FILES будет булевой переменной, которая включает удаление всех файлов (список файлов приводит к TRUE в CMake, поэтому это изменение совместимо).

CPACK_VERBATIM_VARIABLES

Если установлено значение TRUE, значения переменных с префиксом CPACK_ будут экранированы перед записью в конфигурационные файлы, чтобы программа cpack получила их точно так, как они были указаны. В противном случае символы, такие как кавычки и обратные слэши, могут вызвать ошибки разбора или изменить значение, полученное программой cpack. По умолчанию FALSE для обратной совместимости.

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

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

Дополнительные скрипты CMake, выполняемые CPack во время локальной установки (staging), непосредственно перед архивированием файлов. Эти скрипты не вызываются при самостоятельной установке (например: make install). Для каждого скрипта будут установлены следующие переменные: CMAKE_CURRENT_SOURCE_DIR, CMAKE_CURRENT_BINARY_DIR и CMAKE_INSTALL_PREFIX (которая установлена в директорию staging установки). Сингулярная форма CMAKE_INSTALL_SCRIPT поддерживается в качестве альтернативной переменной по историческим причинам, но её значение игнорируется, если установлено CMAKE_INSTALL_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.