Skip to content
Code Inside Out

AAOS - Build Android Automotive

Android Automotive extends Android, by adding support for automotive-specific requirements, features, and technologies.

Android Automotive is not a fork or parallel development of Android. It is the same codebase and lives in the same repository as the Android shipped on phones, tablets, etc.

General guide for Android Devices: https://source.android.com/docs/setup,
and for Automotive Android Devices: https://source.android.com/docs/automotive

Host Requirements

Refer: https://source.android.com/docs/setup/start/requirements.

Minimal Hardware:

  • 64-bit Linux System with glibc >= 2.17 (check with ldd --version)
  • 400 GB SSD (need more when using repo mirroring)
  • 16 GB RAM (need more when using more parallel threads -jN)

Build tools:

Required packages:

sudo apt update
sudo apt install git-core gnupg flex bison build-essential zip curl \
    zlib1g-dev libc6-dev-i386 x11proto-core-dev libx11-dev lib32z1-dev \
    libgl1-mesa-dev libxml2-utils xsltproc unzip fontconfig

May need these:

sudo apt install libncurses-dev software-properties-common

Recommend to use ccache for GCC/G++ compilation:

sudo apt install ccache
mkdir -p ~/.ccache
ccache -M 50G -F 0

Add below line into ~/.bashrc to use ccache for AOSP build:

export USE_CCACHE=1
export CCACHE_EXEC=/usr/bin/ccache

Repo tool:

The Repo launcher provides scripts that to checkout and download a full repo:

export REPO=$(mktemp /tmp/repo.XXXXXXXXX)
curl -o ${REPO} https://storage.googleapis.com/git-repo-downloads/repo
gpg --recv-keys 8BB9AD793E8E6153AF0F9A4416530D5E920F5C65
curl -s https://storage.googleapis.com/git-repo-downloads/repo.asc | \
    gpg --verify - ${REPO} && sudo install -m 755 ${REPO} /usr/bin/repo

Android Source Code

The Android source is located in a collection of Git repositories hosted by Google.

Download Repo

For the latest source code, default main branch is used (i.e. -b main).
For faster cloning, refer to Git partial clone and shallow clone.

repo init --partial-clone \
    -u https://android.googlesource.com/platform/manifest

For a list of branches and tag names, see Source code tags and builds:

CodenameVersionAPI LevelTagBuild IDSecurity patch
Android151535android-15.0.0_r1AP3A.240905.015.A22024-09-05
Android141434android-14.0.0_r74AD1A.240905.0042024-09-05
Android131333android-13.0.0_r83TQ3A.230805.001.S12023-08-05
Android12L1232android-12.1.0_r27SP2A.220505.0082022-05-05
Android121231android-12.1.0_r26SD2A.220601.004.B22022-06-01

Define macros:

export AOSP_HOME="$HOME/aosp"
export AOSP_BRANCH="android-14.0.0_r74"

Initialize the repo using shallow clone:

mkdir -p $AOSP_HOME/$AOSP_BRANCH
cd $AOSP_HOME/$AOSP_BRANCH
repo init --depth=1 \
    -u https://android.googlesource.com/platform/manifest \
    -b $AOSP_BRANCH

Sync (download) source code of the current branch:

repo sync -c -j$(nproc)

Folders Structure

There are many folders in the root folder of AOSP, here are short descriptions of them:

art: Android Runtime

  • Implementation of Android Runtime layer, including Ahead-Of-Time (AOT) compilation, Just-In-Time (JIT) compilation

bionic: C-runtime Library

  • Android is not using glibc like most Linux distributions, instead, the c-library is called bionic based mostly on BSD-derived sources

bootable: Bootup, OTA, Recovery

  • Bootloader, and some tools for recovery, flashing such as fastboot

build: Scripts, Configurations fot Build process

  • The build directory serves as the backbone of the build system, coordinating the compilation, linking, and packaging of various components

cts: Compatibility Test

  • The test suite to ensure that a build complies with the Android specification

dalvik: Dalvik Virtual Machine

  • Dalvik VM has been replaced by the Android Runtime (ART) since Android 5.0

developers: Demos, Sample resources

  • Assist developers in building, testing, and optimizing Android applications

development: Development Platform

  • Development tools such as the SDK and NDK

device: Products, Device-specific files

  • Build configuration, hardware modules and specific code for different devices
  • Contains BSP with overlay, boad configs, device, kernel, and SEpolicy

external: External open source components

  • Contains source code for all external open source projects, such as SQLite, FreeType and WebKit.

frameworks: Android framework

  • Implementation of key services such as System Server, Activity managers.
  • Combination of Java and C/C++ native libraries where interaction between sources will happen, such as mapping between the java application APIs and the native C++ libraries

hardware: Hardware implementation

  • The Android Hardware Abstraction Layer specification and implementation

libnativehelper:

  • Helper functions for use with Java Native Interface (JNI)

kernel: Prebuilt kernel files

  • Just binary files, source code does not come here

packages: Applications

  • Source code of default application such as Contacts, Calendar, etc.

prebuilt: Binary tools

  • Files that are distributed in binary form for convenience
  • Include the cross compilations toolchain for different development machines

system: Android core

  • That is the minimal Linux system that is started before the Dalvik VM and any java based services are enabled
  • This includes the source code for the init process and the default init.rc script that provide the dynamic configuration of the platform

sdk: Base additional apps

  • Useful apps that developers can leverage on and can be enhanced further as part of the operating system.

vendor: Vendor-specific stuff

  • It is vendor-specific and contains custom apps, SE policies, hardware configurations, and so on.
  • This folder is not part of the AOSP source.

Source code Tools

Android Code Search is an online source code searching engine, and cross referencing.

AOSP Build Environment build/envsetup.sh is provided as a script to initialize the workspace, and it must be always activated before any build.

Android Studio for Platform is the version of the Android Studio IDE for Android Open Source Project platform.

Build a Target

Set up Environment

Activate AOSP Build Environment:

cd $AOSP_HOME/$AOSP_BRANCH
source build/envsetup.sh

This script provides methods to make different targets, commands for searching:

Make targets

List of make targets:

  • make all - make everything, whether it is included in the product definition or not.
  • make clean - remove all built files (prepare for a new build).
  • make sdk - build the tools that are part of an SDK (adb, fastboot, etc.)
  • make snod - build the system image from the current software binaries.
  • make modules - shows a list of submodules that can be built.
  • make <local_module> - make a specific module defined in LOCAL_MODULE in the Android.mk, not the same as directory name
  • make clean-<local_module> - clean a specific module

Build Macros

  • croot - change directory to the top of the tree
  • m - execute make from the top of the tree (even if your current directory is somewhere else)
  • mm - builds all the modules in the current directory
  • mmm <dir1> ... - Builds all the modules in the supplied directories, but not their dependencies.
  • mma - Builds all the modules in the current directory, and their dependencies.
  • mmma <dir1> ... - Builds all the modules in the supplied directories, and their dependencies.
  • allmod - List all of Modules.
  • gomod <module> - Jump to the folder of calling module.
  • outmod <module>- Returns the output file for the module (.so/.jar/.apk/…)

Search Macros

  • cgrep <PATTERN> - Greps on all local C/C++ files.
  • ggrep <PATTERN> - Greps on all local Gradle files.
  • jgrep <PATTERN> - Greps on all local Java files.
  • resgrep <PATTERN> - Greps on all local res/*.xml files.
  • mangrep <PATTERN> - Greps on all local AndroidManifest.xml files.
  • mgrep <PATTERN> - Greps on all local Makefiles files.
  • sepgrep <PATTERN> - Greps on all local sepolicy files.
  • sgrep <PATTERN> - Greps on all local source files.
  • godir <filename> - Go to the directory containing a file

Select a Target

There are some kinds of target device:

Physical Device

  • This is the real hardware, but it is not always available
  • The best environment to test and develop because it is how thing actually run with real devices and environment
  • The build will need some specific packages for the target, such as the drivers, configurations (usually known as Board Support Packages)

Android Emulator can run the entire Android Architecture with different Android Virtual Device (AVD) images:

  • An AVD containts the full Android software stack, with many functional hooks to appeal to the use cases of the Android app developer
  • This may present challenges when building an AVD with customized Android framework due to virtual drivers / devices
  • The target is usually named sdk_car

Cuttlefish is a configurable virtual Android device that can run both remotely (using third-party cloud offerings such as Google Cloud Engine) and locally (on Linux x86 and ARM64 machines).

  • Cuttlefish Virtual Device contains a configurable virtual Android device, including all of the framework code and any custom platform code
  • Replicate the framework-based behavior of a real device with a focus on high fidelity by maintaining close alignment with the core framework
  • The target is usually named aosp_cf_*_auto

Product Definition

The target selection is an option listed in COMMON_LUNCH_CHOICES which is defined across multiple AndroidProducts.mk files.

To see all lunch target, run the command:

lunch

then select an option by its index or name.

Lunch targets

android-14.0.0_r74
Lunch menu .. Here are the common combinations:
      1. aosp_akita-trunk_staging-userdebug
      2. aosp_arm-trunk_staging-eng
      3. aosp_arm64-trunk_staging-eng
      4. aosp_barbet-trunk_staging-userdebug
      5. aosp_bluejay-trunk_staging-userdebug
      6. aosp_bluejay_car-trunk_staging-userdebug
      7. aosp_bramble-trunk_staging-userdebug
      8. aosp_bramble_car-trunk_staging-userdebug
      9. aosp_caiman-trunk_staging-userdebug
     10. aosp_cf_arm64_auto-trunk_staging-userdebug
     11. aosp_cf_arm64_phone-trunk_staging-userdebug
     12. aosp_cf_riscv64_phone-trunk_staging-userdebug
     13. aosp_cf_x86_64_auto-trunk_staging-userdebug
     14. aosp_cf_x86_64_auto_mdnd-trunk_staging-userdebug
     15. aosp_cf_x86_64_foldable-trunk_staging-userdebug
     16. aosp_cf_x86_64_only_phone_hsum-trunk_staging-userdebug
     17. aosp_cf_x86_64_pc-trunk_staging-userdebug
     18. aosp_cf_x86_64_phone-trunk_staging-userdebug
     19. aosp_cf_x86_64_tv-trunk_staging-userdebug
     20. aosp_cf_x86_phone-trunk_staging-userdebug
     21. aosp_cf_x86_tv-trunk_staging-userdebug
     22. aosp_cheetah-trunk_staging-userdebug
     23. aosp_cheetah_car-trunk_staging-userdebug
     24. aosp_cheetah_hwasan-trunk_staging-userdebug
     25. aosp_cloudripper-trunk_staging-userdebug
     26. aosp_comet-trunk_staging-userdebug
     27. aosp_coral-trunk_staging-userdebug
     28. aosp_felix-trunk_staging-userdebug
     29. aosp_flame-trunk_staging-userdebug
     30. aosp_husky-trunk_staging-userdebug
     31. aosp_komodo-trunk_staging-userdebug
     32. aosp_lynx-trunk_staging-userdebug
     33. aosp_oriole-trunk_staging-userdebug
     34. aosp_oriole_car-trunk_staging-userdebug
     35. aosp_panther-trunk_staging-userdebug
     36. aosp_panther_car-trunk_staging-userdebug
     37. aosp_panther_hwasan-trunk_staging-userdebug
     38. aosp_raven-trunk_staging-userdebug
     39. aosp_raven_car-trunk_staging-userdebug
     40. aosp_ravenclaw-trunk_staging-userdebug
     41. aosp_redfin-trunk_staging-userdebug
     42. aosp_redfin_car-trunk_staging-userdebug
     43. aosp_redfin_vf-trunk_staging-userdebug
     44. aosp_ripcurrent-trunk_staging-userdebug
     45. aosp_ripcurrent24-trunk_staging-userdebug
     46. aosp_ripcurrentpro-trunk_staging-userdebug
     47. aosp_shiba-trunk_staging-userdebug
     48. aosp_slider-trunk_staging-userdebug
     49. aosp_sunfish-trunk_staging-userdebug
     50. aosp_sunfish_car-trunk_staging-userdebug
     51. aosp_tangorpro-trunk_staging-userdebug
     52. aosp_tangorpro_car-trunk_staging-userdebug
     53. aosp_tokay-trunk_staging-userdebug
     54. aosp_trout_arm64-trunk_staging-userdebug
     55. aosp_trout_x86_64-trunk_staging-userdebug
     56. aosp_whitefin-trunk_staging-userdebug
     57. aosp_x86-trunk_staging-eng
     58. aosp_x86_64-trunk_staging-eng
     59. arm_krait-trunk_staging-eng
     60. arm_v7_v8-trunk_staging-eng
     61. armv8-trunk_staging-eng
     62. armv8_cortex_a55-trunk_staging-eng
     63. armv8_kryo385-trunk_staging-eng
     64. db845c-trunk_staging-userdebug
     65. gsi_car_arm64-trunk_staging-userdebug
     66. gsi_car_x86_64-trunk_staging-userdebug
     67. hikey-trunk_staging-userdebug
     68. hikey64_only-trunk_staging-userdebug
     69. hikey960-trunk_staging-userdebug
     70. hikey960_tv-trunk_staging-userdebug
     71. hikey_tv-trunk_staging-userdebug
     72. poplar-trunk_staging-eng
     73. poplar-trunk_staging-user
     74. poplar-trunk_staging-userdebug
     75. qemu_trusty_arm64-trunk_staging-userdebug
     76. rb5-trunk_staging-userdebug
     77. riscv64-trunk_staging-eng
     78. sdk_car_arm64-trunk_staging-userdebug
     79. sdk_car_md_x86_64-trunk_staging-userdebug
     80. sdk_car_portrait_x86_64-trunk_staging-userdebug
     81. sdk_car_x86_64-trunk_staging-userdebug
     82. silvermont-trunk_staging-eng
     83. uml-trunk_staging-userdebug
     84. yukawa-trunk_staging-userdebug
     85. yukawa_sei510-trunk_staging-userdebug

If there is an error that prevents lunch to show all target. Here is a quick fix:

  • run export TARGET_RELEASE=trunk_staging,
  • then run build_build_var_cache,
  • then finally run lunch again.

Each target name contains:

  • TARGET_PRODUCT, for example, a combination of aosp for google AOSP, then optinally cf for cuttlefish device, then Architecture x86_64 and Hardware (codename) such as auto, to make the final name aosp_cf_x86_64_auto TARGET_RELEASE is set to trunk_staging.
  • TARGET_BUILD_VARIANT is one of user (for production), userdebug (with debugging enabled), and eng (fast build, for development).

Build Cuttlefish Emulator

Cuttlefish is recommended for platform development. Working on Automotive Android is likely to do something in the Platform side, so this is a first choice when selecting an emulator.

Build Cuttlefish Image

Find a cuttlefish product:

mgrep "aosp_cf_x86_64_auto"
google/cuttlefish/AndroidProducts.mk:  aosp_cf_x86_64_auto-trunk_staging-userdebug
google/cuttlefish/AndroidProducts.mk:  aosp_cf_x86_64_auto_mdnd-trunk_staging-userdebug

Select the target:

cd $AOSP_HOME/$AOSP_BRANCH
source build/envsetup.sh
lunch aosp_cf_x86_64_auto-trunk_staging-userdebug

Now, compile the target:

m -j$(nproc)

The image is located at out/target/product/vsoc_x86_64_only.

Some problems may happen.

  • ccache is readonly → mount ccache to a different point:

    sudo mkdir -p /mnt/ccache
    sudo mount --bind ~/.ccache /mnt/ccache
    export USE_CCACHE=1
    export CCACHE_EXEC=/usr/bin/ccache
    export CCACHE_DIR=/mnt/ccache

  • test is not found → exclude them from test list:

    nano platform_testing/build/tasks/tests/native_test_list.mk
    ifeq ($(BOARD_IS_AUTOMOTIVE), true)
    native_tests += \
        libwatchdog_test \
        evsmanagerd_test \
        #sv_2d_session_tests \
        #sv_3d_session_tests
    endif

  • some randome failures → lower the threads, such as from -j20 to -j10

Build Cuttlefish Device

Refer: https://source.android.com/docs/devices/cuttlefish/get-started.

Verify KVM availability, this command should return a nonzero value:

grep -c -w "vmx\|svm" /proc/cpuinfo

Download support packages:

sudo apt update
sudo apt install devscripts equivs config-package-dev debhelper-compat golang

Download Cuttlefish source code:

cd $AOSP_HOME
git clone https://github.com/google/android-cuttlefish

Compile Cuttlefish packages:

cd android-cuttlefish
tools/buildutils/build_packages.sh

Install Cuttlefish packages:

sudo dpkg -i ./cuttlefish-base_*_*64.deb || sudo apt-get install -f
sudo dpkg -i ./cuttlefish-user_*_*64.deb || sudo apt-get install -f
sudo usermod -aG kvm,cvdnetwork,render $USER

Finally, reboot system to apply changes, trigger installing additional kernel modules and applies udev rules.

sudo reboot

Launch Cuttlefish

Cuttlefish virtual device needs to know the built target’s artifacts to find required configs and images, so it always needs to enter the build environment:

cd $AOSP_HOME/$AOSP_BRANCH
source build/envsetup.sh
lunch aosp_cf_x86_64_auto-trunk_staging-userdebug

Now run the emulator:

launch_cvd --gpu_mode=gfxstream

Cuttlefish launches with --start_webrtc, which enables a webview through port 8443 on the host machine.

Useful debugging information:

  • Point browser to https://localhost:8443 to interact with the device.
  • Serial console is disabled; use -console=true to enable it.
  • Logcat output: ~/cuttlefish/instances/cvd-1/logs/logcat
  • Kernel log: ~/cuttlefish/instances/cvd-1/kernel.log
  • Launcher log: ~/cuttlefish/instances/cvd-1/logs/launcher.log
  • Instance configuration: ~/cuttlefish/instances/cvd-1/cuttlefish_config.json
  • Launcher Build ID: eng.trongv.20241007.012401

Android Platform Tools

Android platform tools are provide in this package:

sudo apt install google-android-platform-tools-installer

Emulator can be accessed via adb as a normal Android device. For example, check the kernel version:

adb devices
List of devices attached
0.0.0.0:6520  device
adb shell

In the device shell, check the kernel version:

vsoc_x86_64_only
uname -a
Linux localhost 6.1.68-android14-11-ga7f647f49daf-ab11484633 #1 SMP PREEMPT Wed Feb 21 00:52:15 UTC 2024 x86_64 Toybox

The kernel version is correct for android14.

"Cuttlefish device"

For stop, restart or reset the emulator:

  • If device is responsive, perform a clean restart using adb reboot.
  • If device is unresponsive, perform an unclean restart using restart_cvd.
  • Reset the device state using powerwash_cvd.
  • Stop the device and exit stop_cvd
  • Stop the device and launch again with specifi flag launch_cvd --resume=false

Build Android Virtual Device

Find an AVD SDK product:

mgrep "sdk_car_x86_64" --include=AndroidProducts.mk
./device/generic/car/AndroidProducts.mk:32:    sdk_car_x86_64-trunk_staging-userdebug \

Select the target:

cd $AOSP_HOME/$AOSP_BRANCH
source build/envsetup.sh
lunch sdk_car_x86_64-trunk_staging-userdebug

Now, compile the target:

m -j$(nproc)

The image is located at out/target/product/emulator_car64_x86_64.

Run AVD Emulator

Android Emulator is provided as a prebuilt tool in AOSP, located in prebuilts/android-emulator/linux-x86_64/emulator. Building Emulator requires to checkout then compile a different repo.

Run the emulator:

emulator -version

Emulator Command Line provides options to run an emulator. Basically, for development:

emulator -gpu host -selinux permissive \
  -memory 8192 -writable-system -show-kernel \
  -no-audio \
  -no-snapshot -wipe-data

Most used options:

  • verbose: displays which files and settings are actually selected when starting
  • shell: open the root shell
  • show-kernel: option to show the kernel console, it’s good for debugging
  • selinux {disabled|permissive}: SELinux will not be enforced
  • gpu {host|guest}: use
  • writable-system: system is writable so it can save user’s created files
  • no-boot-anim: disable the boot animation
  • no-snapshot: do not save system state
  • wipe-data: remove all user data

emulator

Connect to he device shell, and check the kernel version:

emulator_car64_x86_64
uname -a
Linux localhost 6.6.9-android15-0-g515a956763d8-ab11275718 #1 SMP PREEMPT Thu Jan  4 21:38:14 UTC 2024 x86_64 Toybox

It seems that the kernel version is wrong! It should be android14 for sdk_car_x86_64.

This is an error that the service bt* is created and killed repeatly.

P/s: even using kernel in branch common-android14-6.1, the above issue still happens.

Build Trout Device

Refer to: https://source.android.com/docs/automotive/virtualization/reference_platform

Through a new product named trout, Android Automotive (AAOS) now provides support for deployment as a guest virtual machine (VM) in environments compatible with the VirtIO standard. trout is based on the Cuttlefish virtual reference platform and is available as the trout device configuration.

cd $AOSP_HOME/$AOSP_BRANCH
source build/envsetup.sh
lunch aosp_trout_x86_64-trunk_staging-userdebug

However, at this time, trout target can not be built!