如何贡献代码

首先，感谢您抽出时间为 Accompanist Lyrics UI 做出贡献！

本文档提供了一些贡献指南。这些主要是建议而非硬性规定。请运用您的判断力，欢迎提交 Pull Request 来完善本文档。

项目结构

Accompanist Lyrics UI 是一个 混合 Kotlin Multiplatform (KMP) + Rust 的项目。理解目录结构对于高效开发至关重要。

• lyrics-ui/: 包含 UI 库代码的主 KMP 模块。

  • src/commonMain/kotlin/...: 库的核心部分。包含：
    • ui/composable/lyrics/: 所有 Compose UI 组件 (KaraokeLyricsView, KaraokeLineText 等)。
    • core/model/: 平台无关的数据模型 (Lyrics, KaraokeLine)。
    • text/: 文本引擎的共享接口 (NativeTextEngine)。
  • src/androidMain/kotlin/...: Android 平台实现。
    • 包含 Rust 库的 JNI 绑定 (NativeTextEngine.android.kt)。
    • 处理 Android 平台的 Bitmap 创建和内存管理。
  • src/jvmMain/kotlin/...: Desktop/JVM 平台实现。
    • 使用 JNA/JNI 绑定编译后的动态链接库。
    • 处理 BufferedImage 到 ImageBitmap 的转换。

• text_engine/: 使用 Rust 编写的高性能文本处理核心。

  • src/lib.rs: 暴露 C兼容 FFI (外部函数接口) 的入口点。
  • src/font.rs: 字体解析和 SDF 生成逻辑。
  • src/text.rs: 使用 rustybuzz 进行排版 (Shaping) 的逻辑。
  • Cargo.toml: Rust 依赖配置。

• gradle/: 构建配置。

  • libs.versions.toml: 依赖版本管理目录 (Version Catalog)。

开发环境搭建

要构建和运行本项目，您需要：

1. JDK 17+: 确保正确设置了 JAVA_HOME 环境变量。
2. Rust 工具链: 通过 rustup 安装。确保 cargo 在您的 PATH 中。
   • 如果您构建 Android 版本，还需要添加对应的交叉编译目标：

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

3. Android SDK: 通过 Android Studio 安装。确保设置了 ANDROID_HOME 或 ANDROID_SDK_ROOT。
   • 确保安装了 NDK (版本通常在 build.gradle.kts 中指定，或使用默认版本)。

工作流

构建项目

我们将 Rust 构建过程集成到了 Gradle 中。运行标准的 Gradle 构建任务会自动触发 Rust 编译。

./gradlew build

该命令会： 1. 为目标平台编译 Rust crate (text_engine)。 2. 将生成的 .so / .dll / .dylib 文件复制到相应的 resources/jniLibs 目录。 3. 生成 Kotlin JNI 绑定（如果适用）。 4. 编译 Kotlin 代码。

修改 Rust 代码

如果您修改了 text_engine/src/ 下的文件，只需再次运行 Gradle 构建即可。自定义任务 buildRustAndroid, buildRustJvm 等会检测更改并重新编译 Rust 库。

代码风格

• Kotlin: 我们遵循标准的 Kotlin Coding Conventions。
• Rust: 提交前请使用 cargo fmt 格式化您的 Rust 代码。

Pull Request 流程

1. Fork 仓库并从 main 分支创建您的功能分支。
2. 如果您添加了代码，请确保添加相应的测试。
3. 如果您更改了 API，请更新文档。
4. 确保测试套件通过。

许可证

参与贡献即表示您同意您的贡献遵循本项目的 Apache License 2.0 许可证。