Dokumentacja konfiguracji Lightbuild

Konfiguracja kompilacji projektu Lightbuild składa się z plików YAML: pliku project.lightbuild.yaml w katalogu głównym projektu i pliku lightbuild.yaml w każdym module. Na tej stronie opisujemy ustawienia w każdym pliku.

Plik projektu

Globalne ustawienia projektu znajdują się w pliku project.lightbuild.yaml w katalogu głównym projektu. Przykład:

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"

W tabeli poniżej znajdziesz opis tych ustawień:

Ustawienie Opis
project.name Nazwa projektu, np. MyApp. Android Studio wyświetla tę nazwę jako katalog główny okna Projekt. Podobnie jak rootProject.name w Kotlin DSL, jest on oddzielony od nazwy i identyfikatora aplikacji.
modules Moduły w projekcie, takie jak moduł aplikacji (app) i moduły biblioteki (app-core).
repositories Zdalne repozytoria, z których Lightbuild pobiera zależności. Więcej informacji znajdziesz w sekcji Repozytoria.
lightbuild.version Wersja Lightbuild używana przez projekt.
build.kotlin.version Wersja Kotlina używana w projekcie.
build.java.version Wersja kompilatora Java wymagana przez projekt.
build.jvmTarget Wersja docelowa wygenerowanego kodu bajtowego JVM.

Repozytoria

Użyj repositories, aby wyświetlić listę repozytoriów, z których Lightbuild pobiera zależności. Możesz wyświetlić listę wbudowanych repozytoriów google i mavenCentral oraz dodać niestandardowe repozytoria Maven za pomocą maven:

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

Repozytorium maven ma te ustawienia:

Ustawienie Opis
name Nazwa repozytorium.
url URL repozytorium.
credentials Opcjonalnie: Klucze, które są mapowane na nazwę użytkownika i hasło repozytorium w pliku local.properties. Więcej informacji znajdziesz w artykule Dane logowania do repozytorium.

Dane uwierzytelniające do repozytorium

Jeśli repozytorium Maven wymaga nazwy użytkownika i hasła, dodaj do niego blok credentials. Wartości username i password nie są danymi logowania, ale kluczami, które definiujesz w pliku local.properties projektu:

repositories:

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

Następnie w pliku local.properties projektu zmapuj każdy klucz na jego wartość. Zastąp REPO_USERNAME i REPO_PASSWORD swoimi danymi logowania:

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

Pliki modułu

Każdy moduł ma w swoim katalogu plik lightbuild.yaml, który definiuje ustawienia modułu. W tabeli poniżej opisano ustawienia najwyższego poziomu:

Ustawienie Opis
platform Platforma, na którą kierowany jest moduł: android.
type Typ modułu: application w przypadku modułu aplikacji lub library w przypadku modułu biblioteki. Więcej informacji znajdziesz w artykule o strukturze projektu Lightbuild.
optionalFeatures Opcjonalne funkcje, które można włączyć w module, np. com.android.tools.lightbuild.protobuf do obsługi buforów protokołu. Więcej informacji znajdziesz w artykule Bufory protokołu.
android Ustawienia modułu na Androidzie. Szczegółowe informacje znajdziesz w artykule Ustawienia Androida.

Ustawienia Androida

Blok android zawiera ustawienia kompilacji modułu na Androida:

Ustawienie Opis
namespace Przestrzeń nazw modułu. Więcej informacji znajdziesz w artykule o ustawianiu przestrzeni nazw.
compileSdk Poziom interfejsu API, pod kątem którego kompilowany jest moduł. Więcej informacji znajdziesz w sekcji Wersje pakietu SDK.
minSdk Minimalny poziom interfejsu API obsługiwany przez moduł.
targetSdk Poziom interfejsu API, na który kierowana jest aplikacja. Obsługiwane tylko w modułach aplikacji.
applicationId Identyfikator aplikacji. Ustaw w modułach aplikacji.
versionCode Kod wersji aplikacji. Ustaw w modułach aplikacji.
versionName Nazwa wersji aplikacji. Ustaw w modułach aplikacji.
packaging Ustawienia pakowania kompilacji debug i release aplikacji, takie jak podpisywanie wersji. Obsługiwane tylko w module aplikacji. Szczegółowe informacje znajdziesz w sekcji Opakowanie.
dependencies zależności modułu od innych modułów i bibliotek zewnętrznych; Więcej informacji znajdziesz w sekcji Zależności.
kspProcessors Procesory KSP, które generują kod dla modułu. Więcej informacji znajdziesz w artykule o procesorach KSP.
tests Testy lokalne i testy z instrumentacją modułu. Więcej informacji znajdziesz w sekcji Testy.

Wersje pakietu SDK

Określ ustawienia compileSdk, minSdk i targetSdk jako poziomy interfejsu API w version.release.apiLevel. Na przykład te ustawienia kompilują moduł na poziomie interfejsu API 36, obsługują poziom interfejsu API 24 i wyższy oraz są kierowane na poziom interfejsu API 36:

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

Tylko moduły aplikacji obsługują ustawienie targetSdk. Moduły biblioteki definiują tylko ustawienia compileSdk i minSdk.

Zależności

Zadeklaruj zależności modułu w bloku dependencies:

  • module: inne moduły w projekcie, zapisane jako //, po którym następuje nazwa modułu, na przykład //app-core lub //features/search.
  • maven: biblioteki zewnętrzne zapisane jako współrzędne Maven w formacie group:artifact:version.

Na przykład te ustawienia dodają zależności od modułu app-core i biblioteki AndroidX Core KTX:

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

Ustawienia zależności

Domyślnie moduł kompiluje się z każdą ze swoich zależności i uwzględnia je w czasie działania, ale nie udostępnia ich modułom, które od niego zależą. Aby zmienić sposób, w jaki moduł używa zależności, dodaj po niej dwukropek, a następnie ustawienie compile, ustawienie runtime lub oba te ustawienia:

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

W tym przykładzie moduły, które zależą od tego modułu, mogą też używać klas modułu data. Biblioteka Jetpack Annotation jest używana tylko do kompilowania tego modułu. Core KTX używa ustawień domyślnych.

Ustawienie compile określa, które moduły są kompilowane z zależnością:

  • private (domyślna): ten moduł kompiluje się z zależnością, ale moduły, które od niego zależą, nie.
  • public: ten moduł i moduły, które od niego zależą, są kompilowane z uwzględnieniem zależności. Użyj public, gdy publiczny interfejs API modułu używa typów z zależności.
  • off: ten moduł nie kompiluje się z zależnością.

Ustawienie runtime określa, czy zależność jest dostępna w czasie działania:

  • public (domyślna): zależność jest dostępna w czasie działania dla tego modułu i modułów, które od niego zależą.
  • off: zależność jest niedostępna w czasie działania. Używaj off w przypadku zależności, których Twój kod potrzebuje tylko w czasie kompilowania, takich jak adnotacje.

compile i runtime nie mogą mieć wartości off. W zależnościach testowych compile może być tylko private lub off.

Aby dowiedzieć się, jak te ustawienia odpowiadają konfiguracjom DSL w Kotlin, takim jak api i compileOnly, przeczytaj artykuł Porównanie Lightbuild z Kotlin DSL.

Procesory KSP

Aby użyć generatora kodu opartego na Kotlin Symbol Processing (KSP), takiego jak Moshi lub Room, dodaj procesor do bloku kspProcessors, a biblioteki, których kod używa w czasie działania, do bloku dependencies. Lightbuild automatycznie stosuje wtyczkę KSP i konfiguruje generowanie kodu podczas kompilacji.

Na przykład te ustawienia konfigurują Moshi z generatorem kodu 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

Bufory protokołu

Aby wygenerować kod z plików buforów protokołu (.proto) w module biblioteki, dodaj funkcję buforów protokołu do listy optionalFeatures modułu i dodaj biblioteki środowiska wykonawczego buforów protokołu do zależności modułu. optionalFeatures to ustawienie najwyższego poziomu, poza blokiem 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

Umieść pliki .proto modułu w jego katalogu src/main/proto. Podczas tworzenia modułu Lightbuild generuje klasy Java i Kotlin dla środowiska wykonawczego Protocol Buffers Lite, które jest zalecane w przypadku Androida.

Testy

Skonfiguruj testy modułu w bloku tests:

  • test: testy lokalne, które są uruchamiane na maszynie JVM komputera używanego do programowania. Wymień zależności testów w sekcji dependencies.
  • androidTest: testy instrumentowane, które są uruchamiane na urządzeniu lub emulatorze. Ustaw runner na klasę modułu uruchamiającego testy i wymień zależności testów w sekcji dependencies.

Przykład:

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

Sposób prezentacji

W modułach aplikacji użyj bloku packaging, aby skonfigurować kompilacje debug i release aplikacji. Aby podpisać kompilację do publikacji własnym kluczem, dodaj blok signing do profilu release:

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

Blok signing obsługuje te ustawienia:

  • storeFile: ścieżka do pliku magazynu kluczy, względna do katalogu modułu lub zaczynająca się od ~/ w przypadku lokalizacji w katalogu domowym.
  • storePassword: hasło do magazynu kluczy.
  • keyAlias: alias klucza podpisywania w magazynie kluczy.
  • keyPassword: hasło klucza podpisywania.

Aby hasła nie znajdowały się w plikach projektu, ustaw te wartości na odwołania do zmiennych środowiskowych ze składnią ${NAME}, jak w przykładzie. Możesz wpisać storeFile i keyAlias bezpośrednio lub odwołać się do zmiennych środowiskowych. Podczas kompilacji Lightbuild zastępuje każde odwołanie wartością zmiennej środowiskowej. Każda wartość musi zawierać tylko odwołanie: Lightbuild nie zastępuje odwołania, które jest częścią dłuższej wartości, np. ${HOME}/upload-keystore.jks.

Przykłady

Poniższe przykłady pokazują pełne pliki modułów aplikacji i biblioteki.

Moduł aplikacji

Ten plik app/lightbuild.yaml konfiguruje moduł aplikacji, który zależy od modułu biblioteki 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

Moduł Biblioteka

Ten plik app-core/lightbuild.yaml konfiguruje moduł biblioteki, który używa Jetpack Compose i Moshi oraz zawiera testy lokalne i testy z instrumentacją:

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