Home | History | Annotate | Download | only in source
      1 <html devsite>
      2   <head>
      3     <title>Adding a New Device</title>
      4     <meta name="project_path" value="/_project.yaml" />
      5     <meta name="book_path" value="/_book.yaml" />
      6   </head>
      7   <body>
      8   <!--
      9       Copyright 2017 The Android Open Source Project
     10 
     11       Licensed under the Apache License, Version 2.0 (the "License");
     12       you may not use this file except in compliance with the License.
     13       You may obtain a copy of the License at
     14 
     15           http://www.apache.org/licenses/LICENSE-2.0
     16 
     17       Unless required by applicable law or agreed to in writing, software
     18       distributed under the License is distributed on an "AS IS" BASIS,
     19       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     20       See the License for the specific language governing permissions and
     21       limitations under the License.
     22   -->
     23 
     24 
     25 
     26 <p>Use the information in this page to create the Makefiles for your device and
     27 product. Please note, unlike the other pages in this section, the contents here
     28 are applicable only when creating an entirely new device type and are intended
     29 for company build and product teams only.</p>
     30 
     31 <h2 id="build-layers">Understand Build Layers</h2>
     32 
     33 <p>The build hierarchy includes the abstraction layers that correspond to the
     34 physical makeup of a device. These layers are described in the table below.
     35 Each layer relates to the one above it in a one-to-many relationship. For
     36 example, an architecture can have more than one board and each board can have
     37 more than one product. You may define an element in a given layer as a
     38 specialization of an element in the same layer, thus eliminating copying and
     39 simplifying maintenance.</p>
     40 
     41 <table>
     42  <tbody><tr>
     43   <th>Layer</th>
     44   <th>Example</th>
     45   <th>Description</th>
     46  </tr>
     47   <tr>
     48     <td>Product</td>
     49     <td>myProduct, myProduct_eu, myProduct_eu_fr, j2, sdk</td>
     50     <td>The product layer defines the feature specification of a shipping
     51     product such as the modules to build, locales supported, and the
     52     configuration for various locales. In other words, this is the name
     53     of the overall product. Product-specific variables are defined in
     54     product definition Makefiles. A product can inherit from other
     55     product definitions, which simplifies maintenance. A common method
     56     is to create a base product that contains features that apply for
     57     all products, then creating product variants based on that base
     58     product. For example, you can have two products that differ only by
     59     their radios (CDMA vs GSM) inherit from the same base product that
     60     does not define a radio.
     61 </td>
     62 
     63   </tr>
     64  <tr>
     65     <td>Board/Device</td>
     66     <td>sardine, trout, goldfish</td>
     67     <td>The device/board layer represents the physical layer of plastic on the
     68     device (i.e. the industrial design of the device). For example, North American
     69     devices probably include QWERTY keyboards whereas devices sold in France
     70     probably include AZERTY keyboards. This layer also represents the bare
     71     schematics of a product. These include the peripherals on the board and their
     72     configuration. The names used are merely codes for different board/device
     73     configurations.</td>
     74   </tr>
     75 <tr>
     76     <td>Arch</td>
     77     <td>arm, x86, mips, arm64, x86_64, mips64</td>
     78     <td>The architecture layer describes the processor configuration and ABI
     79     (Application Binary Interface) running on the board. </td>
     80   </tr>
     81 </table>
     82 
     83 <h2 id="build-variants">Use Build Variants</h2>
     84 
     85 <p>When building for a particular product, it's often useful to have minor
     86 variations on what is ultimately the final release build. In a module
     87 definition, the module can specify tags with <code>LOCAL_MODULE_TAGS</code>,
     88 which can be one or more values of <code>optional</code> (default),
     89 <code>debug</code>, <code>eng</code>.</p>
     90 
     91 <p>If a module doesn't specify a tag (by <code>LOCAL_MODULE_TAGS</code>), its
     92 tag defaults to <code>optional</code>. An optional module is installed only if
     93 it is required by product configuration with <code>PRODUCT_PACKAGES</code>.
     94 
     95 <p>These are the currently-defined build variants:</p>
     96 
     97 <table border=1>
     98 <tr>
     99     <td>
    100         <code>eng</code>
    101     </td>
    102     <td>
    103         This is the default flavor.
    104 <ul>
    105 <li>Installs modules tagged with: <code>eng</code> and/or <code>debug</code>.</li>
    106 <li>Installs modules according to the product definition files, in
    107 addition to tagged modules.</li>
    108 <li><code>ro.secure=0</code></li>
    109 <li><code>ro.debuggable=1</code></li>
    110 <li><code>ro.kernel.android.checkjni=1</code></li>
    111 <li><code>adb</code> is enabled by default.</li>
    112 </ul>
    113     </td>
    114 </tr>
    115 <tr>
    116     <td>
    117         <code>user</code>
    118     </td>
    119     <td>
    120         This is the flavor intended to be the final release bits.
    121 <ul>
    122 <li>Installs modules tagged with <code>user</code>.</li>
    123 <li>Installs modules according to the product definition files, in
    124 addition to tagged modules.</li>
    125 <li><code>ro.secure=1</code> </li>
    126 <li><code>ro.debuggable=0</code> </li>
    127 <li><code>adb</code> is disabled by default.</li>
    128 </ul>
    129     </td>
    130 </tr>
    131 <tr>
    132     <td>
    133         <code>userdebug</code>
    134     </td>
    135     <td>
    136         The same as <code>user</code>, except:
    137 <ul>
    138 <li>Also installs modules tagged with <code>debug</code>.</li>
    139 <li><code>ro.debuggable=1</code></li>
    140 <li><code>adb</code> is enabled by default.</li>
    141 </ul>
    142     </td>
    143 </tr>
    144 </table>
    145 
    146 <h2 id="use-resource-overlays">Customize the Build with Resource Overlays</h2>
    147 
    148 <p>The Android build system uses resource overlays to customize
    149 a product at build time. Resource overlays specify resource
    150 files that are applied on top of the defaults. To use resource overlays, modify the project
    151 buildfile to set <code>PRODUCT_PACKAGE_OVERLAYS</code> to a
    152 path relative to your top-level directory. That path becomes a shadow root searched along with
    153 the current root  when the build system searches for resources.</p>
    154 
    155 <p>The most commonly customized settings are contained in the file <a
    156 href="https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/values/config.xml">frameworks/base/core/res/res/config.xml</a>.</p>
    157 
    158 <p> To set up a resource overlay on this file, add the overlay directory to the
    159 project buildfile, as follows:</p>
    160 
    161 <pre class="devsite-click-to-copy">
    162 PRODUCT_PACKAGE_OVERLAYS := device/<var>DEVICE_IMPLEMENTER</var>/<var>DEVICE_NAME</var>/overlay
    163 </pre>
    164 
    165 <p>or</p>
    166 
    167 <pre class="devsite-click-to-copy">
    168 PRODUCT_PACKAGE_OVERLAYS := vendor/<var>VENDOR_NAME</var>/overlay
    169 </pre>
    170 
    171 <p> Then, add an overlay file to the directory, for example:</p>
    172 
    173 <pre class="devsite-click-to-copy">
    174 vendor/foobar/overlay/frameworks/base/core/res/res/config.xml
    175 </pre>
    176 
    177 <p> Any strings or string arrays found in the overlay <code>config.xml</code> file replace
    178 those found in the original file.</p>
    179 
    180 <h2 id="build-a-product">Build a Product</h2>
    181 
    182 <p>
    183 There are many ways to organize the source files for your device. We'll briefly
    184 go over how the Nexus 6 implementation was organized as an example, but you can
    185 organize your source files and build the way you see fit.
    186 </p>
    187 <p>
    188 Nexus 6 was implemented with a main device configuration named
    189 <code>shamu</code>. From this device configuration, a product is created with a
    190 product definition Makefile that declares product-specific information about
    191 the device such as the name and model. You can view the
    192 <code>device/moto/shamu</code> directory to see how all of this is setup.
    193 </p>
    194 <h3 id="makefiles">Write the Makefiles</h3>
    195 <p>
    196   The following steps describe how to set up product Makefiles in a way similar
    197 to that of the Nexus 6 product line:
    198 </p>
    199 <ol>
    200   <li>Create a <code>device/&lt;company_name&gt;/&lt;device_name&gt;</code> directory for your
    201   product. For example, <code>device/moto/shamu</code>. This directory will contain source code
    202   for your device along with the Makefiles to build them.
    203   </li>
    204 
    205   <li>Create a <code>device.mk</code> Makefile that declares the files and modules needed for the
    206   device. For an example, see <code>device/moto/shamu/device.mk</code>.
    207   </li>
    208 
    209   <li>Create a product definition Makefile to create a specific product based on the device. The
    210   following Makefile is taken from <code>device/moto/shamu/aosp_shamu.mk</code> as an example.
    211   Notice the product is inheriting from the
    212   <code>device/moto/shamu/device.mk</code> and
    213   <code>vendor/moto/shamu/device-vendor.mk</code> files via the Makefile while
    214   also declaring the product-specific information such as name, brand, and model.
    215 
    216 <pre class="devsite-click-to-copy">
    217 # Inherit from the common Open Source product configuration
    218 $(call inherit-product, $(SRC_TARGET_DIR)/product/aosp_base_telephony.mk)
    219 
    220 PRODUCT_NAME := aosp_shamu
    221 PRODUCT_DEVICE := shamu
    222 PRODUCT_BRAND := Android
    223 PRODUCT_MODEL := AOSP on Shamu
    224 PRODUCT_MANUFACTURER := motorola
    225 PRODUCT_RESTRICT_VENDOR_FILES := true
    226 
    227 $(call inherit-product, device/moto/shamu/device.mk)
    228 $(call inherit-product-if-exists, vendor/moto/shamu/device-vendor.mk)
    229 
    230 PRODUCT_NAME := aosp_shamu
    231 
    232 PRODUCT_PACKAGES += \
    233     Launcher3
    234 </pre>
    235 
    236     <p>
    237       See <a href="#prod-def">Product Definition Variables</a> for additional product-specific
    238       variables you can add to your Makefiles.
    239     </p>
    240   </li>
    241 
    242   <li>Create an <code>AndroidProducts.mk</code> file that points to the product's Makefiles. In
    243   this example, only the product definition Makefile is needed. The example below is from
    244   <code>device/moto/shamu/AndroidProducts.mk</code>:
    245 <pre class="devsite-click-to-copy">
    246 #
    247 # This file should set PRODUCT_MAKEFILES to a list of product makefiles
    248 # to expose to the build system.  LOCAL_DIR will already be set to
    249 # the directory containing this file.
    250 #
    251 # This file may not rely on the value of any variable other than
    252 # LOCAL_DIR; do not use any conditionals, and do not look up the
    253 # value of any variable that isn't set in this file or in a file that
    254 # it includes.
    255 #
    256 
    257 PRODUCT_MAKEFILES := \
    258     $(LOCAL_DIR)/aosp_shamu.mk
    259 </pre>
    260   </li>
    261 
    262   <li>Create a <code>BoardConfig.mk</code> Makefile that contains board-specific configurations.
    263   For an example, see <code>device/moto/shamu/BoardConfig.mk</code>.
    264   </li>
    265 
    266   <li>Create a <code>vendorsetup.sh</code> file to add your product (a "lunch combo") to the build
    267   along with a <a href="#build-variants">build variant</a> separated by a dash. For example:
    268 <pre class="devsite-click-to-copy">
    269 add_lunch_combo <var>&lt;PRODUCT_NAME&gt;</var>-userdebug
    270 </pre>
    271   </li>
    272 
    273   <li>At this point, you can create more product variants based on the same device.
    274   </li>
    275 
    276 </ol>
    277 <h3 id="prod-def">Set Product Definition Variables</h3>
    278 <p>
    279   Product-specific variables are defined in the product's Makefile. Variables maintained in a
    280   product definition files include:
    281 </p>
    282 <table>
    283   <tbody>
    284     <tr>
    285       <th>
    286         Parameter
    287       </th>
    288       <th>
    289         Description
    290       </th>
    291       <th>
    292         Example
    293       </th>
    294     </tr>
    295     <tr>
    296       <td>
    297         PRODUCT_AAPT_CONFIG
    298       </td>
    299       <td>
    300         <code>aapt</code> configurations to use when creating packages
    301       </td>
    302       <td></td>
    303     </tr>
    304     <tr>
    305       <td>
    306         PRODUCT_BRAND
    307       </td>
    308       <td>
    309         The brand (e.g., carrier) the software is customized for, if any
    310       </td>
    311       <td></td>
    312     </tr>
    313     <tr>
    314       <td>
    315         PRODUCT_CHARACTERISTICS
    316       </td>
    317       <td>
    318         <code>aapt</code> characteristics to allow adding variant-specific resources to a package.
    319       </td>
    320       <td>
    321         tablet,nosdcard
    322       </td>
    323     </tr>
    324     <tr>
    325       <td>
    326         PRODUCT_COPY_FILES
    327       </td>
    328       <td>
    329         List of words like <code>source_path:destination_path</code>. The file at the source path
    330         should be copied to the destination path when building this product. The rules for the copy
    331         steps are defined in config/Makefile
    332       </td>
    333       <td></td>
    334     </tr>
    335     <tr>
    336       <td>
    337         PRODUCT_DEVICE
    338       </td>
    339       <td>
    340         Name of the industrial design. This is also the board name, and the build system uses it to locate the <code>BoardConfig.mk.</code>
    341       </td>
    342       <td>
    343         <code>tuna</code>
    344       </td>
    345     </tr>
    346     <tr>
    347       <td>
    348         PRODUCT_LOCALES
    349       </td>
    350       <td>
    351         A space-separated list of two-letter language code, two-letter country code pairs that
    352         describe several settings for the user, such as the UI language and time, date and currency
    353         formatting. The first locale listed in PRODUCT_LOCALES is used as the product's default locale.
    354       </td>
    355       <td>
    356         <code>en_GB de_DE es_ES fr_CA</code>
    357       </td>
    358     </tr>
    359     <tr>
    360       <td>
    361         PRODUCT_MANUFACTURER
    362       </td>
    363       <td>
    364         Name of the manufacturer
    365       </td>
    366       <td>
    367         <code>acme</code>
    368       </td>
    369     </tr>
    370     <tr>
    371       <td>
    372         PRODUCT_MODEL
    373       </td>
    374       <td>
    375         End-user-visible name for the end product
    376       </td>
    377       <td></td>
    378     </tr>
    379     <tr>
    380       <td>
    381         PRODUCT_NAME
    382       </td>
    383       <td>
    384         End-user-visible name for the overall product. Appears in the Settings &gt; About screen.
    385       </td>
    386       <td></td>
    387     </tr>
    388     <tr>
    389       <td>
    390         PRODUCT_OTA_PUBLIC_KEYS
    391       </td>
    392       <td>
    393         List of Over the Air (OTA) public keys for the product
    394       </td>
    395       <td></td>
    396     </tr>
    397     <tr>
    398       <td>
    399         PRODUCT_PACKAGES
    400       </td>
    401       <td>
    402         Lists the APKs and modules to install.
    403       </td>
    404       <td>
    405         <code>Calendar Contacts</code>
    406       </td>
    407     </tr>
    408     <tr>
    409       <td>
    410         PRODUCT_PACKAGE_OVERLAYS
    411       </td>
    412       <td>
    413         Indicate whether to use default resources or add any product specific overlays
    414       </td>
    415       <td>
    416         <code>vendor/acme/overlay</code>
    417       </td>
    418     </tr>
    419     <tr>
    420       <td>
    421         PRODUCT_PROPERTY_OVERRIDES
    422       </td>
    423       <td>
    424         List of system property assignments in the format "key=value"
    425       </td>
    426       <td></td>
    427     </tr>
    428   </tbody>
    429 </table>
    430 
    431 <h3 id="ANDROID_VENDOR_KEYS">Set ANDROID_VENDOR_KEYS to connect over USB</h3>
    432 
    433 <p>The <code>ANDROID_VENDOR_KEYS</code> environment variable enables device
    434 manufacturers to access production builds over <code>adb</code>. Generate a key
    435 for each release that every device will accept, store those internally (such as at
    436 <code>vendor/oem-name/security/adb/</code>), and then use
    437 <code>ANDROID_VENDOR_KEYS</code> to tell <code>adb</code> to use these canonical
    438 keys rather than random keys.</p>
    439 
    440 <p>Use the <code>ANDROID_VENDOR_KEYS</code> environment variable to
    441 point to the directory containing the generated <code>adb</code> public and
    442 private keys used for encryption. The private key is stored in file. The public
    443 key is stored in file.pub. The <code>ANDROID_VENDOR_KEYS</code> environment
    444 variable points to a file or directory where the generated key pairs are
    445 stored.</p>
    446 
    447 <p>This variable is set to a file or directory that contains 2048-bit RSA
    448 authentication key pairs generated with the <code>adb keygen</code> file command.
    449 These key pairs are in addition to the RSA key pairs generated by the ADB
    450 server. An RSA key pair is needed when you use <code>adb</code> to connect over
    451 USB for the first time.</p>
    452 
    453 <p>You must accept the host computer's RSA key to explicitly grant
    454 <code>adb</code> access to the device. By default key pairs generated by the
    455 ADB server are stored in the following key store directories as
    456 <code>adbkey</code> (private key) and <code>adbkey.pub</code> (public key):</p>
    457 
    458 <p>For file locations, on MacOS, this will likely be:
    459 <code>$HOME/.android</code>.  On Windows and Linux, this will be:
    460 <code>%USERPOFILE%\.android</code>. On Windows, RSA authentication keys can
    461 also be in <code>C:\Windows\System32\config\systemprofile\.android</code> in
    462 some cases. When the ADB server needs a key, it first searches the ADB server
    463 key store directory. If no keys are found, it then checks the
    464 <code>ANDROID_VENDOR_KEYS</code> environment variable. If no keys are found,
    465 the local ADB server generates and saves a new key pair in the ADB server key
    466 store directory.</p>
    467 
    468 <p class="note"><strong>Note:</strong> You can override the default directory
    469 where the ADB server stores RSA keys by setting the
    470 <code>ANDROID_SDK_HOME</code> environment variable. On the device, keys are
    471 stored in the <code>/data/misc/adb/adb_keys/</code> file, and new authorized
    472 keys are appended to the same file as you accept them.</p>
    473 
    474   </body>
    475 </html>
    476