Upgrading the SDK

From m3-rc37a to m5

The M5 release of the Android SDK includes a variety of new features, such as extensions and improvements in the framework API, redesigned applications and UI, and enhancements to the SDK development tools. To take advantage of these new features, you need to upgrade your existing Android applications to the M5 SDK.

Upgrading your Android development environment from M3 to M5 is straightforward. However, there are a few special extra steps that you need to follow for this upgrade. The list below guides you through the upgrade process.

1. Backup your existing applications and workspace as necessary.
2. Download the SDK

   The first step is to obtain the SDK distribution. You can find it here: http://code.google.com/android/download.html Please be sure to download the correct version of the SDK for your operating system.

3. Install the SDK

   Once you have downloaded the new SDK, you can install it by following the steps given in Installing the SDK. As mentioned there, though, be sure to update your PATH environment variable.

4. Install the new ADT Eclipse plugin

   Now you need to install the new ADT plugin, which contains two Eclipse "features", where the old version contained only one. To begin, go to Help > Software Updates > Find and Install. You can then follow the steps listed in Installing the Eclipse Plugin (ADT). However, note that you should skip steps 1 through 5, since you will already have added the Remote Site containing ADT to your Eclipse configuration. After restarting Eclipse, remember to reset your preferences to point to the new SDK, as described in step 11.

5. Update your project properties

   Once you've updated the ADT plugin and restarted Eclipse, you need to fix the properties of your project to point to the new Android classes. In the Package Explorer view, right-click the project and choose Android Tools > Fix Project Properties. This automatically updates the path to the android.jar file. When you go to the build path properties for the project, you should see a library called "Android Library".

6. Erase old emulator data

   Once you have installed the SDK and the new Eclipse features, you'll need to erase the data used by the previous emulator. Some of the data formats used by applications have changed in M5. Since during this pre-release period we are not maintaining binary compatibility between versions, you must instead wipe the data.

   The easiest way to do this is to manually start the emulator once with the -wipe-data option. To do this, open a terminal or console window (such as an xterm on Linux, Terminal on Mac, or a Command Prompt on Windows). Then change to the directory where you have installed the SDK, and change again to the "tools" subdirectory.

   Then, run one of these commands:

   • Windows: emulator -wipe-data
   • Linux and Mac: ./emulator -wipe-data

   Wait for the emulator window to appear and the system to boot completely.

7. Check your migrated apps for errors caused by API changes

   The M5 release includes changes in the API that you use to write Android applications. For example, there are minor changes that you'll need to make in your manifest and layout files, and you might need to make other modifications because of changes in packages, classes, methods, or fields. In general, the M5 API includes a variety of new capabilities, functional improvements, and bug fixes. To take advantage of those, you'll likely need to make some changes to your M3 application code so that it compiles and runs properly on M5.

   To learn more about the changes in M5, use the resources listed at the top of this page. The Overview of M5 SDK changes and M5 API Diff Report may be especially useful to you in migrating your apps.

Once you've completed the above steps, you will be ready to begin developing with the new M5 SDK. If you have any additional questions or problems, please let us know on the Android Developers Group.

From m3-rc20/22 to m3-rc37a

Upgrading from m3-rc20/22 requires the following steps:

1. Download and unpack the latest SDK.
2. Update the ADT plugin according to the instructions below.

Updating the ADT Plugin

To update to the new plugin you will need to:

1. In Eclipse, select Help > Software Updates > Manage Configuration.
2. Find the ADT (Android Development Tools X.X.X) plugin on the tree in the left panel. Right click and select Uninstall. Agree to restart Eclipse.

   If you mistakenly chose Disable instead of Uninstall, the plugin will not be deleted but simply disappear from the list since by default, disabled plugins are not shown. You can show them again by choosing Show Disabled Features in the toolbar (3rd icon from the left). If you want to fully delete the old plugin, you will have to re-enable it and choose Uninstall again.

3. Eclipse may tell you that it cannot restore the workbench layout. You can ignore those messages. Additionally, if you have the DDMS perspective icon in the upper right corner, you should right click on it and select Close to remove it.
4. Follow the standard instructions to install the new version. Due to this particular install process, you will need to enter the location of the SDK in the Android preference page again. (See step 11 in Installing the Eclipse Plugin.)

Note that your Android projects will not be recognized by the new plugin. To fix this, right click your project in the Package Explorer and choose Android Tools > Convert To Android Project.