Building Android

See the Android Make Build System description in the Android Open Source Project (AOSP) for instructions and build system changes for Android.mk writers.

The Soong build system was introduced in Android 8.0 (Oreo) with support for `android_test` arriving in Android Q, now available in the Android Open Source Project (AOSP) master branch.

Set up environment

Initialize the environment with the envsetup.sh script. Note that replacing source with . (a single dot) saves a few characters, and the short form is more commonly used in documentation.

source build/envsetup.sh

or

. build/envsetup.sh

You will need to re-issue this command after every repo sync to pick up any changes to that script.

The envsetup.sh script imports several commands that enable you to work with the Android source code, including the commands used in this exercise. Here are some important command examples:

• lunch - lunch product_name-build_variant selects product_name as the product to build, and build_variant as the variant to build, and stores those selections in the environment to be read by subsequent invocations of m and other similar commands.
• m - Runs builds from the top of the tree. This is useful because you can run make from within subdirectories. If you have the TOP environment variable set, it uses that. If you don't, it looks up the tree from the current directory, trying to find the top of the tree. You can either build the whole source code tree by running m without arguments or build specific targets by specifying their names.
• mma - Builds all of the modules in the current directory, and their dependencies.
• mmma - Builds all of the modules in the supplied directories, and their dependencies.
• croot - cd to the top of the tree.

To see the full list of available commands, run:

hmm

Choose a target

Choose which target to build with lunch. The exact configuration can be passed as an argument. For example, the following command refers to a complete build for the emulator, with all debugging enabled:

lunch aosp_arm-eng

If run with no arguments, lunch prompts you to choose a target from the menu. See Selecting a device build for the build configurations of all existing devices.

All build targets take the form BUILD-BUILDTYPE, where the BUILD is a codename referring to the particular feature combination. The BUILDTYPE is one of the following.

The userdebug build should behave the same as the user build, with the ability to enable additional debugging that normally violates the security model of the platform. This makes the userdebug build good for user testing with greater diagnosis capabilities. When developing with the userdebug build, follow the userdebug guidelines.

The eng build prioritizes engineering productivity for engineers who work on the platform. The eng build turns off various optimizations used to provide a good user experience. Otherwise, the eng build has behavior similar to the user and userdebug builds so that device developers can see how the code behaves in those environments.

For more information about building for and running on actual hardware, see Running Builds.

Building the code

This section is a quick summary to ensure that setup is complete.

Build everything with m. m 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.

m

As explained above, you can build specific modules instead of the full device image by listing their names in your m command line. In addition, m provides some pseudotargets for special purposes. Some examples are:

• droid - m droid is the normal build. This target is here because the default target requires a name.
• all - m all builds everything that m droid does, plus everything that doesn't have the droid tag. The build server runs this to make sure that everything that is in the tree and has an Android.mk file builds.
• clean - m clean deletes all of the output and intermediate files for this configuration. This is the same as rm -rf out/.

Run m help to see what other pseudotargets m provides.

Run it!

You can either run your build on an emulator or flash it on a device. Note that you've already selected your build target with lunch, and it's unlikely to run on a different target than it was built for.

Flashing with fastboot

To flash a device, use fastboot, which should be included in your path after a successful build. See Flashing a device for instructions.

Emulating an Android device

The emulator is added to your path automatically by the build process. To run the emulator, type:

emulator

Troubleshooting common build errors

Wrong Java version

If you're attempting to build a version of Android that's inconsistent with your version of Java, make aborts with a message such as:

************************************************************
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:

• Failure to install the correct JDK as specified in JDK Requirements. Make sure you've followed the steps in Setting up the environment and Choosing a target.
• Another JDK previously installed appearing in your path. Prepend the correct JDK to the beginning of your path or remove the problematic JDK.

Python version 3

Repo is built on particular functionality from Python 2.x and is incompatible with Python 3. To use Repo, install Python 2.x:

apt-get install python

Case-insensitive file system

If you're building on an HFS file system on macOS, you may encounter an error such as:

************************************************************
You are building on a case-insensitive filesystem.
Please move your source tree to a case-sensitive filesystem.
************************************************************

Follow the instructions in Creating a case-sensitive disk image.

No USB permission

By default on most Linux systems, unprivileged users can't access USB ports. If you see a permission denied error, follow the instructions in Configuring USB access.

If adb was already running and can't connect to the device after getting those rules set up, you can kill it with adb kill-server. That command causes adb to restart with the new configuration.