| page.title=Initializing a Build Environment |
| @jd:body |
| |
| <!-- |
| Copyright 2013 The Android Open Source Project |
| |
| Licensed under the Apache License, Version 2.0 (the "License"); |
| you may not use this file except in compliance with the License. |
| You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <div id="qv-wrapper"> |
| <div id="qv"> |
| <h2>In this document</h2> |
| <ol id="auto-toc"> |
| </ol> |
| </div> |
| </div> |
| |
| <p>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.</p> |
| <p><strong>Note</strong>: The source download is approximately 8.5GB in size. |
| You will need over 30GB free to complete a single build, and |
| up to 100GB (or more) for a full set of builds.</em></p> |
| <p>For an overview of the entire code-review and code-update process, see <a |
| href="life-of-a-patch.html">Life of a Patch</a>.</p> |
| <h2 id="choosing-a-branch">Choosing a Branch</h2> |
| <p>Some of the requirements for your build environment are determined by which |
| version of the source code you plan to compile. See |
| <a href="build-numbers.html">Build Numbers</a> 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.</p> |
| <p>Once you have selected a branch, follow the appropriate instructions below to |
| set up your build environment.</p> |
| <h2 id="setting-up-a-linux-build-environment">Setting up a Linux build environment</h2> |
| <p>These instructions apply to all branches, including master.</p> |
| <p>The Android build is routinely tested in house on recent versions of |
| Ubuntu LTS (12.04), but most distributions should have the required |
| build tools available. Reports of successes or failures on other |
| distributions are welcome.</p> |
| <p>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.</p> |
| <p><strong>Note</strong>: It is also possible to build Android in a virtual machine. |
| If you are running Linux in a virtual machine, you will need at |
| least 16GB of RAM/swap and 30GB or more of disk space in order to |
| build the Android tree.</p> |
| <p>See the <a href="building.html">Downloading and Building</a> page for the |
| list of hardware and software requirements. Then follow the detailed |
| instructions for Ubuntu and MacOS below.</p> |
| |
| <h3 id="installing-the-jdk">Installing the JDK</h3> |
| <p>The master branch of Android in the <a |
| href="https://android.googlesource.com/">Android Open Source Project (AOSP)</a> |
| requires Java 7. On Ubuntu, use <a href="http://openjdk.java.net/install/">OpenJDK</a>.</p> |
| <p>Java 7: For the latest version of Android</p> |
| <pre><code>$ sudo apt-get update |
| $ sudo apt-get install openjdk-7-jdk |
| </code></pre> |
| |
| <p>Optionally, update the default Java version by running:</p> |
| <pre><code>$ sudo update-alternatives --config java |
| $ sudo update-alternatives --config javac |
| </code></pre> |
| |
| <p>If you encounter version errors for Java, set its |
| path as described in the <a href="building-running.html#wrong-java-version">Wrong |
| Java Version</a> section.</p> |
| |
| <p>To develop older versions of Android, download and install the corresponding version of the <a |
| href="http://www.oracle.com/technetwork/java/javase/archive-139210.html">Java JDK</a>:<br/> |
| Java 6: for Gingerbread through KitKat<br/> |
| Java 5: for Cupcake through Froyo</p> |
| |
| <p><strong>Note</strong>: The <code>lunch</code> command in the build step will ensure that the Sun JDK is |
| used instead of any previously installed JDK.</p> |
| |
| <h3 id="installing-required-packages-ubuntu-1204">Installing required packages (Ubuntu 12.04)</h3> |
| <p>You will need a 64-bit version of Ubuntu. Ubuntu 12.04 is recommended. |
| Building using an older version of Ubuntu is not supported on master or recent releases.</p> |
| <pre><code>$ 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 |
| </code></pre> |
| |
| <h3 id="installing-required-packages-ubuntu-1004-1110">Installing required packages (Ubuntu 10.04 -- 11.10)</h3> |
| <p>Building on Ubuntu 10.04-11.10 is no longer supported, but may be useful for building older |
| releases of AOSP.</p> |
| <pre><code>$ sudo apt-get install git-core 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 |
| </code></pre> |
| <p>On Ubuntu 10.10:</p> |
| <pre><code>$ sudo ln -s /usr/lib32/mesa/libGL.so.1 /usr/lib32/mesa/libGL.so |
| </code></pre> |
| <p>On Ubuntu 11.10:</p> |
| <pre><code>$ sudo apt-get install libx11-dev:i386 |
| </code></pre> |
| <h3 id="configuring-usb-access">Configuring USB Access</h3> |
| <p>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.</p> |
| <p>The recommended approach is to create a file |
| <code>/etc/udev/rules.d/51-android.rules</code> (as the root user) and to copy |
| the following lines in it. <code><username></code> must be replaced by the |
| actual username of the user who is authorized to access the phones |
| over USB.</p> |
| <pre><code># 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>" |
| </code></pre> |
| <p>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.</p> |
| <p>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.</p> |
| <p><a name="ccache"></a></p> |
| <h3 id="setting-up-ccache">Setting up ccache</h3> |
| <p>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 do "make clean" often, or if you frequently |
| switch between different build products.</p> |
| <p>Put the following in your .bashrc or equivalent.</p> |
| <pre><code>export USE_CCACHE=1 |
| </code></pre> |
| <p>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 as well.</p> |
| <pre><code>export CCACHE_DIR=<path-to-your-cache-directory> |
| </code></pre> |
| <p>The suggested cache size is 50-100GB. |
| You will need to run the following command once you have downloaded |
| the source code:</p> |
| <pre><code>prebuilts/misc/linux-x86/ccache/ccache -M 50G |
| </code></pre> |
| <p>When building Ice Cream Sandwich (4.0.x) or older, ccache is in |
| a different location:</p> |
| <pre><code>prebuilt/linux-x86/ccache/ccache -M 50G |
| </code></pre> |
| <p>This setting is stored in the CCACHE_DIR and is persistent.</p> |
| <h3 id="using-a-separate-output-directory">Using a separate output directory</h3> |
| <p>By default, the output of each build is stored in the out/ |
| subdirectory of the matching source tree.</p> |
| <p>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.</p> |
| <p>To set this up, export the <code>OUT_DIR_COMMON_BASE</code> variable |
| to point to the location where your output directories |
| will be stored.</p> |
| <pre><code>export OUT_DIR_COMMON_BASE=<path-to-your-out-directory> |
| </code></pre> |
| <p>The output directory for each separate source tree will be |
| named after the directory holding the source tree.</p> |
| <p>For instance, if you have source trees as <code>/source/master1</code> |
| and <code>/source/master2</code> and <code>OUT_DIR_COMMON_BASE</code> is set to |
| <code>/output</code>, the output directories will be <code>/output/master1</code> |
| and <code>/output/master2</code>.</p> |
| <p>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.</p> |
| <p>This is only supported on Jelly Bean (4.1) and newer, |
| including the master branch.</p> |
| <h2 id="setting-up-a-mac-os-x-build-environment">Setting up a Mac OS X build environment</h2> |
| <p>In a default installation, OS X 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.</p> |
| <p>Once the proper filesystem is available, building the master branch in a modern |
| OS X environment is very straightforward. Earlier branches, including ICS, |
| require some additional tools and SDKs.</p> |
| <h3 id="creating-a-case-sensitive-disk-image">Creating a case-sensitive disk image</h3> |
| <p>You can create a case-sensitive filesystem within your existing OS X 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.</p> |
| <p>You can also create it from a shell with the following command:</p> |
| <pre><code># hdiutil create -type SPARSE -fs 'Case-sensitive Journaled HFS+' -size 40g ~/android.dmg |
| </code></pre> |
| <p>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. For a disk image named "android.dmg" stored in your home directory, you can add the following to your <code>~/.bash_profile</code> to mount the image when you execute "mountAndroid":</p> |
| <pre><code># mount the android file image |
| function mountAndroid { hdiutil attach ~/android.dmg -mountpoint /Volumes/android; } |
| </code></pre> |
| <p>Once mounted, you'll do all your work in the "android" volume. You can eject it (unmount it) just like you would with an external drive.</p> |
| <h3 id="master-branch">Master branch</h3> |
| <p>To build the latest source in a Mac OS environment, you will need an Intel/x86 |
| machine running MacOS 10.8 (Mountain Lion), along with Xcode |
| 4.5.2 and Command Line Tools.</p> |
| <p>You will also need the <a |
| href="http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html">Java 7 JDK</a>. |
| Select the file: jdk-7u51-macosx-x64.dmg</p> |
| |
| <h3 id="branch-40x-and-all-earlier-branches">Branch 4.2.x and earlier branches</h3> |
| <p>To build 4.2.x and earlier source in a Mac OS environment, you will need an Intel/x86 |
| machine running MacOS 10.6 (Snow Leopard) or MacOS 10.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.</p> |
| <p>The remaining sections for Mac OS X only apply to those who wish to build |
| earlier branches.</p> |
| <h3 id="branch-40x-and-all-earlier-branches">Branch 4.0.x and all earlier branches</h3> |
| <p>To build android-4.0.x and earlier branches in a Mac OS environment, you need an |
| Intel/x86 machine running MacOS 10.5 (Leopard) or MacOS 10.6 (Snow Leopard). You |
| will need the MacOS 10.5 SDK.</p> |
| <h4 id="installing-required-packages">Installing required packages</h4> |
| <ul> |
| <li> |
| <p>Install Xcode from <a href="http://developer.apple.com/">the Apple developer site</a>. |
| We recommend version 3.1.4 or newer, i.e. 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.</p> |
| </li> |
| <li> |
| <p>Install MacPorts from <a href="http://www.macports.org/install.php">macports.org</a>.</p> |
| <p><em>Note: Make sure that <code>/opt/local/bin</code> appears in your path BEFORE <code>/usr/bin</code>. If not, add</em> </p> |
| <pre><code>export PATH=/opt/local/bin:$PATH |
| </code></pre> |
| <p><em>to your <code>~/.bash_profile</code>.</em></p> |
| </li> |
| <li> |
| <p>Get make, git, and GPG packages from MacPorts: </p> |
| <pre><code>$ POSIXLY_CORRECT=1 sudo port install gmake libsdl git-core gnupg |
| </code></pre> |
| <p>If using Mac OS 10.4, also install bison:</p> |
| <pre><code>$ POSIXLY_CORRECT=1 sudo port install bison |
| </code></pre> |
| </li> |
| </ul> |
| <h4 id="reverting-from-make-382">Reverting from make 3.82</h4> |
| <p>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:</p> |
| <ul> |
| <li> |
| <p>Edit <code>/opt/local/etc/macports/sources.conf</code> and add a line that says</p> |
| <pre><code>file:///Users/Shared/dports |
| </code></pre> |
| <p>above the rsync line. Then create this directory: </p> |
| <pre><code>$ mkdir /Users/Shared/dports |
| </code></pre> |
| </li> |
| <li> |
| <p>In the new <code>dports</code> directory, run </p> |
| <pre><code>$ svn co --revision 50980 http://svn.macports.org/repository/macports/trunk/dports/devel/gmake/ devel/gmake/ |
| </code></pre> |
| </li> |
| <li> |
| <p>Create a port index for your new local repository: </p> |
| <pre><code>$ portindex /Users/Shared/dports |
| </code></pre> |
| </li> |
| <li> |
| <p>Finally, install the old version of gmake with </p> |
| <pre><code>$ sudo port install gmake @3.81 |
| </code></pre> |
| </li> |
| </ul> |
| <h4 id="setting-a-file-descriptor-limit">Setting a file descriptor limit</h4> |
| <p>On MacOS the default limit on the number of simultaneous file descriptors open is too low and a highly parallel build process may exceed this limit.<br /> |
| </p> |
| <p>To increase the cap, add the following lines to your <code>~/.bash_profile</code>: </p> |
| <pre><code># set the number of open files to be 1024 |
| ulimit -S -n 1024 |
| </code></pre> |
| <h2 id="next-download-the-source">Next: Download the source</h2> |
| <p>Your build environment is good to go! Proceed to <a href="downloading.html">downloading the source</a>.</p> |