Framework Compatibility in Android

One of Android's greatest engineering challenges is keeping apps that were written years ago working on the latest OS - and keeping the OS upgradeable without breaking vendor hardware. Android solves these through a layered compatibility system.

App Compatibility - minSdk and targetSdk

• ▸minSdkVersion - the oldest Android version your app supports. OS versions below this won't install your app
• ▸targetSdkVersion - the Android version your app is designed for. The OS uses this to decide which compatibility behaviors to apply
• ▸compileSdkVersion - the API level you compile against. Doesn't affect runtime behavior

  App targets SDK 29 (Android 10)
  Running on Android 14 (SDK 34)
              │
              ▼
  Android 14 applies compatibility shims:
  ┌──────────────────────────────────────────┐
  │ 'This app expects Android 10 behavior'   │
  │                                          │
  │ • Scoped storage not enforced strictly   │
  │ • Background activity launch allowed     │
  │ • Older permission model used            │
  └──────────────────────────────────────────┘
              │
              ▼
  App works, but Google Play may warn users
  (Play requires targetSdk ≥ 33 for new apps)

Vendor Compatibility - VNDK

VNDK (Vendor NDK) is a curated set of system libraries that vendor code (HALs, vendor daemons) is allowed to link against. By restricting which /system libraries vendor code can use, Android ensures a new /system image can be installed on an old /vendor partition without breaking vendor code.

• ▸VNDK libraries - /system libraries approved for vendor use (e.g. libbase, libcutils, libhidlbase)
• ▸LL-NDK - stable C libraries (libc, libm, libdl) that are frozen across all Android versions
• ▸Non-VNDK - /system libraries NOT allowed in vendor code; accessing them will break after an OTA

HAL Interface Stability

AIDL HAL interfaces can be marked @VintfStability, meaning they are frozen in the VINTF (Vendor Interface object) manifest. Once frozen, the interface cannot break backward compatibility - new methods can be added but old ones cannot change. This guarantees the framework and HAL can interoperate even after an OTA.

CTS - Compatibility Test Suite

CTS is the test suite that OEMs must pass before shipping an Android device or an OTA update. It verifies that the device behaves correctly according to the Android specification - ensuring all apps have a consistent environment regardless of manufacturer.

• ▸CTS (Compatibility Test Suite) - tests the Android API surface behaves correctly
• ▸VTS (Vendor Test Suite) - tests that HAL interfaces are implemented correctly by vendor code
• ▸GTS (Google Test Suite) - tests Google-specific apps and services
• ▸STS (Security Test Suite) - verifies security patches are applied