Project Chimera
Меню

Исходники

109 строк · 9 КиБ

tools/env-dump-harness/README.md

1# Харнесс сравнения окружения: bash vs `chl env`
2
3Инструмент для критерия готовности Фазы 0 (см. `ROADMAP.md`): дамп
4окружения, с которым `sw_runlib` запустил бы игру, сравнивается с `chl env
5<игра>` — без единого реального запуска Wine.
6
7## Как это работает
8
9`sw_runlib` — это не исполняемый скрипт, а библиотека функций, которую
10`sw_function.sh` подключает через `. sw_runlib` и затем вызывает
11`RUN_VULKAN "$@"`. Реальный запуск игры в итоге сводится к одной из четырёх
12строк вида `"${WINELOADER}" ... "$@" ${LAUNCH_PARAMETERS}` (OpenGL/vulkan ×
13виртуальный рабочий стол вкл/выкл) в самом конце `RUN_VULKAN`.
14
15`setup.sh` строит «теневую» установку StartWine рядом (`OUT_DIR/StartWine`):
16своя копия `sw_runlib`/`sw_function.sh` (единственные два реально
17скопированных и изменённых файла — патчит их `patch-sw-runlib.py`),
18всё остальное — симлинки на настоящую установку (`~/Games/StartWine` по
19умолчанию). `app_config/` и `data/scripts/` симлинкуются файл-за-файлом, а
20не каталогом целиком — это позволяет добавлять свои тестовые/шаблонные
21`app_config`-файлы, не трогая реальную установку.
22
23Патч (`patch-sw-runlib.py`) делает три вещи:
24
251. Каждую из четырёх exec-строк заменяет на `env | sort` в файл
26 `$SW_ENV_DUMP_FILE` + `exit 0` — до `"${WINESERVER}" -w` и
27 `create_backup()` (это уже послезапусковая бухгалтерия, не нужная для
28 дампа) выполнение не доходит.
292. `sw_win_ver()`: убирает единственный реальный запуск Wine в этой функции
30 (`winecfg -v`, срабатывает только если версия Windows в префиксе ещё не
31 та, что нужна) — превращает в лог и `return 1`.
323. `try_fix_pfx()`: убирает переинициализацию ещё не созданного префикса
33 (`try_remove` + `unsquashfs` + `wineboot`) — харнесс дампает окружение
34 только для уже рабочих префиксов, создавать новые ему не нужно и не
35 безопасно.
36
37Всё остальное (DLL-копии в префикс, симлинки дисков, правки `system.reg`)
38остаётся как в оригинале: это обычная подготовка перед запуском, которая
39происходит при любом реальном старте игры, и без неё сравнение с bash было
40бы нечестным. Копируемые DLL действительно попадают в настоящий префикс —
41это ожидаемо и безвредно, ровно то же самое произошло бы при реальном
42запуске той же игры через старый интерфейс.
43
44## Использование
45
46```bash
47./setup.sh # ~/Games/StartWine -> временный OUT_DIR
48./setup.sh /путь/к/StartWine /путь/к/OUT_DIR # явно
49
50OUT=/путь/к/OUT_DIR # setup.sh печатает его в конце
51
52"$OUT/baseline-dump.sh" > "$OUT/baseline.dump"
53"$OUT/run-dump.sh" "$OUT/bash-<игра>.dump" /абсолютный/путь/к/игра.exe [аргументы]
54
55# на стороне chl -- собранный бинарник, не `cargo run` (иначе в PATH и
56# LD_LIBRARY_PATH попадает мусор сборки cargo/rustc, который не имеет
57# отношения к самой игре):
58cargo build -p chl-cli --release
59chl env <игра> --root /путь/к/StartWine > chl-<игра>.txt
60
61python3 compare.py "$OUT/baseline.dump" "$OUT/bash-<игра>.dump" chl-<игра>.txt \
62 --scratch-root "$OUT/StartWine" --real-root /путь/к/StartWine --chl-root /путь/к/StartWine
63```
64
65`--scratch-root`/`--real-root` нужны потому, что пути внутри дампа bash
66буквально содержат `$OUT/StartWine/...` (там, где скрипт физически лежит),
67хотя через симлинки это ровно те же файлы, что под настоящим
68`~/Games/StartWine/...` — `compare.py` меняет префикс перед сравнением.
69
70## Методология сравнения
71
72`env | sort` у bash — это **весь** унаследованный процесс: `TERM`, `HOME`,
73`DISPLAY`, входящий `PATH` и далее по списку, вперемешку с тем, что реально
74выставил `sw_runlib`. `chl env`, наоборот, печатает только то, чем реально
75управляет `chl-runtime::env::build` (см. `Env::dump()`) — не полный
76слепок процесса. Прямое сравнение двух таких дампов один-в-один дало бы
77сотни «расхождений», не имеющих отношения к порту.
78
79Поэтому `compare.py` сначала считает **дельту** bash-дампа относительно
80`baseline.dump` (тот же процесс, тот же `PATH`, но без `. sw_runlib`) —
81это и есть «что именно сделал sw_runlib», по конструкции свободное от
82`TERM`/`DISPLAY`/`HOME` и прочего окружения сеанса. Дальше сравниваются
83только переменные, которыми управляет хотя бы одна из сторон:
84
85- **совпадение** — оба выставили одно и то же значение (либо оба сняли);
86- **расхождение** — разное значение, либо одна сторона выставляет, а
87 другая снимает или не трогает;
88- **только bash** — bash это трогает, `chl env` — нет вовсе (кандидат в
89 недостающую часть порта);
90- **только chl** — обратное (в основном безвредный артефакт методики: `chl`
91 явно объявляет переменную «снятой» через `Note`, а bash её никогда не
92 трогал — результат один и тот же, «переменной нет», просто дельта
93 относительно baseline это не видит, потому что различий на входе и
94 выходе у bash нет).
95
96## Как выбирались 5 игр
97
98Реально установленных игр с собственным bash-конфигом на машине было
99только две: `bananarfo` (RF Online, 32-бит, DX9) и (частично) `StartWine`
100сама по себе. Остальные три категории закрыты либо реальным exe без
101исторического bash-конфига (конфиг для сравнения строится из
102дефолтов `chl-core::settings::REGISTRY`, переведённых обратно в
103bash-присваивания скриптом ниже, плюс те же оверрайды, что в реальном
104`.toml` игры — так гарантируется, что bash- и chl-стороны стартуют с
105ОДИНАКОВЫХ настроек, а не с разных наборов дефолтов), либо шаблоном
106`.default/<launcher>` из самой установки StartWine, когда на машине нет
107вообще ни одного реального примера категории (OpenGL). Подробности — в
108финальном отчёте сессии (STATUS.md/Plane), не здесь.
109