Juan José Gutiérrez de Quevedo Pérez
f9558008e1
Some checks reported errors
continuous-integration/drone Build encountered an error
389 lines
No EOL
8.5 KiB
Markdown
389 lines
No EOL
8.5 KiB
Markdown
# 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. |