scar-chat/android_client/SETUP_GUIDE.md

# Android Build Setup Guide

## Quick Setup (5 minutes)

### Option 1: Using Android Studio (Recommended)

1. **Install Android Studio**
   - Download from: https://developer.android.com/studio
   - Run installer, follow prompts

2. **Open Project**
   - Launch Android Studio
   - File → Open → Navigate to `android_client/` → OK
   - Wait for Gradle sync (may take 1-2 minutes first time)

3. **Build**
   - Build → Make Project (Ctrl+F9 / Cmd+F9)
   - Wait for completion
   - APK at: `android_client/app/build/outputs/apk/debug/app-debug.apk`

---

### Option 2: Command Line (Linux/macOS/Windows)

**Prerequisites:**
```bash
# 1. Install Java JDK 11+
# Ubuntu/Debian:
sudo apt-get install openjdk-11-jdk

# macOS:
brew install java@11

# Windows: https://adoptopenjdk.net/

# 2. Verify Java
java -version

# 3. Set Android SDK path
export ANDROID_HOME=~/Android/Sdk  # Linux/macOS
# or on Windows (PowerShell):
$env:ANDROID_HOME = "$env:USERPROFILE\AppData\Local\Android\Sdk"
```

**Build:**
```bash
cd android_client

# Option A: Use provided build script
./build.sh              # Linux/macOS

# Option B: Use Gradle directly
./gradlew build         # Linux/macOS
gradlew.bat build       # Windows
```

---

## Troubleshooting

### Problem: "gradle command not found" or "./gradlew not found"
**Solution:** 
```bash
cd android_client
chmod +x gradlew        # Make it executable (Linux/macOS)
./gradlew build         # Run it
```

### Problem: "ANDROID_HOME not set"
**Solution:** 
```bash
# Find your Android SDK installation
find ~ -name "platform-tools" -type d 2>/dev/null

# Set ANDROID_HOME to the parent directory
export ANDROID_HOME=/path/to/Android/Sdk

# Add to ~/.bashrc or ~/.zshrc to persist:
echo 'export ANDROID_HOME=$HOME/Android/Sdk' >> ~/.bashrc
source ~/.bashrc
```

### Problem: "No Java version found"
**Solution:**
```bash
# Install Java 11 or later
# Ubuntu/Debian:
sudo apt-get install openjdk-11-jdk

# macOS:
brew install java@11

# Windows: https://adoptopenjdk.net/

# Verify:
java -version
```

### Problem: "Build fails with Android SDK error"
**Solution:**
```bash
# Update Android SDK from Android Studio:
# Android Studio → Tools → SDK Manager → Install latest SDK
# OR
# From command line:
sdkmanager --update
sdkmanager "build-tools;34.0.0"
sdkmanager "platforms;android-34"
```

### Problem: "Gradle build takes forever on first run"
**Solution:** This is normal! First build downloads dependencies (~500MB).
- Subsequent builds will be much faster
- Keep internet connection stable
- Be patient (5-10 minutes typical)

---

## Full Android Setup (New Machine)

### Linux (Ubuntu/Debian)

```bash
# 1. Install Java
sudo apt-get update
sudo apt-get install openjdk-11-jdk

# 2. Download Android Studio
# Visit: https://developer.android.com/studio
# Or use command (if available):
wget https://redirector.gvt1.com/edgedl/android/studio/ide-zips/2024.1.1/android-studio-2024.1.1-linux.tar.gz

# 3. Extract and run
tar -xzf android-studio-*.tar.gz
cd android-studio/bin
./studio.sh

# 4. In Android Studio:
# - Accept license agreements
# - Install Android SDK (API 34+)
# - Install build tools

# 5. Set environment (add to ~/.bashrc):
export ANDROID_HOME=$HOME/Android/Sdk
export PATH=$PATH:$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools

# 6. Open SCAR Chat project
# File → Open → android_client → OK
```

### macOS

```bash
# 1. Install Java
brew install java@11

# 2. Install Android Studio
brew install android-studio

# 3. Run Android Studio
open /Applications/Android\ Studio.app

# 4. In Android Studio:
# - Accept license agreements
# - Install Android SDK (API 34+)
# - Install build tools

# 5. Set environment (add to ~/.zshrc):
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools

# 6. Open SCAR Chat project
# File → Open → android_client → OK
```

### Windows

1. **Install Java**
   - Download: https://adoptopenjdk.net/
   - Run installer, follow defaults
   - Add to PATH (installer usually does this)

2. **Install Android Studio**
   - Download: https://developer.android.com/studio
   - Run `.exe` installer
   - Follow setup wizard
   - Accept license agreements
   - Install Android SDK & build tools

3. **Set Environment Variables**
   - Right-click Computer → Properties → Environment Variables
   - New system variable:
     - Name: `ANDROID_HOME`
     - Value: `C:\Users\YourUsername\AppData\Local\Android\Sdk`
   - Add to PATH: `%ANDROID_HOME%\tools`; `%ANDROID_HOME%\platform-tools`

4. **Open Project**
   - Launch Android Studio
   - File → Open → Select `android_client` folder
   - Wait for sync

---

## Verify Installation

```bash
# Check Java
java -version
# Should show Java 11 or later

# Check Android SDK
ls $ANDROID_HOME/platforms
# Should show android-34 or similar

# Check Gradle (will work even if not installed)
cd android_client
./gradlew --version
# Should show Gradle 8.1+ info
```

---

## Building for the First Time

First build will:
1. Download Gradle (~100 MB)
2. Download Android SDK components (~500 MB)
3. Download dependencies for project
4. Compile project

**Expect 5-15 minutes** on first build depending on internet speed.

Subsequent builds: **30 seconds - 2 minutes**

---

## Quick Commands Reference

```bash
cd android_client

# Clean build (if you have issues)
./gradlew clean build

# Build debug APK only (faster)
./gradlew assembleDebug

# Build and install on connected device
./gradlew installDebug

# Build release APK
./gradlew assembleRelease

# View all available tasks
./gradlew tasks

# View build logs
./gradlew build --info
```

---

## Environment Setup Scripts

### Linux/macOS Setup Script
Save as `setup-android-build.sh`:

```bash
#!/bin/bash
set -e

echo "Setting up Android build environment..."

# Check Java
if ! command -v java &> /dev/null; then
    echo "Installing Java..."
    if [[ "$OSTYPE" == "linux-gnu"* ]]; then
        sudo apt-get update
        sudo apt-get install -y openjdk-11-jdk
    elif [[ "$OSTYPE" == "darwin"* ]]; then
        brew install java@11
    fi
fi

# Set Android SDK
if [ -z "$ANDROID_HOME" ]; then
    if [ -d "$HOME/Android/Sdk" ]; then
        export ANDROID_HOME="$HOME/Android/Sdk"
    else
        echo "Please install Android Studio from https://developer.android.com/studio"
        exit 1
    fi
fi

# Add to shell config
SHELL_RC=""
if [ -f "$HOME/.bashrc" ]; then
    SHELL_RC="$HOME/.bashrc"
elif [ -f "$HOME/.zshrc" ]; then
    SHELL_RC="$HOME/.zshrc"
fi

if [ -n "$SHELL_RC" ] && ! grep -q "ANDROID_HOME" "$SHELL_RC"; then
    echo "export ANDROID_HOME=$ANDROID_HOME" >> "$SHELL_RC"
    echo "export PATH=\$PATH:\$ANDROID_HOME/tools:\$ANDROID_HOME/platform-tools" >> "$SHELL_RC"
fi

echo "✓ Setup complete!"
echo "✓ ANDROID_HOME: $ANDROID_HOME"
echo "✓ Java: $(java -version 2>&1 | head -1)"
```

Run with: `bash setup-android-build.sh`

---

## Still Having Issues?

1. **Check official docs**: https://developer.android.com/studio/build
2. **Verify Android SDK**: Android Studio → Tools → SDK Manager
3. **Check Java compatibility**: `java -version` (need 11+)
4. **Clear cache**: `rm -rf .gradle` in android_client directory
5. **Fresh build**: `./gradlew clean build`

---

Last Updated: December 4, 2025