1 <!-- 2 Copyright 2010 The Android Open Source Project 3 4 Licensed under the Apache License, Version 2.0 (the "License"); 5 you may not use this file except in compliance with the License. 6 You may obtain a copy of the License at 7 8 http://www.apache.org/licenses/LICENSE-2.0 9 10 Unless required by applicable law or agreed to in writing, software 11 distributed under the License is distributed on an "AS IS" BASIS, 12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 See the License for the specific language governing permissions and 14 limitations under the License. 15 --> 16 17 # Initializing a Build Environment # 18 19 The "Getting Started" section describes how to set up your local work environment, how to use Repo to get the Android files, and how to build the files on your machine. To build the Android source files, you will need to use Linux or Mac OS. Building under Windows is not currently supported. 20 21 *Note: The source download is approximately 6GB in size. 22 You will need 25GB free to complete a single build, and 23 up to 90GB (or more) for a full set of builds.* 24 25 For an overview of the entire code-review and code-update process, see [Life of a Patch](life-of-a-patch.html). 26 27 28 29 # Setting up a Linux build environment # 30 31 The Android build is routinely tested in house on recent versions of 32 Ubuntu LTS (10.04), but most distributions should have the required 33 build tools available. Reports of successes or failures on other 34 distributions are welcome. 35 36 *Note: It is also possible to build Android in a virtual machine. 37 If you are running Linux in a virtual machine, you will need at 38 least 16GB of RAM/swap and 30GB or more of disk space in order to 39 build the Android tree.* 40 41 In general you will need: 42 43 - Python 2.5 -- 2.7, which you can download from [python.org](http://www.python.org/download/). 44 45 - GNU Make 3.81 -- 3.82, which you can download from [gnu.org](http://ftp.gnu.org/gnu/make/), 46 47 - JDK 6 if you wish to build Gingerbread or newer; JDK 5 for Froyo or older. You can download both from [java.sun.com](http://java.sun.com/javase/downloads/). 48 49 - Git 1.7 or newer. You can find it at [git-scm.com](http://git-scm.com/download). 50 51 Detailed instructions for Ubuntu 10.04+ follow. 52 53 ## Installing the JDK ## 54 55 The Sun JDK is no longer in Ubuntu's main package repository. In order to download it, you need to add the appropriate repository and indicate to the system which JDK should be used. 56 57 Java 6: for Gingerbread and newer 58 59 $ sudo add-apt-repository "deb http://archive.canonical.com/ lucid partner" 60 $ sudo apt-get update 61 $ sudo apt-get install sun-java6-jdk 62 63 Java 5: for Froyo and older 64 65 $ sudo add-apt-repository "deb http://archive.ubuntu.com/ubuntu hardy main multiverse" 66 $ sudo add-apt-repository "deb http://archive.ubuntu.com/ubuntu hardy-updates main multiverse" 67 $ sudo apt-get update 68 $ sudo apt-get install sun-java5-jdk 69 70 *Note: The `lunch` command in the build step will ensure that the Sun JDK is 71 used instead of any previously installed JDK.* 72 73 ## Installing required packages (Ubuntu 10.04 -- 11.10) ## 74 75 You will need a 64-bit version of Ubuntu. Ubuntu 10.04 is recommended. 76 Building using a newer version of Ubuntu is currently only experimentally 77 supported and is not guaranteed to work on branches other than master. 78 79 $ sudo apt-get install git-core gnupg flex bison gperf build-essential \ 80 zip curl zlib1g-dev libc6-dev lib32ncurses5-dev ia32-libs \ 81 x11proto-core-dev libx11-dev lib32readline5-dev lib32z-dev \ 82 libgl1-mesa-dev g++-multilib mingw32 tofrodos python-markdown \ 83 libxml2-utils xsltproc 84 85 On Ubuntu 10.10: 86 87 $ sudo ln -s /usr/lib32/mesa/libGL.so.1 /usr/lib32/mesa/libGL.so 88 89 On Ubuntu 11.10: 90 91 $ sudo apt-get install libx11-dev:i386 92 93 ## Installing required packages (Ubuntu 12.04) ## 94 95 Building on Ubuntu 12.04 is currently only experimentally supported and is not 96 guaranteed to work on branches other than master. 97 98 $ sudo apt-get install git-core gnupg flex bison gperf build-essential \ 99 zip curl libc6-dev libncurses5-dev:i386 x11proto-core-dev \ 100 libx11-dev:i386 libreadline6-dev:i386 libgl1-mesa-dev:i386 \ 101 g++-multilib mingw32 openjdk-6-jdk tofrodos python-markdown \ 102 libxml2-utils xsltproc zlib1g-dev:i386 103 104 ## Configuring USB Access ## 105 106 Under GNU/linux systems (and specifically under Ubuntu systems), 107 regular users can't directly access USB devices by default. The 108 system needs to be configured to allow such access. 109 110 The recommended approach is to create a file 111 `/etc/udev/rules.d/51-android.rules` (as the root user) and to copy 112 the following lines in it. <username> must be replaced by the 113 actual username of the user who is authorized to access the phones 114 over USB. 115 116 # adb protocol on passion (Nexus One) 117 SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e12", MODE="0600", OWNER="<username>" 118 # fastboot protocol on passion (Nexus One) 119 SUBSYSTEM=="usb", ATTR{idVendor}=="0bb4", ATTR{idProduct}=="0fff", MODE="0600", OWNER="<username>" 120 # adb protocol on crespo/crespo4g (Nexus S) 121 SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e22", MODE="0600", OWNER="<username>" 122 # fastboot protocol on crespo/crespo4g (Nexus S) 123 SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e20", MODE="0600", OWNER="<username>" 124 # adb protocol on stingray/wingray (Xoom) 125 SUBSYSTEM=="usb", ATTR{idVendor}=="22b8", ATTR{idProduct}=="70a9", MODE="0600", OWNER="<username>" 126 # fastboot protocol on stingray/wingray (Xoom) 127 SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="708c", MODE="0600", OWNER="<username>" 128 # adb protocol on maguro/toro (Galaxy Nexus) 129 SUBSYSTEM=="usb", ATTR{idVendor}=="04e8", ATTR{idProduct}=="6860", MODE="0600", OWNER="<username>" 130 # fastboot protocol on maguro/toro (Galaxy Nexus) 131 SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e30", MODE="0600", OWNER="<username>" 132 # adb protocol on panda (PandaBoard) 133 SUBSYSTEM=="usb", ATTR{idVendor}=="0451", ATTR{idProduct}=="d101", MODE="0600", OWNER="<username>" 134 # fastboot protocol on panda (PandaBoard) 135 SUBSYSTEM=="usb", ATTR{idVendor}=="0451", ATTR{idProduct}=="d022", MODE="0600", OWNER="<username>" 136 # usbboot protocol on panda (PandaBoard) 137 SUBSYSTEM=="usb", ATTR{idVendor}=="0451", ATTR{idProduct}=="d010", MODE="0600", OWNER="<username>" 138 139 Those new rules take effect the next time a device is plugged in. 140 It might therefore be necessary to unplug the device and plug it 141 back into the computer. 142 143 This is known to work on both Ubuntu Hardy Heron (8.04.x LTS) and 144 Lucid Lynx (10.04.x LTS). Other versions of Ubuntu or other 145 variants of GNU/linux might require different configurations. 146 147 <a name="ccache"></a> 148 ## Setting up ccache ## 149 150 You can optionally tell the build to use the ccache compilation tool. 151 Ccache acts as a compiler cache that can be used to speed-up rebuilds. 152 This works very well if you do "make clean" often, or if you frequently 153 switch between different build products. 154 155 Put the following in your .bashrc or equivalent. 156 157 export USE_CCACHE=1 158 159 By default the cache will be stored in ~/.ccache. 160 If your home directory is on NFS or some other non-local filesystem, 161 you will want to specify the directory in your .bashrc as well. 162 163 export CCACHE_DIR=<path-to-your-cache-directory> 164 165 The suggested cache size is 50-100GB. 166 You will need to run the following command once you have downloaded 167 the source code. 168 169 prebuilt/linux-x86/ccache/ccache -M 50G 170 171 This setting is stored in the CCACHE_DIR and is persistent. 172 173 174 # Setting up a Mac OS X build environment # 175 176 To build the Android files in a Mac OS environment, you need an 177 Intel/x86 machine running MacOS 10.6 (Snow Leopard). 178 179 Android must be built on a case-sensitive file system because the sources contain files that differ only in case. We recommend that you build Android on a partition that has been formatted with the journaled file system HFS+. HFS+ is required to successfully build Mac OS applications such as the Android Emulator for OS X. 180 181 ## Creating a case sensitive disk image ## 182 183 If you want to avoid partitioning/formatting your hard drive, you can use 184 a case-sensitive disk image instead. To create the image, launch Disk 185 Utility and select "New Image". A size of 25GB is the minimum to 186 complete the build, larger numbers are more future-proof. Using sparse images 187 saves space while allowing to grow later as the need arises. Be sure to select 188 "case sensitive, journaled" as the volume format. 189 190 You can also create it from a shell with the following command: 191 192 # hdiutil create -type SPARSE -fs 'Case-sensitive Journaled HFS+' -size 40g ~/android.dmg 193 194 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 `~/.bash_profile` to mount the image when you execute "mountAndroid": 195 196 # mount the android file image 197 function mountAndroid { hdiutil attach ~/android.dmg -mountpoint /Volumes/android; } 198 199 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. 200 201 ## Installing required packages ## 202 203 - Install XCode from [the Apple developer site](http://developer.apple.com/). 204 We recommend version 3.1.4 or newer, i.e. gcc 4.2. 205 Version 4.x could cause difficulties. 206 If you are not already registered as an Apple developer, you will have to 207 create an Apple ID in order to download. 208 209 - Install MacPorts from [macports.org](http://www.macports.org/install.php). 210 211 *Note: Make sure that `/opt/local/bin` appears in your path BEFORE `/usr/bin`. If not, add* 212 213 export PATH=/opt/local/bin:$PATH 214 215 *to your `~/.bash_profile`.* 216 217 - Get make, git, and GPG packages from MacPorts: 218 219 $ POSIXLY_CORRECT=1 sudo port install gmake libsdl git-core gnupg 220 221 If using Mac OS 10.4, also install bison: 222 223 $ POSIXLY_CORRECT=1 sudo port install bison 224 225 ## Reverting from make 3.82 ## 226 227 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: 228 229 - Edit `/opt/local/etc/macports/sources.conf` and add a line that says 230 231 file:///Users/Shared/dports 232 233 above the rsync line. Then create this directory: 234 235 $ mkdir /Users/Shared/dports 236 237 - In the new `dports` directory, run 238 239 $ svn co --revision 50980 http://svn.macports.org/repository/macports/trunk/dports/devel/gmake/ devel/gmake/ 240 241 - Create a port index for your new local repository: 242 243 $ portindex /Users/Shared/dports 244 245 - Finally, install the old version of gmake with 246 247 $ sudo port install gmake @3.81 248 249 ## Setting a file descriptor limit ## 250 251 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. 252 253 To increase the cap, add the following lines to your `~/.bash_profile`: 254 255 # set the number of open files to be 1024 256 ulimit -S -n 1024 257 258 # Next: Download the source # 259 260 Your build environment is good to go! Proceed to [downloading the source](downloading.html).... 261
