Android virtual device as a development platform

To use Android Virtual Devices (AVDs), Android Emulator supports a Graphical User Interface (GUI) and Command Line Interface (CLI). You select the optimal workflow for your environment.

Launch an AOSP Car AVD using prebuilt

To quickly launch and test using prebuilt AOSP Car AVD, use an open source script to download and launch an emulator build from ci.android.com. The script has been tested on macOS and Linux.

You'll need Curl to use this script.

To run the script:

  1. Copy the launch_emu.sh script contents to your local file, assuming you use launch_emu.sh as the local file name.
  2. Make your local script executable. For example, run chmod +x ./launch_emu.sh.
  3. Check the available options by running the script with ./launch_emu.sh -h.
  4. On ci.android.com, go to the aosp-main-throttled branch and select a recent build in which sdk_car_x86_64 is green. For example, 11370359. If you don't see build information, log out of your Google Account and try again.
  5. Download and install the emulator-relevant binary files with the build ID. For example, ./launch_emu.sh -i -a 11370359.
  6. After this, you can use ./launch_emu.sh to launch the downloaded and installed emulator (don't use the -i or -a options).
  7. To download and install another build ID, run ./launch_emu.sh -c to clean your workspace and then repeat Step 4 and Step 5 above.

To specify Android emulator Command-line startup options options when launching the emulator, use the -v option. For example:

  ./launch_emu.sh -v “-cores 4 -memory 6144 -no-snapshot"

Build an AOSP Car AVD

The process to build an AOSP Car AVD is similar to Building AVD images for a phone (for example, aosp_car_x86_64):

  1. To set up the development environment and identify a branch, see Source Control Tools. Then review Downloading the Source:
    ANDROID_BRANCH="android12L-release"
    REPO_URL="https://android.googlesource.com/platform/manifest"
    mkdir $ANDROID_BRANCH && cd $ANDROID_BRANCH && repo init -u $REPO_URL -b $ANDROID_BRANCH --partial-clone && repo sync -c -j8
  2. Build the AVD image:
    . build/envsetup.sh && lunch sdk_car_x86_64-userdebug && m -j32
  3. Run the AVD image (append additional Command-line startup options as needed):
    emulator &

    For example:

    Figure 1. Android Virtual Emulator screen

    Notes about this process:

    • Because the build process is the same as that required to build Android for a physical device, allow some time to download the source and then build it.
    • To work on other branches, set $ANDROID_BRANCH to another branch/tag.
    • AVD images, such as system.img, are built at $ANDROID_PRODUCT_OUT. To learn more about key images, see AVD system directory.
    • See the README file to learn how the prebuilt emulator binaries in your Android tree are used to run the emulator.

Create a Car AVD

Adding a new car AVD is almost identical to Adding a New Device. For example, 1660554 creates a new avd_car AVD.

To create a Car AVD:

  1. Create a company and a device folder as needed. This example uses $ANDROID_BUILD_TOP/device/google_car/avd_car.
  2. Create the product makefile, avd_car.mk, which defines how to build the AVD.
  3. Create a device folder, avd_car_device, in which to contain BoardConfig.mk and source.properties.
  4. Add the new makefile and the new lunch choice to AndroidProducts.mk.
  5. To build and run the new avd_car AVD:
    . build/envsetup.sh && lunch acar-userdebug && m -j32 && emulator &
You're now ready to prototype most HMI and app features on your new AVD.

Pack an AVD image zip file

You can pack and share your AVD with others or use it on another computer. Use emu_img_zip.mk to generate the AVD image zip file:

  1. After you build the AVD, make emu_img_zip the target:
    m emu_img_zip
  2. The AVD image zip file, prefixed with sdk-repo-linux-system-images, is created in the folder named $ANDROID_PRODUCT_OUT.

Build an AVD kernel

AVD kernels are similar to other Android kernels in that all are pre-built images. Normally, you can use the standard goldfish kernel pre-built images as is from each Android release.

To experiment with kernel changes:

  1. Run the following series of instructions:
    mkdir goldfish-kernel-54
    cd goldfish-kernel-54
    repo init -u https://android.googlesource.com/kernel/manifest -b
    common-android11-5.4
    repo sync
    BUILD_CONFIG=common/build.config.gki.x86_64 build/build.sh
    BUILD_CONFIG=common-modules/virtual-device/build.config.goldfish.x86_64
    build/build.sh
    ls -l ./out/android11-5.4/dist/
    
  2. Replace the kernel binary in the codebase according to the AVD makefile. For example, x86_64-vendor.mk includes x86_64-kernel.mk.

The kernel code and config is located as follows:

Item Value
Branch common-android11-5.4 (used in Android 11)
Manifest kernel/manifest/common-android11-5.4
common-modules/virtual-device kernel/common-modules/virtual-device/android11-5.4
Kernel kernel/common/android11-5.4

Create a new device profile

To enable users to create a specific AVD in Android Studio AVD Manager, see Create and manage virtual devices. Device makers can define their own hardware specifications, such as for screen size and DPI, through use of a devices.xml file included in the AVD image.

  • For example, see the Automotive Device profiles in automotive.xml.
  • For HMI development or prototyping, multiple devices can be added to the file for the same AVD image.
  • Include the file in the OEM AVD image zip file in the [ABI] folder. For example, as x86_64.
  • Device makers can also Create an emulator skin. For instance, to define additional hardware buttons for higher fidelity UX. This isn't only useful for developer workflows, but also for other tasks such as UX research and review.

Create the AVD image XML file

Device makers can create an AVD Image XML file for Android Studio to download it.

  • For example, see the AAOS AVD image XML file, sys-img2-1.xml.
  • Device makers can define their own OEM AVD license agreement for their target users (employing the honor system), with the license for Android Emulator. Android Studio gets user consensus when such a license is included.

To create the image:

  1. Prepare an AVD image zip file.
  2. Unzip ${ANDROID_PRODUCT_OUT}/sdk-repo-linux-system-images-*.zip.
  3. Add devices.xml to the x86_64 folder and then compress the file in a zip file. For example, as oem_avd_img_x86_64.zip.
  4. Update oem-sys-img2-1.xml.
  5. Update the zip file name, size, and shasum (sample XML files are provided in tools).

For example, to host the AVD on Google Cloud Storage, see Creating storage buckets.

To upload and make the AVD publicly accessible, see Making data public:

BUCKET_NAME="aaos-avd"
gsutil mb gs://$BUCKET_NAME
gsutil cp oem_avd_img_x86_64.zip gs://$BUCKET_NAME
gsutil cp oem-sys-img2-1.xml gs://$BUCKET_NAME
gsutil iam ch allUsers:objectViewer gs://$BUCKET_NAME

The AVD image SDK add-on URL format is as: https://storage.googleapis.com/$BUCKET_NAME/oem-sys-img2-1.xml. For example, if the BUCKET_NAME is aaos-avd, the URL is: https://storage.googleapis.com/aaos-avd/oem-sys-img2-1.xml.

Share an AVD image with Android Studio users

So that your users can download AVD images and use your AVD by Android Studio, you can provide an SDK add-on XML file. For details, see Update the IDE and SDK Tools.

To download the AVD from the network:

  1. Host the image zip file and XML files on a server.
  2. Provide the URL to your target users.
  3. (Optional) Limit access by user name and password.

Alternatively, to speed up development, download the AVD to a local directory:

  1. Save the XML files and all the artifacts specified in the XML file to a folder (for instance, all the AVD image zip files) named ADDON_DIR.
  2. Specify the URL as file://$ADDON_DIR/oem-sys-img2-1.xml.