| page.title=Upgrading the SDK |
| sdk.version=1.6 |
| @jd:body |
| |
| |
| <div id="qv-wrapper"> |
| <div id="qv"> |
| |
| <h2>Upgrading the SDK</h2> |
| <ul> |
| <li>If you are developing on the Android 1.5 SDK, migrating your |
| applications is straightforward and typically requires no modifications.</li> |
| <li>For Eclipse users, a new version of ADT is available. To use the Android |
| 1.6 SDK, please upgrade to ADT 0.9.3 (or later).</li> |
| <li>For Windows users, the SDK includes a new USB driver that you can |
| install, if you are developing on a device. </li> |
| <li>A new Android SDK and AVD Manager tool is available. To access |
| it, run the <code>android</code> tool without options. </li> |
| </ul> |
| |
| <h2>In this document</h2> |
| <ol> |
| <li><a href="#Install">Install the SDK</a></li> |
| <li><a href="#UpdateAdt">Update Your Eclipse ADT Plugin</a></li> |
| <li><a href="#RunYourApps">Run Your Applications</a></li> |
| <li><a href="#MigrateYourApps">Migrate Your Applications</a></li> |
| </ol> |
| |
| <h2>Migrating information</h2> |
| <ol> |
| <li><a href="{@docRoot}sdk/api_diff/4/changes.html">Android 1.6 API |
| Differences</a></li> |
| </ol> |
| |
| </div> |
| </div> |
| |
| <p>This document describes how to move your development environment and existing |
| Android applications from an Android 1.5 SDK to the Android 1.6 SDK. If you are |
| migrating applications from an SDK older than 1.5, please also read the |
| upgrading document available in the Android 1.5 SDK package.</p> |
| |
| <p>There are several compelling reasons to upgrade, such as new SDK tools that |
| make developing more efficient and new APIs that allow you to expand the |
| feature-set of your applications. However, even if you or your applications |
| don't require these enhancements, it's important that you upgrade to ensure that |
| your applications run properly on the upcoming Android platform.</p> |
| |
| <p>The Android 1.6 platform will soon be deployable to devices around the world. |
| If you have already released Android applications to the public, you should test |
| the forward-compatibility of your applications on the latest version of the |
| platform as soon as possible. It's unlikely that you'll encounter problems in |
| your applications, but in the interest of maintaining the best user experience, |
| you should take no risks. So, please install the new Android SDK and test your |
| applications on the new platform.</p> |
| |
| <!-- NOT AVAILABLE FOR PREVIEW RELEASES --> |
| <p>For more information on new SDK features and system changes, |
| see the <a href="{@docRoot}sdk/android-1.6.html">Android 1.6 Version Notes</a>.</p> |
| <!-- --> |
| |
| <h2 id="Install">Install the SDK</h2> |
| |
| <p>If you haven't yet downloaded the SDK, <a href="index.html">download it from |
| here</a> and unpack it into a safe location.</p> |
| |
| <p>If you had previously setup your <code>PATH</code> variable to point to the SDK |
| tools directory, then you need to update it to point to the new SDK. For example, for |
| a <code>.bashrc</code> or <code>.bash_profile</code> file:</p> |
| <pre>export PATH=$PATH:<em><your_sdk_dir></em>/tools</pre> |
| |
| |
| <h2 id="UpdateAdt">Update Your Eclipse ADT Plugin</h2> |
| |
| <p>If you don't use the Eclipse IDE for development, |
| skip to <a href="#RunYourApps">Run Your Applications</a>.</p> |
| |
| <p>A new version of the ADT Plugin, ADT 0.9.3, is available in conjunction with |
| this SDK release. To use the SDK, you must upgrade your ADT Plugin to version |
| 0.9.3. With ADT 0.9.3, you can still compile your existing applications against |
| multiple platform versions, such as Android 1.5, Android 1.1, and so on. However, |
| ADT 0.9.3 is not compatible with previous versions of the SDK and its tools, so |
| make sure that you upgrade both your SDK <em>and</em> the ADT Plugin.</p> |
| |
| The upgrade steps for ADT are described below. For information about new features in ADT, see the <a |
| href="{@docRoot}sdk/RELEASENOTES.html">Release Notes</a> document. </p> |
| |
| <p>If you're currently using a version of ADT <em>older</em> than version 0.9, |
| then you must uninstall ADT before you proceed (read how to <a |
| href="{@docRoot}sdk/1.5_r3/upgrading.html#uninstallAdt">Uninstall your previous |
| ADT plugin</a>). If you currently have version 0.9 or 0.9.1, then you don't need |
| to uninstall and can continue with the procedure below.</p> |
| |
| <table style="font-size:100%"> |
| <tr><th>Eclipse 3.4 (Ganymede)</th><th>Eclipse 3.5 (Galileo)</th></tr> |
| <tr> |
| <td width="50%"> |
| <!-- 3.4 steps --> |
| <ol> |
| <li>Select <strong>Help</strong> > <strong>Software Updates</strong>.</li> |
| <li>Select the <strong>Available Software</strong> tab.</li> |
| <li>Select the checkboxes next to Android DDMS and Android Developer Tools, |
| then click <strong>Update</strong>.</li> |
| <li>In the resulting Available Updates dialog, ensure that both Android DDMS |
| and Android Development Tools are selected, then click |
| <strong>Next</strong>.</li> |
| <li>Read and accept the license agreement and then click <strong>Finish</strong>. |
| This will download and install the latest version of Android DDMS and |
| Android Development Tools.</li> |
| <li>Restart Eclipse.</li> |
| </ol> |
| </td> |
| <td> |
| <!-- 3.5 steps --> |
| <ol> |
| <li>Select <strong>Help</strong> > <strong>Check for Updates</strong>. </li> |
| <li>In the resulting Available Updates dialog, locate the Android DDMS and |
| Android Development Tools features in the list and ensure that the checkboxes |
| next to them are selected. Click <strong>Next</strong>. |
| <p>If the Available Updates dialog does not list Android DDMS and Android |
| Development tools, make sure that you have set up a remote update site |
| for them, as described in |
| <a href="installing.html#InstallingADT">Installing the ADT Plugin</a>. |
| </p></li> |
| <li>In the Update Details dialog, click <strong>Next</strong>.</li> |
| <li>Read and accept the license agreement and then click <strong>Finish</strong>. |
| This will download and install the latest version of Android DDMS and |
| Android Development Tools.</li> |
| <li>Restart Eclipse.</li> |
| </ol> |
| </td> |
| </tr> |
| </table> |
| |
| <p>If you encounter problems with this update procedure, try performing a fresh |
| installation. Fully remove your existing ADT Plugin as described in <a |
| href="{@docRoot}sdk/1.5_r3/upgrading.html#uninstallAdt">Uninstall your previous |
| ADT plugin</a> and then follow the guide to <a |
| href="installing.html#InstallingADT">Installing the ADT Plugin for |
| Eclipse</a>.</p> |
| |
| <h3 id="updateEclipsePrefs">Update your Eclipse SDK Preferences</h3> |
| |
| <p>The last step is to update your Eclipse preferences to point to the new |
| SDK directory:</p> |
| <ol> |
| <li>Select <strong>Window</strong> > <strong>Preferences</strong> to open |
| the Preferences panel (Mac: <strong>Eclipse</strong> > <strong>Preferences |
| </strong>).</li> |
| <li>Select <strong>Android</strong> from the left panel.</li> |
| <li>For the SDK Location, click <strong>Browse</strong> |
| and locate your SDK directory.</li> |
| <li>Click <strong>Apply</strong>, then <strong>OK</strong>.</li> |
| </ol> |
| |
| |
| <h2 id="RunYourApps">Run Your Applications to Test Forward Compatibility</h2> |
| |
| <p>Now that you have installed the Android 1.6 SDK, we encourage you run each of |
| your existing applications on the Android 1.6 system image that is included in |
| the SDK, to ensure that it functions properly on the new platform. |
| Testing forward-compatibility in this way is especially important for |
| applications that you may have already published and that may be installed on |
| devices that will upgrade to the new platform. </p> |
| |
| <p>In most cases, your applications will function properly when run on the new |
| version of the platform. However, it is possible that you will encounter |
| unexpected behavior, because of changes in the API or underlying platform. If |
| you do find problems, you can use the SDK tools to compile and publish an update |
| to the applications, which users can then download. |
| |
| <p>To test forward-compatibility, simply run your application, as-is, on an |
| instance of the Android Emulator that uses an AVD targeted to the "Android 1.6" |
| system image. Here are the steps: </p> |
| |
| <ol> |
| <li>Make no changes to your application code.</li> |
| <li>Create a new AVD that runs the new "Android 1.6" platform. </li> |
| <li>Launch your application in an emulator running the new AVD.</li> |
| <li>Perform normal testing on your application to ensure everything works as |
| expected.</li> |
| </ol> |
| |
| <p>Note that, for the purposes of forward-compatibility testing, you should not |
| change how your application is compiled. That is, you should continue to compile |
| the application against the same version of the Android library as before. The |
| only change needed is to the AVD, which controls the version of the Android |
| system image (run-time environment) on which the application is run. |
| |
| <p>For more information on creating an AVD and launching your application, see |
| <a href="{@docRoot}guide/developing/eclipse-adt.html#Running">Running Your |
| Applications (Eclipse)</a> or <a |
| href="{@docRoot}guide/developing/other-ide.html#Running">Running |
| Your Applications (other IDEs)</a>, depending on your development |
| environment.</p> |
| |
| <h3 id="FutureProofYourApps">Android 1.6 Forward-Compatibility Tips</h3> |
| |
| <p>The new version of the Android platform includes several new APIs, but |
| very few actual changes to existing APIs. This means that, in most |
| cases, your applications written with earlier versions of the Android library |
| should run properly on the Android 1.6 platform. </p> |
| |
| <p>However, here are some areas to pay attention to as you test forward-compatibility:</p> |
| |
| <ul> |
| <li><strong>Make sure your application doesn't use internal APIs</strong>. Your |
| application should not use any APIs that are not officially supported and are |
| not published in the Android reference documentation. Unofficial APIs can change |
| at any time without notice and — if your application happens to be using |
| them — such a change could cause the application to break.</li> |
| |
| <li><strong>Watch for assumptions about available hardware</strong>. Remember |
| that not all compatible devices offer the same hardware capabilities — |
| screens, keyboards, and physical keys, and so on. As you test your application, |
| watch for areas where your application depends on the presence of specific |
| hardware capabilities. If you find dependencies, you can design around them by |
| building in alternate support or graceful degradation, or you can specify them |
| as hardware requirements in a |
| <a href="{@docRoot}guide/topics/manifest/uses-configuration-element.html"><code><uses-configuration></code>.</a> |
| 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> |
| manifest element, which lets your application declare a requirement for |
| specific features, such as an OpenGL ES version or a camera that has |
| autofocus capability. |
| </li> |
| |
| <li><strong>Watch for assumptions about available features</strong>. Not all |
| compatible devices offer equal support for embedded features. same hardware capabilities — |
| screens, keyboards, and physical keys, and so on. As you test your application, |
| watch for areas where your application depends on the presence of specific |
| hardware capabilities. If you find dependencies, you can design around them by |
| building in alternate support or graceful degradation, or you can specify them |
| as hardware requirements in a |
| <a href="{@docRoot}guide/topics/manifest/uses-configuration-element.html"><code><uses-configuration></code>.</a> |
| element in the application's manifest file. </li> |
| |
| <p>When testing forward-compatibility, try running your application in various |
| AVDs that emulate different hardware configurations. For example, you can create |
| an AVD that does not offer a physical keyboard or one that uses a dpad instead |
| of a trackball. Running your application in different emulated hardware |
| configurations will give you an idea of where its dependencies are and help you |
| identify problems. </p> |
| </li> |
| |
| <li><strong>Watch for assumptions about screen resolution and |
| density</strong>. A device's screen resolution and density is likely to affect |
| the way that your application's UI is rendered, especially if your app specifies |
| dimensions or positions using pixels or absolute layouts. To ensure consistent |
| UI across screens, your app should specify the dimensions and positions of |
| layouts and drawables in relative units that can be scaled by the system as |
| appropriate, according to the density of the device's screen. Alternatively, you |
| can create custom sets of layout/drawable resources for specific screens, which |
| the system can then load as appropriate, based on the current device screen.</p> |
| |
| <p>When testing forward-compatibility, try running your application in various |
| AVDs that emulate different screen resolutions and densities. Also note that, |
| starting with Android 1.6, the platform provides a Compatibility Mode that |
| automatically scales the UI of applications if they do not explicitly indicate |
| support for the current screen in the |
| <a href="{@docRoot}guide/topics/manifest/supports-screen-element.html"><code><supports-screen></code></a> |
| element in their manifest files. As part of testing, you should evaluate how |
| your application is displayed in Compatibility Mode on different screens. </p> |
| </li> |
| |
| <li><strong>Avoid performing layout orientation changes based on the |
| acceletometer (or via other sensors)</strong>. Some Android-powered devices will |
| automatically rotate the orientation (and all devices have the option to turn on |
| auto-rotation), so if your application also attempts to rotate the orientation, |
| it can result in strange behavior. In addition, if your application uses the |
| accelerometer to detect shaking and you do not want to rotate the orientation, |
| then you should lock the current orientation with <a |
| href="{@docRoot}guide/topics/manifest/activity-element.html#screen">android:screenOrientation</a>. |
| </li> |
| |
| </ul> |
| |
| <h2 id="MigrateYourApps">Migrate Your Applications</h2> |
| |
| <p>If you want to use any of the new Android 1.6 APIs in your existing |
| applications, you must first migrate the applications to the new Android |
| platform version. Generally, migrating an application includes: </p> |
| |
| <ul> |
| <li>Referencing the proper API Level in the application's manifest file, |
| and</li> |
| <li>Resetting its project properties so that it is compiled against the Android |
| 1.6 build target.</li> |
| </ul> |
| |
| <p>Additionally, to run your application in the emulator, you need to |
| create an AVD that uses the Android 1.6 system image. </p> |
| |
| <p class="note"><strong>Note:</strong> You only need migrate your application as |
| described in this section if the application will actually use APIs |
| <em>introduced</em> in the Android 1.6 platform (which are not available on |
| devices running older versions of the Android platform). If your application |
| does not use any new APIs, you can compile and run it without modification and |
| not migration is necessary.</p> |
| |
| <h3>Reference the Proper API Level</h3> |
| |
| <p>If your application is using APIs introduced in Android 1.6, you must |
| reference that dependency in the application's manifest file so that it can be |
| deployed to devices running the Android 1.6 platform. </p> |
| |
| <p>Open the manifest file and locate the <code>minSdkVersion</code> attribute |
| in the <code><uses-sdk></code> manifest element. Set the value of |
| <code>minSdkVersion</code> to <code>"4"</code> (the API Level |
| identifier corresponding to Android 1.6). Here's an example:</p> |
| |
| <pre> |
| <manifest> |
| ... |
| <uses-sdk android:minSdkVersion="4" /> |
| ... |
| </manifest> |
| </pre> |
| |
| <h3>Compile Against the Proper Build Target</h3> |
| |
| <p>Once you've changed the <code>minSdkVersion</code> value in your |
| application's manifest, you need to set the application's project properties so |
| that the application will be compiled against the Android 1.6 library. To do so, |
| follow the steps below for your respective development environment. </p> |
| |
| <h4 id="EclipseUsers">Eclipse Users</h4> |
| |
| <ol> |
| <li>Right-click on the individual project (in the Package Explorer) |
| and select <strong>Properties</strong>.</li> |
| <li>In the properties, open the Android panel and select a new Project Build Target. |
| Select "Android 1.6" to target the new platform (or "Google APIs" with the "4" |
| API Level, if your application uses the Google Maps APIs).</li> |
| <li>Click <strong>Apply</strong>, then <strong>OK</strong>.</li> |
| </ol> |
| |
| <h4 id="AntUsers">Ant Users</h4> |
| |
| <p>Use the <code>android</code> tool (located in |
| <code><em>your_sdk</em>/tools/</code>) to create a new <code>build.xml</code> |
| that references the new platform target. To see a list of available targets, |
| execute:</p> |
| |
| <pre>android list targets</pre> |
| |
| <p>Select the target <code>id</code> that corresponds to the "Android 1.6" platform |
| and pass it with the <code>--target</code> parameter when updating your project. |
| For example:</p> |
| |
| <pre>android update project --path /path/to/my-project --target 2</pre> |
| |
| <p>If your application uses the Google Maps APIs (i.e., MapView), be certain to |
| select a Google APIs target.</p> |
| |
| <h3>Create an AVD that Uses the Android 1.6 Platform</h3> |
| |
| <p>Finally, you need to set up a new AVD that uses the Android 1.6 platform, so that |
| you can run your application in the emulator. |
| |
| <p>To set up the new AVD, use the <code>android</code> tool, available in the |
| <code>tools/</code> directory of the SDK. You can run the AVD manager by simply |
| changing to the <code>tools/</code> directory and entering <code>android</code> |
| at the command line. Click "New" to create the AVD and set its properties.</p> |
| |
| <p>When creating the AVD, make sure to select a target of "Android 1.6 - API |
| Level 4". If your application uses the Google Maps APIs (MapView), select the |
| target "Google APIs (Google Inc.) - API Level 4". </p> |
| |
| <p>For more information about running your application in an AVD, see <a |
| href="{@docRoot}guide/developing/eclipse-adt.html#Running">Running Your |
| Application (Eclipse)</a> or <a |
| href="{@docRoot}guide/developing/other-ide.html#Running">Running Your |
| Application (other IDEs)</a>. </p> |
| |
| <p>For general information about AVDs, see the <a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual |
| Devices</a> document. </p> |
| |
| |
| |
| <div class="special"> |
| <p>If you have trouble migrating to the new version of the SDK, visit the |
| <a href="http://groups.google.com/group/android-developers">Android Developers Group</a> |
| to seek help from other Android developers.</p> |
| </div> |
| |