Contributing to Accompanist Lyrics UI

First off, thanks for taking the time to contribute!

The following is a set of guidelines for contributing to Accompanist Lyrics UI. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.

Project Structure

Accompanist Lyrics UI is a hybrid Kotlin Multiplatform (KMP) + Rust project. Understanding the directory structure is key to efficient development.

• lyrics-ui/: The main KMP module containing the UI library code.

  • src/commonMain/kotlin/...: The heart of the library. Contains:
    • ui/composable/lyrics/: All Compose UI components (KaraokeLyricsView, KaraokeLineText, etc.).
    • core/model/: Platform-agnostic data models (Lyrics, KaraokeLine).
    • text/: Shared interfaces for the text engine (NativeTextEngine).
  • src/androidMain/kotlin/...: Android implementations.
    • Contains JNI bindings to the Rust library (NativeTextEngine.android.kt).
    • Handles Bitmap creation and memory management for Android.
  • src/jvmMain/kotlin/...: Desktop/JVM implementations.
    • Uses JNA/JNI to bind to the compiled dynamic library.
    • Handles BufferedImage to ImageBitmap conversion.

• text_engine/: The high-performance text handling core written in Rust.

  • src/lib.rs: Entry point exposing the C-compatible FFI (Foreign Function Interface).
  • src/font.rs: Font parsing and SDF generation logic.
  • src/text.rs: Shaping logic using rustybuzz.
  • Cargo.toml: Rust dependencies configuration.

• gradle/: Build configuration.

  • libs.versions.toml: Version catalog for managing dependencies.

Development Setup

To build and run this project, you need:

1. JDK 17+: Ensure JAVA_HOME is set correctly.
2. Rust Toolchain: Install via rustup. Ensure cargo is in your PATH.
   • You also need targets for cross-compilation if you are building for Android:

     rustup target add aarch64-linux-android armv7-linux-androideabi x86_64-linux-android i686-linux-android
     

3. Android SDK: Install via Android Studio. Ensure ANDROID_HOME or ANDROID_SDK_ROOT is set.
   • Make sure you have the NDK installed (version specified in build.gradle.kts or default).

Workflow

Building the Project

We have integrated the Rust build process into Gradle. Running the standard Gradle build tasks will automatically trigger the Rust compilation.

./gradlew build

This will: 1. Compile the Rust crate (text_engine) for the target platforms. 2. Copy the resulting .so / .dll / .dylib files to the appropriate resources/jniLibs directories. 3. Generate Kotlin JNI bindings (if applicable). 4. Compile the Kotlin code.

Modifying Rust Code

If you modify files in text_engine/src/, simple run the Gradle build again. The custom tasks buildRustAndroid, buildRustJvm, etc., will detect changes and recompile the Rust library.

Code Style

• Kotlin: We follow the standard Kotlin Coding Conventions.
• Rust: Use cargo fmt to format your Rust code before submitting.

Pull Requests

1. Fork the repo and create your branch from main.
2. If you've added code that needs testing, add tests.
3. If you've changed APIs, update the documentation.
4. Ensure the test suite passes.
5. Make sure your code lints.

License

By contributing, you agree that your contributions will be licensed under its Apache License 2.0.