Build Android

Follow the instructions on this page to build Android.

Set up your build environment

From within your working directory, source the envsetup.sh script to set up your build environment:

source build/envsetup.sh

This script imports several commands that let you work with the Android source code, including the commands used on this page. To view the source of the script, refer to platform/build/envsetup.sh. To view the built-in help, type hmm.

Choose a target

Before building Android, you must identify a target to build. A target reflects the target platform you're building for. To identify your target to build, use the lunch command followed by a string representing the target. For example:

lunch aosp_cf_x86_64_only_phone-aosp_current-userdebug

You should see a synopsis of your target and build environment:

============================================
PLATFORM_VERSION_CODENAME=Baklava
PLATFORM_VERSION=Baklava
TARGET_PRODUCT=aosp_cf_x86_64_only_phone
TARGET_BUILD_VARIANT=userdebug
TARGET_ARCH=x86_64
TARGET_ARCH_VARIANT=silvermont
HOST_OS=linux
HOST_OS_EXTRA=Linux-6.10.11-1rodete2-amd64-x86_64-Debian-GNU/Linux-rodete
HOST_CROSS_OS=windows
BUILD_ID=BP1A.250305.020
OUT_DIR=out
============================================

The string representing the target has the following format:

lunch product_name-release_config-build_variant

The components of this string are:

  • The product_name is the name of the product you want to build, such as aosp_cf_x86_64_only_phone or aosp_husky. Your specific product_name can follow your own format for your device, but the format that Google uses for its devices has these components:

    • aosp refers to the Android Open Source Project.
    • Optionally, cf is included when the target is intended to be run within the Cuttlefish emulator.
    • Architecture and hardware codename, such as x86_64_only_phone or husky, which is the codename for Pixel 8 Pro. For a list of codenames for Google devices, see Device codenames.

  • release_config is set to a release configuration, such as the development release configuration called aosp_current. A release configuration identifies certain features and code that are behind feature launch flags and are either enabled or disabled for a build. For more on release configurations, see Set feature flag launch values.

  • The build_variant portion of the string can be one of the three values in the following table:

    build_variant Description
    user This build variant provides limited security access and is suited for production.
    userdebug This build variant helps the device developers understand the performance and power of in-development releases. When developing with a userdebug build, follow the Guidelines for userdebug.
    eng This build variant has faster build time and is best suited for day-to-day development environments (where performance and power are less important).

If you run lunch without any arguments, lunch provides a list of common targets. To create custom target strings, combine target string elements with hardware codenames. For a list of codenames, see Device codenames.

View the current target

To see the current lunch settings, run:

$ echo "$TARGET_PRODUCT-$TARGET_BUILD_VARIANT"

Build the code

Run the following command to build your target. Depending on the specification of your workstation, the first build could take less than an hour and up to a few hours. Subsequent builds take significantly less time.

m

The output of your build appears in $OUT_DIR. If you build different targets, each target build appears in $OUT_DIR.

The m command builds from the top of the tree, so you can run m from within subdirectories. If you have the TOP environment variable set, the m command uses it. If TOP isn't set, the m command looks up the tree from the current directory, trying to find the top of the tree.

The m command can handle parallel tasks with a -jN argument. If you don't provide a -j argument, the build system automatically selects a parallel task count that it thinks is optimal for your system.

You can build specific modules instead of the full device image by listing module names in your m command line. In addition, the m command provides some pseudo targets, called goals. For example, m nothing doesn't build anything, but parses and validates the build structure. For a list of valid goals, type m help.

Troubleshoot build errors

This section contains instructions for handling build errors.

Read-only file system errors (Android 17 and higher)

During the build, the AOSP source tree is read-only. If the build you're running attempts to modify the source tree during product config or any other part of the build, the build might fail and report read-only file system errors. You can use these options to temporarily change the source tree to read-write:

  • To change the entire source tree to read-write during the build, add BUILD_BROKEN_SRC_DIR_IS_WRITABLE=true to the build environment.

  • To change a portion of the tree to read-write during the build, use BUILD_BROKEN_SRC_DIR_RW_ALLOWLIST="path1, path2, ...". The paths should be the paths of the directories in which writes should be allowed, relative to the top of the workspace.

Wrong Java version (Android 8.0 and lower)

If you're building Android 8.0 (API level 26) and lower, m might abort when it encounters an issue with your version of Java. For example, you might get this message:

************************************************************
You are attempting to build with the incorrect version of java.

Your version is: WRONG_VERSION.
The correct version is: RIGHT_VERSION.

Please follow the machine setup instructions at
https://source.android.com/source/initializing.html
************************************************************

Here are the likely causes and solutions:

  • The correct JDK isn't installed. For more information, see Set up for AOSP development (2.3-8.0).
  • There's another previously installed JDK appearing in your path. Prepend the correct JDK to the beginning of your path or remove the problematic JDK.