1 <html devsite> 2 <head> 3 <title>Preparing to Build</title> 4 <meta name="project_path" value="/_project.yaml" /> 5 <meta name="book_path" value="/_book.yaml" /> 6 </head> 7 <body> 8 <!-- 9 Copyright 2017 The Android Open Source Project 10 11 Licensed under the Apache License, Version 2.0 (the "License"); 12 you may not use this file except in compliance with the License. 13 You may obtain a copy of the License at 14 15 http://www.apache.org/licenses/LICENSE-2.0 16 17 Unless required by applicable law or agreed to in writing, software 18 distributed under the License is distributed on an "AS IS" BASIS, 19 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 20 See the License for the specific language governing permissions and 21 limitations under the License. 22 --> 23 24 25 26 <p>The following instructions to build the Android source tree apply to all 27 branches, including <code>master</code>. The basic sequence of build commands 28 is as follows:</p> 29 30 <h2 id="obtaining-proprietary-binaries">Obtain proprietary binaries</h2> 31 32 <p>AOSP cannot be used from pure source code only and requires additional 33 hardware-related proprietary libraries to run, such as for hardware 34 graphics acceleration. See the sections below for download links and <a 35 href="requirements.html#binaries">Device binaries requirements</a> for 36 additional resources.</p> 37 38 <h3 id="downloading-proprietary-binaries">Download proprietary binaries</h3> 39 40 <p>You can download official binaries for the supported devices running tagged 41 AOSP release branches from <a 42 href="https://developers.google.com/android/nexus/drivers">Google's Nexus 43 driver page</a>. These binaries add access to additional hardware capabilities 44 with non-open source code. To instead build the AOSP master branch, use the 45 <a href="https://developers.google.com/android/nexus/blobs-preview">Binaries 46 Preview for Nexus Devices</a>. When building the master branch for a device, use 47 the binaries for the <a href="/source/build-numbers.html">most recent 48 numbered release</a> or with the most recent date.</p> 49 50 <h3 id="extracting-proprietary-binaries">Extract proprietary binaries</h3> 51 52 <p>Each set of binaries comes as a self-extracting script in a compressed 53 archive. Uncompress each archive, run the included self-extracting script from 54 the root of the source tree, then confirm that you agree to the terms 55 of the enclosed license agreement. The binaries and their matching makefiles 56 will be installed in the <code>vendor/</code> hierarchy of the source tree.</p> 57 58 <h3 id="cleaning-up">Clean up</h3> 59 60 <p>To ensure the newly installed binaries are properly taken into account after 61 being extracted, delete the existing output of any previous build using:</p> 62 <pre class="devsite-terminal devsite-click-to-copy"> 63 make clobber 64 </pre> 65 66 <h2 id="initialize">Set up environment</h2> 67 <p>Initialize the environment with the <code>envsetup.sh</code> script. Note 68 that replacing <code>source</code> with <code>.</code> (a single dot) saves a few characters, 69 and the short form is more commonly used in documentation.</p> 70 <pre class="devsite-terminal devsite-click-to-copy"> 71 source build/envsetup.sh 72 </pre> 73 <p>or</p> 74 <pre class="devsite-terminal devsite-click-to-copy"> 75 . build/envsetup.sh 76 </pre> 77 78 <h2 id="choose-a-target">Choose a target</h2> 79 <p>Choose which target to build with <code>lunch</code>. The exact configuration can be passed as 80 an argument. For example, the following command:</p> 81 <pre class="devsite-terminal devsite-click-to-copy"> 82 lunch aosp_arm-eng 83 </pre> 84 <p>refers to a complete build for the emulator, with all debugging enabled.</p> 85 <p>If run with no arguments <code>lunch</code> will prompt you to choose a 86 target from the menu.</p> 87 <p>All build targets take the form <code>BUILD-BUILDTYPE</code>, where the 88 <code>BUILD</code> is a codename referring to the particular feature combination.</p> 89 90 <p>The BUILDTYPE is one of the following:</p> 91 <table> 92 <thead> 93 <tr> 94 <th>Buildtype</th> 95 <th>Use</th> 96 </tr> 97 </thead> 98 <tbody> 99 <tr> 100 <td>user</td> 101 <td>limited access; suited for production</td> 102 </tr> 103 <tr> 104 <td>userdebug</td> 105 <td>like "user" but with root access and debuggability; preferred for debugging</td> 106 </tr> 107 <tr> 108 <td>eng</td> 109 <td>development configuration with additional debugging tools</td> 110 </tr> 111 </tbody> 112 </table> 113 <p>For more information about building for and running on actual hardware, see 114 <a href="running.html">Running Builds</a>.</p> 115 116 <h2 id="build-the-code">Build the code</h2> 117 118 <p>Please note, this section is merely a summary to ensure setup is complete. See 119 <a href="running.html">Running Builds</a> for detailed instructions on building 120 Android.</p> 121 122 <p>Build everything with <code>make</code>. GNU make can handle parallel 123 tasks with a <code>-jN</code> argument, and it's common to use a number of 124 tasks N that's between 1 and 2 times the number of hardware 125 threads on the computer being used for the build. For example, on a 126 dual-E5520 machine (2 CPUs, 4 cores per CPU, 2 threads per core), 127 the fastest builds are made with commands between <code>make -j16</code> and 128 <code>make -j32</code>.</p> 129 130 <pre class="devsite-terminal devsite-click-to-copy"> 131 make -j4 132 </pre> 133 134 <h2 id="run-it">Run it!</h2> 135 136 <p>You can either run your build on an emulator or flash it on a device. Please 137 note that you have already selected your build target with <code>lunch</code>, 138 and it is unlikely at best to run on a different target than it was built 139 for.</p> 140 141 <p class="note"><strong>Note:</strong> Remember to <a 142 href="#obtaining-proprietary-binaries">obtain proprietary binaries</a> or your 143 build will not boot successfully on your target hardware. If you obtain binary 144 blobs at this point you will need to unpack them, <code>make clobber</code> and 145 rebuild.</p> 146 147 <h3 id="flash-a-device">Flash with fastboot</h3> 148 149 <p>To flash a device, you will need to use <code>fastboot</code>, which should 150 be included in your path after a successful build. See <a 151 href="running.html#flashing-a-device">Flashing a device</a> for 152 instructions.</p> 153 154 <h3 id="emulate-an-android-device">Emulate an Android Device</h3> 155 156 <p>The emulator is added to your path automatically by the build process. To 157 run the emulator, type:</p> 158 159 <pre class="devsite-terminal devsite-click-to-copy"> 160 emulator 161 </pre> 162 163 <h2 id="troubleshooting-common-build-errors">Troubleshooting Common Build Errors</h2> 164 165 <h3 id="wrong-java-version">Wrong Java Version</h3> 166 167 <p>If you are attempting to build a version of Android inconsistent with your 168 version of Java, <code>make</code> will abort with a message such as</p> 169 <pre> 170 ************************************************************ 171 You are attempting to build with the incorrect version 172 of java. 173 174 Your version is: WRONG_VERSION. 175 The correct version is: RIGHT_VERSION. 176 177 Please follow the machine setup instructions at 178 https://source.android.com/source/initializing.html 179 ************************************************************ 180 </pre> 181 182 <p>This may be caused by:</p> 183 184 <ul> 185 <li>Failing to install the correct JDK as specified in <a 186 href="requirements.html#jdk">JDK Requirements</a>.</li> 187 <li>Another JDK previously installed appearing in your path. Prepend the 188 correct JDK to the beginning of your PATH or remove the problematic JDK.</li> 189 </ul> 190 191 <h3 id="python-version-3">Python Version 3</h3> 192 193 <p>Repo is built on particular functionality from Python 2.x and is 194 unfortunately incompatible with Python 3. In order to use repo, please install 195 Python 2.x:</p> 196 197 <pre class="devsite-terminal devsite-click-to-copy"> 198 apt-get install python 199 </pre> 200 201 <h3 id="case-insensitive-filesystem">Case Insensitive Filesystem</h3> 202 203 <p>If you are building on an HFS filesystem on Mac OS, you may encounter an error such as</p> 204 <pre> 205 ************************************************************ 206 You are building on a case-insensitive filesystem. 207 Please move your source tree to a case-sensitive filesystem. 208 ************************************************************ 209 </pre> 210 <p>Please follow the instructions in <a href="initializing.html">Initializing 211 the Build Environment</a> for creating a case-sensitive disk image.</p> 212 213 <h3 id="no-usb-permission">No USB Permission</h3> 214 215 <p>On most Linux systems, unprivileged users cannot access USB ports by 216 default. If you see a permission denied error, follow the instructions 217 <a href="initializing.html">Initializing the Build Environment</a> for 218 configuring USB access.</p> 219 220 <p>If adb was already running and cannot connect to the device after 221 getting those rules set up, it can be killed with <code>adb kill-server</code>. 222 That will cause adb to restart with the new configuration.</p> 223 224 </body> 225 </html> 226
