Android Generic System Image is a pure Android OS without vendor specific customizations; it includes the core OS functionality for all of the same Android OS generation running on devices supporting Treble (which includes Android Pie and above). After validating that applications function normally on GSI, the apps are guaranteed to work on all devices with the same version of Android OS. GSI could also be built once and used for multiple compatible devices: one build, applies to all.

This codelab teaches you how to build a GSI and flash it to an Android device. You can also skip the building GSI section, download a prebuilt GSI, and start with the "flashing the GSI" section if you already have a pre-built GSI image.

What is Generic System Image (GSI)?

Android GSI is a tool to enable developers to perform early application development and validation on future Android OS versions: if an application works on GSI, it should execute smoothly on future certified OEM platforms that have the same Android API level.

Project Treble makes Android GSI project possible: Treble creates a clean interface between hardware platforms and Android OS

An OS built with full Treble compliance would behave consistently on all fully Treble-compliant devices. Generic System Image (GSI) is a fully Treble-enabled Android OS:

Android devices launched with Android 9 Pie are guaranteed to be fully Treble-compliant. With a phone launched with Pie and above, you can load any future Android GSI images.

This codelab will walk you through creating your own GSI or download from AOSP, and install it to your Android device. Android Pie GSI is used as an example, but the concepts and steps are applicable to future Android OS versions.

What you will build

In this codelab, you're going to:

  • Build GSI from source code
  • Install GSI to Android devices

From that point on, you could do your application development and validation as usual: GSI is the OS.

What you'll learn

What you'll need

This codelab is focused on building and flashing GSI. It tries to gloss over the concepts and background knowledge.

Follow instructions on developer.android.com to enable your Android device for USB debugging:

  1. Settings > System > About phone, tap "Build number" for 7 times
  2. Settings > System > advanced > Developer options > USB debugging, tap to enable it.
  3. Connect your device physically to your Linux host machine via USB cable, "allow USB debugging" when prompted on your Android device.
  4. In a terminal type: adb devices
    you should see your device's serial number listed in terminal.

Flashing GSI requires your Android device's bootloader to be unlocked, different Android devices may have different instructions and tools for unlocking the bootloader, refer to your device's manufacturer or carrier for details.

This codelab, uses Pixel 3, simply do:

  1. On the phone, settings > system > Developer Options > OEM unlocking, tap to enable if not enabled
  2. On Linux host, inside terminal, do
    adb reboot bootloader
    fastboot flashing unlock
    fastboot reboot

Check for GSI compatibility

GSI is part of Project Treble, and requires full Treble compatible devices. Treble is a mandatory feature for Android 9 Pie and above. This codelab uses Pixel 3, which is released with Android 9 Pie, it meets the GSI requirement.

If you are not sure whether your device is fully compliant with Project Treble, the following steps, executed inside the terminal window, would help to confirm that:
adb shell getprop ro.treble.enabled ⇒ returns true
adb shell cat /system/etc/ld.config.txt
...
[vendor]
⇐ check this section
namespace.default.isolated = true

If the above line is false,it means that vendor code might call some private OS functions: it is not Treble compliant, you could not use GSI on this device.

Decide the GSI type

CPU architecture

Android device's cpu architecture decides GSI's architecture: they must match. You could find out device's $arch-type via following command:

adb shell getprop ro.product.cpu.abi

It should return one of the following:

For Pixel 3, it is arm64-v8a, meaning 64 bit ARM platform.

GSI vs. Legacy GSI

If "system" is not running as root on the device, legacy GSI must be used. In AOSP image, legacy GSI is tagged as "_ab" in the image's lunch menu. Check the status of system-as-root with:

adb shell cat /proc/mounts | grep -q /dev/root && echo "system-as-root" || echo "non-system-as-root"

For Pixel 3, it returns "system-as-root", you could use non-legacy GSI. Note that legacy GSI would also work for system-as-root device, just that it will not fully utilize all of new features in the new Android OS.

Build Variant

GSI is a development tool, so you build userdebug variation, which enables us to see more debugging messages(in case you like to get a closer look when something unexpected happened).

Adding up the above Android signatures, you have worked out your GSI: it should be arm64-userdebug, the equivalent lunch menu to build is aosp_arm64-userdebug

AOSP master and GSI has their own Continuous Integration (CI), yeah! Android 9 Pie GSI could be downloaded from Android 9 Pie GSI CI page

Those are all that you need to flash Pie GSI into the Pixel 3 device: go to Flashing GSI to continue. If you like to build your own GSI, or your GSI type is unavailable on Pie-GSI CI page, go to the next step: Building GSI.

You should follow the instructions on the AOSP for this step, except that simplified steps could be used as your device is Pixel 3.

Download the Code

GSI source code is part of AOSP: from Android Pie and above, GSI has its own branch for each OS, named ${dessert-name}-gsi; for Android Pie, it is pie-gsi. Let's get source code for pie-gsi:

mkdir -p ~/source/pie-gsi && cd ~/source/pie-gsi

repo init -b pie-gsi -u https://android.googlesource.com/platform/manifest

repo sync -c

This may take a fair amount of time, depending on your Linux system performance and internet connection.

Build GSI

With 2 simple commands, you build your GSI

  1. Set up lunch menu as decided from the previous step of "Finding the Matching GSI Type"

source build/envsetup.sh

lunch aosp_arm64-userdebug

  1. build GSI

make -j

Again this may take 30+ minutes, depending on your Linux system performance. GSI branches are well maintained, it should build successfully; but if you do see failures, please file a bug for GSI.

Congratulations! Your GSI should be built into 2 files:

out/target/product/generic_arm64/system.img

out/target/product/generic_arm64/vbmeta.img

where,

Please note that this part is also heavily device dependent: OEMs may have their own flashing tools and instructions, please refer to your device's manufacturer for details; but the theory is the same and simple: load GSI onto the device and reboot, that is all.

For Pixel 3, the tools you will use are:

When GSI is built, those tools also get built inside the Android source tree and they are in the ${PATH} already. When you were downloading GSI, you also downloaded these 2 utilities at that time, and added them into the ${PATH}. In both cases, tools are ready to be used; the flashing steps are the same except the location of the GSI are different:

simply pick the case that matches how you get your GSI.

Flashing Downloaded GSI

you are still in the same directory where your downloaded GSI is., i.e., ~/pie-gsi

adb reboot bootloader

fastboot flash vbmeta ./vbmeta.img

fastboot flash system ./system.img

fastboot reboot -w

Flashing Locally Build GSI

Note: skip these flashing steps if you did not build your GSI.

Assuming you are still in the same terminal you built Android GSI, i.e., still at the root directory of your pie-gsi source tree

~/source/pie-gsi

Let us install GSI:

adb reboot bootloader

fastboot flash vbmeta out/target/product/generic_arm64/vbmeta.img

fastboot flash system out/target/product/generic_arm64/system.img

fastboot reboot -w

Note that you erased user data on the device when you boot up GSI: you get a fresh GSI device for your application development; it also means that you would lose everything previously saved on this phone, so please be reminded.

In a minute or so, GSI boots up and you should see:

There it is: you have got a fresh GSI running on your Android device! Now you could really start your development on new OS -- GSI.

Summary

As a tool, GSI enables developers to:

Starting from Android 9 Pie , the GSI branches are maintained on AOSP; when CI is enabled, GSI binary will also be to be downloaded, making it much easier to be used by developers.

In this codelab, we have covered:

Further reading

We encourage developers to use GSI to assist application development. Got some ideas or found issues about GSI? please file GSI bugs, we appreciate your efforts for a better GSI!