docs(BUILDING): add Android emulator guide without Android Studio

- Add "Android Emulator Without Android Studio" section under Android Build
- Document env setup, SDK components, and API 36 system images
- Include Mac Silicon (arm64-v8a) and Intel (x86_64) AVD instructions
- Add steps: start emulator, build, install APK, and launch app
- Document one-shot build-and-run (debug:run, test:run)
- Update Prerequisites to mention command-line-only option and link to section
- Link to doc/android-emulator-deployment-guide.md for troubleshooting
This commit is contained in:
Jose Olarte III
2026-02-06 17:16:01 +08:00
parent fe9cdd6398
commit 0a88f23bc7

View File

@@ -196,7 +196,7 @@ cp .env.example .env.development
- Node.js 18+ and npm
- Git
- For mobile builds: Xcode (macOS) or Android Studio
- For mobile builds: Xcode (macOS) or Android Studio (or Android SDK Command Line Tools for Android emulator only; see [Android Emulator Without Android Studio](#android-emulator-without-android-studio-command-line-only))
- For desktop builds: Additional build tools based on your OS
## Forks
@@ -1181,7 +1181,127 @@ npm run build:ios:prod
### Android Build
Prerequisites: Android Studio with Java SDK installed
Prerequisites: Android Studio with Java SDK installed (or **Android SDK Command Line Tools** only — see [Android Emulator Without Android Studio](#android-emulator-without-android-studio-command-line-only) below).
#### Android Emulator Without Android Studio (Command-Line Only)
You can build and run the app on an Android emulator using only the **Android SDK Command Line Tools** (no Android Studio). The project uses **API 36** (see `android/variables.gradle`: `compileSdkVersion` / `targetSdkVersion`).
##### 1. Environment
Set your SDK location and PATH (e.g. in `~/.zshrc` or `~/.bashrc`):
```bash
# macOS default SDK location
export ANDROID_HOME=$HOME/Library/Android/sdk
# or: export ANDROID_HOME=$HOME/Android/Sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/platform-tools
export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin
export PATH=$PATH:$ANDROID_HOME/build-tools/34.0.0
```
Reload your shell (e.g. `source ~/.zshrc`), then verify:
```bash
adb version
emulator -version
avdmanager list
```
##### 2. Install SDK components
Install platform tools, build tools, platform, and emulator:
```bash
sdkmanager "platform-tools"
sdkmanager "build-tools;34.0.0"
sdkmanager "platforms;android-36"
sdkmanager "emulator"
```
##### 3. Install system image and create AVD
**Mac Silicon (Apple M1/M2/M3)** — use **ARM64** for native performance:
```bash
# System image (API 36 matches the project)
sdkmanager "system-images;android-36;google_apis;arm64-v8a"
# Create AVD
avdmanager create avd \
--name "TimeSafari_Emulator" \
--package "system-images;android-36;google_apis;arm64-v8a" \
--device "pixel_7"
```
**Intel Mac (x86_64):**
```bash
sdkmanager "system-images;android-36;google_apis;x86_64"
avdmanager create avd \
--name "TimeSafari_Emulator" \
--package "system-images;android-36;google_apis;x86_64" \
--device "pixel_7"
```
List AVDs: `avdmanager list avd`
##### 4. Start the emulator
```bash
# Start in background (Mac Silicon or Intel)
emulator -avd TimeSafari_Emulator -gpu host -no-audio &
# Optional: wait until booted
adb wait-for-device
while [ "$(adb shell getprop sys.boot_completed 2>/dev/null)" != "1" ]; do sleep 2; done
```
If you have limited RAM, use reduced resources:
```bash
emulator -avd TimeSafari_Emulator -no-audio -memory 2048 -cores 2 -gpu swiftshader_indirect &
```
Check device: `adb devices`
##### 5. Build the app
From the project root:
```bash
npm run build:android
# or: npm run build:android:debug
```
The debug APK is produced at:
`android/app/build/outputs/apk/debug/app-debug.apk`
##### 6. Install and launch on the emulator
With the emulator running:
```bash
adb install -r android/app/build/outputs/apk/debug/app-debug.apk
adb shell am start -n app.timesafari.app/app.timesafari.MainActivity
```
##### One-shot build and run
To build and run in one go (emulator or device must already be running):
```bash
npm run build:android:debug:run # debug build, install, launch
# or
npm run build:android:test:run # test env build, install, launch
```
##### Reference
- Full troubleshooting and options: [doc/android-emulator-deployment-guide.md](doc/android-emulator-deployment-guide.md)
#### Android Build Commands