Referencia de configuración de Lightbuild

La configuración de compilación de un proyecto de Lightbuild consta de archivos YAML: un archivo project.lightbuild.yaml en el directorio raíz del proyecto y un archivo lightbuild.yaml en cada módulo. En esta página, se describen los parámetros de configuración de cada archivo.

Archivo de proyecto

La configuración global del proyecto se encuentra en el archivo project.lightbuild.yaml del directorio raíz de tu proyecto. Por ejemplo:

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"

En la siguiente tabla, se describen estos parámetros de configuración:

Repositorios

Usa repositories para enumerar los repositorios de los que Lightbuild resuelve las dependencias. Puedes enumerar los repositorios integrados de google y mavenCentral, y agregar repositorios de Maven personalizados con maven:

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

Un repositorio de maven tiene los siguientes parámetros de configuración:

Credenciales del repositorio

Si un repositorio de Maven requiere un nombre de usuario y una contraseña, agrega un bloque credentials al repositorio. Los valores username y password no son las credenciales en sí, sino claves que defines en el archivo local.properties de tu proyecto:

repositories:

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

Luego, en el archivo local.properties de tu proyecto, asigna cada clave a su valor. Reemplaza REPO_USERNAME y REPO_PASSWORD por tus credenciales:

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

Archivos del módulo

Cada módulo tiene un archivo lightbuild.yaml en su directorio que define la configuración del módulo. En la siguiente tabla, se describen los parámetros de configuración de nivel superior:

Configuración de Android

El bloque android contiene la configuración de compilación de Android del módulo:

Versiones del SDK

Especifica los parámetros de configuración de compileSdk, minSdk y targetSdk como niveles de API en version.release.apiLevel. Por ejemplo, los siguientes parámetros de configuración compilan el módulo con el nivel de API 36, admiten el nivel de API 24 y versiones posteriores, y se orientan al nivel de API 36:

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

Solo los módulos de la app admiten el parámetro de configuración targetSdk. Los módulos de biblioteca solo definen los parámetros de configuración compileSdk y minSdk.

Dependencias

Declara las dependencias de un módulo en el bloque dependencies:

• module: Son otros módulos de tu proyecto, escritos como // seguido del nombre del módulo, por ejemplo, //app-core o //features/search.
• maven: Son las bibliotecas externas, escritas como coordenadas de Maven en el formato group:artifact:version.

Por ejemplo, los siguientes parámetros de configuración agregan dependencias en el módulo app-core y en la biblioteca de AndroidX Core KTX:

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

Configuración de dependencias

De forma predeterminada, un módulo se compila con cada una de sus dependencias y las incluye en el entorno de ejecución, pero no las expone a los módulos que dependen de él. Para cambiar la forma en que un módulo usa una dependencia, agrega dos puntos después de la dependencia y, luego, agrega el parámetro de configuración compile, el parámetro de configuración runtime o ambos debajo de ella:

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

En este ejemplo, los módulos que dependen de este módulo también pueden usar las clases del módulo data. La biblioteca de Jetpack Annotation solo se usa para compilar este módulo. Core KTX usa la configuración predeterminada.

El parámetro de configuración compile controla qué módulos se compilan con la dependencia:

• private (predeterminado): Este módulo se compila con la dependencia, pero los módulos que dependen de este módulo no lo hacen.
• public: Este módulo y los módulos que dependen de él se compilan con la dependencia. Usa public cuando la API pública de tu módulo use tipos de la dependencia.
• off: Este módulo no se compila con la dependencia.

El parámetro de configuración runtime controla si la dependencia está disponible en el entorno de ejecución:

• public (predeterminado): La dependencia está disponible durante el tiempo de ejecución para este módulo y los módulos que dependen de él.
• off: La dependencia no está disponible durante el tiempo de ejecución. Usa off para las dependencias que tu código necesita solo en el tiempo de compilación, como las anotaciones.

compile y runtime no pueden ser off. En las dependencias de prueba, compile solo puede ser private o off.

Para ver cómo estos parámetros de configuración se corresponden con los de DSL de Kotlin, como api y compileOnly, consulta Compara Lightbuild con DSL de Kotlin.

Procesadores de KSP

Para usar un generador de código basado en el procesamiento de símbolos de Kotlin (KSP), como Moshi o Room, agrega el procesador al bloque kspProcessors y las bibliotecas que usa tu código en el entorno de ejecución al bloque dependencies. Lightbuild aplica automáticamente el complemento de KSP y configura la generación de código durante la compilación.

Por ejemplo, los siguientes parámetros de configuración establecen Moshi con su generador de código 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

Búferes de protocolo

Para generar código a partir de archivos de búferes de protocolo (.proto) en un módulo de biblioteca, agrega la función de búferes de protocolo a la lista optionalFeatures del módulo y agrega las bibliotecas de entorno de ejecución de búferes de protocolo a las dependencias del módulo. optionalFeatures es un parámetro de configuración de nivel superior, fuera del bloque 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

Coloca los archivos .proto del módulo en su directorio src/main/proto. Cuando compilas el módulo, Lightbuild genera clases de Java y Kotlin para el entorno de ejecución de búferes de protocolo lite, que se recomienda para Android.

Pruebas

Configura las pruebas de un módulo en el bloque tests:

• test: Son pruebas locales que se ejecutan en la JVM de tu máquina de desarrollo. Enumera las dependencias de las pruebas en dependencies.
• androidTest: Son pruebas de instrumentación que se ejecutan en un dispositivo o emulador. Establece runner en la clase del ejecutor de pruebas y enumera las dependencias de las pruebas en dependencies.

Por ejemplo:

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

Empaquetado

En los módulos de la app, usa el bloque packaging para configurar las compilaciones debug y release de la app. Para firmar tu compilación de lanzamiento con tu propia clave, agrega un bloque signing al perfil release:

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

El bloque signing admite los siguientes parámetros de configuración:

• storeFile: Es la ruta de acceso al archivo del almacén de claves, ya sea relativa al directorio del módulo o que comience con ~/ para una ubicación en tu directorio principal.
• storePassword: Es la contraseña del almacén de claves.
• keyAlias: Es el alias de la clave de firma en el almacén de claves.
• keyPassword: Es la contraseña de la clave de firma.

Para mantener tus contraseñas fuera de los archivos de tu proyecto, establece estos valores en referencias de variables de entorno con la sintaxis ${NAME}, como en el ejemplo. Puedes escribir storeFile y keyAlias directamente, o bien hacer referencia a las variables de entorno para ellas. Cuando compilas, Lightbuild reemplaza cada referencia por el valor de la variable de entorno. Cada valor debe contener solo la referencia: Lightbuild no reemplaza una referencia que forma parte de un valor más largo, como ${HOME}/upload-keystore.jks.

Ejemplos

En los siguientes ejemplos, se muestran archivos de módulo completos para un módulo de app y un módulo de biblioteca.

Módulo de la app

En el siguiente archivo app/lightbuild.yaml, se configura un módulo de app que depende del módulo de biblioteca 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

Módulo de biblioteca

En el siguiente archivo app-core/lightbuild.yaml, se configura un módulo de biblioteca que usa Jetpack Compose y Moshi, y contiene pruebas locales y de instrumentación:

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