Команда binarycreator -c config/config.xml -p packages MyInstaller.exe завершается ошибкой вида «Cannot find package» почти всегда из-за неверной структуры каталога packages — имя подпапки обязано совпадать с идентификатором пакета в package.xml, и это первое, что стоит проверить при сборке инсталлятора через Qt Installer Framework. Дальше обычно всплывают проблемы с путями в config.xml и отсутствующими файлами данных в папке data.
Qt Installer Framework (сокращённо QtIFW) — официальный инструментарий от Qt для создания кроссплатформенных установщиков: офлайн-инсталляторов, онлайн-установщиков с загрузкой пакетов из репозитория и менеджеров обновлений. Он подходит не только для приложений на Qt — упаковать можно любое ПО, включая программы на C++, Python или .NET. В этой статье разберём установку инструмента, структуру проекта, сборку установщика и типичные ошибки.
Что такое Qt Installer Framework и когда он нужен
Qt Installer Framework — это набор утилит и библиотек, позволяющий собрать установщик с мастером выбора компонентов, лицензионным соглашением, созданием ярлыков и встроенным деинсталлятором. Фреймворк работает на Windows, Linux и macOS, а сам установщик пишет логи и поддерживает тихую установку через параметры командной строки.
Инструмент особенно удобен, когда продукт состоит из нескольких модулей: пользователь может отметить галочками нужные компоненты, а позже через тот же инсталлятор обновить или удалить отдельные части. Именно так устроен официальный установщик самой Qt — он построен на этом же фреймворке.
- 📦 Офлайн-установщик — один исполняемый файл со всеми данными внутри.
- 🌐 Онлайн-установщик — маленький лаунчер, скачивающий пакеты из репозитория.
- 🔧 Репозиторий обновлений — серверная папка, откуда клиенты получают новые версии.
- 🧩 Скриптовая логика — операции на JavaScript-подобном языке внутри пакетов.
Установка Qt Installer Framework
Самый простой способ получить QtIFW — скачать готовый установщик фреймворка с официального сайта Qt в разделе загрузок. Доступны сборки для Windows, Linux и macOS; после установки в каталоге появятся утилиты binarycreator, repogen, archivegen и installerbase, а также папка examples с образцами проектов.
Альтернативный путь — собрать фреймворк из исходников через qmake или cmake, но для большинства задач это избыточно: официальная сборка закрывает стандартные сценарии. Вам понадобится только добавить путь к bin в переменную окружения PATH, чтобы вызывать утилиты из любой папки проекта.
⚠️ Внимание: версия QtIFW и версия Qt, на которой собран фреймворк, не обязаны совпадать с версией Qt вашего приложения. Установщик — отдельный инструмент, он не линкуется с вашей программой.
Структура проекта установщика
Проект инсталлятора состоит из двух обязательных частей: папки config с файлом config.xml и папки packages с описанием компонентов. Каждый компонент — это подпапка внутри packages, содержащая meta/package.xml и каталог data с файлами, которые попадут на машину пользователя.
Файл config.xml задаёт глобальные параметры: имя продукта, версию, издателя, иконку, заголовок окна и целевой каталог по умолчанию через переменную @TargetDir@. Вот минимальный пример:
<Installer>
<Name>My Application</Name>
<Version>1.0.0</Version>
<Title>My Application Installer</Title>
<Publisher>My Company</Publisher>
<StartMenuDir>My Application</StartMenuDir>
<TargetDir>@ApplicationsDir@/MyApp</TargetDir>
</Installer>
Внутри packages/com.vendor.app/meta/package.xml описывается сам компонент: отображаемое имя, версия, дата релиза, зависимости и скрипт установки. Имя подпапки — это и есть идентификатор пакета, принято использовать обратную доменную нотацию вида com.vendor.component.
Сборка установщика: binarycreator и repogen
Для офлайн-инсталлятора используется утилита binarycreator. Базовая команда выглядит так:
binarycreator -c config/config.xml -p packages MyAppInstaller.exeФлаг --offline-only явно запрещает сетевые операции, а --online-only создаёт лёгкий установщик, который тянет пакеты из репозитория. Для онлайн-режима сначала нужно сгенерировать репозиторий утилитой repogen:
repogen -p packages repositoryПолученную папку repository выкладывают на HTTP-сервер, а её URL прописывают в config.xml в секции <RemoteRepositories>. Тогда установщик при запуске проверит наличие новых версий и предложит обновление.
☑️ Проверка перед сборкой установщика
Скрипты установки и операции с файлами
Логика сверх простого копирования файлов реализуется через installscript.qs в папке meta пакета. Скрипт позволяет создавать ярлыки, прописывать переменные окружения, запускать внешние программы и задавать вопросы пользователю через дополнительные страницы мастера.
Типичный пример — создание ярлыка на рабочем столе через операцию createShortcut:
component.addOperation("CreateShortcut",
"@TargetDir@/MyApp.exe",
"@DesktopDir@/MyApp.lnk");
Переменные вида @TargetDir@, @HomeDir@, @ApplicationsDir@ подставляются фреймворком автоматически и различаются в зависимости от ОС. Учитывайте, что набор доступных операций и поведение скриптов могут отличаться между версиями QtIFW — сверяйтесь с документацией именно вашей версии.
Как добавить лицензионное соглашение
В package.xml добавьте секцию <Licenses> с элементом <License>, где укажите имя и путь к текстовому файлу лицензии. Файл положите в папку meta пакета. Мастер установки автоматически покажет страницу принятия соглашения.
Типичные ошибки и их решения
Больше всего вопросов вызывают ошибки на этапе сборки и при запуске готового инсталлятора. Ниже — таблица частых проблем.
| Ошибка | Вероятная причина | Решение |
|---|---|---|
| Cannot find package | Имя папки не совпадает с идентификатором пакета | Переименовать папку в точное имя из package.xml |
| Ошибка парсинга config.xml | Незакрытый тег или недопустимый символ | Проверить XML валидатором, экранировать спецсимволы |
| Пустой установщик | Папка data компонента пуста или файлы не заархивированы | Проверить содержимое data, при необходимости использовать archivegen |
| Онлайн-установщик не видит обновления | Репозиторий не пересобран или неверный URL | Запустить repogen заново, проверить Updates.xml на сервере |
| Ярлык не создаётся | Ошибка в путях операции CreateShortcut | Проверить переменные @TargetDir@ и права на запись |
⚠️ Внимание: дата релиза в
package.xmlвлияет на механизм обновлений. Если дата новой версии не новее предыдущей, менеджер пакетов может не предложить обновление пользователям.
Отдельная категория проблем — антивирусные ложные срабатывания на неподписанные установщики под Windows. Цифровая подпись исполняемого файла установщика сертификатом code signing существенно снижает количество блокировок и предупреждений SmartScreen. Подписывать нужно итоговый файл после сборки через binarycreator.
Сравнение с альтернативами
QtIFW — не единственный способ упаковать приложение. Выбор зависит от платформы, требований к обновлениям и привычного стека.
- 🛠️ Inno Setup — популярный бесплатный инсталлятор только для Windows, гибкий скриптовый язык, но без встроенного механизма онлайн-обновлений.
- 📜 NSIS — компактные установщики для Windows, требует написания скриптов на собственном языке.
- 🐧 Пакеты DEB/RPM и AppImage — нативные форматы для Linux, но они не дают единого кроссплатформенного решения.
- 🔄 Squirrel, Sparkle — специализированные фреймворки автообновлений для Windows и macOS соответственно.
Сильная сторона QtIFW — связка «установщик + менеджер обновлений + репозиторий» в одном инструменте и одинаковое поведение на трёх ОС. Слабая — относительно большой размер самого установщика и необходимость разбираться в XML-конфигурации.
FAQ: частые вопросы о Qt Installer Framework
Можно ли использовать QtIFW для приложения, написанного не на Qt?
Да. Фреймворк упаковывает произвольные файлы: исполняемые файлы, библиотеки, ресурсы любого приложения. Привязки к Qt у вашего продукта нет — Qt используется только самим установщиком.
Как сделать тихую (unattended) установку?
Установщики на QtIFW поддерживают запуск с параметрами командной строки, позволяющими выполнить установку без интерактивного взаимодействия. Точный набор ключей зависит от версии фреймворка — проверьте раздел документации про командную строку для вашей версии.
Как обновить уже установленное приложение?
Используйте онлайн-режим: соберите новую версию пакета с увеличенным номером версии и свежей датой релиза, пересоздайте репозиторий через repogen и выложите его на сервер. Установленный у пользователя менеджер пакетов (MaintenanceTool) обнаружит обновление при запуске.
Поддерживает ли QtIFW цифровую подпись установщика?
Сам фреймворк не подписывает файлы — это делается внешними инструментами, например signtool на Windows или codesign на macOS. Подписывать нужно итоговый исполняемый файл после сборки binarycreator.
Где взять примеры проектов для изучения?
В каталоге установки QtIFW есть папка examples с готовыми демонстрационными проектами: от простейшего офлайн-установщика до примеров со скриптами и кастомными страницами мастера. Начинать изучение удобнее всего с них, копируя структуру в свой проект.