s.a.c. redesign, first checkin
Change-Id: I4dead2f18bc5e4a38f204c92198a267c286e775d
diff --git a/src/source/building-running.jd b/src/source/building-running.jd
new file mode 100644
index 0000000..3fcd457
--- /dev/null
+++ b/src/source/building-running.jd
@@ -0,0 +1,193 @@
+page.title=Building the System
+@jd:body
+
+<!--
+ Copyright 2010 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.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+The following instructions to build the Android source tree apply to all branches, including master.
+
+<h2 id="choosing-a-branch">Choosing a Branch</h2>
+<p>Some of the requirements for your build environment are determined by which
+version of the source code you plan to compile. See
+<a href="build-numbers.html">Codenames, Tags, and Build Numbers</a> for a full listing of branches you may
+choose from. You may also choose to download and build the latest source code
+(called "master"), in which case you will simply omit the branch specification
+when you initialize the repository.</p>
+<p>Once you have selected a branch, follow the appropriate instructions below to
+set up your build environment.</p>
+
+
+<p>The basic sequence of build commands is as follows:</p>
+<h2 id="initialize">Initialize</h2>
+<p>Initialize the environment with the <code>envsetup.sh</code> script. Note
+that replacing "source" with 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, e.g. </p>
+<pre><code>$ lunch full-eng
+</code></pre>
+<p>The example above 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 BUILD-BUILDTYPE, where the BUILD is a codename
+referring to the particular feature combination. Here's a partial list:</p>
+<table>
+<thead>
+<tr>
+<th>Build name</th>
+<th>Device</th>
+<th>Notes</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>full</td>
+<td>emulator</td>
+<td>fully configured with all languages, apps, input methods</td>
+</tr>
+<tr>
+<td>full_maguro</td>
+<td>maguro</td>
+<td><code>full</code> build running on Galaxy Nexus GSM/HSPA+ ("maguro")</td>
+</tr>
+<tr>
+<td>full_panda</td>
+<td>panda</td>
+<td><code>full</code> build running on PandaBoard ("panda")</td>
+</tr>
+</tbody>
+</table>
+<p>and 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="building-devices.html">Building for Devices</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. E.g. 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="building-devices.html">Building for Devices.</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>
+<h1 id="using-ccache">Using ccache</h1>
+<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>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 OSX, 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>
+<h1 id="troubleshooting-common-build-errors">Troubleshooting Common Build Errors</h1>
+<h2 id="wrong-java-version">Wrong Java Version</h2>
+<p>If you are attempting to build froyo or earlier with Java 1.6, or gingerbread or later
+with Java 1.5, <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>
+<p>failing to install the correct JDK as specified in <a href="initializing.html">Initializing the Build Environment</a>. Building Android requires Sun JDK 5 or 6 depending on which release you are building. </p>
+</li>
+<li>
+<p>another JDK that you previously installed appearing in your path. You can remove the offending JDK from your path with:</p>
+<pre><code>$ export PATH=${PATH/\/path\/to\/jdk\/dir:/}
+</code></pre>
+</li>
+</ul>
+<h2 id="python-version-3">Python Version 3</h2>
+<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>
+<h2 id="case-insensitive-filesystem">Case Insensitive Filesystem</h2>
+<p>If you are building on an HFS filesystem on Mac OS X, 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>
+<h2 id="no-usb-permission">No USB Permission</h2>
+<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>