Lightbuild-Konfigurationsreferenz

Die Build-Konfiguration eines Lightbuild-Projekts besteht aus YAML-Dateien: einer project.lightbuild.yaml-Datei im Stammverzeichnis des Projekts und einer lightbuild.yaml-Datei in jedem Modul. Auf dieser Seite werden die Einstellungen in den einzelnen Dateien beschrieben.

Projektdatei

Globale Projekteinstellungen befinden sich in der Datei project.lightbuild.yaml im Stammverzeichnis Ihres Projekts. Beispiel:

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"

In der folgenden Tabelle werden diese Einstellungen beschrieben:

Einstellung Beschreibung
project.name Der Name des Projekts, z. B. MyApp. Android Studio zeigt diesen Namen als Stammverzeichnis des Fensters Project an. Wie rootProject.name in Kotlin DSL ist er vom Namen und der Anwendungs-ID Ihrer App getrennt.
modules Die Module im Projekt, z. B. das App-Modul (app) und Bibliotheksmodule (app-core).
repositories Die Remote-Repositories, aus denen Lightbuild Abhängigkeiten auflöst. Weitere Informationen finden Sie unter Repositories.
lightbuild.version Die Lightbuild-Version, die das Projekt verwendet.
build.kotlin.version Die vom Projekt verwendete Kotlin-Version.
build.java.version Die vom Projekt benötigte Java-Compiler-Version.
build.jvmTarget Die Zielversion des generierten JVM-Bytecodes.

Repositories

Verwenden Sie repositories, um die Repositories aufzulisten, aus denen Lightbuild Abhängigkeiten auflöst. Sie können die integrierten google- und mavenCentral-Repositories auflisten und benutzerdefinierte Maven-Repositories mit maven hinzufügen:

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

Ein maven-Repository hat die folgenden Einstellungen:

Einstellung Beschreibung
name Einen Namen für das Repository.
url Die URL des Repositorys.
credentials Optional. Die Schlüssel, die dem Nutzernamen und dem Passwort des Repositorys in Ihrer local.properties-Datei zugeordnet sind. Weitere Informationen finden Sie unter Repository-Anmeldedaten.

Repository-Anmeldedaten

Wenn für ein Maven-Repository ein Nutzername und ein Passwort erforderlich sind, fügen Sie dem Repository einen credentials-Block hinzu. Die Werte username und password sind nicht die Anmeldedaten selbst, sondern Schlüssel, die Sie in der Datei local.properties Ihres Projekts definieren:

repositories:

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

Ordnen Sie dann in der local.properties-Datei Ihres Projekts jedem Schlüssel den entsprechenden Wert zu. Ersetzen Sie REPO_USERNAME und REPO_PASSWORD durch Ihre Anmeldedaten:

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

Moduldateien

Jedes Modul hat eine lightbuild.yaml-Datei in seinem Verzeichnis, in der die Einstellungen des Moduls definiert sind. In der folgenden Tabelle werden die Einstellungen auf oberster Ebene beschrieben:

Einstellung Beschreibung
platform Die Plattform, auf die das Modul ausgerichtet ist: android.
type Der Modultyp: application für ein App-Modul oder library für ein Bibliotheksmodul. Weitere Informationen finden Sie unter Lightbuild-Projektstruktur.
optionalFeatures Optionale Features, die für das Modul aktiviert werden sollen, z. B. com.android.tools.lightbuild.protobuf für die Unterstützung von Protokollzwischenspeichern. Weitere Informationen finden Sie unter Protokollzwischenspeicher.
android Die Android-Einstellungen des Moduls. Weitere Informationen finden Sie unter Android-Einstellungen.

Android-Einstellungen

Der Block android enthält die Android-Build-Einstellungen des Moduls:

Einstellung Beschreibung
namespace Der Namespace des Moduls. Weitere Informationen finden Sie unter Namespace festlegen.
compileSdk Das API-Level, für das das Modul kompiliert wird. Weitere Informationen finden Sie unter SDK-Versionen.
minSdk Das minimale API-Level, das vom Modul unterstützt wird.
targetSdk Das API-Level, auf das die App ausgerichtet ist. Wird nur in App-Modulen unterstützt.
applicationId Die Anwendungs-ID der App. In App-Modulen festlegen.
versionCode Der Versionscode der App. In App-Modulen festlegen.
versionName Der Versionsname der App. In App-Modulen festlegen.
packaging Einstellungen für das Verpacken der debug- und release-Builds der App, z. B. die Signatur des Releases. Wird nur im App-Modul unterstützt. Weitere Informationen finden Sie unter Verpackung.
dependencies Die Abhängigkeiten des Moduls von anderen Modulen und externen Bibliotheken. Weitere Informationen finden Sie unter Abhängigkeiten.
kspProcessors Die KSP-Prozessoren, die Code für das Modul generieren. Weitere Informationen finden Sie unter KSP-Prozessoren.
tests Die lokalen und Instrumentierungstests des Moduls. Weitere Informationen finden Sie unter Tests.

SDK-Versionen

Geben Sie die Einstellungen compileSdk, minSdk und targetSdk als API-Level unter version.release.apiLevel an. Mit den folgenden Einstellungen wird das Modul beispielsweise für API-Level 36 kompiliert, API-Level 24 und höher unterstützt und auf API-Level 36 ausgerichtet:

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

Die Einstellung targetSdk wird nur von App-Modulen unterstützt. In Bibliotheksmodulen werden nur die Einstellungen compileSdk und minSdk definiert.

Abhängigkeiten

Deklarieren Sie die Abhängigkeiten eines Moduls im Block dependencies:

  • module: Andere Module in Ihrem Projekt, geschrieben als //, gefolgt vom Namen des Moduls, z. B. //app-core oder //features/search.
  • maven: Externe Bibliotheken, geschrieben als Maven-Koordinaten im Format group:artifact:version.

Mit den folgenden Einstellungen werden beispielsweise Abhängigkeiten vom app-core-Modul und von der AndroidX Core KTX-Bibliothek hinzugefügt:

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

Abhängigkeitseinstellungen

Standardmäßig wird ein Modul mit jeder seiner Abhängigkeiten kompiliert und diese werden zur Laufzeit einbezogen, aber nicht für die Module verfügbar gemacht, die von ihm abhängen. Wenn Sie ändern möchten, wie ein Modul eine Abhängigkeit verwendet, fügen Sie nach der Abhängigkeit einen Doppelpunkt und dann darunter die Einstellung compile, die Einstellung runtime oder beide hinzu:

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

In diesem Beispiel können Module, die von diesem Modul abhängen, auch die Klassen des Moduls data verwenden. Die Jetpack Annotation-Bibliothek wird nur zum Kompilieren dieses Moduls verwendet. Core KTX verwendet die Standardeinstellungen.

Mit der Einstellung compile wird gesteuert, welche Module mit der Abhängigkeit kompiliert werden:

  • private (Standard): Dieses Modul wird mit der Abhängigkeit kompiliert, die Module, die von diesem Modul abhängen, jedoch nicht.
  • public: Dieses Modul und die davon abhängigen Module werden mit der Abhängigkeit kompiliert. Verwenden Sie public, wenn die öffentliche API Ihres Moduls Typen aus der Abhängigkeit verwendet.
  • off: Dieses Modul wird nicht mit der Abhängigkeit kompiliert.

Mit der Einstellung runtime wird festgelegt, ob die Abhängigkeit zur Laufzeit verfügbar ist:

  • public (Standard): Die Abhängigkeit ist zur Laufzeit für dieses Modul und für die Module verfügbar, die davon abhängen.
  • off: Die Abhängigkeit ist zur Laufzeit nicht verfügbar. Verwenden Sie off für Abhängigkeiten, die Ihr Code nur zur Kompilierzeit benötigt, z. B. Annotationen.

compile und runtime können nicht beide off sein. In Testabhängigkeiten kann compile nur private oder off sein.

Informationen dazu, wie diese Einstellungen mit Kotlin DSL-Konfigurationen wie api und compileOnly übereinstimmen, finden Sie unter Lightbuild mit Kotlin DSL vergleichen.

KSP-Prozessoren

Wenn Sie einen Codegenerator verwenden möchten, der auf Kotlin Symbol Processing (KSP) basiert, z. B. Moshi oder Room, fügen Sie den Prozessor dem Block kspProcessors und die Bibliotheken, die Ihr Code zur Laufzeit verwendet, dem Block dependencies hinzu. Lightbuild wendet das KSP-Plug-in automatisch an und konfiguriert die Codegenerierung während des Builds.

Mit den folgenden Einstellungen wird beispielsweise Moshi mit dem KSP-Codegenerator konfiguriert:

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

Protokollpuffer

Wenn Sie Code aus Protokollzwischenspeicher-Dateien (.proto) in einem Bibliotheksmodul generieren möchten, fügen Sie die Protokollzwischenspeicher-Funktion der optionalFeatures-Liste des Moduls hinzu und fügen Sie die Protokollzwischenspeicher-Laufzeitbibliotheken den Abhängigkeiten des Moduls hinzu. optionalFeatures ist eine Einstellung auf oberster Ebene außerhalb des Blocks 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

Legen Sie die .proto-Dateien des Moduls in seinem src/main/proto-Verzeichnis ab. Wenn Sie das Modul erstellen, generiert Lightbuild Java- und Kotlin-Klassen für die Protocol Buffers Lite-Laufzeit, die für Android empfohlen wird.

Tests

Konfigurieren Sie die Tests eines Moduls im Block tests:

  • test: Lokale Tests, die auf der JVM Ihrer Entwicklungsmaschine ausgeführt werden. Listen Sie die Abhängigkeiten der Tests unter dependencies auf.
  • androidTest: Instrumentierte Tests, die auf einem Gerät oder Emulator ausgeführt werden. Legen Sie für runner die Test Runner-Klasse fest und listen Sie die Abhängigkeiten der Tests unter dependencies auf.

Beispiel:

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

Videoaufmachung

Verwenden Sie in App-Modulen den Block packaging, um die debug- und release-Builds der App zu konfigurieren. Wenn Sie Ihren Release-Build mit Ihrem eigenen Schlüssel signieren möchten, fügen Sie dem release-Profil einen signing-Block hinzu:

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

Der Block signing unterstützt die folgenden Einstellungen:

  • storeFile: Der Pfad zur Schlüsselspeicherdatei, entweder relativ zum Verzeichnis des Moduls oder beginnend mit ~/ für einen Speicherort in Ihrem Basisverzeichnis.
  • storePassword: Das Passwort des Schlüsselspeichers.
  • keyAlias: Der Alias des Signaturschlüssels im Schlüsselspeicher.
  • keyPassword: Das Passwort des Signaturschlüssels.

Damit Ihre Passwörter nicht in den Dateien Ihres Projekts gespeichert werden, legen Sie diese Werte wie im Beispiel als Verweise auf Umgebungsvariablen mit der Syntax ${NAME} fest. Sie können storeFile und keyAlias direkt schreiben oder auch Umgebungsvariablen dafür referenzieren. Beim Erstellen ersetzt Lightbuild jede Referenz durch den Wert der Umgebungsvariablen. Jeder Wert darf nur die Referenz enthalten: Lightbuild ersetzt keine Referenz, die Teil eines längeren Werts ist, z. B. ${HOME}/upload-keystore.jks.

Beispiele

Die folgenden Beispiele zeigen vollständige Moduldateien für ein App-Modul und ein Bibliotheksmodul.

App-Modul

In der folgenden app/lightbuild.yaml-Datei wird ein App-Modul konfiguriert, das vom Bibliotheksmodul app-core abhängt:

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 „Bibliothek“

In der folgenden app-core/lightbuild.yaml-Datei wird ein Bibliotheksmodul konfiguriert, das Jetpack Compose und Moshi verwendet und lokale und Instrumentierungstests enthält:

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