Lightbuild 配置参考文档

Lightbuild 项目的 build 配置由 YAML 文件组成：项目根目录中的 project.lightbuild.yaml 文件，以及每个模块中的 lightbuild.yaml 文件。本页面介绍了每个文件中的设置。

项目文件

全局项目设置位于项目根目录中的 project.lightbuild.yaml 文件内。例如：

project:
  name: MyApp

modules:
  - app
  - app-core

repositories:
  - google
  - mavenCentral

lightbuild:
  version: 0.0.30

build:
  java:
    version: 17
  kotlin:
    version: 2.3.20
  jvmTarget: "17"

下表介绍了这些设置：

设置 说明
project.name 项目的名称，例如 MyApp。Android Studio 会将此名称显示为 Project 窗口的根目录。与 Kotlin DSL 中的 rootProject.name 一样，它与应用的名称和应用 ID 是分开的。
modules 项目中的模块，例如应用模块 (app) 和库模块 (app-core)。
repositories Lightbuild 从中解析依赖项的远程仓库。如需了解详情，请参阅代码库。
lightbuild.version 项目使用的 Lightbuild 版本。
build.kotlin.version 项目使用的 Kotlin 版本。
build.java.version 项目所需的 Java 编译器版本。
build.jvmTarget 生成的 JVM 字节码的目标版本。

代码库

使用 repositories 列出 Lightbuild 从中解析依赖项的代码库。您可以列出内置的 google 和 mavenCentral 制品库，并使用 maven 添加自定义 Maven 仓库：

repositories:
  - google
  - mavenCentral
  - maven:
      name: "Example Repo"
      url: "https://maven.example.com/releases"

maven 代码库具有以下设置：

设置 说明
name 代码库的名称。
url 代码库的网址。
credentials 可选。local.properties 文件中映射到代码库用户名和密码的密钥。如需了解详情，请参阅代码库凭证。

仓库凭证

如果 Maven 仓库需要用户名和密码，请向该仓库添加 credentials 代码块。username 和 password 值不是凭据本身，而是您在项目的 local.properties 文件中定义的键：

repositories:

  - google
  - mavenCentral
  - maven:
      name: "Internal Repo"
      url: "https://maven.example.com/releases"
      credentials:
        username: internalRepoUser
        password: internalRepoPassword

然后，在项目的 local.properties 文件中，将每个键映射到其值。 将 REPO_USERNAME 和 REPO_PASSWORD 替换为您的凭证：

# Also define sdk.dir, the path to your Android SDK.
internalRepoUser=REPO_USERNAME
internalRepoPassword=REPO_PASSWORD

模块文件

每个模块的目录中都有一个 lightbuild.yaml 文件，用于定义模块的设置。下表介绍了顶级设置：

设置 说明
platform 模块的目标平台：android。
type 模块类型：application 表示应用模块，library 表示库模块。如需了解详情，请参阅 Lightbuild 项目结构。
optionalFeatures 要为模块启用的可选功能，例如用于支持协议缓冲区 的 com.android.tools.lightbuild.protobuf。如需了解详情，请参阅协议缓冲区。
android 模块的 Android 设置。如需了解详情，请参阅 Android 设置。

Android 设置

android 代码块包含模块的 Android build 设置：

设置 说明
namespace 模块的命名空间。如需了解详情，请参阅设置命名空间。
compileSdk 模块编译时所针对的 API 级别。如需了解详情，请参阅 SDK 版本。
minSdk 模块支持的最低 API 级别。
targetSdk 应用的目标 API 级别。仅在应用模块中受支持。
applicationId 应用的 ID。在应用模块中设置。
versionCode 应用的版本代码。在应用模块中设置。
versionName 应用的版本名称。在应用模块中设置。
packaging 用于打包应用的 debug 和 release build 的设置，例如发布签名。仅在应用模块中受支持。如需了解详情，请参阅打包。
dependencies 模块对其他模块和外部库的依赖关系。如需了解详情，请参阅依赖项。
kspProcessors 为模块生成代码的 KSP 处理器。如需了解详情，请参阅 KSP 处理器。
tests 模块的本地测试和插桩测试。如需了解详情，请参阅测试。

SDK 版本

在 version.release.apiLevel 下将 compileSdk、minSdk 和 targetSdk 设置指定为 API 级别。例如，以下设置会针对 API 级别 36 编译模块，支持 API 级别 24 及更高级别，并以目标 API 级别 36 为目标平台：

android:
  compileSdk:
    version:
      release:
        apiLevel: 36
  minSdk:
    version:
      release:
        apiLevel: 24
  targetSdk:
    version:
      release:
        apiLevel: 36

只有应用模块支持 targetSdk 设置。库模块仅定义 compileSdk 和 minSdk 设置。

依赖项

在 dependencies 代码块中声明模块的依赖项：

  • module：项目中的其他模块，写作 // 后跟模块名称，例如 //app-core 或 //features/search。
  • maven：外部库，以 Maven 坐标的形式编写，格式为 group:artifact:version。

例如，以下设置会添加对 app-core 模块和 AndroidX Core KTX 库的依赖项：

android:
  dependencies:
    module:
      - //app-core
    maven:
      - androidx.core:core-ktx:1.18.0

依赖项设置

默认情况下，模块会针对其每个依赖项进行编译，并在运行时包含这些依赖项，但不会将其公开给依赖于它的模块。如需更改模块使用依赖项的方式，请在依赖项后添加英文冒号，然后在下方添加 compile 设置、runtime 设置或同时添加这两项设置：

android:
  dependencies:
    module:
      - //data:
          compile: public
    maven:
      - androidx.core:core-ktx:1.18.0
      - androidx.annotation:annotation:1.9.1:
          runtime: off

在此示例中，依赖于此模块的模块也可以使用 data 模块的类。Jetpack 注解库仅用于编译此模块。Core KTX 使用默认设置。

compile 设置用于控制哪些模块会针对依赖项进行编译：

  • private（默认）：此模块会针对依赖项进行编译，但依赖于此模块的模块不会。
  • public：此模块和依赖于它的模块会针对该依赖项进行编译。当模块的公共 API 使用依赖项中的类型时，请使用 public。
  • off：此模块不会针对依赖项进行编译。

runtime 设置用于控制依赖项在运行时是否可用：

  • public（默认）：此模块以及依赖于此模块的模块在运行时可以使用该依赖项。
  • off：依赖项在运行时不可用。对于代码仅在编译时间需要的依赖项（例如注解），请使用 off。

compile 和 runtime 不能同时为 off。在测试依赖项中，compile 只能是 private 或 off。

如需了解这些设置如何与 Kotlin DSL 配置（例如 api 和 compileOnly）对应，请参阅比较 Lightbuild 与 Kotlin DSL。

KSP 处理器

如需使用基于 Kotlin 符号处理 (KSP) 的代码生成器（例如 Moshi 或 Room），请将处理器添加到 kspProcessors 代码块中，并将代码在运行时使用的库添加到 dependencies 代码块中。Lightbuild 会自动应用 KSP 插件，并在构建期间配置代码生成。

例如，以下设置会使用 Moshi 的 KSP 代码生成器配置 Moshi：

android:
  dependencies:
    maven:
      - com.squareup.moshi:moshi:1.15.2
      - com.squareup.moshi:moshi-kotlin:1.15.2
  kspProcessors:
    maven:
      - com.squareup.moshi:moshi-kotlin-codegen:1.15.2

协议缓冲区

如需从库模块中的 协议缓冲区 (.proto) 文件生成代码，请将协议缓冲区功能添加到模块的 optionalFeatures 列表中，并将协议缓冲区运行时库添加到模块的依赖项中。optionalFeatures 是一个顶级设置，位于 android 代码块之外：

optionalFeatures:
  - com.android.tools.lightbuild.protobuf

android:
  dependencies:
    maven:
      - com.google.protobuf:protobuf-javalite:4.28.2
      - com.google.protobuf:protobuf-kotlin-lite:4.28.2

将模块的 .proto 文件放入其 src/main/proto 目录中。构建模块时，Lightbuild 会为 Protocol Buffers Lite 运行时生成 Java 和 Kotlin 类，这是 Android 的推荐做法。

测试

在 tests 代码块中配置模块的测试：

  • test：在开发机器的 JVM 上运行的本地测试。在 dependencies 下列出测试的依赖项。
  • androidTest：在设备或模拟器上运行的插桩测试。将 runner 设置为测试运行程序类，并在 dependencies 下列出测试的依赖项。

例如：

android:
  tests:
    test:
      dependencies:
        maven:
          - junit:junit:4.13.2
    androidTest:
      runner: androidx.test.runner.AndroidJUnitRunner
      dependencies:
        maven:
          - androidx.test.ext:junit:1.3.0
          - androidx.test.espresso:espresso-core:3.7.0

包装

在应用模块中，使用 packaging 代码块配置应用的 debug 和 release build。如需使用您自己的密钥为发布 build 签名，请向 release 配置文件添加 signing 代码块：

android:
  packaging:
    release:
      signing:
        storeFile: "${RELEASE_STORE_FILE}"
        storePassword: "${RELEASE_STORE_PASSWORD}"
        keyAlias: "${RELEASE_KEY_ALIAS}"
        keyPassword: "${RELEASE_KEY_PASSWORD}"

signing 块支持以下设置：

  • storeFile：密钥库文件的路径，相对于模块的目录，或以 ~/ 开头（表示主目录中的位置）。
  • storePassword：密钥库的密码。
  • keyAlias：密钥库中签名密钥的别名。
  • keyPassword：签名密钥的密码。

为避免将密码存储在项目文件中，请使用 ${NAME} 语法将这些值设置为环境变量引用，如示例所示。您可以直接写入 storeFile 和 keyAlias，也可以引用它们的环境变量。在您构建时，Lightbuild 会将每个引用替换为环境变量的值。每个值都必须仅包含引用：Lightbuild 不会替换属于较长值一部分的引用，例如 ${HOME}/upload-keystore.jks。

示例

以下示例展示了应用模块和库模块的完整模块文件。

应用模块

以下 app/lightbuild.yaml 文件配置了一个依赖于 app-core 库模块的应用模块：

platform: android
type: application
android:
  namespace: com.example.myapp.app
  compileSdk:
    version:
      release:
        apiLevel: 36
  minSdk:
    version:
      release:
        apiLevel: 24
  targetSdk:
    version:
      release:
        apiLevel: 36
  applicationId: com.example.myapp
  versionCode: 1
  versionName: "1.0"
  dependencies:
    module:
      - //app-core

库模块

以下 app-core/lightbuild.yaml 文件配置了一个库模块，该模块使用 Jetpack Compose 和 Moshi，并包含本地测试和插桩测试：

platform: android
type: library
android:
  namespace: com.example.myapp
  compileSdk:
    version:
      release:
        apiLevel: 36
  minSdk:
    version:
      release:
        apiLevel: 24
  dependencies:
    maven:
      - androidx.core:core-ktx:1.18.0
      - androidx.lifecycle:lifecycle-runtime-ktx:2.10.0
      - androidx.activity:activity-compose:1.13.0
      - androidx.lifecycle:lifecycle-runtime-compose:2.10.0
      - androidx.lifecycle:lifecycle-viewmodel-compose:2.10.0
      - androidx.compose.ui:ui:1.10.4
      - androidx.compose.ui:ui-tooling-preview:1.10.4
      - androidx.compose.material3:material3:1.4.0
      - androidx.navigation3:navigation3-ui:1.0.1
      - androidx.navigation3:navigation3-runtime:1.0.1
      - androidx.lifecycle:lifecycle-viewmodel-navigation3:2.10.0
      - androidx.compose.ui:ui-tooling:1.10.4
      - androidx.compose.ui:ui-test-manifest:1.10.4
      - com.squareup.moshi:moshi:1.15.2
      - com.squareup.moshi:moshi-kotlin:1.15.2
  kspProcessors:
    maven:
      - com.squareup.moshi:moshi-kotlin-codegen:1.15.2
  tests:
    test:
      dependencies:
        maven:
          - junit:junit:4.13.2
          - org.jetbrains.kotlinx:kotlinx-coroutines-test:1.10.2
    androidTest:
      runner: androidx.test.runner.AndroidJUnitRunner
      dependencies:
        maven:
          - androidx.test:core:1.7.0
          - androidx.test.ext:junit:1.3.0
          - androidx.test:runner:1.7.0
          - androidx.test.espresso:espresso-core:3.7.0
          - androidx.compose.ui:ui-test-junit4:1.10.4