diff options
Diffstat (limited to 'en/setup/build/building.html')
-rw-r--r-- | en/setup/build/building.html | 230 |
1 files changed, 230 insertions, 0 deletions
diff --git a/en/setup/build/building.html b/en/setup/build/building.html new file mode 100644 index 00000000..ab57d087 --- /dev/null +++ b/en/setup/build/building.html @@ -0,0 +1,230 @@ +<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 instead build the AOSP master branch, use the +<a href="https://developers.google.com/android/blobs-preview" class="external">Binaries +Preview</a>. 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 BUILDTYPE 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>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 make 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 at best 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>This may be caused by:</p> + +<ul> +<li>Failing to install the correct JDK as specified in <a +href="requirements.html#jdk">JDK Requirements</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">Establishing a +Build Environment</a> for creating a case-sensitive disk image.</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 +<a href="initializing.html">Initializing the Build Environment</a> for +configuring USB access.</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> |