CPackComponent

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

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

include(CPackComponent)

• Введение
• Переменные

• Команды

  • Добавление компонента
  • Добавление группы компонентов
  • Добавление типа установки
  • Настройка загрузки

Введение

Этот модуль также автоматически подключается модулем CPack.

Некоторые бинарные установщики (особенно графические) создаваемые CPack позволяют пользователям выбирать отдельные компоненты приложения для установки. Этот модуль позволяет разработчикам настраивать упаковку таких компонентов.

Содержимое назначается компонентам с помощью аргумента COMPONENT команды CMake install(). Компонентам можно назначать понятные пользователям имена и описания, зависимости между компонентами и т. д., а также объединять их в группы различными способами для настройки создаваемого установщика с помощью описанных ниже команд.

Чтобы задавать разные группы для разных генераторов CPack, используйте CPACK_PROJECT_CONFIG_FILE.

Переменные

На упаковку компонентов влияют следующие переменные:

CPACK_COMPONENTS_ALL

Список компонентов для установки.

Значение этой переменной по умолчанию вычисляется CPack и включает все компоненты, определённые проектом. Пользователь может задать значение, включающее только указанные компоненты.

Вместо того чтобы указывать все нужные компоненты, можно получить список всех определённых компонентов и удалить из него ненужные. Для получения свойства COMPONENTS можно использовать команду get_cmake_property(), а затем удалить ненужные компоненты с помощью команды list(REMOVE_ITEM). Например, чтобы использовать все определённые компоненты, кроме foo и bar:

get_cmake_property(CPACK_COMPONENTS_ALL COMPONENTS)
list(REMOVE_ITEM CPACK_COMPONENTS_ALL "foo" "bar")

CPACK_<GENNAME>_COMPONENT_INSTALL

Включает или отключает установку компонентов для генератора CPack <GENNAME>.

Для каждого генератора CPack (RPM, DEB, ARCHIVE, NSIS, DMG и т. д.) задано устаревшее поведение по умолчанию. Например, RPM создаёт монолитный пакет, а NSIS — компонентный. Поведение по умолчанию можно изменить, задав для этой переменной значение 0/1 или OFF/ON.

CPACK_COMPONENTS_GROUPING

Задаёт способ группировки компонентов для генераторов CPack, поддерживающих компоненты и создающих несколько пакетов.

Некоторые генераторы, например RPM или ARCHIVE (TGZ, ZIP и т. д.), могут создавать несколько файлов пакетов при наличии компонентов. Это зависит от значения данной переменной:

• ONE_PER_GROUP (по умолчанию): создать один пакет на группу компонентов
• IGNORE: создать один пакет на компонент (игнорировать группы)
• ALL_COMPONENTS_IN_ONE: создать один пакет со всеми запрошенными компонентами

CPACK_COMPONENT_<compName>_DISPLAY_NAME

Имя компонента, отображаемое пользователю.

CPACK_COMPONENT_<compName>_DESCRIPTION

Описание компонента.

CPACK_COMPONENT_<compName>_GROUP

Группа компонента.

CPACK_COMPONENT_<compName>_DEPENDS

Зависимости (список компонентов), от которых зависит этот компонент.

CPACK_COMPONENT_<compName>_HIDDEN

Значение True означает, что этот компонент скрыт от пользователя.

CPACK_COMPONENT_<compName>_REQUIRED

Значение True означает, что этот компонент обязателен.

CPACK_COMPONENT_<compName>_DISABLED

Значение True означает, что по умолчанию этот компонент не выбран для установки.

Команды

Добавление компонента

cpack_add_component

Описывает компонент установки.

cpack_add_component(compname
                    [DISPLAY_NAME name]
                    [DESCRIPTION description]
                    [HIDDEN | REQUIRED | DISABLED ]
                    [GROUP group]
                    [DEPENDS comp1 comp2 ... ]
                    [INSTALL_TYPES type1 type2 ... ]
                    [DOWNLOADED]
                    [ARCHIVE_FILE filename]
                    [PLIST filename])

compname — это имя компонента установки, заданное аргументом COMPONENT одной или нескольких команд CMake install(). С помощью команды cpack_add_component можно задать имя, описание и другие атрибуты компонента установки. Также компонент можно назначить группе компонентов.

DISPLAY_NAME — отображаемое имя компонента, которое используется графическими установщиками для показа названия компонента. В качестве значения может использоваться любая строка.

DESCRIPTION — расширенное описание компонента, используемое графическими установщиками для предоставления пользователю дополнительной информации о компоненте. Описание может состоять из нескольких строк; в качестве разделителя строк используется \n. Обычно такие описания не должны быть длиннее нескольких строк.

HIDDEN указывает, что этот компонент будет скрыт в графическом установщике, поэтому пользователь не сможет напрямую изменить, устанавливать его или нет.

REQUIRED указывает, что этот компонент обязателен и поэтому всегда будет устанавливаться. Он будет виден в графическом установщике, но его нельзя будет снять. (Обычно обязательные компоненты отображаются серым цветом.)

DISABLED указывает, что по умолчанию этот компонент должен быть отключён (не выбран). Пользователь может выбрать этот компонент для установки, если он также не помечен как HIDDEN.

DEPENDS перечисляет компоненты, от которых зависит этот компонент. Если этот компонент выбран, должны быть выбраны и все перечисленные компоненты. Сведения о зависимостях встраиваются непосредственно в установщик, поэтому пользователи не смогут установить несовместимые наборы компонентов.

GROUP задаёт группу компонентов, к которой относится этот компонент. Если значение не указано, компонент будет самостоятельным и не будет входить ни в одну группу. Группы компонентов описываются командой cpack_add_component_group, которая подробно рассматривается ниже.

INSTALL_TYPES перечисляет типы установки, к которым относится этот компонент. При выборе одного из этих типов установки компонент будет выбран автоматически. Типы установки описываются командой cpack_add_install_type, которая подробно рассматривается ниже.

DOWNLOADED указывает, что этот компонент следует загрузить установщиком непосредственно во время установки, а не включать в сам установщик. Дополнительные сведения см. в описании команды cpack_configure_downloads.

ARCHIVE_FILE задаёт имя файла архива, создаваемого CPack для загружаемых компонентов. Если имя не указано, CPack создаст файл, имя которого будет основано на CPACK_PACKAGE_FILE_NAME и имени компонента. Дополнительные сведения см. в описании команды cpack_configure_downloads.

PLIST задаёт имя файла, который передаётся pkgbuild с аргументом --component-plist при использовании генератора productbuild.

Добавление группы компонентов

cpack_add_component_group

Описывает группу связанных компонентов установки CPack.

cpack_add_component_group(groupname
                         [DISPLAY_NAME name]
                         [DESCRIPTION description]
                         [PARENT_GROUP parent]
                         [EXPANDED]
                         [BOLD_TITLE])

Команда cpack_add_component_group описывает группу компонентов установки, которые будут размещены вместе в списке параметров. Как правило, группы компонентов позволяют пользователю выбрать или отменить выбор всех компонентов группы с помощью одного параметра на уровне группы. Используйте группы компонентов, чтобы упростить установщики с большим количеством параметров. groupname — произвольное имя, используемое для идентификации группы в аргументе GROUP команды cpack_add_component, с помощью которого компонент включается в группу. Имя группы не должно совпадать с именем какого-либо компонента.

DISPLAY_NAME — отображаемое имя группы компонентов, которое используется графическими установщиками для показа названия группы. В качестве значения может использоваться любая строка.

DESCRIPTION — расширенное описание группы компонентов, используемое графическими установщиками для предоставления пользователю дополнительной информации о компонентах этой группы. Описание может состоять из нескольких строк; в качестве разделителя строк используется \n. Обычно такие описания не должны быть длиннее нескольких строк.

PARENT_GROUP, если задан, указывает родительскую группу этой группы. Родительские группы используются для построения иерархии групп, допускающей произвольную вложенность.

EXPANDED указывает, что по умолчанию группа должна отображаться в развёрнутом виде, чтобы пользователь сразу видел все компоненты в ней. В противном случае изначально группа будет отображаться как одна строка.

BOLD_TITLE указывает, что заголовок группы должен отображаться полужирным шрифтом, чтобы привлечь внимание пользователя.

Добавление типа установки

cpack_add_install_type

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

cpack_add_install_type(typename
                       [DISPLAY_NAME name])

Команда cpack_add_install_type задаёт набор предварительно выбранных компонентов, соответствующий распространённому сценарию использования приложения. Например, тип установки "Developer" может включать приложение, а также его заголовочные файлы и файлы библиотек, тогда как тип установки "End user" может включать только исполняемый файл приложения. Каждый компонент связывается с одним или несколькими типами установки с помощью аргумента INSTALL_TYPES команды cpack_add_component.

DISPLAY_NAME — отображаемое имя типа установки, которое обычно показывается в раскрывающемся списке графического установщика. В качестве значения может использоваться любая строка.

Настройка загрузки

cpack_configure_downloads

Настраивает CPack для загрузки выбранных компонентов непосредственно во время установки.

cpack_configure_downloads(site
                          [UPLOAD_DIRECTORY dirname]
                          [ALL]
                          [ADD_REMOVE|NO_ADD_REMOVE])

Команда cpack_configure_downloads настраивает загрузку выбранных компонентов во время установки. Для каждого загружаемого компонента CPack создаёт архив с его содержимым, который следует загрузить на указанный сайт. Когда пользователь выбирает этот компонент для установки, установщик загружает и распаковывает его в нужное место. Эта возможность полезна для создания небольших установщиков, которые загружают только запрошенные компоненты, экономя трафик. Кроме того, установщики достаточно малы, чтобы использоваться в рамках обычного процесса установки; кнопка "Change" в панели управления Windows «Установка и удаление программ» позволяет добавлять или удалять части приложения после первоначальной установки. В Windows для загрузки компонентов требуется подключаемый модуль ZipDLL для NSIS, доступный по адресу:

http://nsis.sourceforge.net/ZipDLL_plug-in

В macOS установщики, загружающие компоненты во время установки, можно собирать и запускать только на системах с macOS 10.5 или новее.

Аргумент site задаёт URL-адрес, по которому будут размещены архивы загружаемых компонентов, например https://cmake.org/files/v3.25/. Все архивы, созданные CPack, следует загрузить в это расположение.

UPLOAD_DIRECTORY — локальный каталог, в котором CPack создаёт архивы для каждого компонента. Содержимое этого каталога следует загрузить в расположение, доступное по URL-адресу, заданному аргументом site. Если значение не указано, CPack будет хранить созданные архивы в каталоге CPackUploads внутри двоичного каталога CMake.

Флаг ALL указывает, что следует загружать все компоненты. В противном случае будут загружаться только компоненты, явно помеченные как DOWNLOADED или имеющие заданный ARCHIVE_FILE. Кроме того, параметр ALL подразумевает ADD_REMOVE (если не указан NO_ADD_REMOVE).

ADD_REMOVE указывает, что CPack должен установить копию установщика, которую можно запустить из диалогового окна «Установка и удаление программ» Windows (с помощью кнопки "Modify"), чтобы изменить набор установленных компонентов. NO_ADD_REMOVE отключает это поведение. В Mac OS X этот параметр игнорируется.