Configure your build

The Android build system compiles app resources and source code and packages them into APKs or Android App Bundles that you can test, deploy, sign, and distribute.

In Gradle build overview and Android build structure, we discussed build concepts and the structure of an Android app. Now it's time to configure the build.

Android build glossary

Gradle and the Android Gradle plugin help you configure the following aspects of your build:

Build types

Build types define certain properties that Gradle uses when building and packaging your app. Build types are typically configured for different stages of your development lifecycle.

For example, the debug build type enables debug options and signs the app with the debug key, while the release build type may shrink, obfuscate, and sign your app with a release key for distribution.

You must define at least one build type to build your app. Android Studio creates the debug and release build types by default. To start customizing packaging settings for your app, learn how to configure build types.

Product flavors

Product flavors represent different versions of your app that you can release to users, such as free and paid versions. You can customize product flavors to use different code and resources while sharing and reusing the parts that are common to all versions of your app. Product flavors are optional, and you must create them manually. To start creating different versions of your app, learn how to configure product flavors.

Build variants

A build variant is a cross-product of build type and product flavor and is the configuration Gradle uses to build your app. Using build variants, you can build the debug version of your product flavors during development and signed release versions of your product flavors for distribution. Although you don't configure build variants directly, you configure the build types and product flavors that form them. Creating additional build types or product flavors also creates additional build variants. To learn how to create and manage build variants, read the Configure build variants overview.

Manifest entries

You can specify values for some properties of the manifest file in the build variant configuration. These build values override the existing values in the manifest file. This is useful if you want to generate multiple variants of your app with a different application name, minimum SDK version, or target SDK version. When multiple manifests are present, the manifest merger tool merges manifest settings.

Dependencies

The build system manages project dependencies from your local file system and from remote repositories. This means you don't have to manually search, download, and copy binary packages of your dependencies into your project directory. To find out more, see Add build dependencies.

Signing

The build system lets you specify signing settings in the build configuration, and it can automatically sign your app during the build process. The build system signs the debug version with a default key and certificate using known credentials to avoid a password prompt at build time. The build system does not sign the release version unless you explicitly define a signing configuration for this build. If you don't have a release key, you can generate one as described in Sign your app. Signed release builds are required for distributing apps through most app stores.

Code and resource shrinking

The build system lets you specify a different ProGuard rules file for each build variant. When building your app, the build system applies the appropriate set of rules to shrink your code and resources using its built-in shrinking tools, such as R8. Shrinking your code and resources can help reduce your APK or AAB size.

Multiple APK support

The build system lets you automatically build different APKs that each contain only the code and resources needed for a specific screen density or Application Binary Interface (ABI). For more information see Build multiple APKs. However, releasing a single AAB is the recommended approach, as it offers splitting by language in addition to screen density and ABI, while avoiding the need to upload multiple artifacts to Google Play. All new apps submitted after August 2021 are required to use AABs.

Java versions in Android builds

Whether your source code is written in Java, Kotlin, or both, there are several places you must choose a JDK or Java language version for your build. See Java versions in Android builds for details.

Build configuration files

Creating custom build configurations requires you to make changes to one or more build configuration files. These plain-text files use a domain-specific language (DSL) to describe and manipulate the build logic using Kotlin script, which is a flavor of the Kotlin language. You can also use Groovy, which is a dynamic language for the Java Virtual Machine (JVM), to configure your builds.

You don't need to know Kotlin script or Groovy to start configuring your build because the Android Gradle plugin introduces most of the DSL elements you need. To learn more about the Android Gradle plugin DSL, read the DSL reference documentation. Kotlin script also relies on the underlying Gradle Kotlin DSL

When starting a new project, Android Studio automatically creates some of these files for you and populates them based on sensible defaults. For an overview of the created files, see Android build structure.

The Gradle Wrapper file

The Gradle wrapper (gradlew) is a small application included with your source code that downloads and launches Gradle itself. This creates more-consistent build execution. Developers download the application source and run gradlew. This downloads the required Gradle distribution, and launches Gradle to build your application.

The gradle/wrapper/gradle-wrapper.properties file contains a property, distributionUrl, that describes which version of Gradle is used to run your build.

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.0-bin.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

The Gradle settings file

The settings.gradle.kts file (for the Kotlin DSL) or settings.gradle file (for the Groovy DSL) is located in the root project directory. This settings file defines project-level repository settings and informs Gradle which modules it should include when building your app. Multi-module projects need to specify each module that should go into the final build.

For most projects, the file looks like the following by default:

pluginManagement {

    /**
      * The pluginManagement.repositories block configures the
      * repositories Gradle uses to search or download the Gradle plugins and
      * their transitive dependencies. Gradle pre-configures support for remote
      * repositories such as JCenter, Maven Central, and Ivy. You can also use
      * local repositories or define your own remote repositories. Here we
      * define the Gradle Plugin Portal, Google's Maven repository,
      * and the Maven Central Repository as the repositories Gradle should use to look for its
      * dependencies.
      */

    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}
dependencyResolutionManagement {

    /**
      * The dependencyResolutionManagement.repositories
      * block is where you configure the repositories and dependencies used by
      * all modules in your project, such as libraries that you are using to
      * create your application. However, you should configure module-specific
      * dependencies in each module-level build.gradle file. For new projects,
      * Android Studio includes Google's Maven repository and the Maven Central
      * Repository by default, but it does not configure any dependencies (unless
      * you select a template that requires some).
      */

  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories {
      google()
      mavenCentral()
  }
}
rootProject.name = "My Application"
include(":app")

pluginManagement {

    /**
      * The pluginManagement.repositories block configures the
      * repositories Gradle uses to search or download the Gradle plugins and
      * their transitive dependencies. Gradle pre-configures support for remote
      * repositories such as JCenter, Maven Central, and Ivy. You can also use
      * local repositories or define your own remote repositories. Here we
      * define the Gradle Plugin Portal, Google's Maven repository,
      * and the Maven Central Repository as the repositories Gradle should use to look for its
      * dependencies.
      */

    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}
dependencyResolutionManagement {

    /**
      * The dependencyResolutionManagement.repositories
      * block is where you configure the repositories and dependencies used by
      * all modules in your project, such as libraries that you are using to
      * create your application. However, you should configure module-specific
      * dependencies in each module-level build.gradle file. For new projects,
      * Android Studio includes Google's Maven repository and the Maven Central
      * Repository by default, but it does not configure any dependencies (unless
      * you select a template that requires some).
      */

    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}
rootProject.name = "My Application"
include ':app'

The top-level build file

The top-level build.gradle.kts file (for the Kotlin DSL) or build.gradle file (for the Groovy DSL) is located in the root project directory. It typically defines the common versions of plugins used by modules in your project.

The following code sample describes the default settings and DSL elements in the top-level build script after creating a new project: