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