Referência de configuração do Lightbuild

Experimental: o Lightbuild é uma prévia experimental. O design dele ainda está em evolução e ainda não oferece suporte a todos os recursos de build do Android. Para apps de produção, projetos atuais ou novos apps ambiciosos, continue usando a DSL do Kotlin. A prévia do Lightbuild é mais adequada para apps pequenos, protótipos e demonstrações. Para detalhes sobre o que é compatível, consulte a comparação da DSL do Kotlin e as notas da versão.

A configuração do build de um projeto do Lightbuild consiste em arquivos YAML: um arquivo project.lightbuild.yaml no diretório raiz do projeto e um arquivo lightbuild.yaml em cada módulo. Nesta página, descrevemos as configurações de cada arquivo.

Arquivo do projeto

As configurações globais do projeto ficam no arquivo project.lightbuild.yaml no diretório raiz do projeto. Exemplo:

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"

A tabela a seguir descreve essas configurações:

Configuração	Descrição
project.name	O nome do projeto, por exemplo, MyApp. O Android Studio mostra esse nome como a raiz da janela Project. Assim como rootProject.name na DSL do Kotlin, ele é separado do nome e do ID do aplicativo.
modules	Os módulos no projeto, como o módulo do app (app) e os módulos de biblioteca (app-core).
repositories	Os repositórios remotos de onde o Lightbuild resolve as dependências. Para mais detalhes, consulte Repositórios.
lightbuild.version	A versão do Lightbuild que o projeto usa.
build.kotlin.version	A versão do Kotlin usada pelo projeto.
build.java.version	A versão do compilador Java exigida pelo projeto.
build.jvmTarget	A versão de destino do bytecode da JVM gerado.

Repositórios

Use repositories para listar os repositórios de onde o Lightbuild resolve as dependências. É possível listar os repositórios google e mavenCentral integrados e adicionar repositórios Maven personalizados com maven:

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

Um repositório maven tem as seguintes configurações:

Configuração	Descrição
name	Um nome para o repositório.
url	O URL do repositório.
credentials	Opcional. As chaves que são mapeadas para o nome de usuário e a senha do repositório no arquivo local.properties. Para mais detalhes, consulte Credenciais do repositório.

Credenciais do repositório

Se um repositório Maven exigir um nome de usuário e uma senha, adicione um bloco credentials ao repositório. Os valores username e password não são as credenciais em si, mas chaves que você define no arquivo local.properties do projeto:

repositories:

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

Em seguida, no arquivo local.properties do projeto, mapeie cada chave para o valor correspondente. Substitua REPO_USERNAME e REPO_PASSWORD pelas suas credenciais:

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

Atenção: não adicione o arquivo local.properties ao controle de versões, porque ele contém credenciais sensíveis.

Arquivos de módulo

Cada módulo tem um arquivo lightbuild.yaml no diretório que define as configurações do módulo. A tabela a seguir descreve as configurações de nível superior:

Configuração	Descrição
platform	A plataforma de destino do módulo: android.
type	O tipo de módulo: application para um módulo de app ou library para um módulo de biblioteca. Para mais informações, consulte Estrutura do projeto do Lightbuild.
optionalFeatures	Recursos opcionais a serem ativados para o módulo, como com.android.tools.lightbuild.protobuf para suporte a buffers de protocolo. Para mais detalhes, consulte Buffers de protocolo.
android	As configurações do Android do módulo. Veja mais detalhes em Configurações do Android.

Configurações do Android

O bloco android contém as configurações de build do Android do módulo:

Configuração	Descrição
namespace	O namespace do módulo. Para mais informações, consulte Definir o namespace.
compileSdk	O nível da API em que o módulo é compilado. Para mais detalhes, consulte Versões do SDK.
minSdk	O nível mínimo de API com que o módulo é compatível.
targetSdk	O nível da API que o app segmenta. Compatível apenas com módulos de app.
applicationId	O ID do aplicativo. Definido nos módulos do app.
versionCode	O código da versão do app. Definido nos módulos do app.
versionName	O nome da versão do app. Definido nos módulos do app.
packaging	Configurações para empacotar os builds debug e release do app, como a assinatura de lançamento. Compatível apenas no módulo do app. Para mais detalhes, consulte Empacotamento.
dependencies	As dependências do módulo em outros módulos e em bibliotecas externas. Para mais detalhes, consulte Dependências.
kspProcessors	Os processadores KSP que geram código para o módulo. Para mais detalhes, consulte Processadores KSP.
tests	Os testes locais e instrumentados do módulo. Para mais detalhes, consulte Testes.

Versão do SDK

Especifique as configurações compileSdk, minSdk e targetSdk como níveis da API em version.release.apiLevel. Por exemplo, as configurações a seguir compilam o módulo com o nível 36 da API, oferecem suporte ao nível 24 e versões mais recentes e segmentam o nível 36 da API:

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

Somente os módulos de app oferecem suporte à configuração targetSdk. Os módulos de biblioteca definem apenas as configurações compileSdk e minSdk.

Dependências

Declare as dependências de um módulo no bloco dependencies:

• module: outros módulos no projeto, escritos como // seguido pelo nome do módulo, por exemplo, //app-core ou //features/search.
• maven: bibliotecas externas, escritas como coordenadas do Maven no formato group:artifact:version.

Por exemplo, as configurações a seguir adicionam dependências ao módulo app-core e à biblioteca AndroidX Core KTX:

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

Configurações de dependência

Por padrão, um módulo é compilado em relação a cada uma das dependências dele e as inclui no ambiente de execução, mas não as expõe aos módulos que dependem dele. Para mudar como um módulo usa uma dependência, adicione dois pontos depois dela e, em seguida, adicione a configuração compile, a configuração runtime ou ambas abaixo dela:

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

Neste exemplo, os módulos que dependem desse módulo também podem usar as classes do módulo data. A biblioteca de anotações do Jetpack é usada apenas para compilar esse módulo. O Core KTX usa as configurações padrão.

A configuração compile controla quais módulos são compilados com a dependência:

• private (padrão): esse módulo é compilado com base na dependência, mas os módulos que dependem dele não.
• public: esse módulo e os módulos que dependem dele são compilados em relação à dependência. Use public quando a API pública do módulo usar tipos da dependência.
• off: esse módulo não é compilado com a dependência.

A configuração runtime controla se a dependência está disponível no ambiente de execução:

• public (padrão): a dependência está disponível no momento da execução para este módulo e para os módulos que dependem dele.
• off: a dependência não está disponível no ambiente de execução. Use off para dependências que seu código precisa apenas no tempo de compilação, como anotações.

compile e runtime não podem ser off. Nas dependências de teste, compile só pode ser private ou off.

Para ver como essas configurações correspondem às configurações da DSL do Kotlin, como api e compileOnly, consulte Comparar o Lightbuild com a DSL do Kotlin.

Processadores KSP

Para usar um gerador de código baseado no Kotlin Symbol Processing (KSP), como o Moshi ou o Room, adicione o processador ao bloco kspProcessors e as bibliotecas que seu código usa no momento da execução ao bloco dependencies. O Lightbuild aplica automaticamente o plug-in do KSP e configura a geração de código durante o build.

Por exemplo, as configurações a seguir configuram o Moshi com o gerador 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

Observação: o bloco kspProcessors só aceita dependências externas do Maven. As dependências de módulo local não são compatíveis com processadores KSP.

Buffers de protocolos

Para gerar código de arquivos de buffers de protocolo (.proto) em um módulo de biblioteca, adicione o recurso de buffers de protocolo à lista optionalFeatures do módulo e adicione as bibliotecas de ambiente de execução de buffers de protocolo às dependências do módulo. optionalFeatures é uma configuração de nível superior, fora do bloco 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

Coloque os arquivos .proto do módulo no diretório src/main/proto. Quando você cria o módulo, o Lightbuild gera classes Java e Kotlin para o ambiente de execução lite de buffers de protocolo, que é recomendado para o Android.

Testes

Configure os testes de um módulo no bloco tests:

• test: testes locais executados na JVM da sua máquina de desenvolvimento. Liste as dependências dos testes em dependencies.
• androidTest: testes instrumentados executados em um dispositivo ou emulador. Defina runner como a classe do executor de testes e liste as dependências dos testes em dependencies.

Exemplo:

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

Apresentação

Nos módulos do app, use o bloco packaging para configurar os builds debug e release do app. Para assinar o build de lançamento com sua própria chave, adicione um bloco signing ao perfil release:

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

O bloco signing é compatível com as seguintes configurações:

• storeFile: o caminho para o arquivo do keystore, relativo ao diretório do módulo ou começando com ~/ para um local no diretório inicial.
• storePassword: a senha do keystore.
• keyAlias: o alias da chave de assinatura no keystore.
• keyPassword: a senha da chave de assinatura.

Para manter as senhas fora dos arquivos do projeto, defina esses valores como referências de variáveis de ambiente com a sintaxe ${NAME}, como no exemplo. É possível escrever storeFile e keyAlias diretamente ou referenciar variáveis de ambiente para eles também. Ao criar, o Lightbuild substitui cada referência pelo valor da variável de ambiente. Cada valor precisa conter apenas a referência: o Lightbuild não substitui uma referência que faz parte de um valor mais longo, como ${HOME}/upload-keystore.jks.

Importante: para evitar que informações sensíveis sejam expostas, não escreva senhas diretamente nos arquivos lightbuild.yaml nem verifique o keystore no controle de versões.

Aviso: se uma variável de ambiente referenciada por um bloco signing não estiver definida, todos os builds do módulo do app vão falhar, incluindo os builds de depuração.

Exemplos

Os exemplos a seguir mostram arquivos de módulo completos para um módulo de app e um módulo de biblioteca.

Módulo do app

O arquivo app/lightbuild.yaml abaixo configura um módulo de app que depende do 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

O arquivo app-core/lightbuild.yaml abaixo configura um módulo de biblioteca que usa o Jetpack Compose e o Moshi e contém testes locais e testes de instrumentação:

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