CompileSdkVersion and targetSdkVersion — what is the difference?
This post was created alongside the video that I posted on my YouTube channel 🎥
In this article, we’ll take a closer look at two values that are set in the build.gradle file: compileSdkVersion and targetSdkVersion.
We usually update both these API level values once the new Android SDK version is released. But why is it so crucial to do it? And why are there two of them since we usually set them to the same value anyway?
Both compileSdkVersion and targetSdkVersion are crucial to handle forward compatibility in Android — so they both are connected with what to do when the new Android SDK version appears. But how do they exactly work?
compileSdkVersion
compileSdkVersion defines which Android SDK version will be used by gradle to compile your app.
For example:
In Android 12, so in SDK version 31, there was a new API introduced, that allows us to easily implement a splash screen. In this new API, the splash screen can be customized using those properties:
If you want to use that API in your app you first have to:
- download SDK version 31 in Android Studio,
- and then: update
compileSdkVersionto 31 in your app.
Only then you can see these new properties. And only then you can use this new splash screen API in your code.
What about older devices?
That doesn’t of course mean that you can use only this new API and forget about users who have older Android versions where this API is not available.
If the minSdkVersion in your app is lower than 31 you have to also provide an alternative way to display a splash screen for those older devices which do not have access to this new API.
Similarly, some methods or properties could be deprecated in this Android SDK version, and some of them even removed. That's why once you update the compiledSdkVersion in your app, you will often see some warnings and errors during compilation that you have to address.
But changing the compileSdkVersion alone does not actually change the behaviour of the app that you created.
So how does the Android system know if it can use new functionalities with your app or not? That’s where targetSdkVersion comes into play.
targetSdkVersion
targetSdkVersion is a property that tells the system for which Android version the app was designed and tested on.
If the user runs your app on a device with an android version that is higher than the targetSdkVersion defined in your app, for new android features, the system may introduce some backwards-compatibility behaviour to ensure your app still looks and works in a way that you designed it.
For example:
In Android 12 the appearance of custom notifications was changed. Previously they could use the whole notification area, but in Android 12 system applies the standard template to all custom notifications so they look more consistent.
If your targetSdkVersion is below 31 system will assume that you haven’t tested that feature and will display notifications in the old way to minimise the risk that notification will not be displayed properly. Only after you update the target SDK version to 31 the new notification appearance will be used.
Are all changes in Android SDK targeted?
No, not all changes that are introduced in new Android versions are targeted and use these backwards-compatibility mechanisms. For each Android version release, in documentation, you can see that changes are split into two groups:
- behavioural changes for apps targeting specific Android versions
- and changes for all apps, no matter which
targetSdkVersionthey define.
An example of the latter may be the introduction of one time permissions in Android 11. When the device uses Android version 11 or higher and the app asks for location permission, the user can grant temporary access to that data and the app has to handle that case properly no matter if it targets SDK version 30 or not.
Relationship between compile and target SDK versions
Even if the compileSdkVersion and targetSdkVersion have completely different meanings they are obviously not independent.
targetSdkVersion cannot be higher than the compileSdkVersion simply because we cannot target things that we know nothing about during compilation.
Ideally, the compileSdkVersion and targetSdkVersion should be equal and both point to the latest SDK. But of course only after you test that every change introduced in that version works smoothly with your app!
Check out my other articles or videos:
- Android Runtime — How Dalvik and ART work? (+ video 🎥)
- How Dagger, Hilt and Koin differ under the hood? (+ video 🎥)
- Create Android Studio plugin to toggle “Show layout bounds” (+ video 🎥)
