Docs: Rename pages to match their purposes
Bug: 10117610
Change-Id: Idbe82e3d7ce328d03ece123c5bd6b46117dc4888
diff --git a/src/source/building.jd b/src/source/building.jd
index 78401da..ecb52db 100644
--- a/src/source/building.jd
+++ b/src/source/building.jd
@@ -1,8 +1,8 @@
-page.title=Downloading and Building
+page.title=Building the System
@jd:body
<!--
- Copyright 2014 The Android Open Source Project
+ Copyright 2015 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.
@@ -16,50 +16,143 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-<p>The Android build is routinely tested in-house on recent versions of
-Ubuntu LTS (14.04), but most distributions should have the required
-build tools available. We welcome reports of successes or failures on other
-distributions.</p>
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
-<p>Before you download and build the Android source, ensure your system meets
-the following requirements:</p>
+<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="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><code>$ source build/envsetup.sh
+</code></pre>
+<p>or</p>
+<pre><code>$ . build/envsetup.sh
+</code></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:</p>
+<pre><code>$ lunch aosp_arm-eng
+</code></pre>
+<p>refers to a complete build for the emulator, with all debugging enabled.</p>
+<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.</p>
+
+<p>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>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><code>$ make -j4
+</code></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>
+<h3 id="flash-a-device">Flash a Device</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. Place the device in fastboot mode either manually by holding the appropriate key combination at boot, or from the shell with</p>
+<pre><code>$ adb reboot bootloader
+</code></pre>
+<p>Once the device is in fastboot mode, run </p>
+<pre><code>$ fastboot flashall -w
+</code></pre>
+<p>The <code>-w</code> option wipes the <code>/data</code> partition on the device; this is useful for your first time flashing a particular device but is otherwise unnecessary.</p>
+<p>For more information about building for and running on actual hardware, see
+<a href="running.html">Running Builds</a>.</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><code>$ emulator
+</code></pre>
+<h2 id="using-ccache">Using ccache</h2>
+<p>ccache is a compiler cache for C and C++ that can help make builds faster.
+In the root of the source tree, do the following:</p>
+<pre><code>$ export USE_CCACHE=1
+$ export CCACHE_DIR=/<path_of_your_choice>/.ccache
+$ prebuilts/misc/linux-x86/ccache/ccache -M 50G
+</code></pre>
+<p>The suggested cache size is 50-100G.</p>
+<p>On Linux, you can watch ccache being used by doing the following:</p>
+<pre><code>$ watch -n1 -d prebuilts/misc/linux-x86/ccache/ccache -s
+</code></pre>
+<p>On Mac OS, you should replace <code>linux-x86</code> with <code>darwin-x86</code>.</p>
+<p>When using Ice Cream Sandwich (4.0.x) or older, you should replace
+<code>prebuilts/misc</code> with <code>prebuilt</code>.</p>
+<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><code>************************************************************
+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/download.html
+************************************************************
+</code></pre>
+<p>This may be caused by:</p>
<ul>
-
- <li>A Linux or Mac OS system. It is also possible
- to build Android in a virtual machine on unsupported systems such as Windows.
- If you are running Linux in a virtual machine, you need at
- least 16GB of RAM/swap and 100GB or more of disk space in order to
- build the Android tree. See disk size requirements below.
- </li>
-
- <li>A 64-bit environment is required for Gingerbread (2.3.x) and newer versions, including the master
- branch. You can compile older versions on 32-bit systems.
- </li>
-
- <li>At least 100GB of free disk space for a checkout, 150GB for a single
- build, and 200GB or more for multiple builds. If you employ ccache, you will
- need even more space.</p>
- </li>
-
- <li>
- Python 2.6 -- 2.7, which you can download from <a href="http://www.python.org/download/">python.org</a>.</p>
- </li>
-
- <li>
- GNU Make 3.81 -- 3.82, which you can download from <a href="http://ftp.gnu.org/gnu/make/">gnu.org</a>,</p>
- </li>
-
- <li>
- JDK 7 to build the master branch of Android in the <a
- href="https://android.googlesource.com/">Android Open Source Project
- (AOSP)</a>; JDK 6 to build Gingerbread through KitKat; JDK 5 for Cupcake through
- Froyo. See <a href="initializing.html">Initializing a Build Environment</a>
- for installation instructions by operating system.</p>
- </li>
-
- <li>
- Git 1.7 or newer. You can find it at <a href="http://git-scm.com/download">git-scm.com</a>.</p>
- </li>
-
+<li>
+<p>Failing to install the correct JDK as specified in <a href="initializing.html">Initializing the Build Environment</a>.</p>
+</li>
+<li>
+<p>Another JDK previously installed appearing in your path. Prepend the correct JDK to the beginning of your PATH or remove the problematic JDK.</p>
+</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><code>$ apt-get install python
+</code></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><code>************************************************************
+You are building on a case-insensitive filesystem.
+Please move your source tree to a case-sensitive filesystem.
+************************************************************
+</code></pre>
+<p>Please follow the instructions in <a href="initializing.html">Initializing the 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>