Riferimento alla configurazione di Lightbuild

La configurazione di compilazione di un progetto Lightbuild è costituita da file YAML: un file project.lightbuild.yaml nella directory root del progetto e un file lightbuild.yaml in ogni modulo. Questa pagina descrive le impostazioni di ogni file.

File di progetto

Le impostazioni progetto globali si trovano nel file project.lightbuild.yaml nella directory root del progetto. Ad esempio:

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"

La tabella seguente descrive queste impostazioni:

Impostazione Descrizione
project.name Il nome del progetto, ad esempio MyApp. Android Studio mostra questo nome come radice della finestra Project (Progetto). Come rootProject.name in Kotlin DSL, è separato dal nome e dall'ID applicazione della tua app.
modules I moduli del progetto, ad esempio il modulo dell'app (app) e i moduli della libreria (app-core).
repositories I repository remoti da cui Lightbuild risolve le dipendenze. Per maggiori dettagli, vedi Repository.
lightbuild.version La versione di Lightbuild utilizzata dal progetto.
build.kotlin.version La versione di Kotlin utilizzata dal progetto.
build.java.version La versione del compilatore Java richiesta dal progetto.
build.jvmTarget La versione target del bytecode JVM generato.

Repository

Utilizza repositories per elencare i repository da cui Lightbuild risolve le dipendenze. Puoi elencare i repository google e mavenCentral integrati e aggiungere repository Maven personalizzati con maven:

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

Un repository maven ha le seguenti impostazioni:

Impostazione Descrizione
name Un nome per il repository.
url L'URL del repository.
credentials Facoltativo. Le chiavi che mappano il nome utente e la password del repository nel file local.properties. Per maggiori dettagli, consulta Credenziali del repository.

Credenziali del repository

Se un repository Maven richiede un nome utente e una password, aggiungi un blocco credentials al repository. I valori username e password non sono le credenziali stesse, ma sono chiavi che definisci nel file local.properties del tuo progetto:

repositories:

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

Poi, nel file local.properties del progetto, mappa ogni chiave al relativo valore. Sostituisci REPO_USERNAME e REPO_PASSWORD con le tue credenziali:

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

File del modulo

Ogni modulo ha un file lightbuild.yaml nella propria directory che definisce le impostazioni del modulo. La tabella seguente descrive le impostazioni di primo livello:

Impostazione Descrizione
platform La piattaforma scelta come target del modulo: android.
type Il tipo di modulo: application per un modulo dell'app o library per un modulo della libreria. Per saperne di più, consulta Struttura del progetto Lightbuild.
optionalFeatures Funzionalità facoltative da attivare per il modulo, ad esempio com.android.tools.lightbuild.protobuf per il supporto dei buffer di protocollo. Per maggiori dettagli, consulta Buffer di protocollo.
android Le impostazioni Android del modulo. Per maggiori dettagli, consulta Impostazioni di Android.

Impostazioni di Android

Il blocco android contiene le impostazioni di build Android del modulo:

Impostazione Descrizione
namespace Lo spazio dei nomi del modulo. Per saperne di più, consulta Imposta lo spazio dei nomi.
compileSdk Il livello API con cui viene compilato il modulo. Per maggiori dettagli, consulta Versioni dell'SDK.
minSdk Il livello API minimo supportato dal modulo.
targetSdk Il livello API scelto come target dall'app. Supportato solo nei moduli dell'app.
applicationId L'ID applicazione dell'app. Imposta nei moduli dell'app.
versionCode Il codice versione dell'app. Imposta nei moduli dell'app.
versionName Il nome della versione dell'app. Imposta nei moduli dell'app.
packaging Impostazioni per il pacchetto delle build debug e release dell'app, ad esempio la firma della release. Supportato solo nel modulo dell'app. Per maggiori dettagli, vedi Packaging.
dependencies Le dipendenze del modulo da altri moduli e da librerie esterne. Per maggiori dettagli, consulta Dipendenze.
kspProcessors I processori KSP che generano il codice per il modulo. Per maggiori dettagli, consulta Processori KSP.
tests I test locali e di instrumentazione del modulo. Per maggiori dettagli, vedi Test.

Versioni SDK

Specifica le impostazioni compileSdk, minSdk e targetSdk come livelli API in version.release.apiLevel. Ad esempio, le seguenti impostazioni compilano il modulo per il livello API 36, supportano il livello API 24 e versioni successive e hanno come livello API target il livello API 36:

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

Solo i moduli dell'app supportano l'impostazione targetSdk. I moduli della libreria definiscono solo le impostazioni compileSdk e minSdk.

Dipendenze

Dichiara le dipendenze di un modulo nel blocco dependencies:

  • module: altri moduli del progetto, scritti come // seguito dal nome del modulo, ad esempio //app-core o //features/search.
  • maven: librerie esterne, scritte come coordinate Maven nel formato group:artifact:version.

Ad esempio, le seguenti impostazioni aggiungono dipendenze al modulo app-core e alla libreria AndroidX Core KTX:

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

Impostazioni delle dipendenze

Per impostazione predefinita, un modulo viene compilato in base a ciascuna delle sue dipendenze e le include in fase di runtime, ma non le espone ai moduli che dipendono da esso. Per modificare il modo in cui un modulo utilizza una dipendenza, aggiungi i due punti dopo la dipendenza, quindi aggiungi l'impostazione compile, l'impostazione runtime o entrambe sotto:

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

In questo esempio, i moduli che dipendono da questo modulo possono utilizzare anche le classi del modulo data. La libreria Jetpack Annotation viene utilizzata solo per compilare questo modulo. Core KTX utilizza le impostazioni predefinite.

L'impostazione compile controlla quali moduli vengono compilati in base alla dipendenza:

  • private (predefinito): questo modulo viene compilato in base alla dipendenza, ma i moduli che dipendono da questo modulo no.
  • public: questo modulo e i moduli che dipendono da questo vengono compilati in base alla dipendenza. Utilizza public quando l'API pubblica del tuo modulo utilizza tipi della dipendenza.
  • off: questo modulo non viene compilato in base alla dipendenza.

L'impostazione runtime controlla se la dipendenza è disponibile in fase di runtime:

  • public (predefinito): la dipendenza è disponibile in fase di runtime per questo modulo e per i moduli che dipendono da questo.
  • off: la dipendenza non è disponibile in fase di runtime. Utilizza off per le dipendenze necessarie al tuo codice solo in tempo di compilazione, ad esempio le annotazioni.

compile e runtime non possono essere entrambi off. Nelle dipendenze di test, compile può essere solo private o off.

Per vedere come queste impostazioni corrispondono alle configurazioni DSL di Kotlin come api e compileOnly, consulta Confronta Lightbuild con Kotlin DSL.

Processori KSP

Per utilizzare un generatore di codice basato su Kotlin Symbol Processing (KSP), come Moshi o Room, aggiungi il processore al blocco kspProcessors e aggiungi le librerie utilizzate dal codice in fase di runtime al blocco dependencies. Lightbuild applica automaticamente il plug-in KSP e configura la generazione del codice durante la build.

Ad esempio, le seguenti impostazioni configurano Moshi con il relativo generatore di codice KSP:

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

Buffer di protocollo

Per generare codice dai file buffer di protocollo (.proto) in un modulo della libreria, aggiungi la funzionalità buffer di protocollo all'elenco optionalFeatures del modulo e aggiungi le librerie di runtime dei buffer di protocollo alle dipendenze del modulo. optionalFeatures è un'impostazione di primo livello, esterna al blocco 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

Inserisci i file .proto del modulo nella directory src/main/proto. Quando crei il modulo, Lightbuild genera classi Java e Kotlin per il runtime lite dei buffer di protocollo, consigliato per Android.

Test

Configura i test di un modulo nel blocco tests:

  • test: test locali eseguiti sulla JVM della macchina di sviluppo. Elenca le dipendenze dei test in dependencies.
  • androidTest: test strumentati eseguiti su un dispositivo o un emulatore. Imposta runner sulla classe del test runner ed elenca le dipendenze dei test in dependencies.

Ad esempio:

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

Imballaggio

Nei moduli dell'app, utilizza il blocco packaging per configurare le build debug e release dell'app. Per firmare la build di release con la tua chiave, aggiungi un blocco signing al profilo release:

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

Il blocco signing supporta le seguenti impostazioni:

  • storeFile: il percorso del file del keystore, relativo alla directory del modulo o che inizia con ~/ per una posizione nella tua home directory.
  • storePassword: la password del keystore.
  • keyAlias: l'alias della chiave di firma nel keystore.
  • keyPassword: la password della chiave di firma.

Per evitare che le password vengano inserite nei file del progetto, imposta questi valori sui riferimenti alle variabili di ambiente con la sintassi ${NAME}, come nell'esempio. Puoi scrivere direttamente storeFile e keyAlias o fare riferimento alle variabili di ambiente anche per questi valori. Durante la build, Lightbuild sostituisce ogni riferimento con il valore della variabile di ambiente. Ogni valore deve contenere solo il riferimento: Lightbuild non sostituisce un riferimento che fa parte di un valore più lungo, ad esempio ${HOME}/upload-keystore.jks.

Esempi

I seguenti esempi mostrano i file dei moduli completi per un modulo dell'app e un modulo della libreria.

Modulo dell'app

Il seguente file app/lightbuild.yaml configura un modulo dell'app che dipende dal modulo della libreria 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

Modulo Libreria

Il seguente file app-core/lightbuild.yaml configura un modulo della libreria che utilizza Jetpack Compose e Moshi e contiene test locali e di instrumentazione:

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