Dirk Dougherty | a6602f1 | 2009-08-27 16:26:43 -0700 | [diff] [blame] | 1 | page.title=Upgrading the SDK |
| 2 | sdk.version=1.6 |
Dirk Dougherty | a6602f1 | 2009-08-27 16:26:43 -0700 | [diff] [blame] | 3 | @jd:body |
| 4 | |
| 5 | |
| 6 | <div id="qv-wrapper"> |
| 7 | <div id="qv"> |
| 8 | |
| 9 | <h2>Upgrading the SDK</h2> |
| 10 | <ul> |
| 11 | <li>If you are developing on the Android 1.5 SDK, migrating your |
| 12 | applications is straightforward and typically requires no modifications.</li> |
| 13 | <li>For Eclipse users, a new version of ADT is available. To use the Android |
| 14 | 1.6 SDK, please upgrade to ADT 0.9.3 (or later).</li> |
| 15 | <li>For Windows users, the SDK includes a new USB driver that you can |
| 16 | install, if you are developing on a device. </li> |
| 17 | <li>A new Android SDK and AVD Manager tool is available. To access |
| 18 | it, run the <code>android</code> tool without options. </li> |
| 19 | </ul> |
| 20 | |
| 21 | <h2>In this document</h2> |
| 22 | <ol> |
| 23 | <li><a href="#Install">Install the SDK</a></li> |
| 24 | <li><a href="#UpdateAdt">Update Your Eclipse ADT Plugin</a></li> |
| 25 | <li><a href="#RunYourApps">Run Your Applications</a></li> |
| 26 | <li><a href="#MigrateYourApps">Migrate Your Applications</a></li> |
| 27 | </ol> |
| 28 | |
| 29 | <h2>Migrating information</h2> |
| 30 | <ol> |
| 31 | <li><a href="{@docRoot}sdk/api_diff/4/changes.html">Android 1.6 API |
| 32 | Differences</a></li> |
| 33 | </ol> |
| 34 | |
| 35 | </div> |
| 36 | </div> |
| 37 | |
| 38 | <p>This document describes how to move your development environment and existing |
| 39 | Android applications from an Android 1.5 SDK to the Android 1.6 SDK. If you are |
| 40 | migrating applications from an SDK older than 1.5, please also read the |
| 41 | upgrading document available in the Android 1.5 SDK package.</p> |
| 42 | |
| 43 | <p>There are several compelling reasons to upgrade, such as new SDK tools that |
| 44 | make developing more efficient and new APIs that allow you to expand the |
| 45 | feature-set of your applications. However, even if you or your applications |
| 46 | don't require these enhancements, it's important that you upgrade to ensure that |
| 47 | your applications run properly on the upcoming Android platform.</p> |
| 48 | |
| 49 | <p>The Android 1.6 platform will soon be deployable to devices around the world. |
| 50 | If you have already released Android applications to the public, you should test |
| 51 | the forward-compatibility of your applications on the latest version of the |
| 52 | platform as soon as possible. It's unlikely that you'll encounter problems in |
| 53 | your applications, but in the interest of maintaining the best user experience, |
| 54 | you should take no risks. So, please install the new Android SDK and test your |
| 55 | applications on the new platform.</p> |
| 56 | |
| 57 | <!-- NOT AVAILABLE FOR PREVIEW RELEASES --> |
| 58 | <p>For more information on new SDK features and system changes, |
| 59 | see the <a href="{@docRoot}sdk/android-1.6.html">Android 1.6 Version Notes</a>.</p> |
| 60 | <!-- --> |
| 61 | |
| 62 | <h2 id="Install">Install the SDK</h2> |
| 63 | |
| 64 | <p>If you haven't yet downloaded the SDK, <a href="index.html">download it from |
| 65 | here</a> and unpack it into a safe location.</p> |
| 66 | |
| 67 | <p>If you had previously setup your <code>PATH</code> variable to point to the SDK |
| 68 | tools directory, then you need to update it to point to the new SDK. For example, for |
| 69 | a <code>.bashrc</code> or <code>.bash_profile</code> file:</p> |
| 70 | <pre>export PATH=$PATH:<em><your_sdk_dir></em>/tools</pre> |
| 71 | |
| 72 | |
| 73 | <h2 id="UpdateAdt">Update Your Eclipse ADT Plugin</h2> |
| 74 | |
| 75 | <p>If you don't use the Eclipse IDE for development, |
| 76 | skip to <a href="#RunYourApps">Run Your Applications</a>.</p> |
| 77 | |
| 78 | <p>A new version of the ADT Plugin, ADT 0.9.3, is available in conjunction with |
| 79 | this SDK release. To use the SDK, you must upgrade your ADT Plugin to version |
| 80 | 0.9.3. With ADT 0.9.3, you can still compile your existing applications against |
| 81 | multiple platform versions, such as Android 1.5, Android 1.1, and so on. However, |
| 82 | ADT 0.9.3 is not compatible with previous versions of the SDK and its tools, so |
| 83 | make sure that you upgrade both your SDK <em>and</em> the ADT Plugin.</p> |
| 84 | |
| 85 | The upgrade steps for ADT are described below. For information about new features in ADT, see the <a |
| 86 | href="{@docRoot}sdk/RELEASENOTES.html">Release Notes</a> document. </p> |
| 87 | |
| 88 | <p>If you're currently using a version of ADT <em>older</em> than version 0.9, |
| 89 | then you must uninstall ADT before you proceed (read how to <a |
| 90 | href="{@docRoot}sdk/1.5_r3/upgrading.html#uninstallAdt">Uninstall your previous |
| 91 | ADT plugin</a>). If you currently have version 0.9 or 0.9.1, then you don't need |
| 92 | to uninstall and can continue with the procedure below.</p> |
| 93 | |
| 94 | <table style="font-size:100%"> |
| 95 | <tr><th>Eclipse 3.4 (Ganymede)</th><th>Eclipse 3.5 (Galileo)</th></tr> |
| 96 | <tr> |
| 97 | <td width="50%"> |
| 98 | <!-- 3.4 steps --> |
| 99 | <ol> |
| 100 | <li>Select <strong>Help</strong> > <strong>Software Updates</strong>.</li> |
| 101 | <li>Select the <strong>Available Software</strong> tab.</li> |
| 102 | <li>Select the checkboxes next to Android DDMS and Android Developer Tools, |
| 103 | then click <strong>Update</strong>.</li> |
| 104 | <li>In the resulting Available Updates dialog, ensure that both Android DDMS |
| 105 | and Android Development Tools are selected, then click |
| 106 | <strong>Next</strong>.</li> |
| 107 | <li>Read and accept the license agreement and then click <strong>Finish</strong>. |
| 108 | This will download and install the latest version of Android DDMS and |
| 109 | Android Development Tools.</li> |
| 110 | <li>Restart Eclipse.</li> |
| 111 | </ol> |
| 112 | </td> |
| 113 | <td> |
| 114 | <!-- 3.5 steps --> |
| 115 | <ol> |
| 116 | <li>Select <strong>Help</strong> > <strong>Check for Updates</strong>. </li> |
| 117 | <li>In the resulting Available Updates dialog, locate the Android DDMS and |
| 118 | Android Development Tools features in the list and ensure that the checkboxes |
| 119 | next to them are selected. Click <strong>Next</strong>. |
| 120 | <p>If the Available Updates dialog does not list Android DDMS and Android |
| 121 | Development tools, make sure that you have set up a remote update site |
| 122 | for them, as described in |
| 123 | <a href="installing.html#InstallingADT">Installing the ADT Plugin</a>. |
| 124 | </p></li> |
| 125 | <li>In the Update Details dialog, click <strong>Next</strong>.</li> |
| 126 | <li>Read and accept the license agreement and then click <strong>Finish</strong>. |
| 127 | This will download and install the latest version of Android DDMS and |
| 128 | Android Development Tools.</li> |
| 129 | <li>Restart Eclipse.</li> |
| 130 | </ol> |
| 131 | </td> |
| 132 | </tr> |
| 133 | </table> |
| 134 | |
| 135 | <p>If you encounter problems with this update procedure, try performing a fresh |
| 136 | installation. Fully remove your existing ADT Plugin as described in <a |
| 137 | href="{@docRoot}sdk/1.5_r3/upgrading.html#uninstallAdt">Uninstall your previous |
| 138 | ADT plugin</a> and then follow the guide to <a |
| 139 | href="installing.html#InstallingADT">Installing the ADT Plugin for |
| 140 | Eclipse</a>.</p> |
| 141 | |
| 142 | <h3 id="updateEclipsePrefs">Update your Eclipse SDK Preferences</h3> |
| 143 | |
| 144 | <p>The last step is to update your Eclipse preferences to point to the new |
| 145 | SDK directory:</p> |
| 146 | <ol> |
| 147 | <li>Select <strong>Window</strong> > <strong>Preferences</strong> to open |
| 148 | the Preferences panel (Mac: <strong>Eclipse</strong> > <strong>Preferences |
| 149 | </strong>).</li> |
| 150 | <li>Select <strong>Android</strong> from the left panel.</li> |
| 151 | <li>For the SDK Location, click <strong>Browse</strong> |
| 152 | and locate your SDK directory.</li> |
| 153 | <li>Click <strong>Apply</strong>, then <strong>OK</strong>.</li> |
| 154 | </ol> |
| 155 | |
| 156 | |
| 157 | <h2 id="RunYourApps">Run Your Applications to Test Forward Compatibility</h2> |
| 158 | |
| 159 | <p>Now that you have installed the Android 1.6 SDK, we encourage you run each of |
| 160 | your existing applications on the Android 1.6 system image that is included in |
| 161 | the SDK, to ensure that it functions properly on the new platform. |
| 162 | Testing forward-compatibility in this way is especially important for |
| 163 | applications that you may have already published and that may be installed on |
| 164 | devices that will upgrade to the new platform. </p> |
| 165 | |
| 166 | <p>In most cases, your applications will function properly when run on the new |
| 167 | version of the platform. However, it is possible that you will encounter |
| 168 | unexpected behavior, because of changes in the API or underlying platform. If |
| 169 | you do find problems, you can use the SDK tools to compile and publish an update |
| 170 | to the applications, which users can then download. |
| 171 | |
| 172 | <p>To test forward-compatibility, simply run your application, as-is, on an |
| 173 | instance of the Android Emulator that uses an AVD targeted to the "Android 1.6" |
| 174 | system image. Here are the steps: </p> |
| 175 | |
| 176 | <ol> |
| 177 | <li>Make no changes to your application code.</li> |
| 178 | <li>Create a new AVD that runs the new "Android 1.6" platform. </li> |
| 179 | <li>Launch your application in an emulator running the new AVD.</li> |
| 180 | <li>Perform normal testing on your application to ensure everything works as |
| 181 | expected.</li> |
| 182 | </ol> |
| 183 | |
| 184 | <p>Note that, for the purposes of forward-compatibility testing, you should not |
| 185 | change how your application is compiled. That is, you should continue to compile |
| 186 | the application against the same version of the Android library as before. The |
| 187 | only change needed is to the AVD, which controls the version of the Android |
| 188 | system image (run-time environment) on which the application is run. |
| 189 | |
| 190 | <p>For more information on creating an AVD and launching your application, see |
| 191 | <a href="{@docRoot}guide/developing/eclipse-adt.html#Running">Running Your |
| 192 | Applications (Eclipse)</a> or <a |
| 193 | href="{@docRoot}guide/developing/other-ide.html#Running">Running |
| 194 | Your Applications (other IDEs)</a>, depending on your development |
| 195 | environment.</p> |
| 196 | |
| 197 | <h3 id="FutureProofYourApps">Android 1.6 Forward-Compatibility Tips</h3> |
| 198 | |
| 199 | <p>The new version of the Android platform includes several new APIs, but |
| 200 | very few actual changes to existing APIs. This means that, in most |
| 201 | cases, your applications written with earlier versions of the Android library |
| 202 | should run properly on the Android 1.6 platform. </p> |
| 203 | |
| 204 | <p>However, here are some areas to pay attention to as you test forward-compatibility:</p> |
| 205 | |
| 206 | <ul> |
| 207 | <li><strong>Make sure your application doesn't use internal APIs</strong>. Your |
| 208 | application should not use any APIs that are not officially supported and are |
| 209 | not published in the Android reference documentation. Unofficial APIs can change |
| 210 | at any time without notice and — if your application happens to be using |
| 211 | them — such a change could cause the application to break.</li> |
| 212 | |
| 213 | <li><strong>Watch for assumptions about available hardware</strong>. Remember |
| 214 | that not all compatible devices offer the same hardware capabilities — |
| 215 | screens, keyboards, and physical keys, and so on. As you test your application, |
| 216 | watch for areas where your application depends on the presence of specific |
| 217 | hardware capabilities. If you find dependencies, you can design around them by |
| 218 | building in alternate support or graceful degradation, or you can specify them |
| 219 | as hardware requirements in a |
| 220 | <a href="{@docRoot}guide/topics/manifest/uses-configuration-element.html"><code><uses-configuration></code>.</a> |
Dirk Dougherty | 4c8a16a | 2009-09-10 10:45:41 -0700 | [diff] [blame] | 221 | element in the application's manifest file. Also see the <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><code><uses-feature></code></a> |
Dirk Dougherty | a6602f1 | 2009-08-27 16:26:43 -0700 | [diff] [blame] | 222 | manifest element, which lets your application declare a requirement for |
| 223 | specific features, such as an OpenGL ES version or a camera that has |
| 224 | autofocus capability. |
| 225 | </li> |
| 226 | |
| 227 | <li><strong>Watch for assumptions about available features</strong>. Not all |
| 228 | compatible devices offer equal support for embedded features. same hardware capabilities — |
| 229 | screens, keyboards, and physical keys, and so on. As you test your application, |
| 230 | watch for areas where your application depends on the presence of specific |
| 231 | hardware capabilities. If you find dependencies, you can design around them by |
| 232 | building in alternate support or graceful degradation, or you can specify them |
| 233 | as hardware requirements in a |
| 234 | <a href="{@docRoot}guide/topics/manifest/uses-configuration-element.html"><code><uses-configuration></code>.</a> |
| 235 | element in the application's manifest file. </li> |
| 236 | |
| 237 | <p>When testing forward-compatibility, try running your application in various |
| 238 | AVDs that emulate different hardware configurations. For example, you can create |
| 239 | an AVD that does not offer a physical keyboard or one that uses a dpad instead |
| 240 | of a trackball. Running your application in different emulated hardware |
| 241 | configurations will give you an idea of where its dependencies are and help you |
| 242 | identify problems. </p> |
| 243 | </li> |
| 244 | |
| 245 | <li><strong>Watch for assumptions about screen resolution and |
| 246 | density</strong>. A device's screen resolution and density is likely to affect |
| 247 | the way that your application's UI is rendered, especially if your app specifies |
| 248 | dimensions or positions using pixels or absolute layouts. To ensure consistent |
| 249 | UI across screens, your app should specify the dimensions and positions of |
| 250 | layouts and drawables in relative units that can be scaled by the system as |
| 251 | appropriate, according to the density of the device's screen. Alternatively, you |
| 252 | can create custom sets of layout/drawable resources for specific screens, which |
| 253 | the system can then load as appropriate, based on the current device screen.</p> |
| 254 | |
| 255 | <p>When testing forward-compatibility, try running your application in various |
| 256 | AVDs that emulate different screen resolutions and densities. Also note that, |
| 257 | starting with Android 1.6, the platform provides a Compatibility Mode that |
| 258 | automatically scales the UI of applications if they do not explicitly indicate |
| 259 | support for the current screen in the |
Dirk Dougherty | 4c8a16a | 2009-09-10 10:45:41 -0700 | [diff] [blame] | 260 | <a href="{@docRoot}guide/topics/manifest/supports-screen-element.html"><code><supports-screen></code></a> |
Dirk Dougherty | a6602f1 | 2009-08-27 16:26:43 -0700 | [diff] [blame] | 261 | element in their manifest files. As part of testing, you should evaluate how |
| 262 | your application is displayed in Compatibility Mode on different screens. </p> |
| 263 | </li> |
| 264 | |
| 265 | <li><strong>Avoid performing layout orientation changes based on the |
| 266 | acceletometer (or via other sensors)</strong>. Some Android-powered devices will |
| 267 | automatically rotate the orientation (and all devices have the option to turn on |
| 268 | auto-rotation), so if your application also attempts to rotate the orientation, |
| 269 | it can result in strange behavior. In addition, if your application uses the |
| 270 | accelerometer to detect shaking and you do not want to rotate the orientation, |
| 271 | then you should lock the current orientation with <a |
| 272 | href="{@docRoot}guide/topics/manifest/activity-element.html#screen">android:screenOrientation</a>. |
| 273 | </li> |
| 274 | |
| 275 | </ul> |
| 276 | |
| 277 | <h2 id="MigrateYourApps">Migrate Your Applications</h2> |
| 278 | |
| 279 | <p>If you want to use any of the new Android 1.6 APIs in your existing |
| 280 | applications, you must first migrate the applications to the new Android |
| 281 | platform version. Generally, migrating an application includes: </p> |
| 282 | |
| 283 | <ul> |
| 284 | <li>Referencing the proper API Level in the application's manifest file, |
| 285 | and</li> |
| 286 | <li>Resetting its project properties so that it is compiled against the Android |
| 287 | 1.6 build target.</li> |
| 288 | </ul> |
| 289 | |
| 290 | <p>Additionally, to run your application in the emulator, you need to |
| 291 | create an AVD that uses the Android 1.6 system image. </p> |
| 292 | |
| 293 | <p class="note"><strong>Note:</strong> You only need migrate your application as |
| 294 | described in this section if the application will actually use APIs |
| 295 | <em>introduced</em> in the Android 1.6 platform (which are not available on |
| 296 | devices running older versions of the Android platform). If your application |
| 297 | does not use any new APIs, you can compile and run it without modification and |
| 298 | not migration is necessary.</p> |
| 299 | |
| 300 | <h3>Reference the Proper API Level</h3> |
| 301 | |
| 302 | <p>If your application is using APIs introduced in Android 1.6, you must |
| 303 | reference that dependency in the application's manifest file so that it can be |
| 304 | deployed to devices running the Android 1.6 platform. </p> |
| 305 | |
| 306 | <p>Open the manifest file and locate the <code>minSdkVersion</code> attribute |
| 307 | in the <code><uses-sdk></code> manifest element. Set the value of |
| 308 | <code>minSdkVersion</code> to <code>"4"</code> (the API Level |
| 309 | identifier corresponding to Android 1.6). Here's an example:</p> |
| 310 | |
| 311 | <pre> |
| 312 | <manifest> |
| 313 | ... |
| 314 | <uses-sdk android:minSdkVersion="4" /> |
| 315 | ... |
| 316 | </manifest> |
| 317 | </pre> |
| 318 | |
| 319 | <h3>Compile Against the Proper Build Target</h3> |
| 320 | |
| 321 | <p>Once you've changed the <code>minSdkVersion</code> value in your |
| 322 | application's manifest, you need to set the application's project properties so |
| 323 | that the application will be compiled against the Android 1.6 library. To do so, |
| 324 | follow the steps below for your respective development environment. </p> |
| 325 | |
| 326 | <h4 id="EclipseUsers">Eclipse Users</h4> |
| 327 | |
| 328 | <ol> |
| 329 | <li>Right-click on the individual project (in the Package Explorer) |
| 330 | and select <strong>Properties</strong>.</li> |
| 331 | <li>In the properties, open the Android panel and select a new Project Build Target. |
| 332 | Select "Android 1.6" to target the new platform (or "Google APIs" with the "4" |
| 333 | API Level, if your application uses the Google Maps APIs).</li> |
| 334 | <li>Click <strong>Apply</strong>, then <strong>OK</strong>.</li> |
| 335 | </ol> |
| 336 | |
| 337 | <h4 id="AntUsers">Ant Users</h4> |
| 338 | |
| 339 | <p>Use the <code>android</code> tool (located in |
| 340 | <code><em>your_sdk</em>/tools/</code>) to create a new <code>build.xml</code> |
| 341 | that references the new platform target. To see a list of available targets, |
| 342 | execute:</p> |
| 343 | |
| 344 | <pre>android list targets</pre> |
| 345 | |
| 346 | <p>Select the target <code>id</code> that corresponds to the "Android 1.6" platform |
| 347 | and pass it with the <code>--target</code> parameter when updating your project. |
| 348 | For example:</p> |
| 349 | |
| 350 | <pre>android update project --path /path/to/my-project --target 2</pre> |
| 351 | |
| 352 | <p>If your application uses the Google Maps APIs (i.e., MapView), be certain to |
| 353 | select a Google APIs target.</p> |
| 354 | |
| 355 | <h3>Create an AVD that Uses the Android 1.6 Platform</h3> |
| 356 | |
| 357 | <p>Finally, you need to set up a new AVD that uses the Android 1.6 platform, so that |
| 358 | you can run your application in the emulator. |
| 359 | |
| 360 | <p>To set up the new AVD, use the <code>android</code> tool, available in the |
| 361 | <code>tools/</code> directory of the SDK. You can run the AVD manager by simply |
| 362 | changing to the <code>tools/</code> directory and entering <code>android</code> |
| 363 | at the command line. Click "New" to create the AVD and set its properties.</p> |
| 364 | |
| 365 | <p>When creating the AVD, make sure to select a target of "Android 1.6 - API |
| 366 | Level 4". If your application uses the Google Maps APIs (MapView), select the |
| 367 | target "Google APIs (Google Inc.) - API Level 4". </p> |
| 368 | |
| 369 | <p>For more information about running your application in an AVD, see <a |
| 370 | href="{@docRoot}guide/developing/eclipse-adt.html#Running">Running Your |
| 371 | Application (Eclipse)</a> or <a |
| 372 | href="{@docRoot}guide/developing/other-ide.html#Running">Running Your |
| 373 | Application (other IDEs)</a>. </p> |
| 374 | |
| 375 | <p>For general information about AVDs, see the <a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual |
| 376 | Devices</a> document. </p> |
| 377 | |
| 378 | |
| 379 | |
| 380 | <div class="special"> |
| 381 | <p>If you have trouble migrating to the new version of the SDK, visit the |
| 382 | <a href="http://groups.google.com/group/android-developers">Android Developers Group</a> |
| 383 | to seek help from other Android developers.</p> |
| 384 | </div> |
| 385 | |