|
|
|
@@ -8,7 +8,7 @@ ArcaneChat is a Delta Chat Android client built on top of the official Delta Cha
|
|
|
|
|
- **Language:** Java (Java 8 compatibility)
|
|
|
|
|
- **Build System:** Gradle with Android Gradle Plugin 8.11.1
|
|
|
|
|
- **Min SDK:** 21 (Android 5.0)
|
|
|
|
|
- **Target SDK:** 35 (Android 15)
|
|
|
|
|
- **Target SDK:** 36 (Android 16)
|
|
|
|
|
- **NDK Version:** 27.0.12077973
|
|
|
|
|
- **Native Components:** Rust (deltachat-core-rust submodule)
|
|
|
|
|
- **UI Framework:** Android SDK, Material Design Components
|
|
|
|
@@ -17,13 +17,23 @@ ArcaneChat is a Delta Chat Android client built on top of the official Delta Cha
|
|
|
|
|
## Repository Structure
|
|
|
|
|
|
|
|
|
|
- `src/main/` - Main application source code
|
|
|
|
|
- `src/main/java/org/thoughtcrime/securesms/` - Main UI components
|
|
|
|
|
- `src/main/java/com/b44t/messenger/` - Delta Chat core integration
|
|
|
|
|
- `src/main/java/chat/delta/rpc/` - JSON-RPC bindings (generated, don't edit manually)
|
|
|
|
|
- `src/main/res/` - Android resources (layouts, strings, drawables)
|
|
|
|
|
- `src/androidTest/` - Instrumented tests (UI tests, benchmarks)
|
|
|
|
|
- `src/androidTest/java/com/b44t/messenger/uitests/` - UI tests
|
|
|
|
|
- `src/androidTest/java/com/b44t/messenger/uibenchmarks/` - Performance benchmarks
|
|
|
|
|
- `src/gplay/` - Google Play flavor-specific code
|
|
|
|
|
- `src/foss/` - F-Droid/FOSS flavor-specific code
|
|
|
|
|
- `jni/deltachat-core-rust/` - Native Rust core library (submodule)
|
|
|
|
|
- `jni/deltachat-core-rust/` - Native Rust core library (submodule, **don't edit directly**)
|
|
|
|
|
- `scripts/` - Build and helper scripts
|
|
|
|
|
- `scripts/ndk-make.sh` - Build native libraries
|
|
|
|
|
- `scripts/install-toolchains.sh` - Install Rust cross-compilation toolchains
|
|
|
|
|
- `scripts/generate-rpc-bindings.sh` - Generate JSON-RPC bindings
|
|
|
|
|
- `docs/` - Documentation
|
|
|
|
|
- `fastlane/` - App store metadata and screenshots
|
|
|
|
|
- `.github/workflows/` - CI/CD workflows (GitHub Actions)
|
|
|
|
|
|
|
|
|
|
## Build Instructions
|
|
|
|
|
|
|
|
|
@@ -33,17 +43,36 @@ ArcaneChat is a Delta Chat Android client built on top of the official Delta Cha
|
|
|
|
|
```bash
|
|
|
|
|
git submodule update --init --recursive
|
|
|
|
|
```
|
|
|
|
|
This MUST be done first before any build attempts.
|
|
|
|
|
|
|
|
|
|
2. **Build native libraries:**
|
|
|
|
|
2. **Set up environment variables:**
|
|
|
|
|
```bash
|
|
|
|
|
export ANDROID_NDK_ROOT=/path/to/ndk/27.0.12077973
|
|
|
|
|
export PATH=${PATH}:${ANDROID_NDK_ROOT}/toolchains/llvm/prebuilt/linux-x86_64/bin/:${ANDROID_NDK_ROOT}
|
|
|
|
|
```
|
|
|
|
|
Note: Path format varies by OS (linux-x86_64, darwin-x86_64, etc.)
|
|
|
|
|
|
|
|
|
|
3. **Install Rust toolchains:**
|
|
|
|
|
```bash
|
|
|
|
|
scripts/install-toolchains.sh
|
|
|
|
|
```
|
|
|
|
|
Required for building the native Rust components.
|
|
|
|
|
|
|
|
|
|
4. **Build native libraries:**
|
|
|
|
|
```bash
|
|
|
|
|
scripts/ndk-make.sh
|
|
|
|
|
```
|
|
|
|
|
Note: First run may take significant time as it builds for all architectures (armeabi-v7a, arm64-v8a, x86, x86_64)
|
|
|
|
|
**IMPORTANT:** First run takes 30-60 minutes as it builds for all architectures (armeabi-v7a, arm64-v8a, x86, x86_64).
|
|
|
|
|
For faster development builds, build for a single architecture:
|
|
|
|
|
```bash
|
|
|
|
|
scripts/ndk-make.sh armeabi-v7a
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
3. **Build APK:**
|
|
|
|
|
5. **Build APK:**
|
|
|
|
|
```bash
|
|
|
|
|
./gradlew assembleDebug
|
|
|
|
|
```
|
|
|
|
|
Build time: ~2-5 minutes after native libraries are built.
|
|
|
|
|
|
|
|
|
|
### Build Flavors
|
|
|
|
|
|
|
|
|
@@ -55,6 +84,24 @@ ArcaneChat is a Delta Chat Android client built on top of the official Delta Cha
|
|
|
|
|
- Debug APKs: `build/outputs/apk/gplay/debug/` and `build/outputs/apk/fat/debug/`
|
|
|
|
|
- Release APKs require signing configuration in `~/.gradle/gradle.properties`
|
|
|
|
|
|
|
|
|
|
### Common Build Issues
|
|
|
|
|
|
|
|
|
|
1. **Missing NDK or incorrect version:**
|
|
|
|
|
- Error: `ANDROID_NDK_ROOT not set` or native library missing
|
|
|
|
|
- Solution: Install NDK 27.0.12077973 and set ANDROID_NDK_ROOT environment variable
|
|
|
|
|
|
|
|
|
|
2. **Submodules not initialized:**
|
|
|
|
|
- Error: Missing deltachat-core-rust files
|
|
|
|
|
- Solution: Run `git submodule update --init --recursive`
|
|
|
|
|
|
|
|
|
|
3. **Gradle wrapper validation:**
|
|
|
|
|
- Always validate gradle wrapper before building: `./gradlew wrapper --gradle-version=current`
|
|
|
|
|
- Wrapper is validated in CI via `gradle/actions/wrapper-validation@v4`
|
|
|
|
|
|
|
|
|
|
4. **Clean build issues:**
|
|
|
|
|
- If build fails, try: `./gradlew clean && scripts/ndk-make.sh && ./gradlew assembleDebug`
|
|
|
|
|
- Remove `build/` directory if clean doesn't work
|
|
|
|
|
|
|
|
|
|
## Testing
|
|
|
|
|
|
|
|
|
|
### Running Unit Tests
|
|
|
|
@@ -62,16 +109,19 @@ ArcaneChat is a Delta Chat Android client built on top of the official Delta Cha
|
|
|
|
|
```bash
|
|
|
|
|
./gradlew test
|
|
|
|
|
```
|
|
|
|
|
Expected duration: 1-3 minutes
|
|
|
|
|
|
|
|
|
|
### Running Instrumented Tests
|
|
|
|
|
|
|
|
|
|
1. **Disable animations** on your device/emulator:
|
|
|
|
|
- Developer Options → Set "Window animation scale", "Transition animation scale", and "Animator duration scale" to 0x
|
|
|
|
|
- **CRITICAL:** Tests will fail if animations are enabled
|
|
|
|
|
|
|
|
|
|
2. **Run tests:**
|
|
|
|
|
```bash
|
|
|
|
|
./gradlew connectedAndroidTest
|
|
|
|
|
```
|
|
|
|
|
Expected duration: 10-30 minutes depending on device/emulator
|
|
|
|
|
|
|
|
|
|
### Online Tests
|
|
|
|
|
|
|
|
|
@@ -129,6 +179,14 @@ TEST_MAIL_PW=yourpassword
|
|
|
|
|
- Java bindings are in `src/main/java/com/b44t/messenger/Dc*.java`
|
|
|
|
|
- JSON-RPC bindings in `chat.delta.rpc.*` package (generated via dcrpcgen)
|
|
|
|
|
|
|
|
|
|
### Generating JSON-RPC Bindings
|
|
|
|
|
|
|
|
|
|
To regenerate JSON-RPC bindings after core changes:
|
|
|
|
|
```bash
|
|
|
|
|
./scripts/generate-rpc-bindings.sh
|
|
|
|
|
```
|
|
|
|
|
**Note:** Requires Rust tooling and [dcrpcgen tool](https://github.com/chatmail/dcrpcgen) installed
|
|
|
|
|
|
|
|
|
|
### Working with Translations
|
|
|
|
|
|
|
|
|
|
- Translations managed via Transifex (not in repository)
|
|
|
|
@@ -142,6 +200,43 @@ Decode crash symbols:
|
|
|
|
|
$ANDROID_NDK_ROOT/ndk-stack --sym obj/local/armeabi-v7a --dump crash.txt > decoded.txt
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Validation and Quality Checks
|
|
|
|
|
|
|
|
|
|
### Pre-commit Checks
|
|
|
|
|
|
|
|
|
|
Before committing changes, always run:
|
|
|
|
|
|
|
|
|
|
1. **Gradle wrapper validation:**
|
|
|
|
|
```bash
|
|
|
|
|
./gradlew wrapper --gradle-version=current
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
2. **Build verification:**
|
|
|
|
|
```bash
|
|
|
|
|
./gradlew assembleDebug
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
3. **Unit tests:**
|
|
|
|
|
```bash
|
|
|
|
|
./gradlew test
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
4. **Code style:** Match existing code style in modified files (no automatic formatter configured)
|
|
|
|
|
|
|
|
|
|
### When to Rebuild Native Libraries
|
|
|
|
|
|
|
|
|
|
Rebuild native libraries (`scripts/ndk-make.sh`) when:
|
|
|
|
|
- Updating deltachat-core-rust submodule
|
|
|
|
|
- Modifying anything in `jni/` directory
|
|
|
|
|
- Changing NDK version
|
|
|
|
|
- After `git clean -fdx` or fresh clone
|
|
|
|
|
|
|
|
|
|
**DO NOT** rebuild native libraries for:
|
|
|
|
|
- Pure Java/Kotlin code changes
|
|
|
|
|
- Resource file changes
|
|
|
|
|
- Gradle configuration changes (unless changing native library linking)
|
|
|
|
|
- Documentation updates
|
|
|
|
|
|
|
|
|
|
## WebXDC Support
|
|
|
|
|
|
|
|
|
|
ArcaneChat has extended WebXDC support:
|
|
|
|
@@ -152,12 +247,24 @@ ArcaneChat has extended WebXDC support:
|
|
|
|
|
|
|
|
|
|
## Important Files
|
|
|
|
|
|
|
|
|
|
- `build.gradle` - Main build configuration
|
|
|
|
|
- `build.gradle` - Main build configuration (Android Gradle Plugin 8.11.1, Java 8 compatibility)
|
|
|
|
|
- `CONTRIBUTING.md` - Contribution guidelines
|
|
|
|
|
- `BUILDING.md` - Detailed build setup
|
|
|
|
|
- `BUILDING.md` - Detailed build setup instructions
|
|
|
|
|
- `RELEASE.md` - Release process
|
|
|
|
|
- `proguard-rules.pro` - ProGuard configuration
|
|
|
|
|
- `google-services.json` - Firebase configuration (gplay flavor)
|
|
|
|
|
- `proguard-rules.pro` - ProGuard configuration (enabled for both debug and release)
|
|
|
|
|
- `google-services.json` - Firebase configuration (gplay flavor only)
|
|
|
|
|
- `settings.gradle` - Gradle settings
|
|
|
|
|
- `.github/workflows/` - CI/CD configuration
|
|
|
|
|
|
|
|
|
|
## Dependencies and Constraints
|
|
|
|
|
|
|
|
|
|
- **Java Version:** Java 8 compatibility (do not use Java 9+ features)
|
|
|
|
|
- **Gradle:** Use wrapper (`./gradlew`) to ensure correct Gradle version
|
|
|
|
|
- **NDK:** Must use version 27.0.12077973 (specified in build.gradle)
|
|
|
|
|
- **Min SDK:** 21 (Android 5.0) - code must be compatible
|
|
|
|
|
- **Target SDK:** 36 (Android 16) - test on this API level when possible
|
|
|
|
|
- **ProGuard:** Always enabled - ensure ProGuard rules are correct for new dependencies
|
|
|
|
|
- **Multi-dex:** Enabled - app exceeds 65k method limit
|
|
|
|
|
|
|
|
|
|
## Package Structure
|
|
|
|
|
|
|
|
|
@@ -173,3 +280,35 @@ ArcaneChat has extended WebXDC support:
|
|
|
|
|
- Native library must be rebuilt after core changes
|
|
|
|
|
- ProGuard is enabled in both debug and release builds
|
|
|
|
|
- Multi-dex is enabled due to app size
|
|
|
|
|
|
|
|
|
|
## CI/CD Workflows
|
|
|
|
|
|
|
|
|
|
### Preview APK Workflow (.github/workflows/preview-apk.yml)
|
|
|
|
|
|
|
|
|
|
Runs on every pull request to build and upload a preview APK:
|
|
|
|
|
|
|
|
|
|
1. **Setup steps:**
|
|
|
|
|
- Checks out repository with submodules
|
|
|
|
|
- Validates Fastlane metadata
|
|
|
|
|
- Sets up Rust cache (working-directory: jni/deltachat-core-rust)
|
|
|
|
|
- Sets up Java 17 (Temurin distribution)
|
|
|
|
|
- Sets up Android SDK
|
|
|
|
|
- Caches Gradle dependencies
|
|
|
|
|
- Sets up NDK r27
|
|
|
|
|
|
|
|
|
|
2. **Build process:**
|
|
|
|
|
```bash
|
|
|
|
|
scripts/install-toolchains.sh && scripts/ndk-make.sh armeabi-v7a
|
|
|
|
|
./gradlew --no-daemon -PABI_FILTER=armeabi-v7a assembleFossDebug
|
|
|
|
|
```
|
|
|
|
|
Note: Builds only armeabi-v7a for faster CI builds
|
|
|
|
|
|
|
|
|
|
3. **Output:** Uploads APK artifact to GitHub Actions
|
|
|
|
|
|
|
|
|
|
### Important CI Considerations
|
|
|
|
|
|
|
|
|
|
- Always validate Gradle wrapper before committing changes
|
|
|
|
|
- Fastlane metadata must be valid (validated in CI)
|
|
|
|
|
- Use `--no-daemon` flag for Gradle in CI environments
|
|
|
|
|
- CI builds use FOSS flavor to avoid Google Services dependencies
|
|
|
|
|
- Expected CI build time: 15-25 minutes for full workflow
|
|
|
|
|