Настройка Linux-среды

Готовая workspace-среда для Codex

В ~/projects/android подготовлены изолированные:

• .jdk/jdk-21.0.11+10;
• .android-sdk с Platform/Build Tools 36, platform-tools, emulator и API 36 x86_64 system image;
• .gradle-user-home с Gradle 9.5/AGP/Compose cache после проверки starter;
• AVD codex-api36.

Перед CLI-командами:

cd ~/projects/android
source scripts/android-env.sh
scripts/android-doctor.sh
scripts/create-avd.sh
scripts/start-avd.sh codex-api36 gui

Для автономных тестов Codex использует headless вместо gui. Доступ к /dev/kvm может быть скрыт sandbox: запуск эмулятора требует разрешённой эскалации, но не системной установки и не физического устройства.

Новый native проект можно начать с проверенного Compose starter. Проектный Gradle Wrapper остаётся обязательным; общий Gradle не вызывается.

Требования к компьютеру

Официальный минимум для Android Studio с эмулятором — 16 ГБ RAM и 16 ГБ свободного места; рекомендуются 32 ГБ RAM и не менее 32 ГБ свободного SSD. Практически для SDK, нескольких API, Gradle-кэша и AVD зарезервируйте 50 ГБ. Требования Android Studio.

Для текущего компьютера сначала:

1. Освободите 30–50 ГБ на разделе рабочей папки.
2. Проверьте, что Android Studio действительно запускается из Snap.
3. Используйте workspace AVD через разрешённый KVM-доступ или физическое устройство.
4. Не удаляйте системные или пользовательские данные без отдельной проверки.

Установка Android Studio и SDK

1. Установите или обновите Android Studio до стабильного канала.
2. Запустите Setup Wizard.
3. Откройте Tools → SDK Manager.
4. В SDK Platforms установите:
   • Android 16, API 36;
   • один старый API для совместимости, например API 29 или 30.
5. В SDK Tools установите:
   • Android SDK Build-Tools;
   • Android SDK Platform-Tools;
   • Android SDK Command-line Tools;
   • Android Emulator.
6. Примите лицензии через UI или sdkmanager --licenses.

Capacitor 8 требует Node.js 22+, Android Studio 2025.2.1+ и Android SDK. Отдельный JDK не требуется: используйте встроенный JDK Android Studio. Capacitor environment.

Переменные окружения

Добавьте в профиль shell фактический путь SDK, найденный в Android Studio:

export ANDROID_HOME="/absolute/path/to/Android/Sdk"
export PATH="$PATH:$ANDROID_HOME/platform-tools"
export PATH="$PATH:$ANDROID_HOME/emulator"
export PATH="$PATH:$ANDROID_HOME/cmdline-tools/latest/bin"

Не копируйте пример вслепую: сначала подтвердите путь в SDK Manager → Android SDK Location. После изменения перезапустите терминал.

Проверка:

node --version
git --version
adb version
sdkmanager --version
emulator -version

Эмулятор и KVM

На Linux Android Emulator использует KVM. На текущем компьютере AMD-V и KVM проверены при разрешённом локальном запуске; внутри ограниченной sandbox доступ к /dev/kvm может отсутствовать, поэтому это проверяется в фактической среде запуска, а не выводится только из sandbox-ошибки.

Диагностика после установки SDK:

emulator -accel-check
test -r /dev/kvm && test -w /dev/kvm

Если KVM отсутствует, проверьте BIOS/UEFI, модули KVM и членство пользователя в группе kvm. Установка системных пакетов и изменение групп требует административных прав и выполняется отдельно под вашу Linux-дистрибуцию. Hardware acceleration.

Физическое устройство

1. Включите Developer options.
2. Включите USB debugging.
3. Подключите телефон и подтвердите RSA fingerprint.
4. Выполните:

adb devices -l

Для Play Console Personal нужен реальный Android-девайс и мобильное приложение Play Console для device verification. Эмулятор эту проверку не заменяет.

Bundletool

Для повторяемого анализа AAB используется закреплённый официальный bundletool:

scripts/install-bundletool.sh
scripts/bundletool.sh version

Скрипт устанавливает 1.18.3 в исключённый .android-sdk/ и проверяет SHA-256. Системный bundletool не требуется.

Node и package manager

Node.js 22 уже соответствует Capacitor 8. Для первого проекта можно сохранить установленный npm. Не смешивайте npm и pnpm в одном репозитории; коммитьте ровно один lock-файл и используйте npm ci в CI.

Fastlane

Fastlane нужен после первой ручной загрузки в Play Console. Устанавливайте его через проектный Ruby/Bundler или используйте закреплённый CI-образ. Не ставьте Ruby gems в системное окружение с sudo.

Минимальные файлы:

# Gemfile
source "https://rubygems.org"
gem "fastlane"

Запуск:

bundle install
bundle exec fastlane --version

Что не нужно ставить глобально

• Gradle — используйте android/gradlew.
• JDK — используйте JDK Android Studio, если проект не требует другого.
• Capacitor CLI — закрепляйте в devDependencies и запускайте через npx.
• Signing keys — это файлы секретов, а не software packages.