Gradle Tutorial for Android: Getting Started – Part 1

Update note: Ricardo Costeira updated this tutorial for Android Studio 2023.1.1. Irina Galata wrote the original.

In this tutorial, you’ll learn about Gradle and how you can set it up in a maintainable and scalable way. By the end of this tutorial, you’ll be able to:

1. Build your Android apps from the command line.
2. Read both Groovy and Kotlin Gradle build files.
3. Manage dependencies with Gradle.

What is Gradle?

Gradle is an open-source build-automation system. It has the convenience of a Groovy- or Kotlin-based DSL and the advantages of Ant and Maven. With Gradle, you can easily manipulate the build process and its logic to create multiple versions of your app. It’s much easier to use and a lot more concise and flexible when compared to Ant or Maven alone.

Getting Started

Download the starter project by clicking the Download Materials link at the top or bottom of the tutorial.

Open the project in Android Studio, and take a look at its structure in the Project pane in Android Studio:

Pay attention to the files with the Gradle elephant icon and .gradle extension. These files are generated by Android Studio automatically during project creation. They are written in Groovy and responsible for processing your project’s build. They contain the necessary info about project structure, library dependencies, library versions and the app versions you’ll get as a result of the build process.

Starting from Android Studio Giraffe, Kotlin will be the default language for build configuration. Gradle files written in Kotlin have the .gradle.kts extension. You can see that there are already a few in the project, but they were manually added. These are the Kotlin equivalent to the .gradle ones. Well, more or less — they’re fairly different in behavior at this point, but you’ll understand why as you progress through the tutorial.

Exploring the Project-Level Files

Find the build.gradle file in the root directory of the project. It’s called a top-level (project-level) build.gradle file. It contains the settings that are applied to all modules of the project.

Open the file, and you’ll see the following code:

// 1
buildscript {
    // 2
    repositories {
        google()
        mavenCentral()
    }
    // 3
    dependencies {
        classpath "com.android.tools.build:gradle:8.2.2"
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.20"
    }
}
// 4
allprojects {
    repositories {
        google()
        mavenCentral()
    }
}
// 5
tasks.register('clean', Delete) {
    delete rootProject.buildDir
}

Here’s what’s going on, step by step:

1. In the buildscript block, you define settings needed to build your project.
2. In the repositories block, you add names of the repositories where Gradle should search for the plugins you use.
3. The dependencies block contains necessary plugin dependencies — in this case the Gradle and Kotlin plugins. Don’t put your module dependencies in this block.
4. The structure of the allprojects block is similar to the buildscript block, but here you define repositories for all of your modules, not for Gradle itself. Usually you don’t define the dependencies section for allprojects. The dependencies for each module are different and should reside in the module-level build.gradle.
5. A task represents a piece of work in the build process. This simple one cleans up the build files when executed. You’ll learn more about tasks later in this tutorial.

Moving on to Module-level Files

Now, go to the build.gradle file in the app module directory. It contains dependencies — libraries that a module relies on — and instructions for the build process. Each module defines its own build.gradle file.

// 1
plugins {
    id "com.android.application"
    id "kotlin-android"
}
// 2
android {
    // 3
    namespace "com.kodeco.socializify"
    // 4
    compileSdk 34
    // 5
    defaultConfig {
        // 6
        applicationId "com.kodeco.socializify"
        // 7
        minSdkVersion 23
        // 8
        targetSdkVersion 34
        // 9
        versionCode 1
        // 10
        versionName "1.0"
    }
    // 11
    buildFeatures {
        viewBinding true
    }
    // 12
    kotlin {
        jvmToolchain(17)
    }
}
// 13
dependencies {
    implementation fileTree(include: ["*.jar"], dir: "libs")
    implementation "androidx.appcompat:appcompat:1.6.1"
    implementation "com.google.android.material:material:1.9.0"
}

The code above does the following:

1. Specifies a list of plugins needed to build the module. The com.android.application plugin is necessary in order to set up the Android-specific settings of the build process. Here, you can also use com.android.library if you’re creating a library module. The kotlin-android plugin allows you to use the Kotlin language in your module.
2. In the android block, you place all platform-specific options of the module.
3. Defining a namespace is necessary for things like resource access. This used to be in the AndroidManifest.xml file under the package property, but has now migrated.
4. The compileSdk option indicates the API level your app will be compiled with. In other words, you can’t use features from an API higher than this value. Here, you’ve set the value to use APIs from Android Tiramisu.
5. The defaultConfig block contains options that will be applied to all build versions (e.g., debug, release, etc) of your app by default.
6. The applicationId is the identifier of your app. It should be unique so as to successfully publish or update your app on the Google Play Store. If you leave it undefined, the build system will use the namespace as applicationId.
7. In order to set the lowest API level supported, use minSdkVersion. Your app will not be available in the Play Store for the devices running on lower API levels.
Note: To get more acquainted with the Android SDK versions, read our tutorial covering that topic.
8. The targetSdkVersion parameter defines the maximum API level your app has been tested on. That is to say, you’re sure your app works properly on the devices with this SDK version, and it doesn’t require any backward-compatibility behavior. The best approach is to thoroughly test an app using the latest API, keeping your targetSdkVersion value equal to compileSdk.
9. versionCode is a numeric value for the app version.
10. versionName is a user-friendly string for the app version.
11. The buildFeatures block lets you enable certain features, like View binding or Compose. In this case, it’s doing the former.
Note: If you want to learn more about View binding, check out our tutorial on it.
12. Gradle 8.2 supports JVM 17 by default, so you force the project to use Java 17 through Gradle’s Java toolchain support.
13. The dependencies block contains all dependencies needed for this module. Later in this tutorial, you’ll find out more about managing your project’s dependencies.