pdk/docs/porting/build_new_device.jd

page.title=Configuring a New Product
pdk.version=1.0
doc.type=porting
@jd:body



<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<a name="toc"/>
<ul>
<li><a href="#androidOHDPortingDeviceBuildingProcess">Detailed Instructions</a></li>
<li><a href="#androidBuildNewFileTree">New Product File Tree</a></li>
<li><a href="#androidBuildSystemProductDefFiles">Product Definition Files</a></li>
</ul>
</div>
</div>


<a name="androidOHDPortingDeviceBuildingProcess"></a><h3>Detailed Instructions</h3>

<p>The steps below describe how to configure makefiles for new mobile devices and products running Android.</p>
<ol>
  <li>Create a company directory in <code>//vendor/</code>.<br/>
  <pre class="prettyprint">
  mkdir vendor/&lt;company_name&gt;</pre></li>
  <li>Create a <code>products</code> directory beneath the company directory you created in step 1.<BR>
  <pre class="prettyprint">
  mkdir vendor/&lt;company_name&gt;/products/</pre></li>
  <li>Create a product-specific makefile, called <code>vendor/&lt;company_name&gt;/products/&lt;first_product_name&gt;.mk</code>, that includes at least the following code:<BR>
    <pre class="prettyprint">
  $(call inherit-product, $(SRC_TARGET_DIR)/product/generic.mk)
  #
  # Overrides
  PRODUCT_NAME := &lt;first_product_name&gt;
  PRODUCT_DEVICE := &lt;board_name&gt;</pre>
  <li>
  Additional product-specific variables can be added to this <a href="#androidBuildSystemProductDefFiles">Product Definition</a> 
file.
  </li>
  <li>In the <code>products</code> directory, create an <code>AndroidProducts.mk</code> file that point to (and is responsible for finding) the individual product make files.<BR>
  <pre class="prettyprint">
  #
  # 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)/first_product_name.mk \</pre></li>
  <li>Create a board-specific directory beneath your company directory that matches the <code>PRODUCT_DEVICE</code> variable <code>&lt;board_name&gt;</code> referenced in the product-specific make file above. This will include a make file that gets accessed by any product using this board.<BR>
  <pre class="prettyprint">
  mkdir vendor/&lt;company_name&gt;/&lt;board_name&gt;</pre></li>
    <li>Create a <code>BoardConfig.mk</code> file in the directory created in the previous step (<code>vendor/&lt;company_name&gt;/&lt;board_name&gt;</code>). <BR>
  <pre class="prettyprint">
  # These definitions override the defaults in config/config.make for &lt;board_name&gt;
  #
  # TARGET_NO_BOOTLOADER := false
  #
  TARGET_USE_GENERIC_AUDIO := true</pre></li>  
  <li>If you wish to modify system properties, create a <code>system.prop</code> file in your <code>&lt;board_name&gt;</code> directory(<code>vendor/&lt;company_name&gt;/&lt;board_name&gt;</code>).<BR>
  <pre class="prettyprint">
  # system.prop for <board_name>
  # This overrides settings in the products/generic/system.prop file
  #
  # rild.libpath=/system/lib/libreference-ril.so
  # rild.libargs=-d /dev/ttyS0</pre></li>   
  <li>Add a pointer to <code>&lt;second_product_name&gt;.mk</code> within <code>products/AndroidProducts.mk</code>.<BR>
  <pre class="prettypring">
  PRODUCT_MAKEFILES := \
    $(LOCAL_DIR)/first_product_name.mk \
    $(LOCAL_DIR)/second_product_name.mk</pre></li>
  <li>An <code>Android.mk</code> file must be included in <code>vendor/&lt;company_name&gt;/&lt;board_name&gt;</code> with at least the following code:<BR>
  <pre class="prettyprint">
  # make file for new hardware <board_name> from <company_name>
  #
  LOCAL_PATH := $(call my-dir)
  #
  # this is here to use the pre-built kernel
  ifeq ($(TARGET_PREBUILT_KERNEL),)
  TARGET_PREBUILT_KERNEL := $(LOCAL_PATH)/kernel
  endif
  #
  file := $(INSTALLED_KERNEL_TARGET)
  ALL_PREBUILT += $(file)
  $(file): $(TARGET_PREBUILT_KERNEL) | $(ACP)
		$(transform-prebuilt-to-target)
  #
  # no boot loader, so we don't need any of that stuff..  
  #
  LOCAL_PATH := vendor/&lt;company_name&gt;/&lt;board_name&gt;
  #
  include $(CLEAR_VARS)
  #
  # include more board specific stuff here? Such as Audio parameters.      
  #</pre>

  </li>
<li>To create a second product for the same board, create a second product-specific make file called <code>vendor/company_name/products/&lt;second_product_name&gt;.mk</code> that includes:<BR>
<pre class="prettyprint">
  $(call inherit-product, $(SRC_TARGET_DIR)/product/generic.mk)
  #
  # Overrides
  PRODUCT_NAME := &lt;second_product_name&gt;
  PRODUCT_DEVICE := &lt;board_name&gt;</pre></li>   	
</ol>
<p>By now, you should have two new products, called <code>&lt;first_product_name&gt;</code> and <code>&lt;second_product_name&gt;</code> associated with <code>&lt;company_name&gt;</code>. To verify that a product is properly configured (<code>&lt;first_product_name&gt;</code>, for example), execute the following:<BR>
<pre class="prettyprint">
  . build/envsetup.sh
  make PRODUCT-&lt;first_product_name&gt;-user
</pre>
<p>You should find new build binaries located in <code>/out/target/product/&lt;board_name&gt;</code>.


<a name="androidBuildNewFileTree"></a><h3>New Product File Tree</h3>

<p>The file tree below illustrates what your own system should look like after completing the steps above.</p>
<p>
<ul>
  <li><code>&lt;company_name&gt;</code></li>
  <ul>
    <li><code>&lt;board_name&gt;</code></li>
    <ul>
      <li><code>Android.mk</code></li>
      <li><code>product_config.mk</code></li>
      <li><code>system.prop</code></li>
    </ul>
    <li><code>products</code></li>
    <ul>
      <li><code>AndroidProducts.mk</code></li>
      <li><code>&lt;first_product_name&gt;.mk</code></li>
      <li><code>&lt;second_product_name&gt;.mk</code></li>
    </ul>
  </ul>
</ul>
</p>

<a name="androidBuildSystemProductDefFiles"></a><h3>Product Definition Files</h3>

<p>Product-specific variables are defined in product definition files. A product definition file can inherit from other product definition files, thus reducing the need to copy and simplifying maintenance.</p>
<p>Variables maintained in a product definition files include:</p>
<p>
<table border=1 cellpadding=2 cellspacing=0>
 <tbody><tr>
  <th scope="col">Parameter</th>
  <th scope="col">Description</th>
  <th scope="col">Example</th>
 </tr>
 <tr>
   <td valign="top">PRODUCT_NAME</td>
   <td valign="top">End-user-visible name for the overall product. Appears in the "About the phone" info.</td>
   <td valign="top"></td>
 </tr>
 <tr>
   <td valign="top">PRODUCT_MODEL</td>
   <td valign="top">End-user-visible name for the end product</td>
   <td valign="top"></td>
 </tr>
 <tr>
   <td valign="top">PRODUCT_LOCALES</td>
   <td valign="top">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 is used if the locale has never been set before.</td>
   <td valign="top"><code>en_GB de_DE es_ES fr_CA</code></td>
 </tr>
 <tr>
   <td valign="top">PRODUCT_PACKAGES</td>
   <td valign="top">Lists the APKs to install.</td>
   <td valign="top"><code>Calendar Contacts</code></td>
 </tr>
 <tr>
   <td valign="top">PRODUCT_DEVICE</td>
   <td valign="top">Name of the industrial design</td>
   <td valign="top"><code>dream</code></td>
 </tr>
 <tr>
   <td valign="top">PRODUCT_MANUFACTURER</td>
   <td valign="top">Name of the manufacturer</td>
   <td valign="top"><code>acme</code></td>
 </tr>
 <tr>
   <td valign="top">PRODUCT_BRAND</td>
   <td valign="top">The brand (e.g., carrier) the software is customized for, if any</td>
   <td valign="top"></td>
 </tr>
 <tr>
   <td valign="top">PRODUCT_PROPERTY_OVERRIDES</td>
   <td valign="top">List of property assignments in the format "key=value"</td>
   <td valign="top"></td>
 </tr>
 <tr>
   <td valign="top">PRODUCT_COPY_FILES</td>
   <td valign="top">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 valign="top"></td>
 </tr>
 <tr>
   <td valign="top">PRODUCT_OTA_PUBLIC_KEYS</td>
   <td valign="top">List of OTA public keys for the product</td>
   <td valign="top"></td>
 </tr>
 <tr>
   <td valign="top">PRODUCT_POLICY</td>
   <td valign="top">Indicate which policy this product should use</td>
   <td valign="top"></td>
 </tr>
 <tr>
   <td valign="top">PRODUCT_PACKAGE_OVERLAYS</td>
   <td valign="top">Indicate whether to use default resources or add any product specific overlays</td>
   <td valign="top"><code>vendor/acme/overlay</code></td>
 </tr>
 <tr>
   <td valign="top">PRODUCT_CONTRIBUTORS_FILE</td>
   <td valign="top">HTML file containing the contributors to the project.</td>
   <td valign="top"></td>
 </tr>
 <tr>
   <td valign="top">PRODUCT_TAGS</td>
   <td valign="top">list of space-separated words for a given product</td>
   <td valign="top"></td>
 </tr>
</table>

</P>
<p>The snippet below illustrates a typical product definition file.</p>
<pre class="prettyprint">
$(call inherit-product, build/target/product/generic.mk)

#Overrides
PRODUCT_NAME := MyDevice
PRODUCT_MANUFACTURER := acme
PRODUCT_BRAND := acme_us
PRODUCT_LOCALES := en_GB es_ES fr_FR
PRODUCT_PACKAGE_OVERLAYS := vendor/acme/overlay

</pre>