1 page.title=Upgrading the SDK 2 sdk.version=1.6 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> 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> 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 260 <a href="{@docRoot}guide/topics/manifest/supports-screen-element.html"><code><supports-screen></code></a> 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 386
