src/devices/build_system.jd

page.title=Building the PDK
@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>

<p>Android uses a custom build system to generate tools, binaries, and documentation.</p>

<p>The build system is Make-based and requires a recent version of GNU Make (note that
  Android uses advanced features of GNU Make that may not yet appear on the GNU Make web site).
  Before continuing, check your version of make by running <code>% make -v</code>. If you
  don't have version 3.80 or greater, you need to
  <a href="http://www.gnu.org/software/make/">upgrade your version of make</a>.
</p>


<h2 id="layers">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 device.
  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.
    <p>For a full list of product definition variables, see the
    <a href="{@docRoot}devices/build_new_device.html#prod-def">Product Definition Files</a> section.</p>
</td>

  </tr>
  <tr>
    <td>Device</td>
    <td>myDevice, myDevice_eu, myDevice_eu_lite</td>
    <td>The device 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.</td>
  </tr>
  <tr>
    <td>Board</td>
    <td>sardine, trout, goldfish </td>
    <td>The board layer represents the bare schematics of a product. This includes the peripherals on the board and their
      configuraiton.</td>
  </tr>
  <tr>
    <td>Arch</td>
    <td>arm (armv7-a-neon, armv7), x86, 68k </td>
    <td>The architecture layer describes the processor configuration and ABI (Application Binary Interface) running on the board. </td>
  </tr>
</table>


<h2 id="variants">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.  These are the
currently-defined build variants:
</p> 
 
<table border=1> 
<tr> 
    <td> 
        <code>eng<code> 
    </td> 
    <td> 
        This is the default flavor. A plain <code>make</code> is the
        same as <code>make eng</code>.
        <ul> 
        <li>Installs modules tagged with: <code>eng</code>, <code>debug</code>,
            <code>user</code>, and/or <code>development</code>.
        <li>Installs non-APK modules that have no tags specified.
        <li>Installs APKs according to the product definition files, in
            addition to tagged APKs.
        <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>
        <code>make user</code>
        <p> 
        This is the flavor intended to be the final release bits.
        <ul> 
        <li>Installs modules tagged with <code>user</code>.</li>
        <li>Installs non-APK modules that have no tags specified.</li>
        <li>Installs APKs according to the product definition files; tags
            are ignored for APK 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> 
        <code>make userdebug</code>
        <p> 
        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> 

<p class="note"><strong>Note:</strong> 
If you build one flavor and then want to build another, you should run
<code>make installclean</code> between the two makes to guarantee that
you don't pick up files installed by the previous flavor.  <code>make
clean</code> also suffices, but it takes a lot longer.
</p>

<h2 id="pdk-build">The PDK Build</h2>
<p>The PDK build differs from a normal platform build in that it does not contain the entire Android source tree.
  A <code>platform.zip</code> binary is provided that contains the missing pieces that aren't in the PDK source tree.
  The PDK supports two different build flavors, Fusion and non-Fusion:
</p>
<ul>
  <li>The Fusion build includes the <code>platform.zip</code>
  components and allows your device to boot up into a usable Android system with a UI.
  </li>
  <li>The non-Fusion build omits the <code>platform.zip</code> components and boots
  your device without a UI. In this mode,
  you can <code>adb shell</code> into the device to run command line programs to test your
  hardware in the early stages of development. This is useful when you only have a few HAL
  implementations and drivers to test initially.
  </li>
</ul>

  <h3 id="running-pdk-build">Running a default PDK build</h3>
<p>When you have the PDK source synced, you can run a default build for the PDK to verify that your environment
  is setup correctly. To do this, run the following commands:</p>

<pre>
source build/envsetup.sh
lunch mini_armv7a_neon-userdebug
PDK_FUSION_PLATFORM_ZIP=vendor/pdk/mini_armv7a_neon/mini_armv7a_neon-userdebug/platform/platform.zip make -j32
</pre>