Documentation de référence sur la configuration de Lightbuild

La configuration de compilation d'un projet Lightbuild se compose de fichiers YAML : un fichier project.lightbuild.yaml dans le répertoire racine du projet et un fichier lightbuild.yaml dans chaque module. Cette page décrit les paramètres de chaque fichier.

Fichier de projet

Les paramètres globaux du projet se trouvent dans le fichier project.lightbuild.yaml du répertoire racine de votre projet. Exemple :

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"

Le tableau suivant décrit ces paramètres :

Paramètre Description
project.name Nom du projet, par exemple MyApp. Android Studio affiche ce nom à la racine de la fenêtre Project (Projet). Comme rootProject.name dans le DSL Kotlin, il est distinct du nom et de l'ID d'application de votre application.
modules Les modules du projet, tels que le module d'application (app) et les modules de bibliothèque (app-core).
repositories Dépôts distants à partir desquels Lightbuild résout les dépendances. Pour en savoir plus, consultez Dépôts.
lightbuild.version Version de Lightbuild utilisée par le projet.
build.kotlin.version Version de Kotlin utilisée par le projet.
build.java.version Version du compilateur Java requise par le projet.
build.jvmTarget Version cible du bytecode JVM généré.

Dépôts

Utilisez repositories pour lister les dépôts à partir desquels Lightbuild résout les dépendances. Vous pouvez lister les dépôts google et mavenCentral intégrés, et ajouter des dépôts Maven personnalisés avec maven :

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

Un dépôt maven possède les paramètres suivants :

Paramètre Description
name Nom du dépôt.
url URL du dépôt.
credentials Facultatif. Clés qui correspondent au nom d'utilisateur et au mot de passe du dépôt dans votre fichier local.properties. Pour en savoir plus, consultez Identifiants du dépôt.

Identifiants du dépôt

Si un dépôt Maven nécessite un nom d'utilisateur et un mot de passe, ajoutez un bloc credentials au dépôt. Les valeurs username et password ne sont pas les identifiants eux-mêmes. Ce sont des clés que vous définissez dans le fichier local.properties de votre projet :

repositories:

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

Ensuite, dans le fichier local.properties de votre projet, mappez chaque clé à sa valeur. Remplacez REPO_USERNAME et REPO_PASSWORD par vos identifiants :

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

Fichiers de module

Chaque module possède un fichier lightbuild.yaml dans son répertoire qui définit les paramètres du module. Le tableau suivant décrit les paramètres de premier niveau :

Paramètre Description
platform La plate-forme ciblée par le module : android.
type Type de module : application pour un module d'application ou library pour un module de bibliothèque. Pour en savoir plus, consultez Structure d'un projet Lightbuild.
optionalFeatures Fonctionnalités facultatives à activer pour le module, telles que com.android.tools.lightbuild.protobuf pour la compatibilité avec les tampons de protocole. Pour en savoir plus, consultez Tampons de protocole.
android Paramètres Android du module. Pour en savoir plus, consultez Paramètres Android.

Paramètres Android

Le bloc android contient les paramètres de compilation Android du module :

Paramètre Description
namespace Espace de noms du module. Pour en savoir plus, consultez Définir l'espace de noms.
compileSdk Niveau d'API sur lequel le module est compilé. Pour en savoir plus, consultez Versions du SDK.
minSdk Niveau d'API minimal accepté par le module.
targetSdk Niveau d'API ciblé par l'application. Compatible uniquement avec les modules d'application.
applicationId ID d'application de l'application. Définissez-les dans les modules d'application.
versionCode Code de version de l'application. Définissez-les dans les modules d'application.
versionName Nom de la version de l'application. Définissez-les dans les modules d'application.
packaging Paramètres d'empaquetage des builds debug et release de l'application, tels que la signature de la version. Compatible uniquement avec le module d'application. Pour en savoir plus, consultez Packaging.
dependencies Les dépendances du module vis-à-vis d'autres modules et de bibliothèques externes. Pour en savoir plus, consultez Dépendances.
kspProcessors Processeurs KSP qui génèrent du code pour le module. Pour en savoir plus, consultez Processeurs KSP.
tests Les tests locaux et d'instrumentation du module. Pour en savoir plus, consultez Tests.

Versions du SDK

Spécifiez les paramètres compileSdk, minSdk et targetSdk en tant que niveaux d'API sous version.release.apiLevel. Par exemple, les paramètres suivants compilent le module pour le niveau d'API 36, prennent en charge le niveau d'API 24 et supérieur, et ciblent le niveau d'API 36 :

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

Seuls les modules d'application sont compatibles avec le paramètre targetSdk. Les modules de bibliothèque ne définissent que les paramètres compileSdk et minSdk.

Dépendances

Déclarez les dépendances d'un module dans le bloc dependencies :

  • module : autres modules de votre projet, écrits sous la forme // suivi du nom du module, par exemple //app-core ou //features/search.
  • maven : bibliothèques externes, écrites sous forme de coordonnées Maven au format group:artifact:version.

Par exemple, les paramètres suivants ajoutent des dépendances au module app-core et à la bibliothèque AndroidX Core KTX :

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

Paramètres de dépendance

Par défaut, un module compile chacune de ses dépendances et les inclut au moment de l'exécution, mais ne les expose pas aux modules qui en dépendent. Pour modifier la façon dont un module utilise une dépendance, ajoutez un deux-points après la dépendance, puis ajoutez le paramètre compile, le paramètre runtime ou les deux en dessous :

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

Dans cet exemple, les modules qui dépendent de ce module peuvent également utiliser les classes du module data. La bibliothèque Jetpack Annotation n'est utilisée que pour compiler ce module. Core KTX utilise les paramètres par défaut.

Le paramètre compile contrôle les modules qui sont compilés par rapport à la dépendance :

  • private (par défaut) : ce module est compilé par rapport à la dépendance, mais pas les modules qui en dépendent.
  • public : ce module et les modules qui en dépendent sont compilés par rapport à la dépendance. Utilisez public lorsque l'API publique de votre module utilise des types de la dépendance.
  • off : ce module ne se compile pas avec la dépendance.

Le paramètre runtime détermine si la dépendance est disponible au moment de l'exécution :

  • public (par défaut) : la dépendance est disponible au moment de l'exécution, pour ce module et pour les modules qui en dépendent.
  • off : la dépendance n'est pas disponible au moment de l'exécution. Utilisez off pour les dépendances dont votre code n'a besoin qu'au moment de la compilation, telles que les annotations.

compile et runtime ne peuvent pas être tous les deux définis sur off. Dans les dépendances de test, compile ne peut être que private ou off.

Pour voir comment ces paramètres correspondent aux configurations DSL Kotlin telles que api et compileOnly, consultez Comparer Lightbuild avec le DSL Kotlin.

Processeurs KSP

Pour utiliser un générateur de code basé sur le traitement des symboles Kotlin (KSP), tel que Moshi ou Room, ajoutez le processeur au bloc kspProcessors et ajoutez les bibliothèques que votre code utilise au moment de l'exécution au bloc dependencies. Lightbuild applique automatiquement le plug-in KSP et configure la génération de code pendant la compilation.

Par exemple, les paramètres suivants configurent Moshi avec son générateur de code 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

Tampons de protocole

Pour générer du code à partir de fichiers de tampons de protocole (.proto) dans un module de bibliothèque, ajoutez la fonctionnalité de tampons de protocole à la liste optionalFeatures du module, puis ajoutez les bibliothèques d'exécution de tampons de protocole aux dépendances du module. optionalFeatures est un paramètre de premier niveau, en dehors du bloc 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

Placez les fichiers .proto du module dans son répertoire src/main/proto. Lorsque vous compilez le module, Lightbuild génère des classes Java et Kotlin pour l'environnement d'exécution Protocol Buffers Lite, qui est recommandé pour Android.

Tests

Configurez les tests d'un module dans le bloc tests :

  • test : tests locaux qui s'exécutent sur la JVM de votre ordinateur de développement. Répertoriez les dépendances des tests sous dependencies.
  • androidTest : tests d'instrumentation qui s'exécutent sur un appareil ou un émulateur. Définissez runner sur la classe du lanceur de test, puis listez les dépendances des tests sous dependencies.

Exemple :

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

Packaging

Dans les modules d'application, utilisez le bloc packaging pour configurer les builds debug et release de l'application. Pour signer votre build de release avec votre propre clé, ajoutez un bloc signing au profil release :

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

Le bloc signing accepte les paramètres suivants :

  • storeFile : chemin d'accès au fichier keystore, relatif au répertoire du module ou commençant par ~/ pour un emplacement dans votre répertoire d'accueil.
  • storePassword : mot de passe du keystore.
  • keyAlias : alias de la clé de signature dans le keystore.
  • keyPassword : mot de passe de la clé de signature.

Pour que vos mots de passe ne figurent pas dans les fichiers de votre projet, définissez ces valeurs sur des références de variables d'environnement avec la syntaxe ${NAME}, comme dans l'exemple. Vous pouvez écrire storeFile et keyAlias directement, ou référencer des variables d'environnement pour eux également. Lors de la compilation, Lightbuild remplace chaque référence par la valeur de la variable d'environnement. Chaque valeur ne doit contenir que la référence : Lightbuild ne remplace pas une référence qui fait partie d'une valeur plus longue, comme ${HOME}/upload-keystore.jks.

Exemples

Les exemples suivants montrent des fichiers de module complets pour un module d'application et un module de bibliothèque.

Module d'application

Le fichier app/lightbuild.yaml suivant configure un module d'application qui dépend du module de bibliothèque 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

Module de bibliothèque

Le fichier app-core/lightbuild.yaml suivant configure un module de bibliothèque qui utilise Jetpack Compose et Moshi, et contient des tests locaux et d'instrumentation :

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