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