From 0a88f23bc776d5b482d1627672e53eb61ac0d802 Mon Sep 17 00:00:00 2001
From: Jose Olarte III <jose.anomalist.design@gmail.com>
Date: Fri, 6 Feb 2026 17:16:01 +0800
Subject: [PATCH] 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
---
 BUILDING.md | 124 +++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 122 insertions(+), 2 deletions(-)

diff --git a/BUILDING.md b/BUILDING.md
index e2de3962..a782d400 100644
--- a/BUILDING.md
+++ b/BUILDING.md
@@ -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