Skip to content

About

My Chinese hymns Android app. Check it out in Google play store :)

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Repository files navigation

holysongs-android

Automatically exported from code.google.com/p/holysongs

My Chinese hymns Android app. Check it out in Google play store :)

Project background

This repository contains a lightweight, offline-first Android app for browsing and reading Chinese hymn lyrics. The modernization work keeps the bundled song catalog and preference semantics while replacing the legacy Ant/Eclipse build with a maintained Gradle-based workflow. The current release uses a new application ID because the original production signing key was lost. The app module now uses the standard Android layout under app/src/main/ for its manifest, Kotlin sources, resources, and assets.

Current status

The Kotlin/Compose modernization phase is complete and owner-accepted. Main, lyric, Settings, and About use Compose hosts, and the video boundary remains a programmatic Android View/WebView. The current catalog migration keeps human-editable XML as the canonical source and generates the read-only SQLite asset consumed by the app. Legacy preference keys, share behavior, provider identities, and all 414 effective lyrics remain preserved. The new package installs separately from the original Play app and cannot update or automatically inherit its data.

The supported install floor is API 23: API 14–22 devices are no longer eligible to install/update this build. On 2026-09-16 the owner reported completing phone testing across the app and accepted the result as looking great. The final PR candidate also passes a clean CLI debug build, JVM tests, lint, and androidTest APK assembly. API23 runtime execution remains explicitly waived and the tracked evidence retains narrower automated-test and provider-audit limitations; phase acceptance does not claim release signing or Play Store publication.

Historical Feature 001 build evidence remains available in pr-checkpoint.md; it describes the earlier build checkpoint and is not evidence of this Compose migration's runtime acceptance.

Song catalog architecture

app/src/main/assets/songs.xml is the sole human-edited catalog. It contains 414 unique effective titles after the eight old shadowed duplicate entries were removed while retaining each prior last-entry winner. The historical 422-entry fixture remains under app/src/test/resources/ and is used to prove exhaustive effective-content parity.

The build runs tools/catalog/generate_song_database.py and writes the untracked generated asset app/build/generated/songCatalog/assets/songs.db. The app copies the packaged database to a short-lived private cache file, opens it read-only, loads all rows, closes it, and deletes the copy. It does not parse XML during normal startup and does not maintain a persistent user database.

Maintain songs only through XML; never edit SQLite directly. See tools/catalog/README.md for add/edit/rename/delete instructions and specs/003-song-database/quickstart.md for complete verification. Title and lyric are separate SQLite text columns, but search UI, FTS/tokenization, and ranking remain deferred to a later feature.

Toolchain and compatibility

  • AGP 9.4.0; Gradle 9.6.0; host JDK 17
  • App Java and Kotlin JVM targets: 11
  • AGP built-in Kotlin 2.2.10, matching Compose compiler plugin 2.2.10, and Compose BOM 2026.09.00
  • Android Studio Quail 4 (2026.1.4)
  • Android SDK platforms;android-37, build-tools;36.0.0; minSdk 23, compile/target 37
  • AndroidX is enabled. Espresso 3.7.0 is pinned to avoid the API 37 InputManager mismatch.

The launcher class remains com.goodtrendltd.HolySongs.MainActivity (Kotlin namespace unchanged); the new installed application ID is com.goodtrendpromos.hymns, versionCode 11 / versionName 3.0.1. The APK has the two legacy permissions (INTERNET and ACCESS_NETWORK_STATE) plus the AndroidX-generated app-scoped DYNAMIC_RECEIVER_NOT_EXPORTED_PERMISSION protective permission. The added app-private permission has signature protection; no new dangerous/runtime permission is introduced.

Android Studio may use its bundled JBR, but Gradle must use a local JDK 17. On Homebrew, JAVA_HOME points to the JDK root's libexec (for example $(brew --prefix openjdk@17)/libexec), not the formula directory itself. Keep discovery paths in the shell/user-local configuration, never in tracked gradle.properties; do not copy a daemon-JVM criteria file.

Local prerequisites

  • Linux x86_64, Bash, Git, Python 3, and unzip
  • Network access for initial downloads and dependency resolution
  • Local JDK 17 installed under a developer-owned path
  • Android SDK with platforms;android-37, build-tools;36.0.0, and platform-tools
  • Android Studio with its Gradle JDK set to the same local JDK 17
  • adb available via platform-tools on PATH (device execution is not claimed here)
  • Human review and acceptance of Android SDK licenses before invoking sdkmanager package installs

The official command-line tool setup is documented here:

If the command-line tools are missing, provisioning is blocked until the developer installs them locally. Missing sdkmanager does not invalidate a build that is already succeeding with an installed SDK; it simply means the full provisioning path is still pending.

Session-local environment setup

Run from the repository root. Adjust the example JDK/SDK paths below to your installations. Use session-local variables and do not commit a machine-specific local.properties or any personal SDK path. A stale local.properties overrides ANDROID_HOME; use the temporary override below, or intentionally set sdk.dir in your ignored local file.

# Portable example; on Homebrew use "$(brew --prefix openjdk@17)/libexec".
export JAVA_HOME="/path/to/jdk-17"
export ANDROID_HOME="$HOME/Android/Sdk"
export ANDROID_SDK_ROOT="$ANDROID_HOME"
export PATH="$JAVA_HOME/bin:$ANDROID_HOME/platform-tools:$ANDROID_HOME/cmdline-tools/latest/bin:$PATH"

Use a self-contained temporary override for one command instead of leaving a changed file on disk:

(
  set -eu
  tmpdir=$(mktemp -d)
  cleanup() {
    if [ -f "$tmpdir/local.properties" ]; then
      cp -p "$tmpdir/local.properties" local.properties
    else
      rm -f local.properties
    fi
    rm -rf "$tmpdir"
  }
  if [ -f local.properties ]; then
    cp -p local.properties "$tmpdir/local.properties"
  fi
  # Arm restoration only after a successful backup; never delete an original
  # file if copying it failed.
  trap cleanup EXIT
  printf 'sdk.dir=%s\n' "$ANDROID_HOME" > local.properties
  ./gradlew --version
  ./gradlew clean :app:assembleDebug :app:testDebugUnitTest :app:lintDebug --no-build-cache --rerun-tasks
)

This keeps the repository free of global changes and leaves the original file content alone unless the developer intentionally wants a local override for an active shell session.

Build commands

For a checkout with no local.properties, or with a correct ignored sdk.dir, use these commands directly. If the original stale file remains, use the complete temporary-override block above instead; it runs the same build and restores the original immediately afterward.

# Use the same portable environment setup shown above.
./gradlew --version
./gradlew clean :app:verifySongCatalog :app:assembleDebug :app:testDebugUnitTest :app:lintDebug :app:assembleDebugAndroidTest --no-build-cache --rerun-tasks

Replay the app/test build offline without changing the lockfile:

sha256sum app/gradle.lockfile
./gradlew --offline :app:assembleDebug :app:testDebugUnitTest --no-build-cache --rerun-tasks
sha256sum app/gradle.lockfile  # must match the first hash; do not use --write-locks

If the local SDK is already installed and complete, this path can still work without a global Gradle install. The project does not require a global installation and does not auto-provision missing Android tool packages.

Artifact verification

APK=app/build/outputs/apk/debug/app-debug.apk
sha256sum "$APK" app/src/main/assets/songs.xml
rm -f /tmp/holysongs-packaged.db
unzip -p "$APK" assets/songs.db > /tmp/holysongs-packaged.db
python3 tools/catalog/generate_song_database.py verify \
  --source app/src/main/assets/songs.xml \
  --schema tools/catalog/schema.sql \
  --database /tmp/holysongs-packaged.db \
  --baseline app/src/test/resources/catalog-baseline.xml \
  --expected-count 414
rm -f /tmp/holysongs-packaged.db
"$ANDROID_HOME/build-tools/36.0.0/aapt" dump badging "$APK"
"$ANDROID_HOME/build-tools/36.0.0/apksigner" verify --verbose --print-certs --min-sdk-version 23 "$APK"

Check the following:

  • package is com.goodtrendpromos.hymns; version code/name are 10 / 3.0
  • minSdk is 23 and targetSdk is 37
  • only INTERNET, ACCESS_NETWORK_STATE, and AndroidX's app-scoped protective dynamic-receiver permission are packaged
  • packaged assets/songs.db passes logical schema/metadata/all-414-row verification against canonical XML and the historical effective baseline
  • packaged assets/songs.xml may remain for source transparency, but production Kotlin does not open or parse it
  • Maven Central dependency com.belerweb:pinyin4j:2.5.0 remains pinned in the dependency lockfile
  • v1 signature compatibility is present, not just v2/v3 signing output

Install and launch

The modernization phase has owner phone acceptance and bounded automated runtime evidence. For additional validation, use explicit device selection with adb -s <serial> on API 23 or newer; API 14–22 are below this build's install/update floor. Do not uninstall an existing production app to get past a signature mismatch.

export ANDROID_SERIAL=your-test-device-serial
adb devices -l
adb -s "$ANDROID_SERIAL" shell getprop ro.build.version.sdk
adb -s "$ANDROID_SERIAL" install -r app/build/outputs/apk/debug/app-debug.apk
adb -s "$ANDROID_SERIAL" shell am start -n com.goodtrendpromos.hymns/com.goodtrendltd.HolySongs.MainActivity

Inventory device state before installation, stop on signing conflicts, and keep a local catalog run offline when appropriate.

Troubleshooting and missing tools

Missing Java or Android tools:

java -version
which adb
which sdkmanager
ls "$ANDROID_HOME"

If the Android SDK is not fully installed, review the applicable license terms yourself before installing packages. The following are manual provisioning instructions, not commands executed by this migration:

sdkmanager --licenses
sdkmanager "platform-tools" "platforms;android-37" "build-tools;36.0.0"

If sdkmanager is not present, the local environment is still valid only if the required SDK components already exist. Missing command-line provisioning is a local setup blocker, not a product success claim.

Release optimization

Release builds enable R8 code shrinking, optimization, obfuscation, and resource shrinking through AGP's optimization DSL. Debug builds remain unoptimized for development.

./gradlew :app:bundleRelease :app:assembleRelease :app:testDebugUnitTest :app:lintRelease :app:verifySongCatalog
./gradlew :app:analyzeReleaseR8Config

Without a release signing configuration, the generated APK/AAB is unsigned and is not ready for installation or Play upload. Keep app/build/outputs/mapping/release/mapping.txt with its exact release artifact for crash retracing; the AAB also embeds this mapping for Play. JVM tests do not exercise optimized DEX. Before publication, smoke-test the optimized release on a dedicated test device: offline catalog loading, Chinese/pinyin search and letter navigation, lyrics, font/theme persistence, sharing, and video search/Back. Do not replace an installed production app with a differently signed test build.

If optimization causes a runtime failure, add only evidence-backed, targeted keep rules under app/src/release/keepRules/*.keep; avoid blanket rules that defeat shrinking or obfuscation.

Release signing and upgrade boundaries

  • This project does not generate or publish release keys
  • debug APKs are for local testing only
  • a genuine in-place upgrade requires compatible signing identity, reviewed version progression, and explicit maintainer approval
  • no new runtime permissions, SDK range changes, or provider replacements are accepted without clear review

Evidence and dependency risk

Use the curated project evidence and review records:

  • specs/001-modernize-build-system/evidence/recovery.md
  • specs/001-modernize-build-system/evidence/us1-build.md
  • specs/001-modernize-build-system/evidence/review.md
  • specs/001-modernize-build-system/evidence/handoff-blocker.md
  • specs/001-modernize-build-system/evidence/dependencies.md
  • specs/001-modernize-build-system/plan.md
  • specs/001-modernize-build-system/quickstart.md

Pinyin processing uses the pinned Maven Central dependency com.belerweb:pinyin4j:2.5.0. Historical records under specs/001-modernize-build-system/ document the formerly vendored JAR and remain unchanged as evidence of that earlier baseline.

Third-party video provider behavior remains an audit topic rather than a passed validation result.

About

My Chinese hymns Android app. Check it out in Google play store :)

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages