umbrix/BUILD_INSTRUCTIONS.md

# Инструкция по сборке Hiddify v2.5.7

## Успешная сборка выполнена 25 декабря 2025 г.

### Системные требования

- **ОС**: Linux (Ubuntu 24.04)
- **Java**: OpenJDK 17
- **Go**: 1.25.5 (для libcore, если собирать самостоятельно)
- **Android SDK**: Platform 34, Build Tools, NDK 26.1.10909125
- **Disk Space**: ~15GB свободного места

### Версии компонентов

#### Flutter
```bash
# Установка FVM (Flutter Version Manager)
flutter pub global activate fvm

# Установка Flutter 3.24.0 (НЕ 3.24.3!)
fvm install 3.24.0
fvm use 3.24.0 --force
```

**ВАЖНО**: В pubspec.yaml указано `flutter: ">=3.24.0 <=3.24.3"`, но в официальной сборке используется **3.24.0** (не 3.24.3). При использовании 3.24.3 возникает конфликт зависимостей intl.

#### Gradle & Android
- **Gradle**: 8.7 (обновлен с 7.6.1)
- **AGP** (Android Gradle Plugin): 8.2.0 (обновлен с 7.4.2)
- **Kotlin**: 1.9.22 (обновлен с 1.8.21)
- **compileSdk**: 34 (НЕ 35 - несовместим с libcore)
- **targetSdk**: 34
- **minSdk**: 21

#### Java
```bash
# Проверка версии
java -version
# Должно быть: openjdk 17.x.x

# Настройка Flutter для использования Java 17
flutter config --jdk-dir="/usr/lib/jvm/java-1.17.0-openjdk-amd64"
```

### Пошаговая инструкция сборки

#### 1. Клонирование репозитория

```bash
cd /home/vodorod/dorod
git clone --depth 1 --branch v2.5.7 --recurse-submodules https://github.com/hiddify/hiddify-app.git Umbrix-hid
cd Umbrix-hid
```

#### 2. Исправление зависимостей

**Проблема**: `flutter_easy_permission` устарел и не собирается с современными версиями Android.

**Решение**: Закомментировать в `pubspec.yaml`:

```yaml
# Строки 90-92, было:
#flutter_easy_permission: ^1.1.2
flutter_easy_permission: 
   git: https://github.com/unger1984/flutter_easy_permission.git

# Изменить на:
#flutter_easy_permission: ^1.1.2
#flutter_easy_permission: 
#   git: https://github.com/unger1984/flutter_easy_permission.git
```

**Изменения в коде** (`lib/features/common/qr_code_scanner_screen.dart`):

```dart
// Закомментировать импорт:
// import 'package:flutter_easy_permission/easy_permissions.dart';

// Закомментировать константы:
// const permissions = [Permissions.CAMERA];
// const permissionGroup = [PermissionGroup.Camera];

// В методе _requestCameraPermission() упростить:
Future<bool> _requestCameraPermission() async {
  // Simplified: assuming permission is granted
  return true;
}

// В dispose() закомментировать:
// FlutterEasyPermission().dispose();

// Во всех методах, где проверяется hasPermission, заменить на:
final hasPermission = true;
```

#### 3. Обновление Gradle и AGP

**android/settings.gradle**:
```gradle
plugins {
    id "dev.flutter.flutter-plugin-loader" version "1.0.0"
    id "com.android.application" version "8.2.0" apply false  // было 7.4.2
    id "org.jetbrains.kotlin.android" version "1.9.22" apply false  // было 1.8.21
}
```

**android/gradle/wrapper/gradle-wrapper.properties**:
```properties
distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-bin.zip
# Было: gradle-7.6.1-bin.zip
```

#### 4. Скачивание libcore

```bash
mkdir -p android/app/libs
curl -L https://github.com/hiddify/hiddify-next-core/releases/download/v3.1.8/hiddify-core-android.tar.gz | tar xz -C android/app/libs/
```

Должен появиться файл `android/app/libs/libcore.aar` (~119MB).

#### 5. Генерация кода

```bash
$HOME/.pub-cache/bin/fvm flutter pub get
$HOME/.pub-cache/bin/fvm flutter pub run build_runner build --delete-conflicting-outputs
```

Эта команда генерирует:
- Riverpod providers
- Freezed модели
- Drift database код
- Localization файлы
- Asset файлы

#### 6. Сборка APK

```bash
# Debug версия (без shrink для быстрой сборки)
$HOME/.pub-cache/bin/fvm flutter build apk --debug --no-shrink

# Release версия (требует keystore)
# $HOME/.pub-cache/bin/fvm flutter build apk --release
```

**Результат**:
```
✓ Built build/app/outputs/flutter-apk/app-debug.apk (193 MB)
✓ Built build/app/outputs/flutter-apk/app-arm64-v8a-debug.apk (88 MB)
✓ Built build/app/outputs/flutter-apk/app-armeabi-v7a-debug.apk (83 MB)
✓ Built build/app/outputs/flutter-apk/app-x86_64-debug.apk (86 MB)
```

#### 7. Установка на устройство/эмулятор

```bash
# Запуск эмулятора (если есть)
$HOME/Android/Sdk/emulator/emulator -avd <ИМЯ_AVD>

# Проверка подключенных устройств
$HOME/.pub-cache/bin/fvm flutter devices

# Установка APK
$HOME/Android/Sdk/platform-tools/adb install -r build/app/outputs/flutter-apk/app-x86_64-debug.apk
```

### Типичные ошибки и решения

#### Ошибка 1: intl version conflict
```
Because hiddify depends on flutter_localizations from sdk which depends on intl 0.20.2,
intl 0.20.2 is required.
So, because hiddify depends on intl ^0.19.0, version solving failed.
```

**Причина**: Flutter 3.24.3 требует intl 0.20.2, но проект использует 0.19.0.

**Решение**: Использовать Flutter 3.24.0 (не 3.24.3).

#### Ошибка 2: flutter_easy_permission compilation error
```
error: package pub.devrel.easypermissions does not exist
```

**Причина**: Пакет устарел и не имеет зависимости EasyPermissions.

**Решение**: Закомментировать в pubspec.yaml и коде (см. шаг 2).

#### Ошибка 3: Unresolved reference: nekohasekai
```
e: Unresolved reference: nekohasekai
```

**Причина**: Отсутствует libcore.aar.

**Решение**: Скачать libcore v3.1.8 (см. шаг 4).

#### Ошибка 4: Error while dexing
```
ERROR:D8: com.android.tools.r8.kotlin.H
Execution failed for task ':app:mergeExtDexDebug'.
```

**Причина**: Несовместимость AGP 7.4.2 с Gradle 8.7.

**Решение**: Обновить AGP до 8.2.0 и Kotlin до 1.9.22 (см. шаг 3).

#### Ошибка 5: Namespace not specified
```
Namespace not specified. Specify a namespace in the module's build file.
```

**Причина**: flutter_easy_permission не закомментирован полностью в pubspec.yaml.

**Решение**: Проверить что ВСЕ строки (включая git секцию) закомментированы.

#### Ошибка 6: Android resource linking failed
```
aapt2 E: Failed to load resources table in APK '.../android-35/android.jar'
```

**Причина**: compileSdk 35 несовместим с AGP 7.x или поврежден SDK.

**Решение**: Использовать compileSdk 34.

### Структура изменений

#### Измененные файлы:

1. **pubspec.yaml**
   - Закомментирован flutter_easy_permission

2. **lib/features/common/qr_code_scanner_screen.dart**
   - Упрощена проверка permissions
   - Удалены вызовы FlutterEasyPermission

3. **android/settings.gradle**
   - AGP: 7.4.2 → 8.2.0
   - Kotlin: 1.8.21 → 1.9.22

4. **android/gradle/wrapper/gradle-wrapper.properties**
   - Gradle: 7.6.1 → 8.7

5. **android/app/build.gradle**
   - Без изменений (compileSdk 34, targetSdk 34 остались)

#### Добавленные файлы:

- **android/app/libs/libcore.aar** (119 MB) - Core библиотека sing-box

### Очистка после ошибок

Если сборка не удалась:

```bash
# Полная очистка
rm -rf ~/.gradle/caches/
rm -rf ~/.pub-cache/git/flutter_easy_permission-*
rm -rf .flutter-plugins*
rm -f pubspec.lock

# Пересборка
$HOME/.pub-cache/bin/fvm flutter clean
$HOME/.pub-cache/bin/fvm flutter pub get
$HOME/.pub-cache/bin/fvm flutter pub run build_runner build --delete-conflicting-outputs
./android/gradlew -p android clean
```

### Проверка окружения

```bash
# Flutter
$HOME/.pub-cache/bin/fvm flutter doctor -v

# Java
java -version

# Gradle
./android/gradlew -p android --version

# Android SDK
ls -la $HOME/Android/Sdk/platforms/
```

### Время сборки

- **Первая сборка**: ~3-5 минут (с загрузкой зависимостей)
- **Повторная сборка**: ~1.5-2 минуты
- **Сборка после clean**: ~2-3 минуты

### Размер артефактов

- **app-debug.apk** (universal): 193 MB
- **app-arm64-v8a-debug.apk**: 88 MB (рекомендуется для современных устройств)
- **app-armeabi-v7a-debug.apk**: 83 MB (для старых устройств)
- **app-x86_64-debug.apk**: 86 MB (для эмуляторов)

### Примечания

1. **Не используйте системный Flutter** - только через FVM с версией 3.24.0
2. **Java 17 обязателен** - Java 21 не совместим с Gradle 7.x/8.x конфигурацией проекта
3. **libcore нельзя пропустить** - без него будут ошибки Kotlin компиляции
4. **AGP 8.2+ обязателен** для Gradle 8.7
5. **flutter_easy_permission** должен быть полностью закомментирован, включая git секцию

### Дополнительная информация

- **Официальный репозиторий**: https://github.com/hiddify/hiddify-app
- **Релиз v2.5.7**: https://github.com/hiddify/hiddify-app/releases/tag/v2.5.7
- **libcore v3.1.8**: https://github.com/hiddify/hiddify-next-core/releases/tag/v3.1.8
- **CI/CD конфигурация**: `.github/workflows/build.yml` (использует Flutter 3.24.0)

### Контрольные суммы

```bash
# Проверка libcore.aar
ls -lh android/app/libs/libcore.aar
# Должно быть: ~119M

# Проверка APK
ls -lh build/app/outputs/flutter-apk/
```

---

**Дата создания документа**: 25 декабря 2025 г.
**Версия Hiddify**: 2.5.7
**Статус сборки**: ✅ Успешно