MyActivityPub/docs/SETUP.md

# Development Setup Guide
This guide will help you set up the My ActivityPub project for development.
## Prerequisites
### Required Software
1. **Android Studio**
   - Version: Hedgehog (2023.1.1) or newer
   - Download: https://developer.android.com/studio
2. **Java Development Kit (JDK)**
   - Version: JDK 11 or higher
   - Android Studio includes a JDK, or download from: https://adoptium.net/
3. **Git**
   - Version: Latest stable
   - Download: https://git-scm.com/downloads
4. **Android SDK**
   - API Level 24 (Android 7.0) minimum
   - API Level 35 (Android 14) target
   - Installed via Android Studio SDK Manager
### Recommended Tools
- **Android Device** or **Emulator** for testing
- **ADB (Android Debug Bridge)** - included with Android Studio
- **Gradle** - wrapper included in project
## Project Setup
### 1. Clone the Repository
```bash
git clone https://github.com/your-username/MyActivityPub.git
cd MyActivityPub
```
### 2. Open in Android Studio
1. Launch Android Studio
2. Select **File > Open**
3. Navigate to the cloned repository
4. Click **OK**
### 3. Gradle Sync
Android Studio will automatically trigger a Gradle sync. If not:
1. Click **File > Sync Project with Gradle Files**
2. Wait for sync to complete
3. Resolve any errors if they appear
### 4. Install Dependencies
The Gradle build system will automatically download all dependencies:
- Kotlin standard library
- Jetpack Compose libraries
- Retrofit for networking
- Coil for image loading
- Material 3 components
### 5. Configure Build Variants
1. Click **Build > Select Build Variant**
2. Choose `debug` for development
3. Use `release` for production builds
## Building the Project
### Debug Build
```bash
# From command line
./gradlew assembleDebug
# Output location
app/build/outputs/apk/debug/app-debug.apk
```
### Release Build
```bash
# Create signed release APK
./gradlew assembleRelease
# Output location
app/build/outputs/apk/release/app-release.apk
```
## Running the App
### On Physical Device
1. Enable **Developer Options** on your Android device:
   - Go to **Settings > About Phone**
   - Tap **Build Number** 7 times
2. Enable **USB Debugging**:
   - Go to **Settings > Developer Options**
   - Enable **USB Debugging**
3. Connect device via USB
4. In Android Studio:
   - Click **Run > Run 'app'**
   - Or press **Shift + F10**
   - Select your device
### On Emulator
1. Create an AVD (Android Virtual Device):
   - Click **Tools > Device Manager**
   - Click **Create Device**
   - Select a device definition (e.g., Pixel 6)
   - Select system image (API 24+)
   - Click **Finish**
2. Run the app:
   - Click **Run > Run 'app'**
   - Select the emulator
## Configuration
### Gradle Properties
Edit `gradle.properties` to configure build settings:
```properties
# Increase memory for large projects
org.gradle.jvmargs=-Xmx4096m -Dfile.encoding=UTF-8
# Enable parallel builds
org.gradle.parallel=true
# Enable configuration cache (Gradle 8.0+)
org.gradle.configuration-cache=true
```
### API Configuration
To connect to a different Mastodon instance, edit `MainActivity.kt`:
```kotlin
val retrofit = Retrofit.Builder()
    .baseUrl("https://your-instance.social/")  // Change this
    .client(client)
    .addConverterFactory(GsonConverterFactory.create())
    .build()
```
## Troubleshooting
### Common Issues
#### 1. Gradle Sync Failed
**Problem**: "Could not download dependencies"
**Solutions**:
```bash
# Clear Gradle cache
rm -rf ~/.gradle/caches/
./gradlew clean --no-daemon
# Or in Android Studio:
# File > Invalidate Caches > Invalidate and Restart
```
#### 2. Build Failed with Memory Error
**Problem**: "Java heap space" or "OutOfMemoryError"
**Solution**: Increase memory in `gradle.properties`:
```properties
org.gradle.jvmargs=-Xmx4096m
```
#### 3. SDK Not Found
**Problem**: "Failed to find target with hash string 'android-35'"
**Solution**:
1. Open SDK Manager: **Tools > SDK Manager**
2. Install Android 14.0 (API 35)
3. Sync Gradle files
#### 4. Emulator Won't Start
**Problem**: Emulator crashes or doesn't start
**Solutions**:
- Enable virtualization in BIOS/UEFI
- Install HAXM (Intel) or WHPX (Windows)
- Reduce emulator RAM allocation
- Use ARM system image instead of x86
#### 5. App Crashes on Launch
**Problem**: App crashes immediately after launch
**Solutions**:
- Check Logcat for error messages
- Verify internet permission in manifest
- Clear app data: `adb shell pm clear com.manalejandro.myactivitypub`
### Debugging
#### View Logs
```bash
# View all logs
adb logcat
# Filter by app
adb logcat | grep MyActivityPub
# Filter by tag
adb logcat -s TimelineViewModel
# Clear logs
adb logcat -c
```
#### Debug in Android Studio
1. Set breakpoints in code
2. Click **Run > Debug 'app'**
3. Interact with app
4. Use debug panel to inspect variables
## IDE Configuration
### Android Studio Settings
Recommended settings for development:
1. **Code Style**:
   - **Settings > Editor > Code Style > Kotlin**
   - Set from: **Kotlin style guide**
2. **Auto Import**:
   - **Settings > Editor > General > Auto Import**
   - Enable **Add unambiguous imports on the fly**
   - Enable **Optimize imports on the fly**
3. **Live Templates**:
   - **Settings > Editor > Live Templates**
   - Useful templates: `comp`, `vm`, `repo`
4. **Version Control**:
   - **Settings > Version Control > Git**
   - Configure your Git author info
### Useful Plugins
- **Rainbow Brackets**: Colorize bracket pairs
- **GitToolBox**: Enhanced Git integration  
- **Key Promoter X**: Learn keyboard shortcuts
- **ADB Idea**: Quick ADB commands
- **.ignore**: Manage .gitignore files
## Testing Setup
### Unit Tests
```bash
# Run all unit tests
./gradlew test
# Run tests for specific variant
./gradlew testDebugUnitTest
```
### Instrumented Tests
```bash
# Run on connected device/emulator
./gradlew connectedAndroidTest
```
### Test Coverage
```bash
# Generate coverage report
./gradlew jacocoTestReport
# View report at:
# app/build/reports/jacoco/test/html/index.html
```
## Code Quality
### Lint Checks
```bash
# Run lint
./gradlew lint
# View report at:
# app/build/reports/lint-results.html
```
### Static Analysis
```bash
# Run detekt (if configured)
./gradlew detekt
```
## Environment Variables
For sensitive data, use local environment variables:
```bash
# In ~/.bashrc or ~/.zshrc
export MASTODON_BASE_URL="https://mastodon.social/"
export API_KEY="your-api-key"
```
Access in Gradle:
```kotlin
android {
    defaultConfig {
        buildConfigField("String", "BASE_URL", "\"${System.getenv("MASTODON_BASE_URL")}\"")
    }
}
```
## Next Steps
After setup:
1. Read [ARCHITECTURE.md](ARCHITECTURE.md) to understand the codebase
2. Check [CONTRIBUTING.md](../CONTRIBUTING.md) for contribution guidelines
3. Review [API.md](API.md) for API documentation
4. Start coding! 🚀
## Getting Help
If you encounter issues:
1. Check this guide thoroughly
2. Search existing [Issues](https://github.com/your-repo/issues)
3. Check [Stack Overflow](https://stackoverflow.com/questions/tagged/android)
4. Ask in [Discussions](https://github.com/your-repo/discussions)
5. Create a new issue with details
## Additional Resources
- [Android Developer Guides](https://developer.android.com/guide)
- [Kotlin Documentation](https://kotlinlang.org/docs/home.html)
- [Jetpack Compose Pathway](https://developer.android.com/courses/pathways/compose)
- [Mastodon API Docs](https://docs.joinmastodon.org/api/)