How to install the Android Q Beta GSI on your device so you can test your apps
As we inch closer and closer the final Android Q release, the time for developers to update their applications shortens. Although Android 9 Pie (API level 28) has yet to reach the vast majority of devices, Google Play’s API level requirements, which you should already be well aware of, will force you to target API level 29 in 2020. If you haven’t already updated your app to target Android 9 Pie, then you have until August if you plan on launching a new app or until November if you plan on updating an existing app. For those of you who want to get started on developing for the next Android version, you can already test your app on the Android Studio emulator or on physical hardware if you own any Google Pixel smartphone. This year, though, Google is providing developers another way to test their apps against the latest Android version: flashing an Android Q beta GSI onto a Project Treble-compatible device.
Project Treble is a major initiative to improve the speed at which smartphone device makers can push out software and security updates. In a nutshell, Treble requires that device makers separate the software that makes the hardware work from the software behind the OS. This allows device makers to boot new Android releases on their existing devices so they can start the arduous task of porting their existing code base on top of the new Android source code release. Complementary to CTS is VTS, or Vendor Test Suite, a set of tests that device makers use to verify their device meets Project Treble’s requirements. One of the most important checks for device makers to test is the ability for a Treble-compatible smartphone to boot what’s called a GSI, or Generic System Image. A GSI is an unmodified build of AOSP that’s intended for device makers to see if they’ve properly implemented Treble. Beyond OEMs, though, Google believes that GSIs can be used by developers for Android app compatibility testing.
For example, if you don’t own a Google Pixel, the only way for you to test your app’s behavior under the conditions that best match Google’s documentation is for you to either acquire a Pixel device of your own, boot up the Android Studio emulator, or look into a cloud testing service. Each of these have their pros and cons, but if you have an existing Treble-compatible device and don’t want to spend any money or deal with the limitations of an emulator, why not slap a GSI onto it? If your app works on a GSI, it should work on almost all devices running that Android version.
That’s the thought process behind Google’s decision to release Android Q GSIs, or at least that’s what we think. The source code for Android Q won’t be available until August, so Google’s official GSI binaries are the only way right now to test Android Q on real, non-Pixel hardware. Here’s how you can get started.
Before you even consider installing the Android Q beta, you should check to see if your device is Project Treble-compatible and can accept flashing system images from the bootloader.
Before we go any further, it’s worth mentioning that flashing a GSI will require you to perform a full wipe of the userdata partition. This means that you will lose all photos, videos, music, documents, or anything else on the device’s internal and external (/data/media) storage. Thus, making an off-device backup before going any further is highly recommended.
Next, keep in mind that these GSIs haven’t passed CTS, so if your app uses the SafetyNet Attestation API to check for device integrity with a CTS profile match, then that won’t work. Also, these builds aren’t intended for daily use, so don’t be surprised if one or more basic hardware functions don’t work on top of the already documented bugs in Android Q. Google has already listed a few known issues with the GSI, which you can find here. Any new bugs that you find should be filed here.
Run the following command:
adb shell getprop ro.treble.enabled
If the response is false, then your device is not Project Treble compatible, and you should not continue. If the response is true, then you’re free to move on.
Next, check for cross-version support by running these commands:
adb shell cat /system/etc/ld.config.28.txt | grep -A 20 "\[vendor\]"
In the output, look for the section [vendor], and then within that section, look for namespace.default.isolated. If the value for that attribute is true, then your device should support booting the Android Q GSI on top of an Android 9 Pie vendor image. If the value is false, then your device can only use the GSI for the same on-device version of the OS.
Lastly, you need to confirm if your device is system-as-root, in which the ramdisk is merged with the system image. System-as-root is not mandatory for devices upgrading to Android 9 Pie, but is necessary to support a system-only OTA such as in the case of flashing a new OS version via GSI. Run the following commands and verify that the output matches “system-as-root”:
adb shell cat /proc/mounts | grep -q /dev/root && echo "system-as-root" || echo "non-system-as-root"
Now that you know your device is Treble-compatible, you need to figure out which version of the GSI binary to download, since there are different images for different architectures. To see which architecture your device has, run the following command:
adb shell getprop ro.product.cpu.abi
Make a note of the output here, as you’ll need it when downloading the GSI.
Downloading the GSI
Download links for official builds of the Android Q beta GSI are available from Google here. You should download the appropriate version based on your device’s architecture, which you found out in the previous step. The download will be fairly large if you download the build with GMS, or Google Mobile Services, something we highly recommend so you can test your app on a build with Google Play Services.
Once the file has finished downloading, you can unzip it. Contained within are two files, system.img, and vbmeta.img.
Flashing the GSI
- Reboot to your device’s bootloader using either a button combination or by issuing the command:
adb reboot bootloader
- Next, we need to disable Android Verified Boot (AVB). You can do this by entering the following command:
fastboot flash vbmeta vbmeta.img
- Next, let’s wipe the system partition:
fastboot erase system
- We can finally flash the Android Q GSI with:
fastboot flash system system.img
- Once that’s done, wipe the userdata partition with:
- Reboot your device using either the power button or entering:
Hopefully, it should boot after a few minutes. These steps were validated on a Pixel 3 XL, but should work universally. We can verify that the Android Q beta 2 GSI does not boot on the OnePlus 6T, but it does boot on the Xiaomi Mi 9. It may work on the Sony Xperia XZ3, but we’re told that it doesn’t boot on the Moto G7. Your mileage may vary as Google’s requirements only confirm same OS version GSI compatibility.