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

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

Добавлено в версии 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, если задано. В противном случае, значение по умолчанию будет пустым, и 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 при необходимости.