new docs for project

2026-09-03 09:16:56 +03:00
parent f1a840174b
commit 00e7c957e4
34 changed files with 5323 additions and 0 deletions
@@ -0,0 +1,77 @@
+# javalocator.h — JavaLocator
+
+## Обзор
+
+Для запуска Minecraft нужна Java подходящей версии: старым версиям игры — восьмая, новым —
+семнадцатая или двадцать первая. Лаунчер умеет скачивать сборки Java сам (см.
+[JavaInstaller](JavaInstaller.md)), но сначала стоит посмотреть, что уже есть на машине.
+
+`JavaLocator` отвечает за поиск: собирает все доступные java, определяет их версии и выбирает
+подходящую под требование версии игры. Пространство имён используется при подготовке запуска и при
+показе списка найденных Java в настройках.
+
+## Пространства имён
+
+`JavaLocator` группирует четыре функции поиска и выбора. Состояния нет, но результат определения
+версии кэшируется внутри реализации.
+
+## Функции
+
+#### QStringList findAll(const QString &gameDir)
+
+Все java, которые удалось найти, без дублей и в порядке приоритета. Просматриваются четыре
+источника: рантайм самого Minecraft внутри папки игры, переменная `JAVA_HOME`, переменная `PATH` и
+стандартные каталоги установки JDK и JRE.
+
+Параметр `gameDir` — папка игры; из неё берётся первый источник.
+
+Результат показывается в диалоге настроек списком «что нашлось в системе».
+
+#### int majorVersion(const QString &javaPath)
+
+Мажорная версия java по её пути: 8, 17, 21 и так далее. Возвращает `0`, если запустить
+исполняемый файл не удалось — путь неверен, файл не исполняемый или это не java.
+
+Результат кэшируется: определение версии требует запуска процесса, а один и тот же путь
+проверяется многократно.
+
+#### QString windowlessVariant(const QString &javaPath)
+
+Заменяет `java.exe` на `javaw.exe`, чтобы игра не открывала окно консоли. На Unix возвращает вход
+без изменений — там разницы нет.
+
+#### QString select(const QString &gameDir, int requiredMajor, const QString &preferred, QString \*error)
+
+Выбирает java не ниже `requiredMajor`. Если задан `preferred` — путь, указанный пользователем в
+настройках, — он проверяется первым и, если подходит, побеждает. Иначе перебираются найденные
+`findAll()` варианты.
+
+При неудаче возвращает пустую строку и заполняет `error` — текст объясняет, что именно не нашлось:
+подходящей версии нет вовсе или указанный пользователем путь не подошёл.
+
+Функция запускает процессы для определения версий, поэтому может занять заметное время; вызывать
+её в обработчике нажатия не стоит.
+
+## Зависимости
+
+Подключает `QString` и `QStringList`. От классов проекта не зависит.
+
+## Пример использования
+
+```cpp
+QString error;
+const QString java = JavaLocator::select(gameDir,
+                                         version.javaMajor,
+                                         settings.javaPath,
+                                         &error);
+if (java.isEmpty()) {
+    emit launchError(error);
+    return;
+}
+
+process.start(JavaLocator::windowlessVariant(java), arguments);
+```
+
+---
+
+При создании этого документа использовался ИИ.