248
docs/SETUP.md
Archivo normal
248
docs/SETUP.md
Archivo normal
@@ -0,0 +1,248 @@
|
||||
# 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/)
|
||||
Referencia en una nueva incidencia
Block a user