mathstuff/MathHomeworkHelper/INSTALLATION.md

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
• 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

# 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

# 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

# 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

# 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

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:

defaultConfig {
    minSdk 21  // Change this value
}

Change Target SDK Version

Edit app/build.gradle:

android {
    targetSdk 34  // Change this value
}

Enable ProGuard/R8 for Release

Edit app/build.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

# Clear Gradle cache
./gradlew clean

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

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

Emulator Issues

# 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

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

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:

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

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