Project Treble (which includes Android Pie and above devices) creates a clear interface between the Android OS and the Vendor portion. The Vendor portion includes a Board Support Package (BSP). The OS part is called Android Generic System Image (GSI):

Android OS builds that conform with the Treble interface can run on any Treble-compliant Android device. However, these builds often don't include OS customizations from OEMs.

What is Generic System Image (GSI)?

Android GSI is a full OS image that matches with the AOSP source code. To application developers. GSI provides values to application developers in that, at OS beta time, developers can flash the OS to a device that otherwise wouldn't be able to run the OS. If an application works on GSI, then it should execute smoothly on future certified OEM platforms that have the same Android API level as the GSI.

This capability allows app developers to validate their applications earlier than before. In doing so, developers can prepare their applications for the next version of the Android OS before it's released.

In short, GSI saves time for application developers, and it provides a better Android OS and ecosystem.

This codelab teaches you how to flash Android GSI 10 to a device that runs Android 9 (API level 28) device, and start our development for Android 10 on it.

Device Requirement for Android GSI

Three things are needed to use Android GSI:

Most of these are available from the device's manufacturer. For this codelab, we'll use a Pixel 3 device as an example.

What you will build

In this codelab, you're going to:

  • Identify the GSI to download
  • Install the GSI onto an Android device

From that point on, you can perform application development and validation as usual: the GSI is your device's new OS.

What you'll learn

What you'll need

If you run into any issues (code bugs, grammatical errors, unclear wording, etc.) as you work through this codelab, please report the issue via the Report a mistake link in the lower left corner of the codelab.

Enable USB Debug

After following the instructions to enable USB debugging, type the following in a terminal window:

adb devices


You should see your test device's serial number listed in terminal.

Confirm device launching OS version

To confirm that Android 9 is installed on your test device, type the following statement into a terminal window:

adb shell getprop ro.product.first_api_level

If the result of this command is 28, which represents Android 9, we are ready to go.

The available GSI types are listed on the Android Generic System Images (GSIs) page.To check the CPU architecture for your device, run the following command in a terminal window:

adb shell getprop ro.product.cpu.abi

It should return one of the following:

Pixel 3 uses the arm64-v8a architecture, so we could use either ARM64 or ARM64+GMS. ARM64+GMS allows you to use Google Play services on the device. For download image size purposes, we'll use the ARM64 GSI binary for this codelab, but feel free to use the version that includes GMS.

Download Android 10 GSI

The Android Generic System Images (GSIs) page also allows you to download a GSI image. For this codelab with Pixel 3, we'll demonstrate how to download the ARM64 GSI type.

  1. Navigate to the image download table on the page.
  2. Select the link next to ARM64, highlighted in the following screenshot:
  3. After agreeing to the GSI terms and conditions, download the file and unzip it into a local directory. For the purposes of this codelab, we'll create a directory called q-gsi to contain the unzipped GSI image.
mkdir  ~/q-gsi
cd ~/q-gsi
mv ~/Downloads/aosp_arm64-exp*.zip ./
unzip aosp_arm64-exp*.zip

(Optional) Check the version of your SDK's flashing tool.

To flash GSI onto your test device, you need the adb and fastboot tools. It is recommended that you use the version that matches your device's running OS type.

To determine the version of your SDK's platform tools, run the following command:

adb --version

This part is heavily device dependent. Different Android device manufacturers have their own flashing tools and instructions. For tools and processes specific to your device, visit your device manufacturer's documentation.

The steps used in this codelab are specific to a Pixel 3 device.

The GSI flashing process consists of the following steps:

  1. Navigate to the directory where your unzipped GSI image is saved.
cd ~/q-gsi
  1. Enter flashing mode on the device:
adb reboot bootloader
  1. Flash GSI onto the device:
fastboot flash --disable-verification vbmeta vbmeta.img
fastboot flash system system.img
  1. Reboot and erase user data:
fastboot -w reboot

After a minute or so, your device should boot into the newly-installed Android GSI OS:

There it is: you have a fresh GSI image running on an Android phone! Now you can start developing for the latest and greatest versions of Android.

Use the Android GSI issue tracker to report any GSI-specific bugs.

Summary

In this codelab, we have covered:

As a development tool, Android GSI enables you to perform the following:

Further reading

We love your feedback for GSI and Android! Please share your ideas and report GSI issues – file GSI bugs, discuss topics on StackOverflow, and contribute to our Reddit page, we appreciate your efforts for a better GSI!