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/<company_name>/<device_name></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 <product_name>-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 > 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>