Referensi konfigurasi Lightbuild

Konfigurasi build project Lightbuild terdiri dari file YAML: file project.lightbuild.yaml di direktori root project, dan file lightbuild.yaml di setiap modul. Halaman ini menjelaskan setelan di setiap file.

File project

Setelan project global berada dalam file project.lightbuild.yaml di direktori root project Anda. Contoh:

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"

Tabel berikut menjelaskan setelan ini:

Setelan Deskripsi
project.name Nama project, misalnya MyApp. Android Studio menampilkan nama ini sebagai root jendela Project. Seperti rootProject.name di DSL Kotlin, namespace ini terpisah dari nama dan ID aplikasi Anda.
modules Modul dalam project, seperti modul aplikasi (app) dan modul library (app-core).
repositories Repositori jarak jauh tempat Lightbuild me-resolve dependensi. Untuk mengetahui detailnya, lihat Repositori.
lightbuild.version Versi Lightbuild yang digunakan project.
build.kotlin.version Versi Kotlin yang digunakan project.
build.java.version Versi compiler Java yang diperlukan project.
build.jvmTarget Versi target bytecode JVM yang dihasilkan.

Repositori

Gunakan repositories untuk mencantumkan repositori yang menjadi sumber dependensi yang di-resolve oleh Lightbuild. Anda dapat mencantumkan repositori google dan mavenCentral bawaan, serta menambahkan repositori Maven kustom dengan maven:

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

Repositori maven memiliki setelan berikut:

Setelan Deskripsi
name Nama untuk repositori.
url URL repositori.
credentials Opsional. Kunci yang dipetakan ke nama pengguna dan sandi repositori dalam file local.properties Anda. Untuk mengetahui detailnya, lihat Kredensial repositori.

Kredensial repositori

Jika repositori Maven memerlukan nama pengguna dan sandi, tambahkan blok credentials ke repositori. Nilai username dan password bukanlah kredensial itu sendiri; nilai tersebut adalah kunci yang Anda tentukan dalam file local.properties project:

repositories:

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

Kemudian, di file local.properties project Anda, petakan setiap kunci ke nilainya. Ganti REPO_USERNAME dan REPO_PASSWORD dengan kredensial Anda:

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

File modul

Setiap modul memiliki file lightbuild.yaml di direktorinya yang menentukan setelan modul. Tabel berikut menjelaskan setelan tingkat teratas:

Setelan Deskripsi
platform Platform yang ditargetkan modul: android.
type Jenis modul: application untuk modul aplikasi, atau library untuk modul library. Untuk mengetahui informasi selengkapnya, lihat Struktur project Lightbuild.
optionalFeatures Fitur opsional yang akan diaktifkan untuk modul, seperti com.android.tools.lightbuild.protobuf untuk dukungan Protocol Buffers. Untuk mengetahui detailnya, lihat Buffering Protokol.
android Setelan Android modul. Untuk mengetahui detailnya, lihat Setelan Android.

Setelan Android

Blok android berisi setelan build Android modul:

Setelan Deskripsi
namespace Namespace modul. Untuk mengetahui informasi selengkapnya, lihat Menetapkan namespace.
compileSdk Level API yang digunakan untuk mengompilasi modul. Untuk mengetahui detailnya, lihat Versi SDK.
minSdk Level API minimum yang didukung modul.
targetSdk Level API yang ditargetkan aplikasi. Hanya didukung dalam modul aplikasi.
applicationId ID aplikasi. Ditetapkan dalam modul aplikasi.
versionCode Kode versi aplikasi. Ditetapkan dalam modul aplikasi.
versionName Nama versi aplikasi. Ditetapkan dalam modul aplikasi.
packaging Setelan untuk memaketkan build debug dan release aplikasi, seperti penandatanganan rilis. Hanya didukung dalam modul aplikasi. Untuk mengetahui detailnya, lihat Pengemasan.
dependencies Dependensi modul pada modul lain dan pada library eksternal. Untuk mengetahui detailnya, lihat Dependensi.
kspProcessors Pemroses KSP yang menghasilkan kode untuk modul. Untuk mengetahui detailnya, lihat Pemroses KSP.
tests Pengujian lokal dan uji instrumentasi modul. Untuk mengetahui detailnya, lihat Pengujian.

Versi SDK

Tentukan setelan compileSdk, minSdk, dan targetSdk sebagai level API di bagian version.release.apiLevel. Misalnya, setelan berikut mengompilasi modul terhadap API level 36, mendukung API level 24 dan yang lebih tinggi, serta menarget API level 36:

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

Hanya modul aplikasi yang mendukung setelan targetSdk. Modul library hanya menentukan setelan compileSdk dan minSdk.

Dependensi

Deklarasikan dependensi modul dalam blok dependencies:

  • module: Modul lain dalam project Anda, yang ditulis sebagai // diikuti dengan nama modul, misalnya //app-core atau //features/search.
  • maven: Library eksternal, ditulis sebagai koordinat Maven dalam format group:artifact:version.

Misalnya, setelan berikut menambahkan dependensi pada modul app-core dan pada library AndroidX Core KTX:

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

Setelan dependensi

Secara default, modul mengompilasi setiap dependensinya dan menyertakannya saat runtime, tetapi tidak mengeksposnya ke modul yang bergantung padanya. Untuk mengubah cara modul menggunakan dependensi, tambahkan titik dua setelah dependensi, lalu tambahkan setelan compile, setelan runtime, atau keduanya di bawahnya:

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

Dalam contoh ini, modul yang bergantung pada modul ini juga dapat menggunakan class modul data. Library Jetpack Annotation hanya digunakan untuk mengompilasi modul ini. Core KTX menggunakan setelan default.

Setelan compile mengontrol modul mana yang dikompilasi terhadap dependensi:

  • private (default): Modul ini mengompilasi dependensi, tetapi modul yang bergantung pada modul ini tidak.
  • public: Modul ini dan modul yang bergantung padanya mengompilasi dependensi. Gunakan public jika API publik modul Anda menggunakan jenis dari dependensi.
  • off: Modul ini tidak mengompilasi dependensi.

Setelan runtime mengontrol apakah dependensi tersedia saat runtime:

  • public (default): Dependensi tersedia saat runtime, untuk modul ini dan untuk modul yang bergantung padanya.
  • off: Dependensi tidak tersedia saat runtime. Gunakan off untuk dependensi yang hanya diperlukan kode Anda pada waktu kompilasi, seperti anotasi.

compile dan runtime tidak boleh sama-sama off. Dalam dependensi pengujian, compile hanya dapat berupa private atau off.

Untuk melihat keterkaitan setelan ini dengan konfigurasi DSL Kotlin seperti api dan compileOnly, lihat Membandingkan Lightbuild dengan DSL Kotlin.

Pemroses KSP

Untuk menggunakan generator kode yang didasarkan pada Kotlin Symbol Processing (KSP), seperti Moshi atau Room, tambahkan pemroses ke blok kspProcessors, dan tambahkan library yang digunakan kode Anda saat runtime ke blok dependencies. Lightbuild otomatis menerapkan plugin KSP dan mengonfigurasi pembuatan kode selama build.

Misalnya, setelan berikut mengonfigurasi Moshi dengan generator kode KSP-nya:

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

Buffering Protokol

Untuk membuat kode dari file Protocol Buffers (.proto) dalam modul library, tambahkan fitur Protocol Buffers ke daftar optionalFeatures modul, dan tambahkan library runtime Protocol Buffers ke dependensi modul. optionalFeatures adalah setelan tingkat teratas, di luar blok 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

Tempatkan file .proto modul di direktori src/main/proto-nya. Saat Anda mem-build modul, Lightbuild akan membuat class Java dan Kotlin untuk runtime lite Buffering Protokol, yang direkomendasikan untuk Android.

Pengujian

Konfigurasikan pengujian modul di blok tests:

  • test: Pengujian lokal yang berjalan di JVM mesin pengembangan Anda. Cantumkan dependensi pengujian di bagian dependencies.
  • androidTest: Pengujian berinstrumen yang berjalan di perangkat atau emulator. Tetapkan runner ke class runner pengujian, dan cantumkan dependensi pengujian di bagian dependencies.

Contoh:

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

Kemasan

Dalam modul aplikasi, gunakan blok packaging untuk mengonfigurasi build debug dan release aplikasi. Untuk menandatangani build rilis dengan kunci Anda sendiri, tambahkan blok signing ke profil release:

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

Blok signing mendukung setelan berikut:

  • storeFile: Jalur ke file keystore, baik yang relatif terhadap direktori modul atau dimulai dengan ~/ untuk lokasi di direktori utama Anda.
  • storePassword: Sandi keystore.
  • keyAlias: Alias kunci penandatanganan di keystore.
  • keyPassword: Sandi kunci penandatanganan.

Agar sandi Anda tidak berada dalam file project, tetapkan nilai ini ke referensi variabel lingkungan dengan sintaksis ${NAME}, seperti dalam contoh. Anda dapat menulis storeFile dan keyAlias secara langsung, atau mereferensikan variabel lingkungan untuk keduanya juga. Saat Anda melakukan build, Lightbuild akan mengganti setiap referensi dengan nilai variabel lingkungan. Setiap nilai hanya boleh berisi referensi: Lightbuild tidak mengganti referensi yang merupakan bagian dari nilai yang lebih panjang, seperti ${HOME}/upload-keystore.jks.

Contoh

Contoh berikut menunjukkan file modul lengkap untuk modul aplikasi dan modul library.

Modul aplikasi

File app/lightbuild.yaml berikut mengonfigurasi modul aplikasi yang bergantung pada modul library 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

Modul library

File app-core/lightbuild.yaml berikut mengonfigurasi modul library yang menggunakan Jetpack Compose dan Moshi serta berisi uji lokal dan uji instrumentasi:

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