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