Android Plugin for Gradle Configuration

One of the most important areas for configuration in app/build.gradle is inside the android closure. That configures the Android Plugin for Gradle, teaching it the details of how you want your app to be assembled from its source code, resources, etc.

In theory, this closure can get very complex. In practice, most apps will configure just a few things, as the starter app does:

android {
  compileSdk 31

  defaultConfig {
    applicationId "com.commonsware.jetpack.hello"
    minSdk 21
    targetSdk 31
    versionCode 1
    versionName "1.0"

    testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
  }

  buildTypes {
    release {
      minifyEnabled false
      proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
    }
  }
  compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
  }
  kotlinOptions {
    jvmTarget = '1.8'
  }
}

Package Name and Application ID

In the previous chapter, we saw that there is a package attribute on the root <manifest> element of a manifest, and that indicates where some code-generated classes will go.

The package value also serves as the default value for your application ID. However, you can override it, as the starter app does, via an applicationId statement in the defaultConfig closure inside that android closure.

The application ID is a unique identifier for our app, such that:

• no two apps can be installed on the same device at the same time with the same application ID
• no two apps can be uploaded to the Play Store with the same application ID (and other distribution channels may have the same limitation)

Convention says that the application ID starts with a reversed edition of some domain name that you control, to reduce the likelihood of an accidental collision with the application ID of some other developer.

compileSdkVersion, minSdkVersion, and targetSdkVersion

Back in the chapter introducing resources, we discussed the concept of API levels. API levels are integers, with higher numbers indicating newer versions of Android. A new API level is created for:

• Every major version of Android (e.g., Android 8.0 is API Level 26)
• Every minor version of Android (e.g., Android 8.1 is API Level 27)
• Some patch versions of Android (e.g., Android 4.0 was API Level 14, but Android 4.0.3 was API Level 15)

We use those API levels in three key places in the module’s build.gradle file: compileSdkVersion, minSdkVersion, and targetSdkVersion.

compileSdkVersion indicates what version of Android do we want to compile against. Classes, methods, and other symbols that existed in Android at that time (or from before) will be available to us at compile time, but newer things will not. Usually, therefore, we set the compileSdkVersion to be a fairly modern API level, such as the latest production version of Android.

minSdkVersion indicates what is the oldest version of Android you are willing to support. So, if you are only supporting your app on Android 5.0 and newer versions of Android, you would set your minSdkVersion to be 21. Older devices will be incapable of installing your app, and your app will not appear in the Play Store app for devices running an older version of Android.

targetSdkVersion indicates what version of Android you are thinking of as you are writing your code. If your application is run on a newer version of Android, Android may do some things to try to improve compatibility of your code with respect to changes made in the newer Android. However, from a practical standpoint, nowadays the targetSdkVersion usually is the same value as the compileSdkVersion — we update both of them at the same time to the same value.

Note that in Arctic Fox, you may see these values defined without the Version suffix, as compileSdk, minSdk, and targetSdk.

Version Code and Version Name

The defaultConfig closure has versionCode and versionName properties. These two values represent the versions of your application.

The versionName value is what the user will see for a version indicator in places like the Settings app and the Play Store. This can be whatever string you want, using whatever naming or numbering system that you want. However, for customer support purposes, you should have some system that varies by release, rather than using the same string all of the time.

The versionCode, on the other hand, must be an integer, and newer versions must have higher version codes than do older versions. Android and the Play Store will compare the version code of a new APK to the version code of an installed application to determine if the new APK is indeed an update. The typical approach is to start the version code at 1 and increment it with each production release of your application, though you can choose another convention if you wish. During development, you can leave these alone, but when you move to production, these attributes will matter greatly.