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 | |
| 25 | 1. Каждую из четырёх exec-строк заменяет на `env | sort` в файл |
| 26 | `$SW_ENV_DUMP_FILE` + `exit 0` — до `"${WINESERVER}" -w` и |
| 27 | `create_backup()` (это уже послезапусковая бухгалтерия, не нужная для |
| 28 | дампа) выполнение не доходит. |
| 29 | 2. `sw_win_ver()`: убирает единственный реальный запуск Wine в этой функции |
| 30 | (`winecfg -v`, срабатывает только если версия Windows в префиксе ещё не |
| 31 | та, что нужна) — превращает в лог и `return 1`. |
| 32 | 3. `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 | |
| 50 | OUT=/путь/к/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 | # отношения к самой игре): |
| 58 | cargo build -p chl-cli --release |
| 59 | chl env <игра> --root /путь/к/StartWine > chl-<игра>.txt |
| 60 | |
| 61 | python3 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`, переведённых обратно в |
| 103 | bash-присваивания скриптом ниже, плюс те же оверрайды, что в реальном |
| 104 | `.toml` игры — так гарантируется, что bash- и chl-стороны стартуют с |
| 105 | ОДИНАКОВЫХ настроек, а не с разных наборов дефолтов), либо шаблоном |
| 106 | `.default/<launcher>` из самой установки StartWine, когда на машине нет |
| 107 | вообще ни одного реального примера категории (OpenGL). Подробности — в |
| 108 | финальном отчёте сессии (STATUS.md/Plane), не здесь. |
| 109 |