blob: 4286e71f012515eee694816f3b6688940669ab9f [file] [log] [blame]
The Android Open Source Project5c118522008-10-21 07:00:00 -07001
2<html>
3<head>
4<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
The Android Open Source Projecte943f2f2008-12-17 18:04:04 -08005<title>Android - Porting Guide</title>
The Android Open Source Project5c118522008-10-21 07:00:00 -07006<script src="http://www.google.com/uds/api?file=uds.js&amp;v=1.0&amp;key=internal-codesite" type="text/javascript"></script>
7<script src="http://code.google.com/js/jquery.js" type="text/javascript"></script>
8<script type="text/javascript">var _tocPath_ = 'http://code.google.com/android/_toc.ezt';</script>
9<script src="http://code.google.com/js/codesite.pack.01312008.js" type="text/javascript"></script>
The Android Open Source Projecte943f2f2008-12-17 18:04:04 -080010<script language="JavaScript">
11function resizeHeight() {
12 if(document.getElementById && !(document.all)) {
13 height= document.getElementById('doxygen').contentDocument.body.scrollHeight + 20;
14 document.getElementById('doxygen').style.height = height;
15 }
16 else if(document.all) {
17 height= document.frames('doxygen').document.body.scrollHeight + 20;
18 document.all.doxygen.style.height = height;
19 }
20}
21</script>
The Android Open Source Project5c118522008-10-21 07:00:00 -070022<link href="http://code.google.com/css/codesite.pack.01312008.css" type="text/css" rel="stylesheet">
23</link>
24
25<!--[if IE]><link rel="stylesheet" type="text/css" href="/css/iehacks.css" /><![endif]-->
26<script src="http://code.google.com/android/assets/search_autocomplete.js"></script>
27<link rel="stylesheet" type="text/css" href="http://code.google.com/css/semantic_headers.css" />
28<link rel="stylesheet" type="text/css" href="http://code.google.com/android/assets/style.css" />
29<script>
30 jQuery(document).ready(function() {
31 jQuery("pre").addClass("prettyprint");
32 });
33 </script>
34<style type="text/css">
35<!--
36h1,h2,h3 {
37 color: #000000;
38}
39-->
40</style>
41</head>
42<body class="gc-documentation">
43<div id="gc-container">
44<a name="top"></a>
45<div id="skipto"> </div>
46<div id="langpref">
47 <!--<a class="dropdown" href="/">English</a> <span>|</span> <a href="/more/">Site Directory</a> -->
The Android Open Source Projecte943f2f2008-12-17 18:04:04 -080048
The Android Open Source Project5c118522008-10-21 07:00:00 -070049</div>
50<div id="gc-header">
51 <div id="logo"><a href="http://code.google.com/android/index.html"><img src="http://code.google.com/android/images/logo_android.gif" alt="Android"/></a></div>
52 <div id="search" style="inline">
53 <div id="searchForm" class="searchForm" style="height: 44px;">
54 <!--previously form was here-->
55 </div>
56 <!-- end searchForm -->
57 <noscript>
58 <style type="text/css">
59 .searchForm {
60 display : none !important;
61 }
62 .searchForm2 {
63 display : inline !important;
64 }
65 </style>
66 </noscript>
The Android Open Source Projecte943f2f2008-12-17 18:04:04 -080067
The Android Open Source Project5c118522008-10-21 07:00:00 -070068 <div id="searchForm2" class="searchForm2" style="display:none">
69 <form id="searchbox_001456098540849067467:6whlsytkdqg" action="http://www.google.com/cse">
70 <input type="hidden" name="cx" value="001456098540849067467:6whlsytkdqg" />
71 <input type="hidden" name="cof" value="FORID:0" />
72 <input type="text" name="q" maxlength="2048" size="41" autocomplete="off" title="Google Code Search"/>
73 <input type="submit" name="sa" value="Search" title="Search"/>
74 <br/>
75 <div class="greytext">e.g. "ajax apis" or "open source"</div>
The Android Open Source Projecte943f2f2008-12-17 18:04:04 -080076
The Android Open Source Project5c118522008-10-21 07:00:00 -070077 </form>
78 </div>
79 <!-- end searchForm2 -->
80 </div>
81 <!-- end search -->
82</div>
83<!-- end gc-header -->
84<div id="searchControl" class="search-control"></div>
85<!--[if IE]><iframe id="backiFrame" name="backiFrame" src='/dummy.html' style="display:none"></iframe><![endif]-->
86<div id="codesiteContent">
87<a name="gc-topnav-anchor"></a>
88<div id="gc-topnav">
The Android Open Source Projecte943f2f2008-12-17 18:04:04 -080089
The Android Open Source Project5c118522008-10-21 07:00:00 -070090 <h1>Android Platform Development Kit</h1>
91 <ul class="gc-topnav-tabs">
92 <li id="sdk_link"> <a href="http://code.google.com/android/index.html" title="Android Software Development Kit">SDK</a> </li>
93 <li id="docs_link"> <a href="index.html" title="Official Android documentation">Docs</a> </li>
94 <li id="faq_link"> <a href="http://code.google.com/android/kb/index.html" title="Answers to frequently asked questions about Android">FAQ</a> </li>
The Android Open Source Projecte943f2f2008-12-17 18:04:04 -080095
The Android Open Source Project5c118522008-10-21 07:00:00 -070096 <li> <a href="http://android-developers.blogspot.com/" title="Official Android blog">Blog</a> </li>
97 <li> <a href="http://code.google.com/android/groups.html" title="Android developer forum">Group</a> </li>
98 <li> <a href="http://code.google.com/android/terms.html" title="Android terms of service">Terms</a> </li>
The Android Open Source Projecte943f2f2008-12-17 18:04:04 -080099 <li> <a href="mailto:android-pdk-feedback@google.com?subject=PDK%20Feedback&body=(filed%20from:%20build_system.html%20v0.6%20-%2025%20November%202008)%0D%0A%0D%0ASUMMARY:%0D%0A%0D%0A%0D%0A%0D%0ASTEPS%20TO%20REPRODUCE:%0D%0A%0D%0A%0D%0A%0D%0AADDITIONAL%20NOTES:">Report a Problem</a> </li>
100
The Android Open Source Project5c118522008-10-21 07:00:00 -0700101 </ul>
102</div>
103<!-- end gc-topnav -->
104<div class="g-section g-tpl-180">
105<a name="gc-toc"></a>
106<div class="g-unit g-first" id="gc-toc">
107 <ul>
108 <li>
109 <h1><a href="index.html">Documentation</a></h1>
110 <ul>
111 <li> <strong>Introduction</strong>
The Android Open Source Projecte943f2f2008-12-17 18:04:04 -0800112
The Android Open Source Project5c118522008-10-21 07:00:00 -0700113 <ul>
114 <li><a href="system_requirements.html">Device Requirements</a></li>
115 </ul>
116 </li>
117 <li> <strong>Dev Environment Setup</strong>
118 <ul>
The Android Open Source Project5c118522008-10-21 07:00:00 -0700119 <li><a href="build_system.html">Build System</a></li>
120 </ul>
121 </li>
122 <li> <strong>Basic Bring up</strong>
The Android Open Source Projecte943f2f2008-12-17 18:04:04 -0800123
The Android Open Source Project5c118522008-10-21 07:00:00 -0700124 <ul>
125 <li><a href="build_new_device.html">Building New Device</a></li>
126 <li><a href="bring_up.html">Bring up</a></li>
127 <li><a href="keymaps_keyboard_input.html">Keymaps and Keyboard</a></li>
128 <li><a href="display_drivers.html">Display Drivers</a></li>
129 </ul>
130 </li>
The Android Open Source Projecte943f2f2008-12-17 18:04:04 -0800131
The Android Open Source Project5c118522008-10-21 07:00:00 -0700132 <li> <strong>Multimedia</strong>
133 <ul>
The Android Open Source Projecte943f2f2008-12-17 18:04:04 -0800134 <li><a href="audio_sub_system.html">Audio</a></li>
135 <li><a href="camera.html">Camera</a></li>
The Android Open Source Project5c118522008-10-21 07:00:00 -0700136 </ul>
137 </li>
138 <li> <strong>Power Management</strong>
The Android Open Source Projecte943f2f2008-12-17 18:04:04 -0800139
The Android Open Source Project5c118522008-10-21 07:00:00 -0700140 <ul>
141 <li><a href="power_management.html">Power Management</a></li>
142 </ul>
143 </li>
The Android Open Source Projecte943f2f2008-12-17 18:04:04 -0800144
145 <li> <strong>Networking</strong>
146 <ul>
147 <li><a href="wifi.html">Wi-Fi</a></li>
148 <li><a href="gps.html">GPS</a></li>
149 <li><a href="bluetooth.html">Bluetooth</a></li>
150 </ul>
151 </li>
152
The Android Open Source Project5c118522008-10-21 07:00:00 -0700153 <li> <strong>Telephony</strong>
154 <ul>
155 <li><a href="telephony.html">Radio Interface Layer</a></li>
The Android Open Source Projecte943f2f2008-12-17 18:04:04 -0800156
The Android Open Source Project5c118522008-10-21 07:00:00 -0700157 </ul>
158 </li>
159 <li> <strong>Testing</strong>
160 <ul>
The Android Open Source Project5c118522008-10-21 07:00:00 -0700161 <li><a href="instrumentation_testing.html">Instrumentation Testing</a></li>
162 </ul>
The Android Open Source Projecte943f2f2008-12-17 18:04:04 -0800163
The Android Open Source Project5c118522008-10-21 07:00:00 -0700164 </li>
165 </ul>
166 </li>
167 </ul>
168</div>
169<a name="gc-pagecontent"></a>
170<div class="g-unit" id="gc-pagecontent">
171<div id="jd-content">
172<div class="jd-descr">
173
174
175<a name="androidBuildSystemTitle"></a><h1>Android Build System</h1>
176
177
178
179<a name="toc"/>
180<div style="padding:10px">
181<a href="#androidBuildSystemIntroduction">Introduction</a><br/>
182<a href="#androidBuildSystemUnderstanding">Understanding Android's Build System</a><br/><div style="padding-left:40px">
183
184<a href="#androidBuildSystemOverview">Understanding the makefile</a><br/>
185<a href="#androidBuildSystemLayers">Layers</a><br/>
186<a href="#androidBuildSystemProductDefFiles">Product Definition Files</a><br/></div>
187<a href="#androidSourceSetupBuildingCodeBase">Building the Android Platform</a><br/><div style="padding-left:40px">
188
189<a href="#androidSourceSetupBuildingDeviceCodeBase">Device Code</a><br/>
190<a href="#androidBuildingCleaning">Cleaning Up</a><br/>
191<a href="#androidBuildingSpeeding">Speeding Up Rebuilds</a><br/>
192<a href="#androidBuildingTroubleshooting">Troubleshooting</a><br/></div>
193<a href="#androidSourceSetupBuildingKernel">Building the Android Kernel</a><br/><div style="padding-left:40px">
194
195<a href="#androidSourceSetupBuildingKernelCheckingBranch">Checking Out a Branch</a><br/>
196<a href="#androidSourceSetupBuildingKernelBranchLocation">Verifying Location</a><br/>
197<a href="#androidSourceSetupBuildingKernelBuild">Building the Kernel</a><br/></div></div></font></div>
198
199<a name="androidBuildSystemIntroduction"></a><h2>Introduction</h2>
200
201<p>Android uses a custom build system to generate tools, binaries, and documentation. This document provides an overview of Android's build system and instructions for doing a simple build. </p>
202<p>Android's build system is make based and requires a recent version of GNU Make (note that Android uses advanced features of GNU Make that may not yet appear on the GNU Make web site). Before continuing, check your version of make by running <code>% make -v</code>. If you don't have version 3.80 or greater, you need to <a href="http://www.gnu.org/software/make/">upgrade your version of make</a>. </p>
203
204
205<a name="androidBuildSystemUnderstanding"></a><h2>Understanding Android's Build System</h2>
206
207
208
209<a name="androidBuildSystemOverview"></a><h3>Understanding the makefile</h3>
210
211<p>A makefile defines how to build a particular application. Makefiles typically include all of the following elements:</p>
212<ol>
213 <li>Name: Give your build a name (<code>LOCAL_MODULE := &lt;build_name&gt;</code>).</li>
214 <li>Local Variables: Clear local variables with CLEAR_VARS (<code>include $(CLEAR_VARS)</code>).</li>
215 <li>Files: Determine which files your application depends upon (<code>LOCAL_SRC_FILES := main.c</code>).</li>
216 <li>Tags: Define tags, as necessary (<code>LOCAL_MODULE_TAGS := eng development</code>).</li>
217 <li>Libraries: Define whether your application links with other libraries (<code>LOCAL_SHARED_LIBRARIES := cutils</code>).</li>
218 <li>Template file: Include a template file to define underlining make tools for a particular target (<code>include $(BUILD_EXECUTABLE)</code>).</li>
219</ol>
220
221<p>The following snippet illustrates a typical makefile.</p>
222<pre class="prettyprint">
223LOCAL_PATH := $(my-dir)
224include $(CLEAR_VARS)
225LOCAL_MODULE := &lt;buil_name&gt;
226LOCAL_SRC_FILES := main.c
227LOCAL_MODULE_TAGS := eng development
228LOCAL_SHARED_LIBRARIES := cutils
229include $(BUILD_EXECUTABLE)
230(HOST_)EXECUTABLE, (HOST_)JAVA_LIBRARY, (HOST_)PREBUILT, (HOST_)SHARED_LIBRARY,
231 (HOST_)STATIC_LIBRARY, PACKAGE, JAVADOC, RAW_EXECUTABLE, RAW_STATIC_LIBRARY,
232 COPY_HEADERS, KEY_CHAR_MAP
233</pre>
234<p>The snippet above includes artificial line breaks to maintain a print-friendly document.</p>
235
236
237<a name="androidBuildSystemLayers"></a><h3>Layers</h3>
238
239<p>The build hierarchy includes the abstraction layers described in the table below.</p>
240
241<p>Each layer relates to the one above it in a one-to-many relationship. For example, an arch can have more than one board and each board can have more than one device. You may define an element in a given layer as a specialization of an element in the same layer, thus eliminating copying and simplifying maintenance.</p>
242
243<table border=1 cellpadding=2 cellspacing=0>
244 <tbody><tr>
245 <th scope="col">Layer</th>
246 <th scope="col">Example</th>
247 <th scope="col">Description</th>
248 </tr>
249 <tr>
250 <td valign="top">Product</td>
251 <td valign="top">myProduct, myProduct_eu, myProduct_eu_fr, j2, sdk</td>
252 <td valign="top">The product layer defines a complete specification of a shipping product, defining which modules to build and how to configure them. You might offer a device in several different versions based on locale, for example, or on features such as a camera. </td>
253 </tr>
254 <tr>
255 <td valign="top">Device</td>
256 <td valign="top">myDevice, myDevice_eu, myDevice_eu_lite</td>
257 <td valign="top">The device layer represents the physical layer of plastic on the device. For example, North American devices probably include QWERTY keyboards whereas devices sold in France probably include AZERTY keyboards. Peripherals typically connect to the device layer. </td>
258 </tr>
259 <tr>
260 <td valign="top">Board</td>
261 <td valign="top">sardine, trout, goldfish </td>
262 <td valign="top">The board layer represents the bare schematics of a product. You may still connect peripherals to the board layer. </td>
263 </tr>
264 <tr>
265 <td valign="top">Arch</td>
266 <td valign="top">arm (arm5te) (arm6), x86, 68k </td>
267 <td valign="top">The arch layer describes the processor running on your board. </td>
268 </tr>
269</table>
270
271
272<a name="androidBuildSystemProductDefFiles"></a><h3>Product Definition Files</h3>
273
274<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>
275<p>Variables maintained in a product definition files include:</p>
276<p><ul>
277<li><code>PRODUCT_DEVICE</code></LI>
278<LI><code>LOCALES</code></LI>
279<LI><code>BRANDING_PARTNER</code></LI>
280<LI><code>PROPERTY_OVERRIDES</code></LI>
281</UL>
282</P>
283<p>The snippet below illustrates a typical product definition file.</p>
284<PRE class="prettyprint">
285//device/target/product/core.mk
286PRODUCT_PACKAGES := Home SettingsProvider ...
287//device/target/product/generic.mk
288PRODUCT_PACKAGES := Calendar Camera SyncProvider ...
289$(call inherit-product, target/product/core.mk)
290PRODUCT_NAME := generic
291//device/partner/google/products/core.mk
292PRODUCT_PACKAGES := Maps GoogleAppsProvider ...
293$(call inherit-product, target/product/core.mk)
294//device/partner/google/products/generic.mk
295PRODUCT_PACKAGES := Gmail GmailProvider ...
296$(call inherit-product, partner/google/products/core.mk)
297$(call inherit-product, target/product/generic.mk)
298PRODUCT_NAME := google_generic
299
300</pre>
301
302
303<a name="androidSourceSetupBuildingCodeBase"></a><h2>Building the Android Platform</h2>
304
305<p>This section describes how to build the default version of Android. Once you are comfortable with a generic build, then you can begin to modify Android for your own target device.</p>
306
307
308<a name="androidSourceSetupBuildingDeviceCodeBase"></a><h3>Device Code</h3>
309
310<p>Of the two options below, the first tends to yield more consistent results.</p>
311
312
313<a name="androidSourceSetupBuildingDeviceCodeBaseOption2"></a><h4>Option 1</h4>
314
315<p>Create a local version of buildspec.mk. The easiest way to do so is to change to your device directory and execute the following:</p>
316<pre class="prettyprint">% cp buildspec.mk.default buildspec.mk ; chmod u=rw buildspec.mk</pre>
317<p>The default <code>buildspec.mk</code>. file is written so that all options appear commented. In order to establish a personal configuration environment, edit <code>buildspec.mk</code> as desired.</p>
318<p>Once you have established your configuration environment, you can build the device code base by executing make in order to build the Android binaries. This may take a long time the first time you issue this command. On a dual-core machine, consider using '-j2' (or even '-j4') to speed up the build.</p>
319<pre class="prettyprint">% make -j2</pre>
320
321
322<a name="androidSourceSetupBuildingDeviceCodeBaseOption1"></a><h4>Option 2</h4>
323
324<p>To do a generic build of android, source <code>//device/envsetup.sh</code>, which contains necessary variable and function definitions, as described below.</p>
325<pre class="prettyprint">
326% cd $TOP
327
328% . envsetup.sh
329
330% partner_setup generic
331 //select generic as the product
332
333% make -j4 PRODUCT-generic-user
334</pre>
335<p>You can also replace user with eng for a debug engineering build:</p>
336
337<pre class="prettyprint">
338% make -j4 PRODUCT-generic-eng
339</pre>
340
341
342<a name="androidBuildingCleaning"></a><h3>Cleaning Up</h3>
343
344<p>Execute <code>% m clean</code> to clean up the binaries you just created. You can also execute <code>% m clobber</code> to get rid of the binaries of all combos. <code>% m clobber</code> is equivalent to removing the <code>//device/out/</code> directory where all generated files are stored.</p>
345
346
347<a name="androidBuildingSpeeding"></a><h3>Speeding Up Rebuilds</h3>
348
349<p> The binaries of each combo are stored as distinct sub-directories of <code>//device/out/</code>, making it possible to quickly switch between combos without having to recompile all sources each time. </p>
350<p> However, performing a clean rebuild is necessary if the build system doesn't catch changes to environment variables or makefiles. If this happens often, you should define the <code>USE_CCACHE</code> environment variable as shown below: </p>
351<pre class="prettyprint">
352% export USE_CCACHE=1
353</pre>
354<p>Doing so will force the build system to use the ccache compiler cache tool, which reduces recompiling all sources.</p>
355
356<p><code>ccache</code> binaries are provided in <code>//device/prebuilt/...</code> and don't need to get installed on your system.</p>
357
358
359<a name="androidBuildingTroubleshooting"></a><h3>Troubleshooting</h3>
360
361<p>The following error is likely caused by running an outdated version of Java.</p>
362<pre class="prettyprint">
363device Dex: core UNEXPECTED TOP-LEVEL ERROR:
364java.lang.NoSuchMethodError: method java.util.Arrays.hashCode with
365signature ([Ljava.lang.Object;)I was not found.
366 at com.google.util.FixedSizeList.hashCode(FixedSizeList.java:66)
367 at com.google.rop.code.Rop.hashCode(Rop.java:245)
368 at java.util.HashMap.hash(libgcj.so.7)
369[...]
370</pre>
371<p><code>dx</code> is a Java program that uses facilities first made available in Java version 1.5. Check your version of Java by executing <code>% java -version</code> in the shell you use to build. You should see something like:</p>
372<pre class="prettyprint">
373java version "1.5.0_07"
374Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_07-164)
375Java HotSpot(TM) Client VM (build 1.5.0_07-87, mixed mode, sharing)
376</pre>
377<p>If you do have Java 1.5 or later and your receive this error, verify that you have properly updated your <code>PATH</code> variable.</p>
378
379
380<a name="androidSourceSetupBuildingKernel"></a><h2>Building the Android Kernel</h2>
381
382<p>This section describes how to build Android's default kernel. Once you are comfortable with a generic build, then you can begin to modify Android drivers for your own target device.</p>
383
384
385<p>To build the kernel base, switch to the device directory (<code>/home/joe/android/device</code>) in order to establish variables and run:
386<pre class="prettyprint">
387% . envsetup.sh
388% partner_setup generic
389</pre>
390<p>Then switch to the kernel directory <code>/home/joe/android/kernel</code>.
391
392
393<a name="androidSourceSetupBuildingKernelCheckingBranch"></a><h3>Checking Out a Branch</h3>
394
395<p>The default branch is always <code>android</code>. To check out a different branch, execute the following:</p>
396
397<pre class="prettyprint">
398% git checkout --track -b android-mydevice origin/android-mydevice
399 //Branch android-mydevice set up to track remote branch
400% refs/remotes/origin/android-mydevice.
401 //Switched to a new branch "android-mydevice"
402</pre>
403
404<p>To simplify code management, give your local branch the same name as the remote branch it is tracking (as illustrated in the snippet above). Switch between branches by executing <code>% git checkout &lt;branchname&gt;</code>.</p>
405
406
407<a name="androidSourceSetupBuildingKernelBranchLocation"></a><h3>Verifying Location</h3>
408
409<p>Find out which branches exist (both locally and remotely) and which one is active (marked with an asterisk) by executing the following:</p>
410<pre class="prettyprint">
411% git branch -a
412 android
413* android-mydevice
414 origin/HEAD
415 origin/android
416 origin/android-mydevice
417 origin/android-mychipset
418</pre>
419<p>To only see local branches, omit the <code>-a</code> flag.</p>
420
421
422<a name="androidSourceSetupBuildingKernelBuild"></a><h3>Building the Kernel</h3>
423
424<p>To build the kernel, execute:</p>
425<pre class="prettyprint">
426% make -j4
427</pre>
428
429
430<p><span class="lh2"><a name="androidFooter"></a></span>
431
432 </div>
433 </div>
434 <!-- end gc-pagecontent -->
435 </div>
436 <!-- end gooey wrapper -->
437 </div>
438 <!-- end codesearchresults -->
439 <div id="gc-footer" dir="ltr">
440 <div class="text"> &copy;2008 Google<!-- - <a href="/">Code Home</a> - <a href="http://www.google.com/accounts/TOS">Site Terms of Service</a> - <a href="http://www.google.com/privacy.html">Privacy Policy</a> - <a href="/more">Site Directory</a> --></div>
441 </div>
442 <!-- end gc-footer -->
443</div>
444<!-- end gc-containter -->
445<script src="http://www.google-analytics.com/ga.js" type="text/javascript">
446</script>
447<script type="text/javascript">
448 try {
449 var pageTracker = _gat._getTracker("UA-18071-1");
450 pageTracker._setAllowAnchor(true);
451 pageTracker._initData();
452 pageTracker._trackPageview();
453 } catch(e) {}
454</script>
The Android Open Source Projecte943f2f2008-12-17 18:04:04 -0800455<div id="jd-build-id"> v0.6 - 25 November 2008</div>
The Android Open Source Project5c118522008-10-21 07:00:00 -0700456</div></div></div></body>
457</html>
458