jellytau/src-tauri/android/README_ANDROID_BUILD.md

⚠️ IMPORTANT: Android Build File Locations

Critical Information for Future Development

DO NOT EDIT FILES IN src-tauri/gen/android/ DIRECTLY!

File Structure

This project has TWO sets of Android source files:

1. src-tauri/android/ - SOURCE FILES (edit these!)

   • This is the template directory
   • Changes here need to be copied to the generated directory

2. src-tauri/gen/android/ - GENERATED BUILD DIRECTORY (do not edit directly!)

   • This is where Gradle actually builds the APK
   • Files here may be overwritten during builds

How to Make Changes to Android Code

When you need to modify Android/Kotlin files:

1. Edit the files in src-tauri/android/src/main/java/

2. Build using the provided script (which auto-syncs files)

   ./scripts/build-android.sh
   

   The build script automatically runs ./scripts/sync-android-sources.sh which copies:

   • src-tauri/android/src/main/java/com/dtourolle/jellytau/player/ → generated directory
   • src-tauri/android/src/main/java/com/dtourolle/jellytau/security/ → generated directory

3. Manual sync (if needed)

   ./scripts/sync-android-sources.sh
   

Why This Matters

• If you only edit src-tauri/gen/android/, your changes will be lost
• If you only edit src-tauri/android/, your changes won't be in the build
• You must edit both (or edit source and copy to generated)

Debug and release install side by side

The debug build type sets applicationIdSuffix = ".debug" in app/build.gradle.kts, so a debug build is a genuinely separate Android app:

build	applicationId	launcher name	versionName	signed with
release	com.dtourolle.jellytau	jellytau	0.5.5	real key (.env)
release --debug	com.dtourolle.jellytau.debug	JellyTau Debug	0.5.5-debug-release	debug keystore
debug	com.dtourolle.jellytau.debug	JellyTau Debug	0.5.5-debug	debug keystore

release --debug is the side-by-side release: fully R8-minified, exactly what ships, but packaged into the debug slot and signed with the local debug keystore. It exists because R8 has broken release APKs here before (stripping JNI-loaded player/security classes), and reproducing that previously meant building with the real key and clobbering your working install. It shares the applicationId and signature with the plain debug build, so the two replace each other cleanly; only the versionName suffix tells you which is installed.

./scripts/build-and-deploy.sh release --device --debug   # build + install it

The flag is plumbed through as JT_SIDE_BY_SIDE=1, read by build.gradle.kts. CI never sets it, so distributable release builds are untouched.

That means:

• No uninstall step. Debug builds are signed with the local auto-generated ~/.android/debug.keystore, release builds with the real key. Two different keys on the same package is INSTALL_FAILED_UPDATE_INCOMPATIBLE; two different packages is just two apps.
• Each has its own data directory — separate settings, credentials, downloads and offline cache. A debug experiment cannot corrupt the state of the build you actually use. This is not optional and cannot be shared: Android gives each applicationId its own UID and enforces the boundary in the kernel. (sharedUserId is deprecated since API 29 and cannot be added to an already-installed app anyway.) You log in again in the debug app, once.
• Only the application id changes. Kotlin classes stay in the namespace package com.dtourolle.jellytau, so the JNI class lookups in src-tauri/src/player/android/mod.rs, the manifest <service> entry and the R8 keep rules in proguard-jellytau.pro are all unaffected. The FileProvider authority is ${applicationId}.fileprovider, so it follows the suffix automatically.
• The launcher labels come from the appLabel / activityLabel manifestPlaceholders (AndroidManifest.xml uses ${appLabel}), not from resValue, which would collide with Tauri's generated strings.xml.

Follow the right log stream with ./scripts/logcat.sh [debug|release] (defaults to debug).

Getting a test APK out of CI

.gitea/workflows/build-test-apk.yml produces installable APKs that are not releases. Two ways in:

Trigger	Result
push to master	Refreshes the rolling latest pre-release automatically
workflow_dispatch	Builds any branch on demand; optionally publishes it as test-<branch>

The rolling latest build

Every push to master (bar doc-only ones) rebuilds and replaces the APK on the latest pre-release. Both the tag and the asset name are stable, so the download URL never changes:

https://gitea.tourolle.paris/dtourolle/jellytau/releases/download/latest/jellytau-latest.apk

Send that link to a tester once and it keeps serving the current build. No account needed — release assets are public, unlike Actions artifacts.

What you get, and why it is safe

Both variants install into the com.dtourolle.jellytau.debug slot:

Variant	What it is	When
side-by-side-release (default, and what latest always is)	R8-minified, exactly what ships, signed with the debug keystore	Almost always — a plain debug build cannot catch R8 stripping JNI-loaded classes, which has broken release APKs here before
debug	Unminified	When you need readable stack traces

Three properties make an automatic build on every master push safe:

• It cannot replace a real install. The applicationId is suffixed .debug, so it sits beside the store build with its own data. A broken master commit can never take out somebody's working app.
• The production signing key is not involved. That stays in the tag-driven build-release.yml. This workflow needs no secrets beyond the API token.
• The tag is latest/test-*, never v*. Only v* triggers build-release.yml. And the desktop updater reads a static latest.json from the updater branch rather than the release list, so nothing here is offered to existing users.

Known gap: the APK builds in parallel with build-and-test.yml, not after it, so latest can carry a commit whose tests later fail. Cross-workflow dependencies are not reliably available here, and duplicating the test job would double an already hour-long queue on a single-slot runner. Check the commit's CI status before handing the link to somebody.

Runs are serialised and cancel-in-progress is on, so a burst of pushes to master collapses into one build rather than one per commit.

Key Files

Player-related Kotlin files:

• player/JellyTauPlayer.kt - Main player implementation
• player/JellyTauPlaybackService.kt - MediaSession service for lockscreen controls
• security/SecureStorage.kt - Android Keystore integration for secure credential storage

Always check BOTH locations exist and match after making changes!