# Installation & Setup Guide

## Complete Setup Instructions for Math Homework Helper Android App

### Prerequisites Checklist

Before you begin, ensure you have:

- [ ] **Android Studio** (latest version) - [Download here](https://developer.android.com/studio)
- [ ] **Java Development Kit (JDK) 11+** - Usually included with Android Studio
- [ ] **Android SDK** - Installed via Android Studio SDK Manager
- [ ] **Minimum 5GB free disk space** - For SDK and emulator
- [ ] **Git** (optional) - For version control

---

## Step 1: Install Android Studio

### Windows/Mac/Linux

1. Download Android Studio from https://developer.android.com/studio
2. Run the installer and follow the setup wizard
3. Choose "Standard" installation (recommended)
4. Accept the default settings
5. Complete the installation

### Verify Installation

```bash
# Check if Android Studio is installed
which android-studio  # macOS/Linux
# or look for Android Studio in Applications/Programs
```

---

## Step 2: Set Up Android SDK

### Using Android Studio

1. Open Android Studio
2. Go to **Tools** → **SDK Manager**
3. Under "SDK Platforms" tab:
   - ✅ Check "Android 14 (API 34)" - **Required**
   - ✅ Check "Android 5.0 (API 21)" - **Minimum**
   - ✅ Check "Android 12 (API 31)" - **Recommended**
4. Under "SDK Tools" tab:
   - ✅ Check "Android SDK Build-Tools 34.x.x"
   - ✅ Check "Android Emulator"
   - ✅ Check "Android SDK Platform-Tools"
5. Click "Apply" and wait for downloads to complete

---

## Step 3: Create Android Virtual Device (Emulator)

### Option A: Using Android Studio GUI

1. Open Android Studio
2. Go to **Tools** → **Device Manager**
3. Click **"Create Device"**
4. Select a device (e.g., "Pixel 4" or "Pixel 5")
5. Click **"Next"**
6. Select API level (API 30 or higher recommended)
7. Click **"Next"**
8. Review settings and click **"Finish"**
9. Click the play button to start the emulator

### Option B: Using Command Line

```bash
# List available devices
emulator -list-avds

# Create a new AVD
avdmanager create avd -n "Pixel4" -k "system-images;android;30;google_apis"

# Start the emulator
emulator -avd Pixel4
```

---

## Step 4: Open the Project

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

1. Launch **Android Studio**
2. Click **"Open an existing Android Studio project"**
3. Navigate to the **MathHomeworkHelper** folder
4. Click **"Open"**
5. Wait for Gradle to sync (first time takes 2-5 minutes)
6. If prompted, click **"Trust Project"**

### Method 2: Using Command Line

```bash
# Navigate to project directory
cd /path/to/MathHomeworkHelper

# Open in Android Studio
open -a "Android Studio" .  # macOS
# or
studio .                     # Linux
# or
start .                      # Windows (if Android Studio is in PATH)
```

---

## Step 5: Configure Project

### Gradle Sync

After opening the project:

1. Android Studio will automatically start Gradle sync
2. Wait for the sync to complete (check bottom status bar)
3. If sync fails:
   - Click **File** → **Sync Now**
   - Or **File** → **Invalidate Caches** → **Invalidate and Restart**

### Verify Configuration

```bash
# From project root directory
./gradlew --version  # Should show Gradle version
./gradlew tasks      # List available tasks
```

---

## Step 6: Build the Project

### Using Android Studio

1. Click **Build** → **Build Bundle(s) / APK(s)** → **Build APK(s)**
2. Wait for build to complete
3. You'll see a notification when build succeeds

### Using Command Line

```bash
cd MathHomeworkHelper

# Build debug APK
./gradlew assembleDebug

# Build release APK
./gradlew assembleRelease

# Clean and rebuild
./gradlew clean build
```

---

## Step 7: Run the App

### On Emulator

1. Start the Android emulator (if not already running)
2. In Android Studio, click the green **Run** button (or press **Shift+F10**)
3. Select your emulator from the device list
4. Click **OK**
5. Wait for app to install and launch

### On Physical Device

1. **Enable Developer Mode:**
   - Go to **Settings** → **About Phone**
   - Tap **Build Number** 7 times
   - Go back to **Settings** → **Developer Options**
   - Enable **USB Debugging**

2. **Connect Device:**
   - Connect Android device via USB cable
   - Allow USB debugging when prompted on device
   - Android Studio will detect the device

3. **Run App:**
   - Click green **Run** button in Android Studio
   - Select your device from the list
   - Click **OK**

---

## Step 8: Verify Installation

### Check App is Running

1. You should see the Math Homework Helper interface
2. Test the following features:
   - ✅ Difficulty slider works
   - ✅ Math problems display
   - ✅ Answer input works
   - ✅ Check Answer button functions
   - ✅ Language selector works
   - ✅ Back button navigates correctly

### Common Issues

| Issue | Solution |
|-------|----------|
| Gradle sync fails | File → Invalidate Caches → Invalidate and Restart |
| Emulator won't start | Check virtualization enabled in BIOS; try different API level |
| App crashes on launch | Check Logcat (View → Tool Windows → Logcat) for errors |
| WebView shows blank | Verify assets in app/src/main/assets/ |
| JavaScript not working | Check MainActivity.java has setJavaScriptEnabled(true) |

---

## Advanced Configuration

### Change Minimum SDK Version

Edit `app/build.gradle`:
```gradle
defaultConfig {
    minSdk 21  // Change this value
}
```

### Change Target SDK Version

Edit `app/build.gradle`:
```gradle
android {
    targetSdk 34  // Change this value
}
```

### Enable ProGuard/R8 for Release

Edit `app/build.gradle`:
```gradle
buildTypes {
    release {
        minifyEnabled true  // Enable code shrinking
        proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
    }
}
```

---

## Building for Distribution

### Create Signed Release APK

1. In Android Studio: **Build** → **Generate Signed Bundle / APK**
2. Select **APK**
3. Click **Next**
4. **Create new keystore** (or select existing):
   - Key store path: Choose location
   - Password: Create strong password
   - Key alias: e.g., "release"
   - Key password: Same as keystore or different
   - Validity: 25+ years recommended
5. Click **Next**
6. Select **release** build type
7. Click **Finish**
8. APK will be generated in `app/build/outputs/apk/release/`

### Upload to Google Play Store

1. Create Google Play Developer account ($25 one-time fee)
2. Create new app in Play Console
3. Fill in app details (description, screenshots, etc.)
4. Upload signed APK
5. Set pricing and distribution
6. Submit for review

---

## Troubleshooting

### Gradle Issues

```bash
# Clear Gradle cache
./gradlew clean

# Rebuild with verbose output
./gradlew build --info

# Update Gradle wrapper
./gradlew wrapper --gradle-version=latest
```

### Emulator Issues

```bash
# List running emulators
emulator -list-avds

# Kill all emulator processes
pkill -f emulator

# Start emulator with more RAM
emulator -avd Pixel4 -memory 2048
```

### Build Issues

```bash
# Check Java version
java -version

# Check Android SDK
$ANDROID_HOME/tools/bin/sdkmanager --list

# Invalidate Android Studio cache
rm -rf ~/.android/
```

---

## Environment Variables (Optional)

### Set ANDROID_HOME

**macOS/Linux:**
```bash
export ANDROID_HOME=$HOME/Library/Android/sdk  # macOS
export ANDROID_HOME=$HOME/Android/Sdk          # Linux
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/platform-tools
```

**Windows:**
```cmd
setx ANDROID_HOME "C:\Users\YourUsername\AppData\Local\Android\Sdk"
setx PATH "%PATH%;%ANDROID_HOME%\tools;%ANDROID_HOME%\platform-tools"
```

---

## Next Steps

1. ✅ Complete installation
2. ✅ Build and run the app
3. ✅ Test all features
4. ✅ Customize app (name, icon, colors)
5. ✅ Build release APK
6. ✅ Publish to Google Play Store (optional)

---

## Support & Resources

- **Android Studio Help**: https://developer.android.com/studio/intro
- **Android Developer Docs**: https://developer.android.com/docs
- **WebView Guide**: https://developer.android.com/guide/webapps/webview
- **Gradle Documentation**: https://gradle.org/
- **Stack Overflow**: Tag with `android` and `android-studio`

---

## Quick Reference Commands

```bash
# Navigate to project
cd MathHomeworkHelper

# Build debug APK
./gradlew assembleDebug

# Build release APK
./gradlew assembleRelease

# Run tests
./gradlew test

# Clean build
./gradlew clean

# Check dependencies
./gradlew dependencies

# Update Gradle
./gradlew wrapper --gradle-version=latest
```

---

**Installation Complete!** 🎉

Your Android project is now ready to build and deploy. Start with the Quick Start Guide (QUICKSTART.md) for next steps.