| <html devsite> | |
| <head> | |
| <title>Preparing to Build</title> | |
| <meta name="project_path" value="/_project.yaml" /> | |
| <meta name="book_path" value="/_book.yaml" /> | |
| </head> | |
| <body> | |
| <!-- | |
| Copyright 2017 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. | |
| --> | |
| <p>The following instructions to build the Android source tree apply to all | |
| branches, including <code>master</code>. The basic sequence of build commands | |
| is as follows.</p> | |
| <h2 id="obtaining-proprietary-binaries">Obtain proprietary binaries</h2> | |
| <p>AOSP cannot be used from pure source code only and requires additional | |
| hardware-related proprietary libraries to run, such as for hardware | |
| graphics acceleration. See the sections below for download links and <a | |
| href="requirements.html#binaries">Device binaries</a> for additional | |
| resources.</p> | |
| <aside class ="note">Some devices package these proprietary binaries on their | |
| <code>/vendor</code> partition.</aside> | |
| <h3 id="downloading-proprietary-binaries">Download proprietary binaries</h3> | |
| <p>You can download official binaries for the supported devices running tagged | |
| AOSP release branches from <a | |
| href="https://developers.google.com/android/drivers" class="external">Google's | |
| drivers</a>. These binaries add access to additional hardware capabilities | |
| with non-open source code. To build the AOSP master branch, use the | |
| <a href="https://developers.google.com/android/blobs-preview" class="external"> | |
| Binaries Preview</a> instead. When building the master branch for a device, use | |
| the binaries for the <a href="/setup/start/build-numbers.html">most recent | |
| numbered release</a> or with the most recent date.</p> | |
| <h3 id="extracting-proprietary-binaries">Extract proprietary binaries</h3> | |
| <p>Each set of binaries comes as a self-extracting script in a compressed | |
| archive. Uncompress each archive, run the included self-extracting script from | |
| the root of the source tree, then confirm you agree to the terms of the enclosed | |
| license agreement. The binaries and their matching makefiles will be installed | |
| in the <code>vendor/</code> hierarchy of the source tree.</p> | |
| <h3 id="cleaning-up">Clean up</h3> | |
| <p>To ensure the newly installed binaries are properly taken into account after | |
| being extracted, delete the existing output of any previous build using:</p> | |
| <pre class="devsite-terminal devsite-click-to-copy"> | |
| make clobber | |
| </pre> | |
| <h2 id="initialize">Set up environment</h2> | |
| <p>Initialize the environment with the <code>envsetup.sh</code> script. Note | |
| that replacing <code>source</code> with <code>.</code> (a single dot) saves a | |
| few characters, and the short form is more commonly used in documentation.</p> | |
| <pre class="devsite-terminal devsite-click-to-copy"> | |
| source build/envsetup.sh | |
| </pre> | |
| <p>or</p> | |
| <pre class="devsite-terminal devsite-click-to-copy"> | |
| . build/envsetup.sh | |
| </pre> | |
| <h2 id="choose-a-target">Choose a target</h2> | |
| <p>Choose which target to build with <code>lunch</code>. 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:</p> | |
| <pre class="devsite-terminal devsite-click-to-copy"> | |
| lunch aosp_arm-eng | |
| </pre> | |
| <p>If run with no arguments <code>lunch</code> will prompt you to choose a | |
| target from the menu.</p> | |
| <p>All build targets take the form <code>BUILD-BUILDTYPE</code>, where the | |
| <code>BUILD</code> is a codename referring to the particular feature | |
| combination. The <code>BUILDTYPE</code> is one of the following:</p> | |
| <table> | |
| <thead> | |
| <tr> | |
| <th>Buildtype</th> | |
| <th>Use</th> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td>user</td> | |
| <td>limited access; suited for production</td> | |
| </tr> | |
| <tr> | |
| <td>userdebug</td> | |
| <td>like user but with root access and debuggability; preferred for | |
| debugging</td> | |
| </tr> | |
| <tr> | |
| <td>eng</td> | |
| <td>development configuration with additional debugging tools</td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <p>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, you should follow the | |
| <a href="../develop/new-device.html#userdebug-guidelines">userdebug guidelines</a>.</p> | |
| <p>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 behaves similar to the user and | |
| userdebug builds so that device developers can see how the code behaves in | |
| those environments.</p> | |
| <p>For more information about building for and running on actual hardware, see | |
| <a href="running.html">Running Builds</a>.</p> | |
| <h2 id="build-the-code">Build the code</h2> | |
| <p>This section is merely a summary to ensure setup is complete. See | |
| <a href="running.html">Running Builds</a> for detailed instructions on building | |
| Android.</p> | |
| <p>Build everything with <code>make</code>. GNU <code>make</code> can handle parallel | |
| tasks with a <code>-jN</code> 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 <code>make -j16</code> and | |
| <code>make -j32</code>.</p> | |
| <pre class="devsite-terminal devsite-click-to-copy"> | |
| make -j4 | |
| </pre> | |
| <h2 id="run-it">Run it!</h2> | |
| <p>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 <code>lunch</code>, | |
| and it is unlikely to run on a different target than it was built | |
| for.</p> | |
| <aside class="note"><strong>Note:</strong> Remember to <a | |
| href="#obtaining-proprietary-binaries">obtain proprietary binaries</a> or your | |
| build will not boot successfully on your target hardware. If you obtain binary | |
| blobs at this point you will need to unpack them, <code>make clobber</code> and | |
| rebuild.</aside> | |
| <h3 id="flash-a-device">Flash with fastboot</h3> | |
| <p>To flash a device, you will need to use <code>fastboot</code>, which should | |
| be included in your path after a successful build. See <a | |
| href="running.html#flashing-a-device">Flashing a device</a> for | |
| instructions.</p> | |
| <h3 id="emulate-an-android-device">Emulate an Android device</h3> | |
| <p>The emulator is added to your path automatically by the build process. To | |
| run the emulator, type:</p> | |
| <pre class="devsite-terminal devsite-click-to-copy"> | |
| emulator | |
| </pre> | |
| <h2 id="troubleshooting-common-build-errors">Troubleshooting common build | |
| errors</h2> | |
| <h3 id="wrong-java-version">Wrong Java version</h3> | |
| <p>If you are attempting to build a version of Android inconsistent with your | |
| version of Java, <code>make</code> will abort with a message such as</p> | |
| <pre> | |
| ************************************************************ | |
| 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 | |
| ************************************************************ | |
| </pre> | |
| <p>Here are the likely causes and solutions:</p> | |
| <ul> | |
| <li>Failing to install the correct JDK as specified in <a | |
| href="requirements.html#jdk">JDK Requirements</a>. Make sure you have followed | |
| the steps in <a href="building.html#initialize">Set up environment</a> and | |
| <a href="building.html#choose-a-target">Choose a target</a>.</li> | |
| <li>Another JDK previously installed appearing in your path. Prepend the | |
| correct JDK to the beginning of your PATH or remove the problematic JDK.</li> | |
| </ul> | |
| <h3 id="python-version-3">Python version 3</h3> | |
| <p>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:</p> | |
| <pre class="devsite-terminal devsite-click-to-copy"> | |
| apt-get install python | |
| </pre> | |
| <h3 id="case-insensitive-filesystem">Case insensitive filesystem</h3> | |
| <p>If you are building on an HFS filesystem on Mac OS, you may encounter an | |
| error such as</p> | |
| <pre> | |
| ************************************************************ | |
| You are building on a case-insensitive filesystem. | |
| Please move your source tree to a case-sensitive filesystem. | |
| ************************************************************ | |
| </pre> | |
| <p>Please follow the instructions in <a href="initializing.html#creating-a-case-sensitive-disk-image">Creating a case-sensitive disk image</a>.</p> | |
| <h3 id="no-usb-permission">No USB permission</h3> | |
| <p>On most Linux systems, unprivileged users cannot access USB ports by | |
| default. If you see a permission denied error, follow the instructions in | |
| <a href="initializing.html#configuring-usb-access">Configuring USB access</a>.</p> | |
| <p>If adb was already running and cannot connect to the device after | |
| getting those rules set up, it can be killed with <code>adb kill-server</code>. | |
| That will cause adb to restart with the new configuration.</p> | |
| </body> | |
| </html> |