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:

# 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:

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:

cd android_client
chmod +x gradlew        # Make it executable (Linux/macOS)
./gradlew build         # Run it

Problem: "ANDROID_HOME not set"

Solution:

# 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:

# 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:

# 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)

# 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

# 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

# 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

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:

#!/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