Docs: Restore deleted contents

Bug: 19484165
Change-Id: I6d7e17a0a2eb2da80388ca63d89ad7e4e6fde223
diff --git a/src/source/building-running.jd b/src/source/building-running.jd
index 239ebe6..d9eb0bf 100644
--- a/src/source/building-running.jd
+++ b/src/source/building-running.jd
@@ -2,7 +2,7 @@
 @jd:body
 
 <!--
-    Copyright 2013 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.
@@ -24,20 +24,10 @@
   </div>
 </div>
 
-The following instructions to build the Android source tree apply to all branches, including <code>master</code>.
+<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="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 <code>master</code>), 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 <code>source</code> with <code>.</code> (a single dot) saves a few characters,
@@ -47,6 +37,7 @@
 <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>
@@ -55,34 +46,9 @@
 <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. Here's a partial list:</p>
-<table>
-<thead>
-<tr>
-<th>Build name</th>
-<th>Device</th>
-<th>Notes</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td>aosp_arm</td>
-<td>ARM emulator</td>
-<td>AOSP, fully configured with all languages, apps, input methods</td>
-</tr>
-<tr>
-<td>aosp_maguro</td>
-<td>maguro</td>
-<td>AOSP, running on Galaxy Nexus GSM/HSPA+ ("maguro")</td>
-</tr>
-<tr>
-<td>aosp_panda</td>
-<td>panda</td>
-<td>AOSP, running on PandaBoard ("panda")</td>
-</tr>
-</tbody>
-</table>
-<p>and the BUILDTYPE is one of the following:</p>
+referring to the particular feature combination.</p>
+
+<p>The BUILDTYPE is one of the following:</p>
 <table>
 <thead>
 <tr>
@@ -107,7 +73,8 @@
 </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>
+
+<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
diff --git a/src/source/configure-products.jd b/src/source/configure-products.jd
new file mode 100644
index 0000000..01fc788
--- /dev/null
+++ b/src/source/configure-products.jd
@@ -0,0 +1,382 @@
+page.title=Configuring the Products
+@jd:body
+
+<!--
+    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.
+    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>
+
+<p>Use the information in this page to create the Makefiles for your device and product.</p>
+
+<h2 id="build-layers">Understand Build Layers</h2>
+
+<p>The build hierarchy includes the abstraction layers that correspond to the
+physical makeup of a device. These layers are described in the table below.
+Each layer relates to the one above it in a one-to-many relationship. For
+example, an architecture can have more than one board and each board can have
+more than one product. You may define an element in a given layer as a
+specialization of an element in the same layer, thus eliminating copying and
+simplifying maintenance.</p>
+
+<table>
+ <tbody><tr>
+  <th>Layer</th>
+  <th>Example</th>
+  <th>Description</th>
+ </tr>
+  <tr>
+    <td>Product</td>
+    <td>myProduct, myProduct_eu, myProduct_eu_fr, j2, sdk</td>
+    <td><p>The product layer defines the feature specification of a shipping product such as the modules to build,
+    locales supported, and the configuration for various locales. In other words, this is the name of the
+    overall product. Product-specific variables are defined in product definition Makefiles. A product
+     can inherit from other product definitions,
+    which simplifies maintenance. A common method is to create a base product that contains features that apply
+    for all products, then creating product variants based on that base product. For example, you can have
+    two products that differ only by their radios (CDMA vs GSM) inherit from the same base product that does not define a radio.
+</td>
+
+  </tr>
+ <tr>
+    <td>Board/Device</td>
+    <td>sardine, trout, goldfish</td>
+    <td>The device/board layer represents the physical layer of plastic on the
+    device (i.e. the industrial design of the device). For example, North American
+    devices probably include QWERTY keyboards whereas devices sold in France
+    probably include AZERTY keyboards. This layer also represents the bare
+    schematics of a product. These include the peripherals on the board and their
+    configuration. The names used are merely codes for different board/device configurations.</td>
+  </tr>
+<tr>
+    <td>Arch</td>
+    <td>arm, x86, mips, arm64, x86_64, mips64</td>
+    <td>The architecture layer describes the processor configuration and ABI (Application Binary Interface) running on the board. </td>
+  </tr>
+</table>
+
+<h2 id="build-variants">Use Build Variants</h2>
+
+<p>When building for a particular product, it's often useful to have minor
+variations on what is ultimately the final release build. In a module
+definition, the module can specify tags with <code>LOCAL_MODULE_TAGS</code>,
+which can be one or more values of <code>optional</code> (default),
+<code>debug</code>, <code>eng</code>.</p>
+
+<p>If a module doesn't specify a tag (by <code>LOCAL_MODULE_TAGS</code>), its
+tag defaults to <code>optional</code>. An optional module is installed only if
+it is required by product configuration with <code>PRODUCT_PACKAGES</code>.
+
+<p>These are the currently-defined build variants:</p>
+
+<table border=1>
+<tr>
+    <td>
+        <code>eng<code>
+    </td>
+    <td>
+        This is the default flavor.
+        <ul>
+        <li>Installs modules tagged with: <code>eng</code> and/or <code>debug</code>.
+        <li>Installs modules according to the product definition files, in addition to tagged modules.</li>
+        <li><code>ro.secure=0</code>
+        <li><code>ro.debuggable=1</code>
+        <li><code>ro.kernel.android.checkjni=1</code>
+        <li><code>adb</code> is enabled by default.
+    </td>
+</tr>
+<tr>
+    <td>
+        <code>user<code>
+    </td>
+    <td>
+        This is the flavor intended to be the final release bits.
+        <ul>
+        <li>Installs modules tagged with <code>user</code>.</li>
+        <li>Installs modules according to the product definition files, in addition to tagged modules.</li>
+        <li><code>ro.secure=1</code> </li>
+        <li><code>ro.debuggable=0</code> </li>
+        <li><code>adb</code> is disabled by default.</li>
+    </td>
+</tr>
+<tr>
+    <td>
+        <code>userdebug<code>
+    </td>
+    <td>
+        The same as <code>user</code>, except:
+        <ul>
+        <li>Also installs modules tagged with <code>debug</code>.
+        <li><code>ro.debuggable=1</code>
+        <li><code>adb</code> is enabled by default.
+    </td>
+</tr>
+</table>
+
+<h2 id="build-a-product">Build a Product</h2>
+
+<p>
+There are many ways to organize the source files for your device. We'll briefly
+go over how the Nexus 6 implementation was organized as an example, but you can
+organize your source files and build the way you see fit.
+</p>
+<p>
+Nexus 6 was implemented with a main device configuration named
+<code>shamu</code>. From this device configuration, a product is created with a
+product definition Makefile that declares product-specific information about
+the device such as the name and model. You can view the
+<code>device/moto/shamu</code> directory to see how all of this is setup.
+</p>
+<h3 id="makefiles">Write the Makefiles</h2>
+<p>
+  The following steps describe how to set up product Makefiles in a way similar
+to that of the Nexus 6 product line:
+</p>
+<ol>
+  <li>Create a <code>device/&lt;company_name&gt;/&lt;device_name&gt;</code> directory for your
+  product. For example, <code>device/moto/shamu</code>. This directory will contain source code
+  for your device along with the Makefiles to build them.
+  </li>
+
+  <li>Create a <code>device.mk</code> Makefile that declares the files and modules needed for the
+  device. For an example, see <code>device/moto/shamu/device.mk</code>.
+  </li>
+
+  <li>Create a product definition Makefile to create a specific product based on the device. The
+  following Makefile is taken from <code>device/moto/shamu/aosp_shamu.mk</code> as an example.
+  Notice the product is inheriting from the
+  <code>device/moto/shamu/device.mk</code> and
+  <code>vendor/moto/shamu/device-vendor.mk</code> files via the Makefile while
+  also declaring the product-specific information such as name, brand, and model.
+
+<pre>
+# Inherit from the common Open Source product configuration
+$(call inherit-product, $(SRC_TARGET_DIR)/product/aosp_base_telephony.mk)
+
+PRODUCT_NAME := aosp_shamu
+PRODUCT_DEVICE := shamu
+PRODUCT_BRAND := Android
+PRODUCT_MODEL := AOSP on Shamu
+PRODUCT_MANUFACTURER := motorola
+PRODUCT_RESTRICT_VENDOR_FILES := true
+
+$(call inherit-product, device/moto/shamu/device.mk)
+$(call inherit-product-if-exists, vendor/moto/shamu/device-vendor.mk)
+
+PRODUCT_NAME := aosp_shamu
+
+PRODUCT_PACKAGES += \
+    Launcher3
+</pre>
+
+    <p>
+      See <a href="#prod-def">Product Definition Variables</a> for additional product-specific
+      variables you can add to your Makefiles.
+    </p>
+  </li>
+
+  <li>Create an <code>AndroidProducts.mk</code> file that points to the product's Makefiles. In
+  this example, only the product definition Makefile is needed. The example below is from
+  <code>device/moto/shamu/AndroidProducts.mk</code>:
+    <pre>
+#
+# This file should set PRODUCT_MAKEFILES to a list of product makefiles
+# to expose to the build system.  LOCAL_DIR will already be set to
+# the directory containing this file.
+#
+# This file may not rely on the value of any variable other than
+# LOCAL_DIR; do not use any conditionals, and do not look up the
+# value of any variable that isn't set in this file or in a file that
+# it includes.
+#
+
+PRODUCT_MAKEFILES := \
+    $(LOCAL_DIR)/aosp_shamu.mk
+</pre>
+  </li>
+
+  <li>Create a <code>BoardConfig.mk</code> Makefile that contains board-specific configurations.
+  For an example, see <code>device/moto/shamu/BoardConfig.mk</code>.
+  </li>
+
+  <li>Create a <code>vendorsetup.sh</code> file to add your product (a "lunch combo") to the build
+  along with a <a href="#build-variants">build variant</a> separated by a dash. For example:
+<pre>
+add_lunch_combo &lt;product_name&gt;-userdebug
+</pre>
+  </li>
+
+  <li>At this point, you can create more product variants based on the same device.
+  </li>
+
+</ol>
+<h3 id="prod-def">Set Product Definition Variables</h3>
+<p>
+  Product-specific variables are defined in the product's Makefile. Variables maintained in a
+  product definition files include:
+</p>
+<table>
+  <tbody>
+    <tr>
+      <th>
+        Parameter
+      </th>
+      <th>
+        Description
+      </th>
+      <th>
+        Example
+      </th>
+    </tr>
+    <tr>
+      <td>
+        PRODUCT_AAPT_CONFIG
+      </td>
+      <td>
+        <code>aapt</code> configurations to use when creating packages
+      </td>
+      <td></td>
+    </tr>
+    <tr>
+      <td>
+        PRODUCT_BRAND
+      </td>
+      <td>
+        The brand (e.g., carrier) the software is customized for, if any
+      </td>
+      <td></td>
+    </tr>
+    <tr>
+      <td>
+        PRODUCT_CHARACTERISTICS
+      </td>
+      <td>
+        <code>aapt</code> characteristics to allow adding variant-specific resources to a package.
+      </td>
+      <td>
+        tablet,nosdcard
+      </td>
+    </tr>
+    <tr>
+      <td>
+        PRODUCT_COPY_FILES
+      </td>
+      <td>
+        List of words like <code>source_path:destination_path</code>. The file at the source path
+        should be copied to the destination path when building this product. The rules for the copy
+        steps are defined in config/Makefile
+      </td>
+      <td></td>
+    </tr>
+    <tr>
+      <td>
+        PRODUCT_DEVICE
+      </td>
+      <td>
+        Name of the industrial design. This is also the board name, and the build system uses it to locate the <code>BoardConfig.mk.</code>
+      </td>
+      <td>
+        <code>tuna</code>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        PRODUCT_LOCALES
+      </td>
+      <td>
+        A space-separated list of two-letter language code, two-letter country code pairs that
+        describe several settings for the user, such as the UI language and time, date and currency
+        formatting. The first locale listed in PRODUCT_LOCALES is used as the product's default locale.
+      </td>
+      <td>
+        <code>en_GB de_DE es_ES fr_CA</code>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        PRODUCT_MANUFACTURER
+      </td>
+      <td>
+        Name of the manufacturer
+      </td>
+      <td>
+        <code>acme</code>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        PRODUCT_MODEL
+      </td>
+      <td>
+        End-user-visible name for the end product
+      </td>
+      <td></td>
+    </tr>
+    <tr>
+      <td>
+        PRODUCT_NAME
+      </td>
+      <td>
+        End-user-visible name for the overall product. Appears in the Settings &gt; About screen.
+      </td>
+      <td></td>
+    </tr>
+    <tr>
+      <td>
+        PRODUCT_OTA_PUBLIC_KEYS
+      </td>
+      <td>
+        List of Over the Air (OTA) public keys for the product
+      </td>
+      <td></td>
+    </tr>
+    <tr>
+      <td>
+        PRODUCT_PACKAGES
+      </td>
+      <td>
+        Lists the APKs and modules to install.
+      </td>
+      <td>
+        <code>Calendar Contacts</code>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        PRODUCT_PACKAGE_OVERLAYS
+      </td>
+      <td>
+        Indicate whether to use default resources or add any product specific overlays
+      </td>
+      <td>
+        <code>vendor/acme/overlay</code>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        PRODUCT_PROPERTY_OVERRIDES
+      </td>
+      <td>
+        List of system property assignments in the format "key=value"
+      </td>
+      <td></td>
+    </tr>
+  </tbody>
+</table>
diff --git a/src/source/source_toc.cs b/src/source/source_toc.cs
index 84897f1..7ec831c 100644
--- a/src/source/source_toc.cs
+++ b/src/source/source_toc.cs
@@ -40,6 +40,7 @@
        <ul>
         <li><a href="<?cs var:toroot ?>source/initializing.html">Initializing the Build Environment</a></li>
         <li><a href="<?cs var:toroot ?>source/downloading.html">Downloading the Source</a></li>
+        <li><a href="<?cs var:toroot ?>source/configure-products.html">Configuring the Products</a></li>
         <li><a href="<?cs var:toroot ?>source/building-running.html">Building and Running</a></li>
         <li><a href="<?cs var:toroot ?>source/building-devices.html">Building for Devices</a></li>
         <li><a href="<?cs var:toroot ?>source/building-kernels.html">Building Kernels</a></li>