Lightbuild 与 Kotlin DSL 比较

如果您熟悉如何使用 Kotlin DSL 配置 Android build，本页面将向您展示常见的 Kotlin DSL 配置如何映射到 Lightbuild。

本页中的示例使用 Kotlin DSL 和 Android Gradle 插件 (AGP) 9.0 或更高版本，其中包含内置 Kotlin 支持。

构建文件

下表显示了每个 Kotlin DSL build 文件的 Lightbuild 等效项：

Kotlin DSL Lightbuild 用途
settings.gradle.kts project.lightbuild.yaml 项目名称、模块和代码库
根 build.gradle.kts 和 gradle-wrapper.properties project.lightbuild.yaml 构建工具和工具链版本
第 build.gradle.kts 单元 第 lightbuild.yaml 单元 模块类型、Android 设置、依赖项和测试
gradle.lockfile resolved.deps 跟踪依赖项版本

项目设置

在 Kotlin DSL 中，settings.gradle.kts 文件定义了项目的名称、模块以及用于解析依赖项的代码库：

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
    }
}

rootProject.name = "MyApp"
include(":app")
include(":app-core")

在 Lightbuild 中，project.lightbuild.yaml 文件定义了相同的设置：

project:
  name: MyApp
modules:
  - app
  - app-core
repositories:
  - google
  - mavenCentral

下表比较了项目级设置：

概念 Kotlin DSL Lightbuild
项目名称 rootProject.name project.name
模块 include(":app") modules
代码库 dependencyResolutionManagement 中的 repositories repositories
自定义 Maven 仓库 maven { url = uri("https://maven.example.com/releases") } maven（与name和url）
仓库凭证 maven 块中的 credentials credentials，其中包含您在 local.properties 中定义的键
构建工具版本 gradle-wrapper.properties 中的 Gradle 版本，以及 plugins 块中的 AGP 版本 lightbuild.version
Kotlin 版本 内置于 AGP。如需使用较新版本，请将 kotlin-gradle-plugin 添加到 buildscript 类路径。 build.kotlin.version
Java 版本 kotlin { jvmToolchain(17) } build.java.version

模块类型和插件

在 Kotlin DSL 中，您可以通过应用插件来选择模块的类型，并应用其他插件来添加 KSP 等功能。在 Lightbuild 中，您只需设置模块的 type，Lightbuild 就会应用配置所需的功能：

概念 Kotlin DSL Lightbuild
应用模块 id("com.android.application") type: application
库模块 id("com.android.library") type: library
Kotlin Multiplatform (KMP) 模块 id("org.jetbrains.kotlin.multiplatform") 暂不支持
Kotlin 内置于 AGP 9.0 及更高版本中 内置
KSP id("com.google.devtools.ksp") 在您声明 kspProcessors 时自动应用
协议缓冲区 id("com.google.protobuf") optionalFeatures 中的 com.android.tools.lightbuild.protobuf
版本目录 libs.versions.toml 个文件 暂不支持
其他插件 应用 Gradle 插件 暂不支持

Android 设置

在 Kotlin DSL 中，您可以在模块的 build.gradle.kts 文件的 android 代码块中配置 Android 设置：

plugins {
    id("com.android.application")
}

android {
    namespace = "com.example.myapp.app"
    compileSdk = 36

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 24
        targetSdk = 36
        versionCode = 1
        versionName = "1.0"
    }
}

在 Lightbuild 中，您可以在模块的 lightbuild.yaml 文件的 android 代码块中配置相同的设置：

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"

下表对这些设置进行了比较：

设置 Kotlin DSL Lightbuild
命名空间 namespace namespace
编译 SDK compileSdk = 36 compileSdk.version.release.apiLevel: 36
最低 SDK 版本 defaultConfig 中的 minSdk = 24 minSdk.version.release.apiLevel: 24
目标 SDK 版本 defaultConfig 中的 targetSdk = 36 targetSdk.version.release.apiLevel: 36
应用 ID defaultConfig 中的 applicationId applicationId
版本代码 defaultConfig 中的 versionCode versionCode
版本名称 defaultConfig 中的 versionName versionName
发布签名 signingConfigs，以及 release build 类型中的 signingConfig packaging.release.signing

依赖项

在 Kotlin DSL 中，您可以使用 implementation 等配置在 dependencies 代码块中声明依赖项：

dependencies {
    implementation(project(":app-core"))
    implementation("androidx.core:core-ktx:1.18.0")
}

在 Lightbuild 中，您可以在 module 下列出模块依赖项，在 maven 下列出外部库：

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

Kotlin DSL 使用其他配置（例如 api、compileOnly 和 runtimeOnly）来控制模块如何使用依赖项：

dependencies {
    api(project(":data"))
    compileOnly("androidx.annotation:annotation:1.9.1")
}

在 Lightbuild 中，您需要改为向依赖项添加 compile 和 runtime 设置：

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

如需详细了解这些设置，请参阅依赖项设置。

下表比较了常见的依赖项声明：

依赖项 Kotlin DSL Lightbuild
项目中的模块 implementation(project(":app-core")) android.dependencies.module 中的 //app-core
外部库 implementation("group:artifact:version") android.dependencies.maven 中的 group:artifact:version
API 依赖项 api("group:artifact:version") android.dependencies.maven的group:artifact:version（compile: public）
仅编译依赖项 compileOnly("group:artifact:version") android.dependencies.maven的group:artifact:version（runtime: off）
仅运行时依赖项 runtimeOnly("group:artifact:version") android.dependencies.maven的group:artifact:version（compile: off）
KSP 处理器 ksp("group:artifact:version") android.kspProcessors.maven 中的 group:artifact:version
本地测试依赖项 testImplementation("group:artifact:version") android.tests.test.dependencies.maven 中的 group:artifact:version
插桩测试依赖项 androidTestImplementation("group:artifact:version") android.tests.androidTest.dependencies.maven 中的 group:artifact:version

KSP

在 Kotlin DSL 中，您需要应用 KSP 插件，并使用 ksp 配置添加处理器：

plugins {
    id("com.android.library")
    id("com.google.devtools.ksp")
}

dependencies {
    implementation("com.squareup.moshi:moshi:1.15.2")
    implementation("com.squareup.moshi:moshi-kotlin:1.15.2")
    ksp("com.squareup.moshi:moshi-kotlin-codegen:1.15.2")
}

在 Lightbuild 中，您需要将处理器添加到 kspProcessors 代码块中，Lightbuild 会自动应用 KSP 插件：

type: library
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

测试

在 Kotlin DSL 中，您可以在 defaultConfig 中设置插桩测试运行程序，并使用 testImplementation 和 androidTestImplementation 配置添加测试依赖项：

android {
    defaultConfig {
        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
    }
}

dependencies {
    testImplementation("junit:junit:4.13.2")
    androidTestImplementation("androidx.test.ext:junit:1.3.0")
    androidTestImplementation("androidx.test.espresso:espresso-core:3.7.0")
}

在 Lightbuild 中，您可以在 tests.test 中配置本地测试，在 tests.androidTest 中配置插桩测试：

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

构建命令

借助 Kotlin DSL，您可以通过使用 Gradle 封装容器运行 Gradle 任务，从命令行进行构建和测试。使用 Lightbuild 时，您需要使用 Lightbuild CLI。

任务 Gradle 封装容器 Lightbuild CLI
构建应用模块 ./gradlew :app:assembleDebug lightbuild build app
构建所有目标 ./gradlew assemble lightbuild build
运行模块的本地测试 ./gradlew :app-core:test lightbuild test app-core:hostTest
运行模块的插桩测试 ./gradlew :app-core:connectedAndroidTest lightbuild test app-core:deviceTest
运行所有测试 ./gradlew test connectedAndroidTest lightbuild test
移除 build 输出和缓存 ./gradlew clean lightbuild clean

如需了解详情，请参阅从命令行构建应用和从命令行构建 Lightbuild 项目。

依赖项锁定

使用 Kotlin DSL 时，依赖项锁定是可选的：您可以在 build 脚本中启用该功能，然后通过运行带有 --write-locks 标志的 build 来写入锁定文件。在 Lightbuild 中，每个模块都有一个 resolved.deps 文件，用于记录模块的已解析依赖项，该文件由 Lightbuild 自动生成。与 Gradle 锁定文件一样，请将 resolved.deps 文件签入版本控制。

如需锁定依赖项（例如在 CI build 中），请将 --locked-dependencies 标志添加到 lightbuild resolve 或 lightbuild test。使用此标志后，如果 resolved.deps 文件与模块的依赖项不匹配，该命令会失败，而不是更新文件：

lightbuild resolve --locked-dependencies

不支持的功能

Lightbuild 不支持以下 Kotlin DSL 功能：

  • 版本目录和惯例插件
  • 自定义插件
  • 产品变种。而是为应用的每个版本创建一个单独的应用模块。如需了解详情，请参阅多个应用模块。
  • Kotlin Multiplatform (KMP) 模块
  • 通过代理服务器进行依赖项解析

此外，项目不能混合使用 Kotlin DSL 和 Lightbuild 模块。如需了解已知问题，请参阅 Lightbuild 版本说明。