Initializing a Build Environment
This section describes how to set up your local work environment to build the Android source files. You will need to use Linux or Mac OS. Building under Windows is not currently supported.
For an overview of the entire code-review and code-update process, see Life of a Patch.
Choosing a Branch
Some of the requirements for your build environment are determined by which version of the source code you plan to compile. See Build Numbers for a full listing of branches you may choose from. You may also choose to download and build the latest source code (calledmaster
), in which case you will simply omit the branch specification when you initialize the repository.
Once you have selected a branch, follow the appropriate instructions below to set up your build environment.
Setting up a Linux build environment
These instructions apply to all branches, including master
.
The Android build is routinely tested in house on recent versions of Ubuntu LTS (14.04), but most distributions should have the required build tools available. Reports of successes or failures on other distributions are welcome.
For Gingerbread (2.3.x) and newer versions, including the master
branch, a 64-bit environment is required. Older versions can be compiled on 32-bit systems.
Note: See the Downloading and Building page for the list of hardware and software requirements. Then follow the detailed instructions for Ubuntu and Mac OS below.
Installing the JDK
The master
branch of Android in the Android Open Source Project (AOSP) requires Java 7. On Ubuntu, useOpenJDK.
Java 7: For the latest version of Android
$ sudo apt-get update
$ sudo apt-get install openjdk-7-jdk
Optionally, update the default Java version by running:
$ sudo update-alternatives --config java
$ sudo update-alternatives --config javac
If you encounter version errors for Java, set its path as described in the Wrong Java Version section.
To develop older versions of Android, download and install the corresponding version of the Java JDK:
Java 6: for Gingerbread through KitKat
Java 5: for Cupcake through Froyo
Note: The lunch
command in the build step will ensure that the Sun JDK is used instead of any previously installed JDK.
Installing required packages (Ubuntu 14.04)
You will need a 64-bit version of Ubuntu. Ubuntu 14.04 is recommended.
$ sudo apt-get install bison g++-multilib git gperf libxml2-utils make python-networkx zlib1g-dev:i386 zip
Installing required packages (Ubuntu 12.04)
You may use Ubuntu 12.04 to build older versions of Android. Version 12.04 is not supported on master or recent releases.
$ sudo apt-get install git gnupg flex bison gperf build-essential \
zip curl libc6-dev libncurses5-dev:i386 x11proto-core-dev \
libx11-dev:i386 libreadline6-dev:i386 libgl1-mesa-glx:i386 \
libgl1-mesa-dev g++-multilib mingw32 tofrodos \
python-markdown libxml2-utils xsltproc zlib1g-dev:i386
$ sudo ln -s /usr/lib/i386-linux-gnu/mesa/libGL.so.1 /usr/lib/i386-linux-gnu/libGL.so
Installing required packages (Ubuntu 10.04 -- 11.10)
Building on Ubuntu 10.04-11.10 is no longer supported, but may be useful for building older releases of AOSP.
$ sudo apt-get install git gnupg flex bison gperf build-essential \
zip curl zlib1g-dev libc6-dev lib32ncurses5-dev ia32-libs \
x11proto-core-dev libx11-dev lib32readline5-dev lib32z-dev \
libgl1-mesa-dev g++-multilib mingw32 tofrodos python-markdown \
libxml2-utils xsltproc
On Ubuntu 10.10:
$ sudo ln -s /usr/lib32/mesa/libGL.so.1 /usr/lib32/mesa/libGL.so
On Ubuntu 11.10:
$ sudo apt-get install libx11-dev:i386
Configuring USB Access
Under GNU/Linux systems (and specifically under Ubuntu systems), regular users can't directly access USB devices by default. The system needs to be configured to allow such access.
The recommended approach is to create a file /etc/udev/rules.d/51-android.rules
(as the root user) and to copy the following lines in it. <username>
must be replaced by the actual username of the user who is authorized to access the phones over USB.
# adb protocol on passion (Nexus One)
SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e12", MODE="0600", OWNER="<username>"
# fastboot protocol on passion (Nexus One)
SUBSYSTEM=="usb", ATTR{idVendor}=="0bb4", ATTR{idProduct}=="0fff", MODE="0600", OWNER="<username>"
# adb protocol on crespo/crespo4g (Nexus S)
SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e22", MODE="0600", OWNER="<username>"
# fastboot protocol on crespo/crespo4g (Nexus S)
SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e20", MODE="0600", OWNER="<username>"
# adb protocol on stingray/wingray (Xoom)
SUBSYSTEM=="usb", ATTR{idVendor}=="22b8", ATTR{idProduct}=="70a9", MODE="0600", OWNER="<username>"
# fastboot protocol on stingray/wingray (Xoom)
SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="708c", MODE="0600", OWNER="<username>"
# adb protocol on maguro/toro (Galaxy Nexus)
SUBSYSTEM=="usb", ATTR{idVendor}=="04e8", ATTR{idProduct}=="6860", MODE="0600", OWNER="<username>"
# fastboot protocol on maguro/toro (Galaxy Nexus)
SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e30", MODE="0600", OWNER="<username>"
# adb protocol on panda (PandaBoard)
SUBSYSTEM=="usb", ATTR{idVendor}=="0451", ATTR{idProduct}=="d101", MODE="0600", OWNER="<username>"
# adb protocol on panda (PandaBoard ES)
SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="d002", MODE="0600", OWNER="<username>"
# fastboot protocol on panda (PandaBoard)
SUBSYSTEM=="usb", ATTR{idVendor}=="0451", ATTR{idProduct}=="d022", MODE="0600", OWNER="<username>"
# usbboot protocol on panda (PandaBoard)
SUBSYSTEM=="usb", ATTR{idVendor}=="0451", ATTR{idProduct}=="d00f", MODE="0600", OWNER="<username>"
# usbboot protocol on panda (PandaBoard ES)
SUBSYSTEM=="usb", ATTR{idVendor}=="0451", ATTR{idProduct}=="d010", MODE="0600", OWNER="<username>"
# adb protocol on grouper/tilapia (Nexus 7)
SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e42", MODE="0600", OWNER="<username>"
# fastboot protocol on grouper/tilapia (Nexus 7)
SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e40", MODE="0600", OWNER="<username>"
# adb protocol on manta (Nexus 10)
SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4ee2", MODE="0600", OWNER="<username>"
# fastboot protocol on manta (Nexus 10)
SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4ee0", MODE="0600", OWNER="<username>"
Those new rules take effect the next time a device is plugged in. It might therefore be necessary to unplug the device and plug it back into the computer.
This is known to work on both Ubuntu Hardy Heron (8.04.x LTS) and Lucid Lynx (10.04.x LTS). Other versions of Ubuntu or other variants of GNU/Linux might require different configurations.
Using a separate output directory
By default, the output of each build is stored in the out/
subdirectory of the matching source tree.
On some machines with multiple storage devices, builds are faster when storing the source files and the output on separate volumes. For additional performance, the output can be stored on a filesystem optimized for speed instead of crash robustness, since all files can be re-generated in case of filesystem corruption.
To set this up, export the OUT_DIR_COMMON_BASE
variable to point to the location where your output directories will be stored.
export OUT_DIR_COMMON_BASE=<path-to-your-out-directory>
The output directory for each separate source tree will be named after the directory holding the source tree.
For instance, if you have source trees as /source/master1
and /source/master2
and OUT_DIR_COMMON_BASE
is set to /output
, the output directories will be /output/master1
and /output/master2
.
It's important in that case to not have multiple source trees stored in directories that have the same name, as those would end up sharing an output directory, with unpredictable results.
This is only supported on Jelly Bean (4.1) and newer, including the master
branch.
Setting up a Mac OS build environment
In a default installation, Mac OS runs on a case-preserving but case-insensitive filesystem. This type of filesystem is not supported by git and will cause some git commands (such as git status
) to behave abnormally. Because of this, we recommend that you always work with the AOSP source files on a case-sensitive filesystem. This can be done fairly easily using a disk image, discussed below.
Once the proper filesystem is available, building the master
branch in a modern Mac OS environment is very straightforward. Earlier branches, including ICS, require some additional tools and SDKs.
Creating a case-sensitive disk image
You can create a case-sensitive filesystem within your existing Mac OS environment using a disk image. To create the image, launch Disk Utility and select "New Image". A size of 25GB is the minimum to complete the build; larger numbers are more future-proof. Using sparse images saves space while allowing to grow later as the need arises. Be sure to select "case sensitive, journaled" as the volume format.
You can also create it from a shell with the following command:
# hdiutil create -type SPARSE -fs 'Case-sensitive Journaled HFS+' -size 40g ~/android.dmg
This will create a .dmg
(or possibly a .dmg.sparsefile
) file which, once mounted, acts as a drive with the required formatting for Android development.
If you need a larger volume later, you can also resize the sparse image with the following command:
# hdiutil resize -size <new-size-you-want>g ~/android.dmg.sparseimage
For a disk image named
android.dmg
stored in your home directory, you can add helper functions to your
~/.bash_profile
:
- To mount the image when you execute
mountAndroid
:# mount the android file image function mountAndroid { hdiutil attach ~/android.dmg -mountpoint /Volumes/android; }
Note: If your system created a
.dmg.sparsefile
file, replace~/android.dmg
with~/android.dmg.sparsefile
. -
To unmount it when you execute
umountAndroid
:# unmount the android file image function umountAndroid() { hdiutil detach /Volumes/android; }
Once you've mounted the android
volume, you'll do all your work there. You can eject it (unmount it) just like you would with an external drive.
Installing the JDK
The master
and 5.0.x
branches of Android in the Android Open Source Project (AOSP) require Java 7. On Mac OS, use jdk-7u71-macosx-x64.dmg.
To develop for versions of Android Gingerbread through KitKat, download and install the Java 6 version of theJava JDK.
Master branch
To build the latest source in a Mac OS environment, you will need an Intel/x86 machine running Mac OS X v10.8 (Mountain Lion) or later, along with Xcode 4.5.2 or later including the Command Line Tools.
Branch 5.0.x and earlier branches
To build 5.0.x and earlier source in a Mac OS environment, you will need an Intel/x86 machine running Mac OS X v10.8 (Mountain Lion), along with Xcode 4.5.2 and Command Line Tools.
Branch 4.4.x and earlier branches
To build 4.2.x and earlier source in a Mac OS environment, you will need an Intel/x86 machine running Mac OS X v10.6 (Snow Leopard) or Mac OS X v10.7 (Lion), along with Xcode 4.2 (Apple's Developer Tools). Although Lion does not come with a JDK, it should install automatically when you attempt to build the source.
The remaining sections for Mac OS apply only to those who wish to build earlier branches.
Branch 4.0.x and all earlier branches
To build android-4.0.x and earlier branches in a Mac OS environment, you need an Intel/x86 machine running Mac OS X v10.5 (Leopard) or Mac OS X v10.6 (Snow Leopard). You will need the Mac OS X v10.5 SDK.
Installing required packages
-
Install Xcode from the Apple developer site. We recommend version 3.1.4 or newer (e.g., gcc 4.2). Version 4.x could cause difficulties. If you are not already registered as an Apple developer, you will have to create an Apple ID in order to download.
-
Install MacPorts from macports.org.
Note: Make sure that
/opt/local/bin
appears in your path before/usr/bin
. If not, please add the following to your~/.bash_profile
file:export PATH=/opt/local/bin:$PATH
Note: If you do not have a
.bash_profile
file in your home directory, create one. -
Get make, git, and GPG packages from MacPorts:
$ POSIXLY_CORRECT=1 sudo port install gmake libsdl git gnupg
If using Mac OS X v10.4, also install bison:
$ POSIXLY_CORRECT=1 sudo port install bison
Reverting from make 3.82
For versions of Android before ICS, there is a bug in gmake 3.82 that prevents android from building. You can install version 3.81 using MacPorts by taking the following steps:
-
Edit
/opt/local/etc/macports/sources.conf
and add a line that saysfile:///Users/Shared/dports
above the rsync line. Then create this directory:
$ mkdir /Users/Shared/dports
-
In the new
dports
directory, run$ svn co --revision 50980 http://svn.macports.org/repository/macports/trunk/dports/devel/gmake/ devel/gmake/
-
Create a port index for your new local repository:
$ portindex /Users/Shared/dports
-
Finally, install the old version of gmake with
$ sudo port install gmake @3.81
Setting a file descriptor limit
On Mac OS, the default limit on the number of simultaneous file descriptors open is too low and a highly parallel build process may exceed this limit.
To increase the cap, add the following lines to your ~/.bash_profile
:
# set the number of open files to be 1024
ulimit -S -n 1024
Optimizing a build environment (optional)
Setting up ccache
You can optionally tell the build to use the ccache compilation tool. Ccache acts as a compiler cache that can be used to speed up rebuilds. This works very well if you use make clean
often, or if you frequently switch between different build products.
Put the following in your .bashrc
(or equivalent):
export USE_CCACHE=1
By default the cache will be stored in ~/.ccache
. If your home directory is on NFS or some other non-local filesystem, you will want to specify the directory in your .bashrc
file as well:
export CCACHE_DIR=<path-to-your-cache-directory>
The suggested cache size is 50-100GB. You will need to run the following command once you have downloaded the source code:
prebuilts/misc/linux-x86/ccache/ccache -M 50G
On Mac OS, you should replace linux-x86
with darwin-x86
:
prebuilts/misc/darwin-x86/ccache/ccache -M 50G
When building Ice Cream Sandwich (4.0.x) or older, ccache is in a different location:
prebuilt/linux-x86/ccache/ccache -M 50G
This setting is stored in the CCACHE_DIR and is persistent.
Downloading the Source
The Android source tree is located in a Git repository hosted by Google. This document describes how to download the source tree for a specific Android code-line.
Installing Repo
Repo is a tool that makes it easier to work with Git in the context of Android. For more information about Repo, see the Developing section.
To install Repo:
-
Make sure you have a bin/ directory in your home directory and that it is included in your path:
$ mkdir ~/bin $ PATH=~/bin:$PATH
-
Download the Repo tool and ensure that it is executable:
$ curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo $ chmod a+x ~/bin/repo
For version 1.17, the SHA-1 checksum for repo is ddd79b6d5a7807e911b524cb223bc3544b661c28
For version 1.19, the SHA-1 checksum for repo is 92cbad8c880f697b58ed83e348d06619f8098e6c
For version 1.20, the SHA-1 checksum for repo is e197cb48ff4ddda4d11f23940d316e323b29671c
For version 1.21, the SHA-1 checksum for repo is b8bd1804f432ecf1bab730949c82b93b0fc5fede
Initializing a Repo client
After installing Repo, set up your client to access the Android source repository:
-
Create an empty directory to hold your working files. If you're using MacOS, this has to be on a case-sensitive filesystem. Give it any name you like:
$ mkdir WORKING_DIRECTORY $ cd WORKING_DIRECTORY
-
Run
repo init
to bring down the latest version of Repo with all its most recent bug fixes. You must specify a URL for the manifest, which specifies where the various repositories included in the Android source will be placed within your working directory.$ repo init -u https://android.googlesource.com/platform/manifest
To check out a branch other than "master", specify it with
-b
. For a list of branches, see Source Code Tags and Builds.$ repo init -u https://android.googlesource.com/platform/manifest -b android-4.0.1_r1
-
When prompted, configure Repo with your real name and email address. To use the Gerrit code-review tool, you will need an email address that is connected with a registered Google account. Make sure this is a live address at which you can receive messages. The name that you provide here will show up in attributions for your code submissions.
A successful initialization will end with a message stating that Repo is initialized in your working directory. Your client directory should now contain a .repo
directory where files such as the manifest will be kept.
Downloading the Android Source Tree
To pull down the Android source tree to your working directory from the repositories as specified in the default manifest, run
$ repo sync
The Android source files will be located in your working directory under their project names. The initial sync operation will take an hour or more to complete. For more about repo sync
and other Repo commands, see theDeveloping section.
Using Authentication
By default, access to the Android source code is anonymous. To protect the servers against excessive usage, each IP address is associated with a quota.
When sharing an IP address with other users (e.g. when accessing the source repositories from beyond a NAT firewall), the quotas can trigger even for regular usage patterns (e.g. if many users sync new clients from the same IP address within a short period).
In that case, it is possible to use authenticated access, which then uses a separate quota for each user, regardless of the IP address.
The first step is to create a password with the password generator and follow the instructions on the password generator page.
The second step is to force authenticated access, by using the following manifest URI:https://android.googlesource.com/a/platform/manifest
. Notice how the /a/
directory prefix triggers mandatory authentication. You can convert an existing client to use mandatory authentication with the following command:
$ repo init -u https://android.googlesource.com/a/platform/manifest
Troubleshooting network issues
When downloading from behind a proxy (which is common in some corporate environments), it might be necessary to explicitly specify the proxy that is then used by repo:
$ export HTTP_PROXY=http://<proxy_user_id>:<proxy_password>@<proxy_server>:<proxy_port> $ export HTTPS_PROXY=http://<proxy_user_id>:<proxy_password>@<proxy_server>:<proxy_port>
More rarely, Linux clients experience connectivity issues, getting stuck in the middle of downloads (typically during "Receiving objects"). It has been reported that tweaking the settings of the TCP/IP stack and using non-parallel commands can improve the situation. You need root access to modify the TCP setting:
$ sudo sysctl -w net.ipv4.tcp_window_scaling=0 $ repo sync -j1
Using a local mirror
When using several clients, especially in situations where bandwidth is scarce, it is better to create a local mirror of the entire server content, and to sync clients from that mirror (which requires no network access). The download for a full mirror is smaller than the download of two clients, while containing more information.
These instructions assume that the mirror is created in /usr/local/aosp/mirror
. The first step is to create and sync the mirror itself. Notice the --mirror
flag, which can be specified only when creating a new client:
$ mkdir -p /usr/local/aosp/mirror $ cd /usr/local/aosp/mirror $ repo init -u https://android.googlesource.com/mirror/manifest --mirror $ repo sync
Once the mirror is synced, new clients can be created from it. Note that it's important to specify an absolute path:
$ mkdir -p /usr/local/aosp/master $ cd /usr/local/aosp/master $ repo init -u /usr/local/aosp/mirror/platform/manifest.git $ repo sync
Finally, to sync a client against the server, the mirror needs to be synced against the server, then the client against the mirror:
$ cd /usr/local/aosp/mirror $ repo sync $ cd /usr/local/aosp/master $ repo sync
It's possible to store the mirror on a LAN server and to access it over NFS, SSH or Git. It's also possible to store it on a removable drive and to pass that drive around between users or between machines.
Verifying Git Tags
Load the following public key into your GnuPG key database. The key is used to sign annotated tags that represent releases.
$ gpg --import
Copy and paste the key(s) below, then enter EOF (Ctrl-D) to end the input and process the keys.
-----BEGIN PGP PUBLIC KEY BLOCK----- Version: GnuPG v1.4.2.2 (GNU/Linux) mQGiBEnnWD4RBACt9/h4v9xnnGDou13y3dvOx6/t43LPPIxeJ8eX9WB+8LLuROSV lFhpHawsVAcFlmi7f7jdSRF+OvtZL9ShPKdLfwBJMNkU66/TZmPewS4m782ndtw7 8tR1cXb197Ob8kOfQB3A9yk2XZ4ei4ZC3i6wVdqHLRxABdncwu5hOF9KXwCgkxMD u4PVgChaAJzTYJ1EG+UYBIUEAJmfearb0qRAN7dEoff0FeXsEaUA6U90sEoVks0Z wNj96SA8BL+a1OoEUUfpMhiHyLuQSftxisJxTh+2QclzDviDyaTrkANjdYY7p2cq /HMdOY7LJlHaqtXmZxXjjtw5Uc2QG8UY8aziU3IE9nTjSwCXeJnuyvoizl9/I1S5 jU5SA/9WwIps4SC84ielIXiGWEqq6i6/sk4I9q1YemZF2XVVKnmI1F4iCMtNKsR4 MGSa1gA8s4iQbsKNWPgp7M3a51JCVCu6l/8zTpA+uUGapw4tWCp4o0dpIvDPBEa9 b/aF/ygcR8mh5hgUfpF9IpXdknOsbKCvM9lSSfRciETykZc4wrRCVGhlIEFuZHJv aWQgT3BlbiBTb3VyY2UgUHJvamVjdCA8aW5pdGlhbC1jb250cmlidXRpb25AYW5k cm9pZC5jb20+iGAEExECACAFAknnWD4CGwMGCwkIBwMCBBUCCAMEFgIDAQIeAQIX gAAKCRDorT+BmrEOeNr+AJ42Xy6tEW7r3KzrJxnRX8mij9z8tgCdFfQYiHpYngkI 2t09Ed+9Bm4gmEO5Ag0ESedYRBAIAKVW1JcMBWvV/0Bo9WiByJ9WJ5swMN36/vAl QN4mWRhfzDOk/Rosdb0csAO/l8Kz0gKQPOfObtyYjvI8JMC3rmi+LIvSUT9806Up hisyEmmHv6U8gUb/xHLIanXGxwhYzjgeuAXVCsv+EvoPIHbY4L/KvP5x+oCJIDbk C2b1TvVk9PryzmE4BPIQL/NtgR1oLWm/uWR9zRUFtBnE411aMAN3qnAHBBMZzKMX LWBGWE0znfRrnczI5p49i2YZJAjyX1P2WzmScK49CV82dzLo71MnrF6fj+Udtb5+ OgTg7Cow+8PRaTkJEW5Y2JIZpnRUq0CYxAmHYX79EMKHDSThf/8AAwUIAJPWsB/M pK+KMs/s3r6nJrnYLTfdZhtmQXimpoDMJg1zxmL8UfNUKiQZ6esoAWtDgpqt7Y7s KZ8laHRARonte394hidZzM5nb6hQvpPjt2OlPRsyqVxw4c/KsjADtAuKW9/d8phb N8bTyOJo856qg4oOEzKG9eeF7oaZTYBy33BTL0408sEBxiMior6b8LrZrAhkqDjA vUXRwm/fFKgpsOysxC6xi553CxBUCH2omNV6Ka1LNMwzSp9ILz8jEGqmUtkBszwo G1S8fXgE0Lq3cdDM/GJ4QXP/p6LiwNF99faDMTV3+2SAOGvytOX6KjKVzKOSsfJQ hN0DlsIw8hqJc0WISQQYEQIACQUCSedYRAIbDAAKCRDorT+BmrEOeCUOAJ9qmR0l EXzeoxcdoafxqf6gZlJZlACgkWF7wi2YLW3Oa+jv2QSTlrx4KLM= =Wi5D -----END PGP PUBLIC KEY BLOCK-----
After importing the keys, you can verify any tag with
$ git tag -v TAG_NAME
If you haven't set up ccache yet, now would be a good time to do it.
Building the System
master
.
Choosing a Branch
Some of the requirements for your build environment are determined by which version of the source code you plan to compile. SeeCodenames, Tags, and Build Numbers for a full listing of branches you may choose from. You may also choose to download and build the latest source code (called master
), in which case you will simply omit the branch specification when you initialize the repository.
Once you have selected a branch, follow the appropriate instructions below to set up your build environment.
The basic sequence of build commands is as follows:
Initialize
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
Choose a Target
Choose which target to build with lunch
. The exact configuration can be passed as an argument. For example, the following command:
$ lunch aosp_arm-eng
refers to a complete build for the emulator, with all debugging enabled.
If run with no arguments lunch
will prompt you to choose a target from the menu.
All build targets take the form BUILD-BUILDTYPE
, where the BUILD
is a codename referring to the particular feature combination. Here's a partial list:
Build name | Device | Notes |
---|---|---|
aosp_arm | ARM emulator | AOSP, fully configured with all languages, apps, input methods |
aosp_maguro | maguro | AOSP, running on Galaxy Nexus GSM/HSPA+ ("maguro") |
aosp_panda | panda | AOSP, running on PandaBoard ("panda") |
and the BUILDTYPE is one of the following:
Buildtype | Use |
---|---|
user | limited access; suited for production |
userdebug | like "user" but with root access and debuggability; preferred for debugging |
eng | development configuration with additional debugging tools |
For more information about building for and running on actual hardware, see Building for Devices.
Build the Code
Build everything with make
. GNU make can handle parallel tasks with a -jN
argument, and it's common to use a number of tasks N that's between 1 and 2 times the number of hardware threads on the computer being used for the build. For example, on a dual-E5520 machine (2 CPUs, 4 cores per CPU, 2 threads per core), the fastest builds are made with commands between make -j16
and make -j32
.
$ make -j4
Run It!
You can either run your build on an emulator or flash it on a device. Please note that you have already selected your build target with lunch
, and it is unlikely at best to run on a different target than it was built for.
Flash a Device
To flash a device, you will need to use fastboot
, which should be included in your path after a successful build. Place the device in fastboot mode either manually by holding the appropriate key combination at boot, or from the shell with
$ adb reboot bootloader
Once the device is in fastboot mode, run
$ fastboot flashall -w
The -w
option wipes the /data
partition on the device; this is useful for your first time flashing a particular device but is otherwise unnecessary.
For more information about building for and running on actual hardware, see Building for Devices.
Emulate an Android Device
The emulator is added to your path automatically by the build process. To run the emulator, type
$ emulator
Using ccache
ccache is a compiler cache for C and C++ that can help make builds faster. In the root of the source tree, do the following:
$ export USE_CCACHE=1
$ export CCACHE_DIR=/<path_of_your_choice>/.ccache
$ prebuilts/misc/linux-x86/ccache/ccache -M 50G
The suggested cache size is 50-100G.
On Linux, you can watch ccache being used by doing the following:
$ watch -n1 -d prebuilts/misc/linux-x86/ccache/ccache -s
On Mac OS, you should replace linux-x86
with darwin-x86
.
When using Ice Cream Sandwich (4.0.x) or older, you should replace prebuilts/misc
with prebuilt
.
Troubleshooting Common Build Errors
Wrong Java Version
If you are attempting to build a version of Android inconsistent with your version of Java, make
will abort 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/download.html
************************************************************
This may be caused by:
-
Failing to install the correct JDK as specified in Initializing the Build Environment.
-
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 unfortunately incompatible with Python 3. In order to use repo, please install Python 2.x:
$ apt-get install python
Case Insensitive Filesystem
If you are building on an HFS filesystem on Mac OS, 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.
************************************************************
Please follow the instructions in Initializing the Build Environment for creating a case-sensitive disk image.
No USB Permission
On most Linux systems, unprivileged users cannot access USB ports by default. If you see a permission denied error, follow the instructions Initializing the Build Environment for configuring USB access.
If adb was already running and cannot connect to the device after getting those rules set up, it can be killed withadb kill-server
. That will cause adb to restart with the new configuration.
Building for devices
This page complements the main page about Building and Runningwith information that is specific to individual devices.
With the current release, it is possible to build for Nexus 4, Nexus 7, and for some variants of Galaxy Nexus. The exact level of functionality for each device depends on the availability of the relevant proprietary hardware-specific binaries.
For Nexus 4 and Nexus 7, all configurations can be used, and all the hardware is functional. Due to hardware differences, do not use 4.1.1 on a Nexus 7 that was originally sold with 4.1.2 or newer.
All configurations of Nexus 10 "manta" can be used with 4.2.2. On those devices, graphics, audio, Wi-Fi, Bluetooth, camera, NFC, GPS and orientation sensors are functional.
The variants of Galaxy Nexus that can be used are the GSM/HSPA+ configuration "maguro" (only if it was originally sold with a "yakju" or "takju" operating system) and the VZW CDMA/LTE configuration "toro". On those devices, graphics and audio are functional, as well as Wi-Fi, Bluetooth, and access to the respective cellular networks. NFC and the orientation sensors are functional.
The Sprint CDMA/LTE configuration "toroplus" of Galaxy Nexus is supported experimentally, in the jb-mr1-dev-plus-aosp branch. On that configuration, the cellular network is not functional, and the other peripherals work like they do on "toro".
The Motorola Xoom can be used in the Wi-Fi configuration "wingray" sold in the USA, with Android 4.1.2. Graphics and audio are functional as well as Wi-Fi and Bluetooth and the orientation sensors.
All configurations of Nexus S and Nexus S 4G can be used with Android 4.1.2. On those devices all the hardware is functional.
In addition, PandaBoard a.k.a. "panda" can be used in the jb-mr1-dev-plus-aosp branch, but is considered experimental. The specific details to use a PandaBoard with the Android Open-Source Project are in the filedevice/ti/panda/README
in the source tree.
Building fastboot and adb
If you don't already have those tools, fastboot and adb can be built with the regular build system. Follow the instructions on the page about Building and Running, and replace the main make
command with
$ make fastboot adb
Booting into fastboot mode
During a cold boot, the following key combinations can be used to boot into fastboot mode, which is a mode in the bootloader that can be used to flash the devices:
Device | Keys |
---|---|
shamu | Press and hold Volume Down, then press and hold Power |
fugu | Press and hold Power |
volantis | Press and hold Volume Down, then press and hold Power |
hammerhead | Press and hold both Volume Up and Volume Down, then press and hold Power |
flo | Press and hold Volume Down, then press and hold Power |
deb | Press and hold Volume Down, then press and hold Power |
manta | Press and hold both Volume Up and Volume Down, then press and hold Power |
mako | Press and hold Volume Down, then press and hold Power |
grouper | Press and hold Volume Down, then press and hold Power |
tilapia | Press and hold Volume Down, then press and hold Power |
phantasm | Power the device, cover it with one hand after the LEDs light up and until they turn red |
maguro | Press and hold both Volume Up and Volume Down, then press and hold Power |
toro | Press and hold both Volume Up and Volume Down, then press and hold Power |
toroplus | Press and hold both Volume Up and Volume Down, then press and hold Power |
panda | Press and hold Input, then press Power |
wingray | Press and hold Volume Down, then press and hold Power |
crespo | Press and hold Volume Up, then press and hold Power |
crespo4g | Press and hold Volume Up, then press and hold Power |
Also, the command adb reboot bootloader
can be used to reboot from Android directly into the bootloader with no key combinations.
Unlocking the bootloader
It's only possible to flash a custom system if the bootloader allows it.
The bootloader is locked by default. With the device in fastboot mode, the bootloader is unlocked with
$ fastboot oem unlock
The procedure must be confirmed on-screen, and deletes the user data for privacy reasons. It only needs to be run once.
All data on the phone is erased, i.e. both the applications' private data and the shared data that is accessible over USB, including photos and movies. Be sure to make a backup of any precious files you have before unlocking the bootloader.
On Nexus 10, after unlocking the bootloader, the internal storage is left unformatted and must be formatted with
$ fastboot format cache
$ fastboot format userdata
The bootloader can be locked back with
$ fastboot oem lock
Note that this erases user data on Xoom (including the shared USB data).
Obtaining proprietary binaries
The Android Open-Source Project can't be used from pure source code only, and requires additional hardware-related proprietary libraries to run, specifically for hardware graphics acceleration.
Official binaries for the supported devices running tagged AOSP release branches can be downloaded fromGoogle's Nexus driver page. These add access to additional hardware capabilities with non-open source code. To instead build the AOSP master branch, use the Binaries Preview for Nexus Devices.
When building the master branch for a device, the binaries for the most recent numbered release or with the most recent date are the ones that should be used.
Extracting the proprietary binaries
Each set of binaries comes as a self-extracting script in a compressed archive. After uncompressing each archive, run the included self-extracting script from the root of the source tree, confirm that you agree to the terms of the enclosed license agreement, and the binaries and their matching makefiles will get installed in thevendor/
hierarchy of the source tree.
Cleaning up when adding proprietary binaries
In order to make sure that the newly installed binaries are properly taken into account after being extracted, the existing output of any previous build needs to be deleted with
$ make clobber
Picking and building the configuration that matches a device
The steps to configure and build the Android Open Source Project are described in the Building page.
The recommended builds for the various devices are available through the lunch menu, accessed when running the lunch
command with no arguments. Factory images and binaries for Nexus devices can be downloaded from:
https://developers.google.com/android/nexus/images
https://developers.google.com/android/nexus/drivers
Device | Code name | Build configuration |
---|---|---|
Nexus 6 | shamu | aosp_shamu-userdebug |
Nexus Player | fugu | aosp_fugu-userdebug |
Nexus 9 | volantis (flounder) | aosp_flounder-userdebug |
Nexus 5 (GSM/LTE) | hammerhead | aosp_hammerhead-userdebug |
Nexus 7 (Wi-Fi) | razor (flo) | aosp_flo-userdebug |
Nexus 7 (Mobile) | razorg (deb) | aosp_deb-userdebug |
Nexus 10 | mantaray (manta) | full_manta-userdebug |
Nexus 4 | occam (mako) | full_mako-userdebug |
Nexus 7 (Wi-Fi) | nakasi (grouper) | full_grouper-userdebug |
Nexus 7 (Mobile) | nakasig (tilapia) | full_tilapia-userdebug |
Galaxy Nexus (GSM/HSPA+) | yakju (maguro) | full_maguro-userdebug |
Galaxy Nexus (Verizon) | mysid (toro) | aosp_toro-userdebug |
Galaxy Nexus (Experimental) | mysidspr (toroplus) | aosp_toroplus-userdebug |
PandaBoard (Archived) | panda | aosp_panda-userdebug |
Motorola Xoom (U.S. Wi-Fi) | wingray | full_wingray-userdebug |
Nexus S | soju (crespo) | full_crespo-userdebug |
Nexus S 4G | sojus (crespo4g) | full_crespo4g-userdebug |
Do not use 4.1.1 on a Nexus 7 that was originally sold with 4.1.2 or newer.
Flashing a device
Set the device in fastboot mode if necessary (see above).
An entire Android system can be flashed in a single command: this writes the boot, recovery and system partitions together after verifying that the system being flashed is compatible with the installed bootloader and radio, and reboots the system. This also erases all the user data, similarly to fastboot oem unlock
mentioned earlier.
$ fastboot -w flashall
Note that filesystems created via fastboot on Motorola Xoom aren't working optimally, and it is strongly recommended to re-create them through recovery
$ adb reboot recovery
Once in recovery, open the menu (press Power + Volume Up), wipe the cache partition, then wipe data.
Restoring a device to its original factory state
Factory images for Nexus 5, Nexus 10, Nexus 4, Nexus Q, Nexus 7, Galaxy Nexus (GSM/HSPA+ "yakju" and "takju", and CDMA/LTE "mysid" and "mysidspr"), Nexus S, and Nexus S 4G are available from Google's factory image page.
Factory images for the Motorola Xoom are distributed directly by Motorola.
Building Kernels
If you are only interested in the kernel, you may use this guide to download and build the appropriate kernel.
The following instructions assume that you have not downloaded all of AOSP. If you have downloaded all of AOSP, you may skip the git clone steps other than the step to download the actual kernel sources.
We will use the Pandaboard kernel in all the following examples.
Figuring out which kernel to build
This table lists the name and locations of the kernel sources and binaries:
Device | Binary location | Source location | Build configuration |
---|---|---|---|
shamu | device/moto/shamu-kernel | kernel/msm | shamu_defconfig |
fugu | device/asus/fugu-kernel | kernel/x86_64 | fugu_defconfig |
volantis | device/htc/flounder-kernel | kernel/tegra | flounder_defconfig |
hammerhead | device/lge/hammerhead-kernel | kernel/msm | hammerhead_defconfig |
flo | device/asus/flo-kernel/kernel | kernel/msm | flo_defconfig |
deb | device/asus/flo-kernel/kernel | kernel/msm | flo_defconfig |
manta | device/samsung/manta/kernel | kernel/exynos | manta_defconfig |
mako | device/lge/mako-kernel/kernel | kernel/msm | mako_defconfig |
grouper | device/asus/grouper/kernel | kernel/tegra | tegra3_android_defconfig |
tilapia | device/asus/grouper/kernel | kernel/tegra | tegra3_android_defconfig |
maguro | device/samsung/tuna/kernel | kernel/omap | tuna_defconfig |
toro | device/samsung/tuna/kernel | kernel/omap | tuna_defconfig |
panda | device/ti/panda/kernel | kernel/omap | panda_defconfig |
stingray | device/moto/wingray/kernel | kernel/tegra | stingray_defconfig |
wingray | device/moto/wingray/kernel | kernel/tegra | stingray_defconfig |
crespo | device/samsung/crespo/kernel | kernel/samsung | herring_defconfig |
crespo4g | device/samsung/crespo/kernel | kernel/samsung | herring_defconfig |
You will want to look at the git log for the kernel binary in the device project that you are interested in.
Device projects are of the form device/<vendor>/<name>.
$ git clone https://android.googlesource.com/device/ti/panda
$ cd panda
$ git log --max-count=1 kernel
The commit message for the kernel binary contains a partial git log of the kernel sources that were used to build the binary in question. The first entry in the log is the most recent, i.e. the one used to build that kernel. You will need it at a later step.
Identifying kernel version
To determine the kernel version used in a particular system image, run the following command against the kernel file:
$ dd if=kernel bs=1 skip=$(LC_ALL=C grep -a -b -o $'\x1f\x8b\x08\x00\x00\x00\x00\x00' kernel | cut -d ':' -f 1) | zgrep -a 'Linux version'
For Nexus 5 (hammerhead), this can be accomplished with:
$ dd if=zImage-dtb bs=1 skip=$(LC_ALL=C od -Ad -x -w2 zImage-dtb | grep 8b1f | cut -d ' ' -f1 | head -1) | zgrep -a 'Linux version'
Downloading sources
Depending on which kernel you want,
$ git clone https://android.googlesource.com/kernel/common.git
$ git clone https://android.googlesource.com/kernel/x86_64.git
$ git clone https://android.googlesource.com/kernel/exynos.git
$ git clone https://android.googlesource.com/kernel/goldfish.git
$ git clone https://android.googlesource.com/kernel/msm.git
$ git clone https://android.googlesource.com/kernel/omap.git
$ git clone https://android.googlesource.com/kernel/samsung.git
$ git clone https://android.googlesource.com/kernel/tegra.git
- The
goldfish
project contains the kernel sources for the emulated platforms. - The
msm
project has the sources for ADP1, ADP2, Nexus One, Nexus 4, Nexus 5, Nexus 6, and can be used as a starting point for work on Qualcomm MSM chipsets. - The
omap
project is used for PandaBoard and Galaxy Nexus, and can be used as a starting point for work on TI OMAP chipsets. - The
samsung
project is used for Nexus S, and can be used as a starting point for work on Samsung Hummingbird chipsets. - The
tegra
project is for Xoom, Nexus 7, Nexus 9, and can be used as a starting point for work on NVIDIA Tegra chipsets. - The
exynos
project has the kernel sources for Nexus 10, and can be used as a starting point for work on Samsung Exynos chipsets. - The
x86_64
project has the kernel sources for Nexus Player, and can be used as a starting point for work on Intel x86_64 chipsets.
Downloading a prebuilt gcc
Ensure that the prebuilt toolchain is in your path.
$ export PATH=$(pwd)/prebuilts/gcc/linux-x86/arm/arm-eabi-4.6/bin:$PATHor
$ export PATH=$(pwd)/prebuilts/gcc/darwin-x86/arm/arm-eabi-4.6/bin:$PATH
On a linux host, if you don't have an Android source tree, you can download the prebuilt toolchain from:
$ git clone https://android.googlesource.com/platform/prebuilts/gcc/linux-x86/arm/arm-eabi-4.6
Building
As an example, we would build the panda kernel using the following commands:
$ export ARCH=arm
$ export SUBARCH=arm
$ export CROSS_COMPILE=arm-eabi-
$ cd omap
$ git checkout <commit_from_first_step>
$ make panda_defconfig
$ make
To build the tuna kernel, you may run the previous commands replacing all instances of "panda" with "tuna".
The kernel binary is output as: `arch/arm/boot/zImage` It can be copied into the Android source tree in order to build the matching boot image.
Or you can include the TARGET_PREBUILT_KERNEL
variable while using make bootimage
or any other make command line that builds a boot image.
$ export TARGET_PREBUILT_KERNEL=$your_kernel_path/arch/arm/boot/zImage
That variable is supported by all devices as it is set up via device/common/populate-new-device.sh