Google Git
Sign in
android / platform / docs / source.android.com / refs/heads/oreo-m2-s3-release / . / en / source / add-device.html
blob: bd869f973627e57a669b310079908018b1fcdc23 [file] [log] [blame]
Android Partner Docs57543d42017-04-06 19:19:47 +0000[diff] [blame]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
Clay Murphy61fe8522015-07-07 17:15:12 -0700[diff] [blame]10
Android Partner Docs57543d42017-04-06 19:19:47 +0000[diff] [blame]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
Clay Murphy61fe8522015-07-07 17:15:12 -0700[diff] [blame]14
Android Partner Docs57543d42017-04-06 19:19:47 +0000[diff] [blame]15 http://www.apache.org/licenses/LICENSE-2.0
Clay Murphy61fe8522015-07-07 17:15:12 -0700[diff] [blame]16
Android Partner Docs57543d42017-04-06 19:19:47 +0000[diff] [blame]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 -->
Clay Murphy61fe8522015-07-07 17:15:12 -0700[diff] [blame]23
Android Partner Docs57543d42017-04-06 19:19:47 +0000[diff] [blame]24
Clay Murphy61fe8522015-07-07 17:15:12 -0700[diff] [blame]25
Clay Murphya5864b52015-07-30 11:44:49 -0700[diff] [blame]26<p>Use the information in this page to create the Makefiles for your device and
27product. Please note, unlike the other pages in this section, the contents here
28are applicable only when creating an entirely new device type and are intended
29for company build and product teams only.</p>
Clay Murphy61fe8522015-07-07 17:15:12 -0700[diff] [blame]30
31<h2 id="build-layers">Understand Build Layers</h2>
32
33<p>The build hierarchy includes the abstraction layers that correspond to the
34physical makeup of a device. These layers are described in the table below.
35Each layer relates to the one above it in a one-to-many relationship. For
36example, an architecture can have more than one board and each board can have
37more than one product. You may define an element in a given layer as a
38specialization of an element in the same layer, thus eliminating copying and
39simplifying 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>
Android Partner Docsdb839ff2017-05-31 17:05:57 -0700[diff] [blame]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.
Clay Murphy61fe8522015-07-07 17:15:12 -0700[diff] [blame]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
Android Partner Docsdb839ff2017-05-31 17:05:57 -0700[diff] [blame]72 configuration. The names used are merely codes for different board/device
73 configurations.</td>
Clay Murphy61fe8522015-07-07 17:15:12 -0700[diff] [blame]74 </tr>
75<tr>
76 <td>Arch</td>
77 <td>arm, x86, mips, arm64, x86_64, mips64</td>
Android Partner Docsdb839ff2017-05-31 17:05:57 -0700[diff] [blame]78 <td>The architecture layer describes the processor configuration and ABI
79 (Application Binary Interface) running on the board. </td>
Clay Murphy61fe8522015-07-07 17:15:12 -0700[diff] [blame]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
86variations on what is ultimately the final release build. In a module
87definition, the module can specify tags with <code>LOCAL_MODULE_TAGS</code>,
88which 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
92tag defaults to <code>optional</code>. An optional module is installed only if
93it 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>
Android Partner Docsdb839ff2017-05-31 17:05:57 -0700[diff] [blame]100 <code>eng</code>
Clay Murphy61fe8522015-07-07 17:15:12 -0700[diff] [blame]101 </td>
102 <td>
103 This is the default flavor.
Android Partner Docsdb839ff2017-05-31 17:05:57 -0700[diff] [blame]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
107addition 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>
Clay Murphy61fe8522015-07-07 17:15:12 -0700[diff] [blame]113 </td>
114</tr>
115<tr>
116 <td>
Android Partner Docsdb839ff2017-05-31 17:05:57 -0700[diff] [blame]117 <code>user</code>
Clay Murphy61fe8522015-07-07 17:15:12 -0700[diff] [blame]118 </td>
119 <td>
120 This is the flavor intended to be the final release bits.
Android Partner Docsdb839ff2017-05-31 17:05:57 -0700[diff] [blame]121<ul>
122<li>Installs modules tagged with <code>user</code>.</li>
123<li>Installs modules according to the product definition files, in
124addition 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>
Clay Murphy61fe8522015-07-07 17:15:12 -0700[diff] [blame]129 </td>
130</tr>
131<tr>
132 <td>
Android Partner Docsdb839ff2017-05-31 17:05:57 -0700[diff] [blame]133 <code>userdebug</code>
Clay Murphy61fe8522015-07-07 17:15:12 -0700[diff] [blame]134 </td>
135 <td>
136 The same as <code>user</code>, except:
Android Partner Docsdb839ff2017-05-31 17:05:57 -0700[diff] [blame]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>
Clay Murphy61fe8522015-07-07 17:15:12 -0700[diff] [blame]142 </td>
143</tr>
144</table>
145
Gina Diminobfee73a2016-12-07 11:30:17 -0800[diff] [blame]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
149a product at build time. Resource overlays specify resource
150files that are applied on top of the defaults. To use resource overlays, modify the project
151buildfile to set <code>PRODUCT_PACKAGE_OVERLAYS</code> to a
152path relative to your top-level directory. That path becomes a shadow root searched along with
153the current root when the build system searches for resources.</p>
154
155<p>The most commonly customized settings are contained in the file <a
156href="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
159project buildfile, as follows:</p>
160
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]161<pre class="devsite-click-to-copy">
162PRODUCT_PACKAGE_OVERLAYS := device/<var>DEVICE_IMPLEMENTER</var>/<var>DEVICE_NAME</var>/overlay
Gina Diminobfee73a2016-12-07 11:30:17 -0800[diff] [blame]163</pre>
164
165<p>or</p>
166
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]167<pre class="devsite-click-to-copy">
168PRODUCT_PACKAGE_OVERLAYS := vendor/<var>VENDOR_NAME</var>/overlay
Gina Diminobfee73a2016-12-07 11:30:17 -0800[diff] [blame]169</pre>
170
171<p> Then, add an overlay file to the directory, for example:</p>
172
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]173<pre class="devsite-click-to-copy">
Gina Diminobfee73a2016-12-07 11:30:17 -0800[diff] [blame]174vendor/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
178those found in the original file.</p>
179
Clay Murphy61fe8522015-07-07 17:15:12 -0700[diff] [blame]180<h2 id="build-a-product">Build a Product</h2>
181
182<p>
183There are many ways to organize the source files for your device. We'll briefly
184go over how the Nexus 6 implementation was organized as an example, but you can
185organize your source files and build the way you see fit.
186</p>
187<p>
188Nexus 6 was implemented with a main device configuration named
189<code>shamu</code>. From this device configuration, a product is created with a
190product definition Makefile that declares product-specific information about
191the 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>
Android Partner Docsdb839ff2017-05-31 17:05:57 -0700[diff] [blame]194<h3 id="makefiles">Write the Makefiles</h3>
Clay Murphy61fe8522015-07-07 17:15:12 -0700[diff] [blame]195<p>
196 The following steps describe how to set up product Makefiles in a way similar
197to 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
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]216<pre class="devsite-click-to-copy">
Clay Murphy61fe8522015-07-07 17:15:12 -0700[diff] [blame]217# Inherit from the common Open Source product configuration
218$(call inherit-product, $(SRC_TARGET_DIR)/product/aosp_base_telephony.mk)
219
220PRODUCT_NAME := aosp_shamu
221PRODUCT_DEVICE := shamu
222PRODUCT_BRAND := Android
223PRODUCT_MODEL := AOSP on Shamu
224PRODUCT_MANUFACTURER := motorola
225PRODUCT_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
230PRODUCT_NAME := aosp_shamu
231
232PRODUCT_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>:
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]245<pre class="devsite-click-to-copy">
Clay Murphy61fe8522015-07-07 17:15:12 -0700[diff] [blame]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
257PRODUCT_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:
Android Partner Docsddbca902017-06-13 09:11:47 -0700[diff] [blame]268<pre class="devsite-click-to-copy">
269add_lunch_combo <var>&lt;PRODUCT_NAME&gt;</var>-userdebug
Clay Murphy61fe8522015-07-07 17:15:12 -0700[diff] [blame]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>
Android Partner Docs57543d42017-04-06 19:19:47 +0000[diff] [blame]430
Android Partner Docs1f4ee092017-05-22 12:53:16 -0700[diff] [blame]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
434manufacturers to access production builds over <code>adb</code>. Generate a key
435for 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
438keys rather than random keys.</p>
439
440<p>Use the <code>ANDROID_VENDOR_KEYS</code> environment variable to
441point to the directory containing the generated <code>adb</code> public and
442private keys used for encryption. The private key is stored in file. The public
443key is stored in file.pub. The <code>ANDROID_VENDOR_KEYS</code> environment
444variable points to a file or directory where the generated key pairs are
445stored.</p>
446
447<p>This variable is set to a file or directory that contains 2048-bit RSA
448authentication key pairs generated with the <code>adb keygen</code> file command.
449These key pairs are in addition to the RSA key pairs generated by the ADB
450server. An RSA key pair is needed when you use <code>adb</code> to connect over
451USB 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
455ADB 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
461also be in <code>C:\Windows\System32\config\systemprofile\.android</code> in
462some cases. When the ADB server needs a key, it first searches the ADB server
463key store directory. If no keys are found, it then checks the
464<code>ANDROID_VENDOR_KEYS</code> environment variable. If no keys are found,
465the local ADB server generates and saves a new key pair in the ADB server key
466store directory.</p>
467
468<p class="note"><strong>Note:</strong> You can override the default directory
469where the ADB server stores RSA keys by setting the
470<code>ANDROID_SDK_HOME</code> environment variable. On the device, keys are
471stored in the <code>/data/misc/adb/adb_keys/</code> file, and new authorized
472keys are appended to the same file as you accept them.</p>
473
Android Partner Docs57543d42017-04-06 19:19:47 +0000[diff] [blame]474 </body>
475</html>