Lightbuild configuration reference

A Lightbuild project's build configuration consists of YAML files: a project.lightbuild.yaml file in the project's root directory, and a lightbuild.yaml file in each module. This page describes the settings in each file.

Project file

Global project settings live in the project.lightbuild.yaml file in your project's root directory. For example:

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"

The following table describes these settings:

Setting	Description
`project.name`	The project's name, for example `MyApp`. Android Studio shows this name as the root of the Project window. Like `rootProject.name` in Kotlin DSL, it's separate from your app's name and application ID.
`modules`	The modules in the project, such as the app module (`app`) and library modules (`app-core`).
`repositories`	The remote repositories that Lightbuild resolves dependencies from. For details, see Repositories.
`lightbuild.version`	The Lightbuild version that the project uses.
`build.kotlin.version`	The Kotlin version that the project uses.
`build.java.version`	The Java compiler version that the project requires.
`build.jvmTarget`	The target version of the generated JVM bytecode.

Repositories

Use repositories to list the repositories that Lightbuild resolves dependencies from. You can list the built-in google and mavenCentral repositories, and add custom Maven repositories with maven:

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

A maven repository has the following settings:

Setting	Description
`name`	A name for the repository.
`url`	The repository's URL.
`credentials`	Optional. The keys that map to the repository's username and password in your `local.properties` file. For details, see Repository credentials.

Repository credentials

If a Maven repository requires a username and password, add a credentials block to the repository. The username and password values aren't the credentials themselves; they're keys that you define in your project's local.properties file:

repositories:

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

Then, in your project's local.properties file, map each key to its value. Replace REPO_USERNAME and REPO_PASSWORD with your credentials:

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

Module files

Each module has a lightbuild.yaml file in its directory that defines the module's settings. The following table describes the top-level settings:

Setting	Description
`platform`	The platform that the module targets: `android`.
`type`	The module type: `application` for an app module, or `library` for a library module. For more information, see Lightbuild project structure.
`optionalFeatures`	Optional features to enable for the module, such as `com.android.tools.lightbuild.protobuf` for Protocol Buffers support. For details, see Protocol Buffers.
`android`	The module's Android settings. For details, see Android settings.

Android settings

The android block contains the module's Android build settings:

Setting	Description
`namespace`	The module's namespace. For more information, see Set the namespace.
`compileSdk`	The API level that the module compiles against. For details, see SDK versions.
`minSdk`	The minimum API level that the module supports.
`targetSdk`	The API level that the app targets. Supported only in app modules.
`applicationId`	The app's application ID. Set in app modules.
`versionCode`	The app's version code. Set in app modules.
`versionName`	The app's version name. Set in app modules.
`packaging`	Settings for packaging the app's `debug` and `release` builds, such as release signing. Supported only in the app module. For details, see Packaging.
`dependencies`	The module's dependencies on other modules and on external libraries. For details, see Dependencies.
`kspProcessors`	The KSP processors that generate code for the module. For details, see KSP processors.
`tests`	The module's local and instrumented tests. For details, see Tests.

SDK versions

Specify the compileSdk, minSdk, and targetSdk settings as API levels under version.release.apiLevel. For example, the following settings compile the module against API level 36, support API level 24 and higher, and target API level 36:

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

Only app modules support the targetSdk setting. Library modules define only the compileSdk and minSdk settings.

Dependencies

Declare a module's dependencies in the dependencies block:

module: Other modules in your project, written as // followed by the module's name, for example //app-core or //features/search.
maven: External libraries, written as Maven coordinates in the format group:artifact:version.

For example, the following settings add dependencies on the app-core module and on the AndroidX Core KTX library:

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

Dependency settings

By default, a module compiles against each of its dependencies and includes them at runtime, but doesn't expose them to the modules that depend on it. To change how a module uses a dependency, add a colon after the dependency, and then add the compile setting, the runtime setting, or both below it:

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

In this example, modules that depend on this module can also use the data module's classes. The Jetpack Annotation library is used only to compile this module. Core KTX uses the default settings.

The compile setting controls which modules compile against the dependency:

private (default): This module compiles against the dependency, but the modules that depend on this module don't.
public: This module and the modules that depend on it compile against the dependency. Use public when your module's public API uses types from the dependency.
off: This module doesn't compile against the dependency.

The runtime setting controls whether the dependency is available at runtime:

public (default): The dependency is available at runtime, to this module and to the modules that depend on it.
off: The dependency isn't available at runtime. Use off for dependencies that your code needs only at compile time, such as annotations.

compile and runtime can't both be off. In test dependencies, compile can be only private or off.

To see how these settings correspond to Kotlin DSL configurations such as api and compileOnly, see Compare Lightbuild with Kotlin DSL.

KSP processors

To use a code generator that's based on Kotlin Symbol Processing (KSP), such as Moshi or Room, add the processor to the kspProcessors block, and add the libraries that your code uses at runtime to the dependencies block. Lightbuild automatically applies the KSP plugin and configures code generation during the build.

For example, the following settings configure Moshi with its KSP code generator:

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

Protocol Buffers

To generate code from Protocol Buffers (.proto) files in a library module, add the Protocol Buffers feature to the module's optionalFeatures list, and add the Protocol Buffers runtime libraries to the module's dependencies. optionalFeatures is a top-level setting, outside the android block:

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

Put the module's .proto files in its src/main/proto directory. When you build the module, Lightbuild generates Java and Kotlin classes for the Protocol Buffers lite runtime, which is recommended for Android.

Tests

Configure a module's tests in the tests block:

test: Local tests that run on your development machine's JVM. List the tests' dependencies under dependencies.
androidTest: Instrumented tests that run on a device or emulator. Set runner to the test runner class, and list the tests' dependencies under dependencies.

For example:

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

In app modules, use the packaging block to configure the app's debug and release builds. To sign your release build with your own key, add a signing block to the release profile:

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

The signing block supports the following settings:

storeFile: The path to the keystore file, either relative to the module's directory or starting with ~/ for a location in your home directory.
storePassword: The keystore's password.
keyAlias: The alias of the signing key in the keystore.
keyPassword: The signing key's password.

To keep your passwords out of your project's files, set these values to environment variable references with the ${NAME} syntax, as in the example. You can write storeFile and keyAlias directly, or reference environment variables for them too. When you build, Lightbuild replaces each reference with the value of the environment variable. Each value must contain only the reference: Lightbuild doesn't replace a reference that's part of a longer value, such as ${HOME}/upload-keystore.jks.

For more information about creating an upload key and publishing your app, see Publish your Lightbuild app.

Examples

The following examples show complete module files for an app module and a library module.

App module

The following app/lightbuild.yaml file configures an app module that depends on the app-core library module:

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

Library module

The following app-core/lightbuild.yaml file configures a library module that uses Jetpack Compose and Moshi and contains local and instrumented tests:

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

Recommended for you

Note: link text is displayed when JavaScript is off
Lightbuild project structure
Build Lightbuild projects from the command line
Compare Lightbuild with Kotlin DSL
Publish your Lightbuild app