BiLauncher/doc/build-and-release.md

Сборка, упаковка и релизы

Что нужно

• CMake 3.20+, компилятор C++17 и C (C нужен для zlib на Linux).
• Qt 6.8 или новее (qt_standard_project_setup(REQUIRES 6.8)). CI собирает на Qt 6.11.1.
• Обязательные модули: Quick, QuickControls2, Qml, Svg, Core, CorePrivate, Gui, Network.
• Необязательный: WebEngineQuick, для входа через Microsoft.

CorePrivate нужен ради QZipReader и QZipWriter: ими распаковываются нативные библиотеки LWJGL, архивы Temurin и архивы сборок. Приватные модули Qt не гарантируют совместимость между версиями, поэтому проект привязан к конкретной версии Qt. Предупреждение об этом отключено (QT_NO_PRIVATE_MODULE_WARNING).

Qt WebEngine

Модуль ставится в MaintenanceTool отдельной галочкой и тянет за собой Qt WebChannel и Qt Positioning. Чтобы он работал, нужны все три.

Если сделать WebEngine обязательным, у любого, кто его не поставил, проект вообще не соберётся, хотя офлайн-вход и Ely.by без него работают. Поэтому:

• модуль найден — определяется LAUNCHER_HAS_WEBENGINE, MicrosoftLoginDialog.qml попадает в модуль, backend.microsoftAvailable равно true;
• не найден — CMake выдаёт предупреждение со списком компонентов, которые надо доставить, а лаунчер собирается без входа через Microsoft.

Релизные сборки в CI всегда с WebEngine: скрипты подготовки раннеров проверяют, что он есть.

Локальная сборка

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=$HOME/Qt/6.11.1/macos

cmake --build build

Из Qt Creator проект открывается как обычный CMake-проект.

Версия и канал сборки

В репозитории хранится только число: project(BiLauncher VERSION x.y.z) в CMakeLists.txt. Оно одинаковое во всех ветках, поэтому merge dev → rc → master версию не перетирает и не даёт конфликтов. PROJECT_VERSION идёт в ресурс версии .exe, в Info.plist и в установщик: все три принимают только числовую версию.

Канал (dev / rc / релиз) в коде не записан — его на каждой сборке вычисляет cmake/LauncherVersion.cmake и пишет в сгенерированный <build>/generated/launcherversion.h (LAUNCHER_VERSION, LAUNCHER_CHANNEL). Порядок определения:

1. -DLAUNCHER_BUILD_VERSION=1.0.1-rc2 — полная версия от CI; база обязана совпадать с project(), иначе configure падает;
2. тег на HEAD: vx.y.z — релиз, vx.y.z-rcN — rc;
3. ветка (из GITHUB_HEAD_REF/GITHUB_REF_NAME или git): master — релиз, rc и beta — rc;
4. любая другая ветка или сборка без git — dev.

Сборка	LAUNCHER_VERSION	В окне
релиз (master, vx.y.z)	1.0.1	Версия: 1.0.1
rc из CI (vx.y.z-rcN)	1.0.1-rc2	+ бейдж RC
rc локально	1.0.1-rc	+ бейдж RC
dev	1.0.1-dev+a1b2c3d	+ бейдж DEV

У dev-сборки после + — короткий хэш коммита, .dirty — есть незакоммиченные правки в отслеживаемых файлах. Генерация идёт на каждой сборке, так что после git checkout другой ветки reconfigure не нужен.

Полная строка уходит в QCoreApplication::applicationVersion, в аргументы запуска игры и в подпись «Версия: …» в левом верхнем углу окна; бейдж канала QML берёт из её суффикса. Почему так, см. ADR-0002.

Когда поднимать версию. Номер поднимается в dev в начале цикла (сразу после релиза) и дальше приходит в rc и master через merge. Хотфикс прямо в rc или master — правка и bump patch там же, затем обратный merge master → rc → dev.

Что собирается

BiLauncher — исполняемый файл и QML-модуль с URI BiLauncher. В модуль входят все .cpp, .qml, картинки из images/, i18n/translations.json, а также CHANGELOG.md, LICENSE и README.md. Последние три сейчас никто из кода не читает, они просто лежат в ресурсах.

QML-модуль собирается в <build>/qml/BiLauncher (OUTPUT_DIRECTORY). Если оставить по умолчанию, на Linux папка BiLauncher совпадёт по имени с исполняемым файлом (у него нет расширения), и линковка упадёт с «Is a directory».

launcher_zlib_reference — только на Linux. Это обычный zlib 1.3.1 из каталога zlib/, выходной файл libz.so.1 в <build>/zlib/. С ним лаунчер не линкуется. Библиотека нужна только установщикам Forge и NeoForge на системах с zlib-ng, см. zlibreference.h. Исходники zlib — чужой код из upstream, документацией он не покрыт.

Иконки

Все размеры собираются из одного файла icons/master/icon_master.png (1024×1024, рисунок до краёв холста) скриптом icons/generate_icons.sh. Для него нужны ImageMagick и iconutil, то есть запускается он на macOS. Правки вносятся в мастер, после чего скрипт перезапускается. Отдельные размеры руками не правятся.

Системы по-разному добавляют поля вокруг иконки, поэтому один и тот же рисунок кладётся по-разному:

• macOS сама поля не добавляет. По сетке Apple рисунок занимает 824 из 1024 точек, углы скруглены радиусом 185.4. Результат — icon.icns, кладётся в Contents/Resources бандла.
• Windows ждёт картинку на весь холст. icon.ico содержит кадры 16–256, включая 20, 40 и 96 для масштабов 125/150/200%. Без явного списка ImageMagick положил бы в .ico только 1024×1024, и система размывала бы иконку при уменьшении. Вкомпилирована через icon.rc.in, где заодно ресурс версии.
• Linux: PNG 16–512 ставятся в тему hicolor под именем bilauncher.png, плюс bilauncher.desktop. Окружения рабочего стола ищут иконку по имени из Icon=, а не по имени файла.

Иконка окна задаётся в main.cpp из ресурса :/icons/ (на всех системах, кроме macOS).

Установка (cmake --install)

• исполняемый файл в bin/ (на macOS — BiLauncher.app);
• qt_generate_deploy_qml_app_script раскладывает рядом Qt, плагины и QML-модули (windeployqt/macdeployqt под капотом; на macOS с -hardened-runtime);
• LICENSE, CHANGELOG.md, packaging/THIRD_PARTY_LICENSES.txt в share/doc/BiLauncher/ (кроме macOS);
• на Linux ещё libz.so.1 в lib/BiLauncher/, иконки и .desktop.

На Linux ставьте с -DCMAKE_INSTALL_LIBDIR=lib. Лаунчер ищет эталонный zlib в <bin>/../lib/BiLauncher, а на Ubuntu по умолчанию LIBDIR был бы lib/x86_64-linux-gnu.

Релизы

Релизы собирает Gitea Actions, .gitea/workflows/release.yml.

Как выпустить версию

0. Запустить workflow tests вручную (Run workflow) и дождаться зелёного прогона на всех трёх системах, включая дымовую проверку установленного дерева. release.yml от тестов не зависит, поэтому этот шаг на совести выпускающего. См. testing.md.
1. Поднять версию в project(BiLauncher VERSION ...) в CMakeLists.txt.
2. Добавить в CHANGELOG.md раздел ## [x.y.z] — дата. Его текст станет описанием релиза. Для пре-релиза можно завести отдельный раздел ## [x.y.z-rcN]: он берётся в первую очередь, а если его нет — используется ## [x.y.z].
3. Запустить релиз одним из способов:
   • Пуш в master — полноценный релиз vx.y.z. Если релиз или тег с этой версией уже есть, прогон ничего не собирает: сначала поднимите версию.
   • Пуш в rc — пре-релиз vx.y.z-rcN, где N — следующий свободный номер для этой версии (rc1, rc2, ...).
   • Тег vx.y.z — полноценный релиз, тег vx.y.z-rcN — пре-релиз. Пре-релизом становится только тег с суффиксом -rc, любой другой суффикс даёт обычный релиз.

Если тег не совпадает с версией в CMakeLists.txt (без учёта суффикса), прогон сразу падает.

Для веток тег создаёт сам Gitea при публикации релиза, на коммите прогона. Этот тег снова запускает release.yml, но прогон видит, что релиз уже есть, и ничего не собирает.

Что происходит

1. create-release (Linux) — определяет тег (из пуша тега или по ветке), сверяет его с версией, вырезает раздел из CHANGELOG.md и создаёт черновик релиза.
2. Параллельно три сборки, каждая прикладывает свои файлы к черновику:
   • Linux: BiLauncher-<v>-x86_64.AppImage и BiLauncher-<v>-linux-x86_64.tar.gz. Сборка идёт с -j 8: на ВМ 6 ГБ памяти, и без ограничения компиляторы съедают её всю.
   • Windows: BiLauncher-<v>-win64-setup.exe (Inno Setup) и BiLauncher-<v>-win64-portable.zip. В portable нет vc_redist, среда выполнения MSVC должна уже стоять в системе. Сборка идёт в C:\r\..., потому что дерево WebEngine легко выходит за MAX_PATH. Zip делается системным tar.exe по полному пути: GNU tar из Git, который стоит в PATH раньше, zip не умеет и принимает C: за имя удалённого хоста.
   • macOS: BiLauncher-<v>-macOS-universal.dmg (arm64 + x86_64). Подпись ad-hoc: без неё приложение вообще не запустится на Apple Silicon. Developer ID нет, поэтому Gatekeeper при первом запуске всё равно спросит подтверждение.
3. publish собирает SHA256SUMS.txt из хешей всех трёх сборок, прикладывает его и снимает с релиза флаг черновика.

Если хоть одна сборка упала, релиз остаётся черновиком и пользователи его не видят.

Ручной запуск (workflow_dispatch) делает те же сборки, но релиз не создаёт: файлы остаются артефактами прогона.

Секрет RELEASE_TOKEN — персональный токен Gitea с правом repository: write.

Установщик Windows

packaging/windows/BiLauncher.iss (Inno Setup 6). Ставит в Program Files\BiLauncher, разрешает выбрать установку только для текущего пользователя, создаёт ярлык в меню «Пуск» и, по желанию, на рабочем столе, тихо ставит vc_redist, если он есть в дереве. Языки установщика — русский и английский.

AppId менять нельзя: по нему новая версия находит и обновляет старую установку.

Раннеры

Раннеры работают в режиме host, то есть прямо на машине, без Docker. Метки: linux, windows, macos.

Пути к Qt раннер передаёт сборке через переменные окружения в своём config.yaml:

• QT_ROOT — kit Qt (например, ~/Qt/6.11.1/gcc_64);
• QT_TOOLS — папка Tools из Qt Online Installer, оттуда CMake и Ninja;
• ISCC_DIR — только Windows, папка Inno Setup.

Qt с WebEngine, CMake и Ninja ставятся заранее через Qt Online Installer. Скрипты подготовки докачивают остальное и регистрируют раннер. Повторный запуск безопасен.

Linux (Ubuntu 22.04), ci/setup-runner-linux.sh [токен]. Запускать от пользователя, которому принадлежит Qt, нужен sudo без пароля. Ставит компилятор, библиотеки для сборки и деплоя (xcb, OpenGL, NSS и т. д.), libfuse2 для appimagetool, Node.js (нужен actions/checkout), appimagetool, gitea-runner и systemd-сервис gitea-runner.

Windows, ci/setup-runner-windows.ps1 [-Token ...] из PowerShell от администратора. Ставит VS 2022 Build Tools (это 20–40 минут), Git, Node.js, Inno Setup, включает длинные пути в системе и в git, регистрирует gitea-runner. Раннер запускается задачей планировщика при входе пользователя, поэтому пароль учётной записи не нужен, но без входа в систему раннер не поднимется. Чтобы он стартовал при загрузке машины, задачу нужно пересоздать с /sc onstart /rp *.

macOS — скрипта подготовки нет, раннер настроен вручную.

Те же раннеры гоняют автотесты (.gitea/workflows/tests.yml): Linux — на каждый push, все три системы — ночью и по кнопке. Подробности — testing.md.

---

При создании этого документа использовался ИИ.