580 строк · 44 КиБ
DECISIONS.md
| 1 | # Решения |
| 2 | |
| 3 | Каждое решение: что выбрано, почему, что рассматривали вместо и чем за это |
| 4 | платим. Записи не переписываются — если решение отменено, добавляется новая |
| 5 | запись со ссылкой на старую. |
| 6 | |
| 7 | --- |
| 8 | |
| 9 | ## ADR-001. Не переписывать с нуля, а замещать подсистемы |
| 10 | |
| 11 | **2026-09-02 · принято** |
| 12 | |
| 13 | **Контекст.** 56 000 строк Python и 3 900 строк bash. Соблазн — снести всё и |
| 14 | написать заново на Rust. |
| 15 | |
| 16 | **Решение.** Strangler fig: новое ядро с первого дня работает поверх |
| 17 | существующей папки `data/` StartWine и читает старые конфиги. Подсистемы |
| 18 | замещаются по одной, порядок задан зависимостями: рантайм запуска → хранилище → |
| 19 | обновления → магазины → GUI. |
| 20 | |
| 21 | **Почему не переписывание с нуля.** Полгода без работающего лаунчера. Хуже |
| 22 | того: значительная часть bash-логики — не мусор, а обходы реальных багов Wine, |
| 23 | накопленные годами. При переписывании вслепую они теряются молча, и выясняется |
| 24 | это через месяцы, когда уже не помнишь, что именно сломалось. |
| 25 | |
| 26 | **Почему GUI последним.** Интерфейс поверх старого bash-ядра пришлось бы |
| 27 | переписывать дважды. |
| 28 | |
| 29 | **Цена.** Какое-то время в проекте живут два формата конфига и обвязка для |
| 30 | чтения bash. Это принято сознательно и ограничено по времени: см. ADR-002. |
| 31 | |
| 32 | **Отменено в части каталога данных.** «Новое ядро с первого дня работает |
| 33 | поверх существующей папки `data/` StartWine» больше не так: каталог свой, |
| 34 | путь к нему — настройка. См. ADR-012. Всё остальное — порядок замещения |
| 35 | подсистем, чтение старых конфигов, GUI последним — в силе. |
| 36 | |
| 37 | **Проверяемость.** `sw_runlib` собирает окружение перед запуском. Порт считается |
| 38 | готовым, когда дамп итогового окружения и командной строки совпадает с |
| 39 | bash-версией **побайтово** по всем 53 переменным на пяти разных играх (DX11, |
| 40 | DX12, OpenGL, 32-битная, с внешним лончером). Это превращает «вроде работает» в |
| 41 | проходящий тест. |
| 42 | |
| 43 | --- |
| 44 | |
| 45 | ## ADR-002. Конфиг — TOML со схемой, bash только для переноса |
| 46 | |
| 47 | **2026-09-02 · принято, реализовано** |
| 48 | |
| 49 | **Контекст.** Конфиг игры в StartWine — исполняемый bash-скрипт, подключаемый |
| 50 | через `source`. Нет схемы, валидации, миграций; конфиг может выполнить |
| 51 | произвольный код. Пока конфиг — bash, лаунчер обязан быть shell. |
| 52 | |
| 53 | **Решение.** TOML с типизированной схемой. Читалка bash-конфигов существует |
| 54 | **только для миграции** и будет удалена, когда переносить станет нечего. |
| 55 | |
| 56 | **Почему не оставить совместимость навсегда.** Тогда замок останется навсегда: |
| 57 | любая настройка должна была бы выражаться в bash, и это диктовало бы |
| 58 | архитектуру вечно. |
| 59 | |
| 60 | **Почему TOML, а не JSON или YAML.** Конфиг правят руками, значит нужны |
| 61 | комментарии — в JSON их нет. YAML отпадает из-за неоднозначной типизации |
| 62 | (`no` как логическое ложь, ведущие нули) — ровно тот класс ошибок, от которого |
| 63 | мы уходим. |
| 64 | |
| 65 | **Реализовано.** `chl-core/src/legacy.rs` и `chl-core/src/migrate.rs`. |
| 66 | |
| 67 | **Проверяемость.** Разбор обязан быть без потерь: каждый конфиг разбирается, |
| 68 | собирается обратно и сравнивается с исходником побайтово (`chl legacy verify`). |
| 69 | На реальной установке проверка проходит, все 53 настройки распознаны. |
| 70 | |
| 71 | **Побочная выгода.** Сгенерированный TOML самодокументирован: над каждой |
| 72 | настройкой печатается объяснение из реестра. |
| 73 | |
| 74 | --- |
| 75 | |
| 76 | ## ADR-003. Хранилище префиксов — контентно-адресуемое, снапшоты через reflink |
| 77 | |
| 78 | **2026-09-02 · принято, не реализовано (фаза 1)** |
| 79 | |
| 80 | **Контекст.** Бэкап префикса в StartWine — полный образ squashfs. Бэкап |
| 81 | сохранений — один общий образ, пересобираемый с нуля с `-noappend`, то есть |
| 82 | затирающий предыдущий. Версий нет: испорченное сохранение вытеснит целое, если |
| 83 | заметить позже пяти дней. |
| 84 | |
| 85 | **Решение.** Файлы префикса складываются в хранилище по хэшу содержимого, |
| 86 | префикс собирается reflink-копиями. Снапшот — операция на миллисекунды. |
| 87 | Одинаковые библиотеки в разных префиксах занимают место один раз. Снапшоты |
| 88 | версионные, старые не затираются новыми. |
| 89 | |
| 90 | Поверх — транзакции: любое изменение префикса (установка библиотеки, смена |
| 91 | версии Wine, применение `.reg`) снапшотится до, и откатывается одной кнопкой. |
| 92 | |
| 93 | **Почему reflink, а не btrfs-снапшоты подтомов.** Снапшот подтома работает |
| 94 | только на btrfs и только для целого подтома. Reflink на уровне файлов |
| 95 | (`FICLONE`) даёт то же на btrfs и xfs, и произвольную гранулярность. На `/home` |
| 96 | здесь btrfs — проверено, работает. |
| 97 | |
| 98 | **Запасной вариант.** Файловые системы без reflink (ext4) — жёсткие ссылки с |
| 99 | дедупликацией по хэшу. Медленнее и требует осторожности при записи, но |
| 100 | работает. |
| 101 | |
| 102 | **Почему не restic или borg целиком.** Они дают дедуплицированные бэкапы, но не |
| 103 | дают дешёвого *рабочего* префикса из хранилища: восстановление — это распаковка. |
| 104 | Нам нужно и то и другое. |
| 105 | |
| 106 | **Цена.** Своё хранилище — код, который обязан быть безупречным: ошибка теряет |
| 107 | данные. Поэтому фаза 1, а не фаза 0, и с проверкой целостности по хэшам. |
| 108 | |
| 109 | --- |
| 110 | |
| 111 | ## ADR-004. Обновления — подписанный манифест, версия закреплена за игрой |
| 112 | |
| 113 | **2026-09-02 · принято, не реализовано (фаза 2)** |
| 114 | |
| 115 | **Контекст.** `wine_version.json`: значение канала — одна строка с URL через |
| 116 | пробел. Ни версий как данных, ни контрольных сумм, ни подписей, ни отката. |
| 117 | Автообновлений нет — на такой структуре их безопасно не построить. |
| 118 | |
| 119 | **Решение.** Манифест с версиями Wine, DXVK, VKD3D и рантаймов, подписанный |
| 120 | ed25519. У каждого артефакта хэш и подпись. Дифф-загрузка вместо перекачивания |
| 121 | архива целиком. |
| 122 | |
| 123 | **Ключевое требование: обновление не может сломать работающую игру.** Версия |
| 124 | закреплена за игрой; обновление добавляет новую, переключение — осознанное |
| 125 | действие с откатом. |
| 126 | |
| 127 | **Почему подпись, а не только хэш.** Хэш защищает от повреждения при передаче, |
| 128 | подпись — от подмены на зеркале. Артефакты качаются с трёх разных зеркал, |
| 129 | включая сторонние. |
| 130 | |
| 131 | **Цена.** Нужно где-то держать приватный ключ и процедуру выпуска манифеста. |
| 132 | Для личного проекта это несколько строк, но забыть про ротацию нельзя. |
| 133 | |
| 134 | --- |
| 135 | |
| 136 | ## ADR-005. Epic: библиотека нативно, магазин через webview |
| 137 | |
| 138 | **2026-09-02 · принято, не реализовано (фаза 3)** |
| 139 | |
| 140 | **Контекст.** В StartWine два несвязанных пути: код на основе legendary тянет |
| 141 | только список игр, отдельно качается настоящий Windows-лончер Epic в свой |
| 142 | префикс. Отсюда «показывает только список игр». |
| 143 | |
| 144 | **Решение.** Библиотека, установка и запуск — нативно, через тот же |
| 145 | OAuth-поток, что у legendary и Heroic. Магазин и настройки аккаунта — webview |
| 146 | на настоящий `store.epicgames.com`. |
| 147 | |
| 148 | **Почему не разбирать приватные API магазина.** Публичного API магазина Epic не |
| 149 | существует. Разбор приватных эндпоинтов означает поломку при каждом их |
| 150 | изменении и работу на стороне обхода их правил. Покупки на настоящем сайте — |
| 151 | и легально, и безопасно. |
| 152 | |
| 153 | **Почему не оставить Windows-лончер Epic.** Это CEF-браузер внутри Wine: |
| 154 | тяжёлый, медленный, и именно он делает интерфейс неотзывчивым. Webview на |
| 155 | WebKitGTK даёт тот же магазин без Wine в цепочке. |
| 156 | |
| 157 | **Цена.** Две технологии вместо одной: нативный клиент плюс webview. Плюс |
| 158 | webview тянет WebKitGTK в зависимости. |
| 159 | |
| 160 | --- |
| 161 | |
| 162 | ## ADR-006. Steam: поддержать оба режима, не обещать замену |
| 163 | |
| 164 | **2026-09-02 · принято, не реализовано (фаза 3)** |
| 165 | |
| 166 | **Контекст.** Желание — вшить Steam так, чтобы нативный Linux-клиент стал не |
| 167 | нужен. Раньше через StartWine ставился Windows-Steam, и это работало. |
| 168 | |
| 169 | **Решение.** Оба режима первоклассны, выбор — на уровне игры. Windows-Steam в |
| 170 | Wine устанавливается автоматически в свой префикс. Нативный Steam |
| 171 | обнаруживается через `libraryfolders.vdf`, игры лаунчера добавляются в него |
| 172 | ярлыками с артом, чтобы попадать в Game Mode на Steam Deck. |
| 173 | |
| 174 | **Чего не обещаем.** Полной замены нативного Steam. Игры с EAC и BattlEye |
| 175 | работают только через нативный Steam с Proton — там задействованы Linux-сборки |
| 176 | самих античитов, и никакая настройка Wine это не обходит. Обещать замену — |
| 177 | обмануть пользователя, и это вернётся баг-репортами, на которые нечего |
| 178 | ответить. |
| 179 | |
| 180 | **Отдельно.** Клиент Steam нельзя включить в поставку: Valve не разрешает |
| 181 | распространение третьими лицами. Автоматизировать скачивание с официального |
| 182 | адреса — можно, так делают все. «Вшитый Steam» на практике означает установку |
| 183 | в один клик. |
| 184 | |
| 185 | --- |
| 186 | |
| 187 | ## ADR-007. GUI — GTK4 и libadwaita через gtk4-rs |
| 188 | |
| 189 | **2026-09-02 · принято, не реализовано (фаза 4)** |
| 190 | |
| 191 | **Решение.** GTK4 с libadwaita через `gtk4-rs`. Один тулкит, два режима |
| 192 | компоновки: настольный и Big Picture с навигацией геймпадом. |
| 193 | |
| 194 | **Почему.** Текущий UI уже GTK4, значит сохраняется визуальная преемственность |
| 195 | и переносятся CSS-темы. libadwaita даёт адаптивность «десктоп ↔ Deck». GTK4 |
| 196 | рендерит через Vulkan, что важно на Deck. Доступность, ввод и Wayland работают |
| 197 | сразу, а не через год допиливания. |
| 198 | |
| 199 | **Почему не Iced или egui.** Геймпад-навигация в них проще, но настольная |
| 200 | интеграция хуже: диалоги файлов, экранная клавиатура, IME, доступность. Для |
| 201 | лаунчера, который должен «не вызывать вопросов», это важнее. |
| 202 | |
| 203 | **Почему не два тулкита.** Соблазн «GTK для десктопа, egui для Big Picture» |
| 204 | кончается двумя недоделанными интерфейсами. |
| 205 | |
| 206 | **Цена.** Своя система навигации фокусом для геймпада: в GTK4 её придётся |
| 207 | писать руками. |
| 208 | |
| 209 | --- |
| 210 | |
| 211 | ## ADR-008. Настройка не может существовать без объяснения |
| 212 | |
| 213 | **2026-09-02 · принято, реализовано** |
| 214 | |
| 215 | **Контекст.** Главная претензия к StartWine со стороны пользователя: «а зачем |
| 216 | вот эта кнопка». Настройки есть, объяснений нет, и никакой процесс это не |
| 217 | исправит — забывать документировать будут всегда. |
| 218 | |
| 219 | **Решение.** Реестр настроек в коде. Структура `Spec` требует `doc` («что |
| 220 | делает»), `impact` («когда менять и что будет») и `tier` (уровень сложности). |
| 221 | Пропустить поле нельзя — компилятор не примет неполный литерал. Из реестра |
| 222 | генерируются UI, справка CLI и комментарии в конфиге. |
| 223 | |
| 224 | **Почему типами, а не соглашением.** Соглашение нарушается в первый же |
| 225 | занятой вечер. Тип — нет. |
| 226 | |
| 227 | **Реализовано.** `chl-core/src/settings.rs`, 53 настройки. Тест |
| 228 | `каждая_настройка_объяснена` не даст оставить объяснение пустым. |
| 229 | |
| 230 | **Дополнительно к реализации.** Провенанс значения: рядом с переключателем |
| 231 | показывать, откуда взялось текущее значение — профиль сообщества, автоопределение |
| 232 | или ручная правка с датой. |
| 233 | |
| 234 | --- |
| 235 | |
| 236 | ## ADR-009. Код живёт в репозитории project-chimera, пока недоступна gitea |
| 237 | |
| 238 | **2026-09-02 · принято, временное** |
| 239 | |
| 240 | **Контекст.** План — отдельный репозиторий `chimera-launcher` в |
| 241 | `git.chimera.local`, по образцу `k8s-manifests`. Но на 2026-09-02 |
| 242 | `git.chimera.local` не резолвится, `/etc/hosts` пуст, `~/.ssh` не существует: |
| 243 | свежая CachyOS ещё не подключена к кластеру. |
| 244 | |
| 245 | **Решение.** Пока код лежит в `13-chimera-launcher/` репозитория |
| 246 | `project-chimera` и синхронизируется Яндекс.Диском. Когда доступ к кластеру |
| 247 | появится, каталог выделяется в свой репозиторий (`git subtree split` сохранит |
| 248 | историю). |
| 249 | |
| 250 | **Каталог сборки уведён за пределы Яндекс.Диска** — в |
| 251 | `~/.cache/chimera-launcher/target` через `code/.cargo/config.toml`. Иначе |
| 252 | гигабайты объектных файлов пойдут в синхронизацию. |
| 253 | |
| 254 | **Условие снятия.** Резолвится `git.chimera.local` — и это единственное, что |
| 255 | осталось. Проверено 2026-09-02 вечером: доверие к `cluster-selfsigned-ca` на |
| 256 | этой машине уже настроено (`curl` без `-k` отдаёт 200), а ключ SSH для git по |
| 257 | HTTPS не нужен. |
| 258 | |
| 259 | Адрес для `/etc/hosts` — **`10.40.8.14`** (acer, ingress), а не |
| 260 | `10.40.8.10` (master xeon, где 80 и 443 закрыты). Полный список хостов и |
| 261 | готовая команда: `02-infrastructure/DNS и доступ к chimera.local.md`. |
| 262 | |
| 263 | --- |
| 264 | |
| 265 | ## ADR-010. Вольт — источник правды, gitea — зеркало через subtree |
| 266 | |
| 267 | **2026-09-02 · принято, ожидает первого push** |
| 268 | |
| 269 | **Контекст.** ADR-009 предполагал выделить каталог в отдельный репозиторий, |
| 270 | когда появится доступ к gitea. Доступ появился: записи в `/etc/hosts` на |
| 271 | `10.40.8.14` сделаны, `git.chimera.local` отдаёт 200, API Gitea 1.27.3 |
| 272 | отвечает. Возник вопрос, где после этого живёт источник правды. |
| 273 | |
| 274 | **Решение.** Каталог `13-chimera-launcher/` в репозитории `project-chimera` |
| 275 | остаётся источником правды. Репозиторий `git.chimera.local/fanchji/chimera-launcher` |
| 276 | — **зеркало**, обновляется командой `git subtree push`. Прямые коммиты в |
| 277 | зеркало не делаются. |
| 278 | |
| 279 | **Почему не сделать зеркало рабочей копией.** Своя папка `.git` внутри |
| 280 | Яндекс.Диска — это риск повреждения объектов git при синхронизации: клиент |
| 281 | может синхронизировать файлы репозитория в момент записи, и получится |
| 282 | рассогласованное состояние. Вольт уже один репозиторий на синхронизируемом |
| 283 | диске, второй вложенный внутрь удваивает риск без выгоды. |
| 284 | |
| 285 | **Почему это согласуется с проектом.** Ровно тот же паттерн уже применён к |
| 286 | `k8s-manifests`: вольт — источник правды по докам и истории, в отдельный |
| 287 | репозиторий зеркалится только нужный подкаталог (`03-kubernetes/`). Одно |
| 288 | правило вместо двух разных. |
| 289 | |
| 290 | **Как обновлять зеркало:** |
| 291 | |
| 292 | ``` |
| 293 | git subtree push -P 13-chimera-launcher launcher master |
| 294 | ``` |
| 295 | |
| 296 | Remote `launcher` уже прописан. |
| 297 | |
| 298 | **Цена и главный риск.** Если закоммитить прямо в зеркало — минуя вольт — |
| 299 | истории разойдутся, и `subtree push` начнёт отвергать. Поэтому правило |
| 300 | жёсткое: править только в вольте. Если понадобится работать с другой машины, |
| 301 | правильный путь — клонировать зеркало, а изменения влить обратно в вольт |
| 302 | через `git subtree pull`, а не пушить в зеркало напрямую. |
| 303 | |
| 304 | **Отменяет** часть ADR-009 про «выделяется в свой репозиторий»: репозиторий |
| 305 | создаётся, но становится зеркалом, а не новым домом проекта. |
| 306 | |
| 307 | --- |
| 308 | |
| 309 | ## ADR-011. Свой репозиторий, а не каталог в вольте |
| 310 | |
| 311 | **2026-09-02 · принято, выполнено · отменяет ADR-010** |
| 312 | |
| 313 | **Контекст.** Распоряжение владельца: «Разделите свои проекты, не надо всё в |
| 314 | кучу валить. Аналог Discord и CachyOS это не относящиеся к кластеру проекты, |
| 315 | они просто будут исходники на моём git держать по сути.» |
| 316 | |
| 317 | **Решение.** Chimera-Launcher — самостоятельный проект в собственном |
| 318 | репозитории `git.chimera.local/fanchji/chimera-launcher` (private, |
| 319 | ветка `main`). Рабочая копия — `~/Projects/chimera-launcher`. Каталога |
| 320 | `13-chimera-launcher/` в `project-chimera` больше нет. |
| 321 | |
| 322 | **Что это отменяет в ADR-010.** Там вольт был источником правды, а Gitea — |
| 323 | зеркалом подкаталога через `git subtree push`, по образцу `k8s-manifests`. |
| 324 | Теперь наоборот: источник правды — этот репозиторий, вольт к проекту |
| 325 | отношения не имеет. Причина смены не техническая: модель зеркала была |
| 326 | разумной, пока лаунчер считался частью хоумлаба. Владелец решил, что он |
| 327 | частью хоумлаба не является — в кластер не деплоится ничего. |
| 328 | |
| 329 | **Что из ADR-010 осталось верным.** Довод против вложенной папки `.git` |
| 330 | внутри Яндекс.Диска: клиент может синхронизировать файлы репозитория в |
| 331 | момент записи и получить рассогласованное состояние. Поэтому рабочая копия |
| 332 | живёт в `~/Projects`, а не на синхронизируемом диске. |
| 333 | |
| 334 | **Перенос.** `git subtree split --prefix=13-chimera-launcher`, 5 коммитов, |
| 335 | push в `main`. Целостность проверена не на глаз: хэш дерева в Gitea |
| 336 | (`0e38bb1d`) совпал с хэшем каталога в вольте, то есть содержимое перенесено |
| 337 | побайтово. Тесты и clippy в отдельной копии проходят, CLI работает против |
| 338 | реальной установки StartWine. |
| 339 | |
| 340 | **Цена: потеряна синхронизация через Яндекс.Диск.** Вольт был механизмом |
| 341 | передачи между машинами и сессиями, и на машине без доступа к кластеру |
| 342 | исходники теперь недоступны — ровно тот блокер, который решали утром |
| 343 | 2026-09-02. Смягчается тем, что рабочая копия лежит локально, а доступ к |
| 344 | кластеру стал устойчивее (wildcard-DNS на Mikrotik вместо записей в |
| 345 | `/etc/hosts`). Но если понадобится работать с машины вне этой сети — нужен |
| 346 | либо доступ к кластеру, либо второе зеркало. |
| 347 | |
| 348 | **Аутентификация.** У Gitea два независимых входа: Dex и Keycloak работают |
| 349 | только в браузере, а `git` умеет исключительно Basic Auth и OAuth-редирект |
| 350 | пройти не может физически. Поэтому пароль от Dex для `git push` не |
| 351 | срабатывает никогда, а ошибка выглядит как «неверные креды». Нужен токен |
| 352 | (`chimera-automation`, скоуп `write:repository`); он лежит в Secret Service, |
| 353 | поэтому push проходит без диалогов. Токен намеренно не умеет создавать |
| 354 | репозитории — на `POST /user/repos` отдаёт 403, для этого нужен `write:user`, |
| 355 | которого у него нет. |
| 356 | |
| 357 | |
| 358 | --- |
| 359 | |
| 360 | ## ADR-012. Самообновление лаунчера: подписанный статический файл, подмена по `rename`, автооткат |
| 361 | |
| 362 | **2026-09-07 · принято, выполнено** |
| 363 | |
| 364 | **Контекст.** Пункт 4 фазы 2 (`ROADMAP.md`) — «атомарное обновление самого |
| 365 | лаунчера с откатом» — был осознанно оставлен design-only: |
| 366 | `chl-wine/WINE-UPDATES-DESIGN.md` объяснял, что ошибка в этом коде отключает |
| 367 | **единственный работающий бинарник**, и оставлял три открытых вопроса, |
| 368 | которые просил решить до кода, а не по ходу. Владелец попросил довести пункт |
| 369 | до конца: «приложение должно обновляться атомарно, не надо никуда ходить, |
| 370 | ничего качать», уведомление как в KDE, раздел с patch notes и выбор из трёх — |
| 371 | поставить сейчас, потом, пропустить. |
| 372 | |
| 373 | **Решение.** Отдельный крейт `chl-selfupdate`; обёртками служат `chl update` |
| 374 | и раздел «Обновления» в интерфейсе, оба зовут одни и те же функции. |
| 375 | |
| 376 | 1. **Источник — статический подписанный файл по HTTPS**, адрес в настройке |
| 377 | `update_feed_url`. Никакого API, никакой авторизации, никакого состояния |
| 378 | на сервере. |
| 379 | 2. **Доверие — подпись ed25519 тем же ключом и тем же кодом |
| 380 | (`chl_wine::sign`), что у манифеста сборок Wine** (ADR-004). Второй модели |
| 381 | доверия проект не заводит. Плюс sha256 каждого файла из подписанного |
| 382 | манифеста — проверяется и сразу после скачивания, и второй раз перед |
| 383 | подменой. |
| 384 | 3. **Атомарность — staging рядом плюс `rename(2)`** в пределах одной |
| 385 | файловой системы. Прежний файл сохраняется как `<имя>.предыдущая` |
| 386 | переименованием, не копией. |
| 387 | 4. **Журнал `.chl-обновление.toml` рядом с бинарниками**, пишется **до** |
| 388 | каждого шага. Он и делает обрыв восстановимым. |
| 389 | 5. **Маркер здоровья с автооткатом.** `Applied { starts, confirmed }`: первый |
| 390 | запуск новой версии увеличивает `starts`, а подтверждает её только код, |
| 391 | дошедший до настоящей работы (в CLI — успешно выполненная команда, в GUI — |
| 392 | собранное и показанное окно плюс три секунды). Запуск, увидевший |
| 393 | неподтверждённую метку, выставленную прошлым запуском, откатывается сам, |
| 394 | без вопросов. |
| 395 | 6. **Проверка автоматическая, установка — никогда.** Настройка |
| 396 | `self_update_check`, включена по умолчанию; ставить всегда выбирает |
| 397 | человек, из трёх вариантов, и «пропустить» запоминается по версии. |
| 398 | |
| 399 | **Ответы на три открытых вопроса design-документа.** |
| 400 | |
| 401 | - *Где лежит `chl`* — каталог берётся из `current_exe()`, а не из зашитого |
| 402 | `~/.local/bin`: обновление пишет туда, где лаунчер работает сейчас, иначе |
| 403 | оно тихо создало бы вторую установку. |
| 404 | - *Автоматически или по спросу* — см. пункт 6. Фоновое обновление без |
| 405 | спроса противоречило бы остальному проекту (`chl wine installed` тоже |
| 406 | только сообщает). |
| 407 | - *Что с двумя бинарниками* — их два (`chl` и `chimera-launcher`), это одна |
| 408 | установка на двоих, и обновляются они одним манифестом за один проход. |
| 409 | Список заменяемых имён закрытый (`manifest::UPDATABLE`): подписанному |
| 410 | манифесту всё равно нельзя разрешать записать произвольный путь. |
| 411 | |
| 412 | **Почему не бэкенд совместимости как API.** `chl-compat` уже умеет говорить |
| 413 | с `chimera-compat.chimera.local`, и соблазн был. Отвергнуто: у него своя |
| 414 | задача (отчёты о совместимости игр), свой токен и свои коды ответа. Отдавать |
| 415 | через него бинарники значило бы связать выпуск релиза с доступностью |
| 416 | прикладного API и потребовать токен там, где он не нужен — подлинность |
| 417 | держится на подписи, а не на том, кто спрашивает. Хост при этом взят тот же: |
| 418 | он единственный в личной инфраструктуре, чей сертификат уже доверен |
| 419 | системным хранилищем. |
| 420 | |
| 421 | **Почему не публичный git-хостинг.** Этого проекта там нет и по замыслу не |
| 422 | будет (README: «публиковаться не планируется»). Завести зеркало ради канала |
| 423 | обновлений — это решение о публикации проекта, а не о механизме обновления. |
| 424 | |
| 425 | **Цена, названная прямо.** |
| 426 | |
| 427 | - **Уже запущенный процесс продолжает работать на старом коде.** `rename` не |
| 428 | трогает открытый inode. Обойти это нельзя никакой схемой замены файла; |
| 429 | обёртки говорят «закрой и открой заново», а не «обновление применено». |
| 430 | - **Два файла — это две операции `rename`, а не одна.** Существует момент, |
| 431 | когда на диске смесь версий. Скрыть его нельзя (в POSIX нет способа |
| 432 | переименовать два файла разом) — он сделан распознаваемым: журнал плюс |
| 433 | `recover`, который достраивает перенос, если staging цел, и откатывает |
| 434 | всё, если нет. |
| 435 | - **Пока `keys/wine-manifest.pub` пуст, обновление не устанавливается |
| 436 | вообще.** Из вариантов «без ключа ставим по одному sha256» и «без ключа не |
| 437 | ставим ничего» выбран второй: хэш, лежащий в том же файле, что и ссылка, |
| 438 | защищает от повреждения при передаче, но не от подмены обоих сразу, то |
| 439 | есть от единственной угрозы, ради которой всё это делается, не защищает. |
| 440 | `chl update --status` и раздел «Обновления» говорят об этом вслух, а не |
| 441 | отказывают в последний момент. |
| 442 | - **Проверка, включённая по умолчанию, — это запрос к серверу при каждом |
| 443 | запуске.** Отличие от `kb_fetch_enabled` (выключена по умолчанию) не в |
| 444 | последовательности: там уходят названия игр из библиотеки на сторонние |
| 445 | сайты, здесь — пустой GET к личной инфраструктуре владельца, уже |
| 446 | единственному адресу в `PRIVACY.md`, к которому лаунчер обращается без |
| 447 | нажатия кнопки. Настройка описана в реестре, названа в `PRIVACY.md` и |
| 448 | выключается в двух местах интерфейса. |
| 449 | |
| 450 | **Проверяемость.** Подмена, откат, обрыв посреди подмены (и когда его можно |
| 451 | достроить, и когда нельзя), несовпадение хэша, порча подготовленного файла |
| 452 | между «скачал» и «поставил», автооткат неподтверждённой версии — юнит-тесты |
| 453 | `chl_selfupdate::apply` на настоящих файлах в tempdir. Плюс живой прогон |
| 454 | 2026-09-07 на выброшенном дереве установки: манифест собран `chl |
| 455 | update-manifest` по настоящим sha256, подписан `chl wine manifest sign`, |
| 456 | подделка манифеста отвергнута проверкой подписи, подменённый файл при верном |
| 457 | манифесте отвергнут проверкой хэша. |
| 458 | |
| 459 | --- |
| 460 | |
| 461 | ## ADR-012. Каталог данных свой, а путь к нему — настройка · отменяет часть ADR-001 |
| 462 | |
| 463 | **2026-09-07 · принято, реализовано** |
| 464 | |
| 465 | **Контекст.** ADR-001 сажал ядро поверх папки `data/` StartWine. Это |
| 466 | кончилось 2026-09-03: StartWine обновил общий префикс сборкой GE-Proton11-6, |
| 467 | конфиг игры остался на GE-Proton10-34, запуск встал с «wine client error: |
| 468 | version mismatch 935/864». Тогда появился `chl migrate` и каталог |
| 469 | `~/Games/Chimera`, но развязка вышла неполной. Путь был зашит в код. Из |
| 470 | чужого каталога копировалась папка `scripts/` целиком — 9,6 МБ питона |
| 471 | StartWine, который мы не запускаем, — и признаком «это каталог данных» |
| 472 | служило именно её наличие, так что удалить StartWine всё ещё было нельзя. |
| 473 | Абсолютные пути внутри префиксов не правились вовсе, кроме одного поля в |
| 474 | библиотеке. |
| 475 | |
| 476 | **Решение.** Каталог данных — свой, опознаётся файлом-меткой |
| 477 | `data/.chimera-каталог`, а не чужой папкой. Путь к нему — настройка |
| 478 | `data_root`; пусто означает `~/Games/Chimera`. Из `scripts/` забираются два |
| 479 | файла каталогов версий в свой `data/catalogs/`. Перенос — команда |
| 480 | `chl move-root <путь>`: по умолчанию отчёт, действие по `--apply`. |
| 481 | |
| 482 | **Почему по умолчанию `~/Games/Chimera`, а не каталог по XDG.** Внутри — |
| 483 | префиксы и сборки Wine, на этой машине 301 ГиБ логического объёма. Это |
| 484 | данные, которые уносят на другой диск, когда на системном становится тесно, |
| 485 | и каталог, на который предполагается показывать пальцем в файловом |
| 486 | менеджере, не должен лежать в скрытой папке. Так же поступают соседи: Heroic |
| 487 | ставит игры в `~/Games/Heroic`, Lutris предлагает `~/Games`. За XDG остаётся |
| 488 | то, что мало и ценно: настройки, библиотека, журналы запусков. |
| 489 | |
| 490 | **Почему один общий префикс, а не по префиксу на игру.** Прямое требование |
| 491 | владельца: «Основная задача — минимизировать потребление ресурсов и |
| 492 | дискового пространства. Иначе у нас раздуется до террабайтов префиксы игр». |
| 493 | Он держал общий префикс в StartWine годами, и это работало. Разные игры |
| 494 | разводятся настройками, а не копиями Windows. |
| 495 | |
| 496 | **Почему `--reflink=always`, а не `auto`.** `auto` при отказе reflink молча |
| 497 | копирует полностью. На 301 ГиБ это означает незамеченный расход диска |
| 498 | вместо ошибки. `always` в том же случае падает, и способ переноса выбирается |
| 499 | заранее — пробным reflink настоящего файла в целевом каталоге, а не по имени |
| 500 | файловой системы: btrfs с `nodatacow` — это btrfs, у которого reflink на |
| 501 | этом подтоме не работает. |
| 502 | |
| 503 | **Что переезд ломает внутри префиксов.** Это оказалось главной работой, а не |
| 504 | деталью. Регистрация шрифтов в `system.reg`/`user.reg` записана абсолютными |
| 505 | DOS-путями внутрь сборки Wine, и написаний два — через `H:` и через `Z:`, |
| 506 | потому что буквы дисков ведут в разные места. Всё вне ASCII Wine пишет |
| 507 | шестнадцатеричным экраном (`\x441\x442…`), так что поиск по тому, как путь |
| 508 | выглядит, на каталоге с русским именем не находит ничего. Ярлыки |
| 509 | `.desktop` в `drive_c` хранят unix-путь. Ссылка `dosdevices/e:` |
| 510 | абсолютная. Ссылка `drive_c/Games` создаётся под условием «если её ещё нет» |
| 511 | и битой остаётся навсегда. Подробный разбор с пометкой, что чинится само, а |
| 512 | что нет, — в шапке `chl-wine/src/rebase.rs` и в вики проекта. |
| 513 | |
| 514 | **Почему старый каталог не удаляется.** Перенос заканчивается тем, что новый |
| 515 | каталог рабочий, а старый лежит как лежал. Откат — вернуть настройку. |
| 516 | Освободить место — отдельное решение владельца отдельной командой. На |
| 517 | reflink это ничего не стоит: 301 ГиБ логических данных в двух каталогах |
| 518 | занимают на диске 218 МиБ сверх исходного. |
| 519 | |
| 520 | **Цена.** Два способа опознать каталог данных (метка и `data/scripts`), пока |
| 521 | жив `chl migrate`. Плюс сам `move-root` — код, который правит реестр |
| 522 | работающих префиксов, то есть обязан быть точным: ошибка здесь ломает |
| 523 | запуск. Отсюда журнал перед действием и проверка после — не «файлы |
| 524 | скопированы», а «префикс открывается, сборка отвечает своей версией, игры |
| 525 | находятся». |
| 526 | |
| 527 | **Проверяемость.** Живой прогон 2026-09-07 на 301,69 ГиБ данных владельца: |
| 528 | 32 правки путей в 3 префиксах, 12 снимках и шаблоне (173 вхождения в |
| 529 | реестре), время копирования 5,8 с. `btrfs filesystem du -s` до: 7,57 ГиБ |
| 530 | исключительных. После: 167 МиБ у старого и 51 МиБ у нового при 301 ГиБ |
| 531 | логического объёма в каждом. Из перенесённого каталога запущена Gothic 1 |
| 532 | Remake — главное меню, VKD3D 60 fps, VRAM 9,1 ГиБ, `WINEPREFIX` и |
| 533 | `WINEDLLPATH` процесса ведут в новый каталог, ни одного отображённого файла |
| 534 | из старого. |
| 535 | |
| 536 | --- |
| 537 | |
| 538 | ## ADR-013. macOS не поддерживаем |
| 539 | |
| 540 | **Дата:** 2026-09-11. **Статус:** принято. |
| 541 | |
| 542 | ### Контекст |
| 543 | |
| 544 | Разобрали GameHub — лаунчер Windows-игр для macOS — и возник вопрос, не сделать |
| 545 | ли то же самое у себя: один лаунчер на Linux и macOS. |
| 546 | |
| 547 | ### Решение |
| 548 | |
| 549 | Не делаем. Силы идут в качество продукта на Linux. |
| 550 | |
| 551 | ### Почему |
| 552 | |
| 553 | Три независимых стены, каждая сама по себе — отдельный проект: |
| 554 | |
| 555 | 1. **Интерфейс.** GTK4 на macOS второсортен, а WebKitGTK там просто нет — |
| 556 | витрины магазинов пришлось бы переписывать на WKWebView. Плюс `ksni` (трей |
| 557 | через D-Bus), `ashpd` (XDG-порталы), `evdev` в двух крейтах (геймпады и |
| 558 | хоткеи через `/dev/input`): четыре подсистемы заново. |
| 559 | 2. **Рантайм.** Мы стоим на Proton, Vulkan и DXVK/VKD3D. На macOS ничего этого |
| 560 | нет — там GPTK, MoltenVK, DXMT, то есть второй бэкенд запуска размером с |
| 561 | половину проекта. Отдельно открыт вопрос, что из этого вообще допустимо в |
| 562 | проекте под GPL-3.0-or-later. |
| 563 | 3. **Железо.** Apple Silicon — ARM, а игры x86. Нужен слой трансляции |
| 564 | (Rosetta, FEX), которого у нас нет вовсе. |
| 565 | |
| 566 | ### Что это значит на практике |
| 567 | |
| 568 | - Разведка на MacBook отменена, задание снято. |
| 569 | - Разбор GameHub не выброшен: его выводы — стабильный ключ игры, слои профилей, |
| 570 | рецепты зависимостей, метка процесса, исключения на `.exe` — про устройство |
| 571 | лаунчера вообще, а не про macOS. Они в фазе 6 `ROADMAP.md`. |
| 572 | - Разрез «переносимое ядро / платформенный слой» остаётся полезным сам по себе |
| 573 | (тесты без GTK, Steam Deck), но делается по месту, а не кампанией под macOS. |
| 574 | |
| 575 | ### Если решение будут пересматривать |
| 576 | |
| 577 | Пересматривать имеет смысл только вместе с ответом на три стены выше. Первым |
| 578 | пунктом — лицензионный разбор графического слоя: без него порт упирается не в |
| 579 | трудоёмкость, а в право. |
| 580 |