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

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

# From command line
./gradlew assembleDebug
# Output location
app/build/outputs/apk/debug/app-debug.apk

Release Build

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

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

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:

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

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

# 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

# Run all unit tests
./gradlew test
# Run tests for specific variant
./gradlew testDebugUnitTest

Instrumented Tests

# Run on connected device/emulator
./gradlew connectedAndroidTest

Test Coverage

# Generate coverage report
./gradlew jacocoTestReport
# View report at:
# app/build/reports/jacoco/test/html/index.html

Code Quality

Lint Checks

# Run lint
./gradlew lint
# View report at:
# app/build/reports/lint-results.html

Static Analysis

# Run detekt (if configured)
./gradlew detekt

Environment Variables

For sensitive data, use local environment variables:

# In ~/.bashrc or ~/.zshrc
export MASTODON_BASE_URL="https://mastodon.social/"
export API_KEY="your-api-key"

Access in Gradle:

android {
    defaultConfig {
        buildConfigField("String", "BASE_URL", "\"${System.getenv("MASTODON_BASE_URL")}\"")
    }
}

Next Steps

After setup:

1. Read ARCHITECTURE.md to understand the codebase
2. Check CONTRIBUTING.md for contribution guidelines
3. Review API.md for API documentation
4. Start coding! 🚀

Getting Help

If you encounter issues:

1. Check this guide thoroughly
2. Search existing Issues
3. Check Stack Overflow
4. Ask in Discussions
5. Create a new issue with details

Additional Resources

• Android Developer Guides
• Kotlin Documentation
• Jetpack Compose Pathway
• Mastodon API Docs