比較 Lightbuild 與 Kotlin DSL

如果您熟悉如何使用 Kotlin DSL 設定 Android 建構作業，本頁面會說明常見的 Kotlin DSL 設定如何對應至 Lightbuild。

本頁範例使用 Kotlin DSL 和 Android Gradle 外掛程式 (AGP) 9.0 以上版本，其中包含內建 Kotlin 支援。

建構檔案

下表列出每個 Kotlin DSL 建構檔案對應的 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
版本簽署 release 建構類型的 signingConfigs 和 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") group:artifact:version (android.dependencies.maven)，compile: public
僅限編譯依附元件 compileOnly("group:artifact:version") group:artifact:version (android.dependencies.maven)，runtime: off
僅限執行階段依附元件 runtimeOnly("group:artifact:version") group:artifact:version (android.dependencies.maven)，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
移除建構輸出內容和快取 ./gradlew clean lightbuild clean

詳情請參閱「透過指令列建構應用程式」和「透過指令列建構 Lightbuild 專案」。

依附元件鎖定

使用 Kotlin DSL 時，依附元件鎖定功能為選用：您可以在建構指令碼中啟用這項功能，然後執行含有 --write-locks 旗標的建構作業，寫入鎖定檔案。在 Lightbuild 中，每個模組都有一個 resolved.deps 檔案，用於記錄模組已解析的依附元件，這個檔案由 Lightbuild 自動產生。與 Gradle 鎖定檔案一樣，請將 resolved.deps 檔案簽入版本管控。

如要鎖定依附元件 (例如在 CI 建構作業中)，請將 --locked-dependencies 旗標新增至 lightbuild resolve 或 lightbuild test。使用這個旗標時，如果 resolved.deps 檔案與模組的依附元件不符，指令會失敗，而不會更新檔案：

lightbuild resolve --locked-dependencies

不支援的功能

Lightbuild 不支援下列 Kotlin DSL 功能：

  • 版本目錄和慣例外掛程式
  • 自訂外掛程式
  • 變種版本。請改為替每個應用程式版本建立獨立的應用程式模組。詳情請參閱「多個應用程式模組」。
  • Kotlin Multiplatform (KMP) 模組
  • 透過 Proxy 伺服器解析依附元件

此外，專案不能同時使用 Kotlin DSL 和 Lightbuild 模組。如需已知問題，請參閱 Lightbuild 版本資訊。