docs/html/sdk/1.5_r1/upgrading.jd - platform/frameworks/base - Git at Google

 page.title=Upgrading the SDK
 sdk.version=1.5_r1
 excludeFromSuggestions=true
 @jd:body


 <div id="qv-wrapper">
 <div id="qv">

   <h2>Upgrading quickview</h2>
   <ul>
     <li>The Android 1.5 SDK uses a new project structure and a new ADT plugin (ADT 0.9). </li>
     <li>To move existing projects into the SDK, you must make some minor changes in your
     development environment.</li>
     <li>The new ADT plugin (ADT 0.9) <em>is not compatible</em> with projects created in previous SDKs.</li>
     <li>You need to uninstall your existing ADT plugin, before installing ADT 0.9.</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="#UpdateYourProjects">Update Your Projects</a>
       <ol>
         <li><a href="#EclipseUsers">Eclipse Users</a></li>
         <li><a href="#AntUsers">Ant Users</a></li>
       </ol>
     </li>
     <li><a href="#MigrateYourApplications">Migrate Your Applications</a>
       <ol><li><a href="#FutureProofYourApps">Future-proof your apps</a></li></ol>
     </li>
   </ol>

   <h2>Migrating references</h2>
   <ol>
     <li><a href="{@docRoot}sdk/api_diff/3/changes.html">Android 1.5 API Differences</a></li>
     <li><a
 href="http://android-developers.blogspot.com/2009/04/future-proofing-your-apps.html">Future-Proofing
 Your Apps &raquo;</a></li>
     <li><a
 href="http://android-developers.blogspot.com/2009/04/ui-framework-changes-in-android-15.html">UI
 framework changes in Android 1.5 &raquo;</a></li>
   </ol>

 </div>
 </div>

 <p>This document describes how to move your development environment and existing
 Android applications from an Android 1.0 or 1.1 SDK to the Android 1.5 SDK.
 If you are migrating applications from an SDK older than 1.0, please also read the upgrading
 document available in the Android 1.0 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
 Android 1.5 platform.</p>

 <p>The Android 1.5 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 breakage 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 Android 1.5.</p>

 <p>For more information on new SDK features and system changes,
 see the <a href="{@docRoot}sdk/android-1.5.html">Android 1.5 Version Notes</a>.</p>


 <h2 id="Install">Install the SDK</h2>

 <p>If you haven't yet downloaded the SDK, <a href="{@docRoot}sdk/1.5_r1/index.html">download from here</a>
 and unpack it into a safe location.</p>

 <p><strong>Before you begin:</strong>
 If you had previously setup your PATH 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>&lt;your_sdk_dir></em>/tools</pre>

 <p>If you don't use Eclipse for development,
 skip to <a href="#updateYourProjects">Update Your Projects</a>.</p>


 <h2 id="UpdateAdt">Update Your Eclipse ADT Plugin</h2>

 <p><em>If you installed ADT-0.9_pre with the early look 1.5 SDK, there have been
 additional changes, so please continue with this guide and update to the final ADT 0.9.</em></p>

 <p>A new ADT plugin (version 0.9) is required for the Android 1.5 SDK.
 Because the component structure has been changed since Android 1.1,
 the Android 1.5 SDK does not work with ADT 0.8 (or older) and previously installed SDKs will not
 work with ADT 0.9. However, the Android 1.5 SDK includes an Android 1.1 SDK image that you
 can build against while using ADT 0.9. </p>

 <p class="note">For information about using different system images (such as Android 1.1)
 while running this SDK, see Developing <a href="{@docRoot}guide/developing/eclipse-adt.html">
 In Eclipse, with ADT</a> or <a href="{@docRoot}guide/developing/other-ide.html">In
 Other IDEs</a>, as appropriate for your development environment.</p>

 <p>In order to upgrade your Eclipse IDE to use the new 0.9 ADT, follow the steps below
 for your respective version of Eclipse.</p>

 <h3 id="uninstallAdt">Uninstall your previous ADT plugin</h3>

 <p>You must uninstall your existing ADT plugin (0.8 or older). If you do not uninstall it,
 you will get a conflict with the Android Editors when installing the new ADT.
 (If you have already installed ADT-0.9_pre with the early look 1.5 SDK, you can skip this
 uninstall procedure and continue to <a href="#installAdt">Install the 0.9 ADT plugin</a>).</p>

 <table style="font-size:100%">
 <tr><th>Eclipse 3.3 (Europa)</th><th>Eclipse 3.4 (Ganymede)</th></tr>
 <tr>
 <td width="50%">
 <!-- 3.3 steps -->
 <ol>
     <li>Select <strong>Help</strong> &gt; <strong>Software Updates</strong> &gt;
       <strong>Manage Configuration</strong>. </li>
     <li>Expand the list in the left panel to reveal the installed tools.</li>
     <li>Right-click "Android Editors" and click <strong>Uninstall</strong>. Click <strong>OK</strong>
     to confirm.</li>
     <li>Restart Eclipse.
       <p>(Do not uninstall "Android Development Tools".)</p></li>
 </ol>
 </td>
 <td>
 <!-- 3.4 steps -->
 <ol>
     <li>Select <strong>Help</strong> &gt; <strong>Software Updates</strong>.</li>
     <li>Select the <strong>Installed Software</strong> tab.</li>
     <li>Select "Android Editors". Click <strong>Uninstall</strong>.</li>
     <li>In the next window, be sure "Android Editors" is checked, then click <strong>Finish</strong>
     to uninstall.</li>
     <li>Restart Eclipse.
       <p>(Do not uninstall "Android Development Tools".)</p></li>
 </ol>
 </td>
 </tr>
 </table>


 <h3 id="installAdt">Install the 0.9 ADT plugin</h3>

 <p>Only install the new plugin once you've completed the procedure to
 <a href="#uninstallAdt">Uninstall your previous ADT plugin</a>.</p>

 <table style="font-size:100%">
 <tr><th>Eclipse 3.3 (Europa)</th><th>Eclipse 3.4 (Ganymede)</th></tr>
 <tr>
 <td width="50%">
 <!-- 3.3 steps -->
 <ol>
     <li>Select <strong>Help</strong> &gt; <strong>Software Updates</strong> &gt;
       <strong>Find and Install</strong>. </li>
     <li>Select <strong>Search for new features to install</strong>.</li>
     <li>Select the Android plugin entry by checking the box next to it,
       then click <strong>Finish</strong>.
       <p>(Your original entry for the plugin should still be here. If not, see the guide
       to <a href="{@docRoot}sdk/1.5_r1/installing.html#installingplugin">Installing the ADT Plugin</a>.)
       </p></li>
     <li>In the results, expand the entry for the Android plugin and
       be sure that "Developer Tools" is checked, then click <strong>Next</strong>.
       (This will install "Android DDMS" and "Android Development Tools".)</li>
     <li>Read and accept the license agreement, then click <strong>Next</strong>.
     <li>In the next window, click <strong>Finish</strong> to start installation.</li>
     <li>The ADT plugin is not digitally signed. Accept the installation anyway by clicking
     <strong>Install All</strong>.</li>
     <li>Restart Eclipse.</li>
 </ol>
 </td>
 <td>
 <!-- 3.4 steps -->
 <ol>
     <li>Select <strong>Help</strong> &gt; <strong>Software Updates</strong>.</li>
     <li>Select the <strong>Available Software</strong> tab.</li>
     <li>Expand the entry for the Andriod plugin (may be listed as the location URL)
       and select "Developer Tools" by checking the box next to it, then click
       <strong>Install</strong>.</li>
     <li>On the next window, "Android DDMS" and "Android Development Tools"
     should both be checked. Click <strong>Finish</strong>.</li>
     <li>Restart Eclipse.</li>
 </ol>
 </td>
 </tr>
 </table>

 <p>If you encounter problems, ensure your ADT is fully uninstalled and then
 follow the guide to
 <a href="{@docRoot}sdk/1.5_r1/installing.html#installingplugin">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 <em>SDK Location</em> in the main panel, click <strong>Browse</strong>
       and locate your SDK directory.</li>
       <li>Click <strong>Apply</strong>, then <strong>OK</strong>.</li>
     </ol>


 <h2 id="UpdateYourProjects">Update Your Projects</h2>

 <p>You will now need to update any and all Android projects that you have
 developed using a previous version of the Android SDK.</p>


 <h3 id="EclipseUsers">Eclipse users</h3>

 <p>If you use Eclipse to develop applications, use the following procedure to
 update each project:</p>

 <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 "build target" to compile
     against. This SDK offers the Android 1.1 and Android 1.5 platforms to choose from. When
     you are initially updating your projects to the new SDK, we recommend that you select a build
     target with the Android 1.1 platform. Click <strong>Apply</strong>, then
     <strong>OK</strong>.</li>
 </ol>

 <p>The new plugin creates a <code>gen/</code> folder in your project, in which it puts the
 <code>R.java</code> file
 and all automatically generated AIDL java files. If you get an error such as
 <code>The type R is already defined</code>,
 then you probably need to delete your old <code>R.java</code> or your old auto-generated
 AIDL Java files in the <code>src/</code> folder.
 (This <em>does not</em> apply to your own hand-crafted parcelable AIDL java files.)</p>

 <p>Note that, with the Android 1.5 SDK, there is a new process for running
 applications in the Android Emulator.
 Specifically, you must create an Android Virtual Device (AVD) before you can launch an instance
 of the Emulator. Before attempting to run your applications with the new SDK,
 please continue with the section below to
 <a href="#MigrateYourApplications">Migrate Your Applications</a>.</p>


 <h3 id="AntUsers">Ant users</h3>

 <p>If you build your projects using the Ant tool (rather than with Eclipse), note the
 following changes with the new SDK tools.</p>

 <h4>build.xml has changed</h4>

 <p>You must re-create your <code>build.xml</code> file.</p>

 <p>If you had customized your <code>build.xml</code>, first make a copy of it:</p>

 <pre>
 $ cd <em>my-project</em>
 $ cp build.xml build.xml.old
 </pre>

 <p>Now use the new <code>android</code> tool (located in <code><em>your_sdk</em>/tools/</code>)
 to create a new <code>build.xml</code> that references
 a specific platform target:</p>

 <pre>$ android update project --path /path/to/my-project --target 1</pre>

 <p>The "target" corresponds to an Android platform library (including any add-ons, such as
 Google APIs) that you would like to build your project against. You can view a list of available
 targets (and their corresponding integer ID) with the command, <code>android list targets</code>.
 When you are initially updating your projects to the new SDK, we recommend that you select the
 first target ("1"), which uses the Android 1.1 platform library.</p>

 <p>A <code>gen/</code> folder will be created the first time you build and your <code>R.java</code> and
 your AIDL Java files will be generated in here. You <strong>must</strong> remove
 the old <code>R.java</code> and old auto-generated AIDL java files from the
 <code>src/</code> folder. (This
 does not apply to your own hand-crafted parcelabe AIDL java files.)</p>

 <p class="note"><strong>Note:</strong> The "activitycreator" tool has been replaced
 by the new "android" tool. For information on creating new projects with the android tool,
 see the documentation about <a href="{@docRoot}guide/developing/other-ide.html">Developing
 In Other IDEs</a>.</p>

 <p>Note that, with the Android 1.5 SDK, there is a new process for running
 applications in the Android Emulator.
 Specifically, you must create an Android Virtual Device (AVD) before you can launch an instance
 of the Emulator. Before attempting to run your applications with the new SDK,
 please continue with the section below to
 <a href="#MigrateYourApplications">Migrate Your Applications</a>.</p>


 <h2 id="MigrateYourApplications">Migrate Your Applications</h2>

 <p>After you have completed the process above to <a href="#UpdateYourProjects">Update Your
 Projects</a>, you are strongly encouraged to run each of your applications in an instance
 of the emulator running the Android 1.5 system image. It's possible (however, unlikely)
 that you'll encounter some breakage in your application when you run your applications on
 the Android 1.5 system image. Whether you believe your application will be affected by
 platform changes or not, it's very important that you test the application's
 forward-compatibility on Android 1.5.</p>

 <p>To test forward-compatibility, simply run your existing application (as-is) on an Android
 Emulator that's running the Android 1.5 system image. The following procedure will guide
 you through the process to running your existing applications on an emulator. <em>Please read
 the following guide completely before you begin</em>.</p>

 <p>To test your application on an emulator running Android 1.5:</p>
 <ol>
   <li><a href="#UpdateYourProjects">Update Your Project</a> (you should have done this
   already, in the section above).</li>
   <li>Run your existing project, as-is, on an emulator running the Android 1.5 system image.
     <p>As mentioned in the guide to <a href="#UpdateYourProjects">Update Your Projects</a>,
     you should have selected a "build
     target" of "1", which compiles your application against the Android 1.1 system image, so there
     should be no new errors in your code.</p>
     <p>Eclipse users: follow the
     <a href="{@docRoot}guide/developing/eclipse-adt.html#Running">Eclipse guide to
     Running Your Application</a>.</p>
     <p>Ant users: follow the
     <a href="{@docRoot}guide/developing/other-ide.html#Running">Ant guide to
     Running Your Application</a>
     <p>During the procedure to Running Your Application, select a "deployment target"
     for the AVD that includes the Android 1.5 platform.
     If your application utilizes the Google Maps APIs (i.e.,
     MapView), be certain to select a target that includes the Google APIs.</p>
     <p>Once you complete the procedures to run your application in your respective environment,
     linked above, return here.</p>
   </li>
   <li>With your application running in the emulator, perform all regular testing on the application
   to ensure that it functions normally (in both landscape and portrait orientations).</li>
 </ol>

 <p>Chances are, your application runs just fine on the Android 1.5 platform &mdash;
 new devices will be able to safely install and run your application and
 current users who update their devices will be able to continue using your application as usual.
 However, if something doesn't work the way you expect, then you might need to revisit
 your project and make any necessary changes to your code.</p>

 <p>You can check for code breakages caused by API changes by opening your project
 in Eclipse, changing the "build target" to one using the Android 1.5 platform,
 and see where the ADT identifies errors in your code.</p>


 <h3 id="FutureProofYourApps">Future-proof your apps</h3>

 <p>There have been several API additions made for this release, but there have been
 very few actual API <em>changes</em>. Only a couple (relatively unused) elements
 have been removed and a few have been deprecated, so your applications written with the
 Android 1.1 system library should work just fine. However,
 your application is more likely to encounter problems on Android 1.5
 if it performs any of the following:</p>

 <ul>
   <li>Uses internal APIs. That is, APIs that are not officially supported
   and not available in the reference documentation. Any un-official APIs are always subject
   to change (which is why they're un-official) and some have indeed changed.
   </li>
   <li>Directly manipulates system settings. There are some settings (such as
   GPS, data roaming, bluetooth and others) that used to be writable by
   applications but have been changed so that they can only be explicitly modified by the user
   through the system settings. Refer to {@link android.provider.Settings.Secure}
   to see which settings are now secured and cannot be directly changed by your application.
   </li>
   <li>Uses View hierarchies that are unreasonably deep (more than 10 or so levels) or
   broad (more than 30 total). View hierarchies this big have always been troublesome, but
   Android 1.5 is much more efficient at exposing this and your application may crash.
   </li>
   <li>Makes assumptions about the available hardware. With new support for soft keyboards,
   not all devices will have full QWERTY keyboards on the hardware. So if your application
   listens for special keypress events that only occur on a keypad, then your application
   should degrade gracefully when there is no keyboard available.
   </li>
   <li>Performs its own layout orientation changes based on the acceletometer (or via other
   sensors). Some devices running Android 1.5 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>

 <p>Please read our blog post on <a
 href="http://android-developers.blogspot.com/2009/04/future-proofing-your-apps.html">Future-Proofing
 Your Apps</a> for more information on the issues mentioned above.</p>

 <p>For information
 about other changes made to Android 1.5, refer to the following documents:</p>
 <ul>
   <li><a href="{@docRoot}sdk/api_diff/3/changes.html">Android 1.5 API Differences</a></li>
   <li><a href="{@docRoot}sdk/android-1.5.html#api-changes">Android 1.5 Version Notes</a></li>
   <li><a
 href="http://android-developers.blogspot.com/2009/04/ui-framework-changes-in-android-15.html">UI
 framework changes in Android 1.5 &raquo;</a></li>
 </ul>

 <p>If you have additional trouble updating your code, visit the
 <a href="http://groups.google.com/group/android-developers">Android Developers Group</a>
 to seek help from other Android developers.</p>
	page.title=Upgrading the SDK
	sdk.version=1.5_r1
	excludeFromSuggestions=true
	@jd:body


	<div id="qv-wrapper">
	<div id="qv">

	<h2>Upgrading quickview</h2>
	<ul>
	<li>The Android 1.5 SDK uses a new project structure and a new ADT plugin (ADT 0.9). </li>
	<li>To move existing projects into the SDK, you must make some minor changes in your
	development environment.</li>
	<li>The new ADT plugin (ADT 0.9) <em>is not compatible</em> with projects created in previous SDKs.</li>
	<li>You need to uninstall your existing ADT plugin, before installing ADT 0.9.</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="#UpdateYourProjects">Update Your Projects</a>
	<ol>
	<li><a href="#EclipseUsers">Eclipse Users</a></li>
	<li><a href="#AntUsers">Ant Users</a></li>
	</ol>
	</li>
	<li><a href="#MigrateYourApplications">Migrate Your Applications</a>
	<ol><li><a href="#FutureProofYourApps">Future-proof your apps</a></li></ol>
	</li>
	</ol>

	<h2>Migrating references</h2>
	<ol>
	<li><a href="{@docRoot}sdk/api_diff/3/changes.html">Android 1.5 API Differences</a></li>
	<li><a
	href="http://android-developers.blogspot.com/2009/04/future-proofing-your-apps.html">Future-Proofing
	Your Apps »</a></li>
	<li><a
	href="http://android-developers.blogspot.com/2009/04/ui-framework-changes-in-android-15.html">UI
	framework changes in Android 1.5 »</a></li>
	</ol>

	</div>
	</div>

	<p>This document describes how to move your development environment and existing
	Android applications from an Android 1.0 or 1.1 SDK to the Android 1.5 SDK.
	If you are migrating applications from an SDK older than 1.0, please also read the upgrading
	document available in the Android 1.0 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
	Android 1.5 platform.</p>

	<p>The Android 1.5 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 breakage 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 Android 1.5.</p>

	<p>For more information on new SDK features and system changes,
	see the <a href="{@docRoot}sdk/android-1.5.html">Android 1.5 Version Notes</a>.</p>


	<h2 id="Install">Install the SDK</h2>

	<p>If you haven't yet downloaded the SDK, <a href="{@docRoot}sdk/1.5_r1/index.html">download from here</a>
	and unpack it into a safe location.</p>

	<p><strong>Before you begin:</strong>
	If you had previously setup your PATH 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>

	<p>If you don't use Eclipse for development,
	skip to <a href="#updateYourProjects">Update Your Projects</a>.</p>


	<h2 id="UpdateAdt">Update Your Eclipse ADT Plugin</h2>

	<p><em>If you installed ADT-0.9_pre with the early look 1.5 SDK, there have been
	additional changes, so please continue with this guide and update to the final ADT 0.9.</em></p>

	<p>A new ADT plugin (version 0.9) is required for the Android 1.5 SDK.
	Because the component structure has been changed since Android 1.1,
	the Android 1.5 SDK does not work with ADT 0.8 (or older) and previously installed SDKs will not
	work with ADT 0.9. However, the Android 1.5 SDK includes an Android 1.1 SDK image that you
	can build against while using ADT 0.9. </p>

	<p class="note">For information about using different system images (such as Android 1.1)
	while running this SDK, see Developing <a href="{@docRoot}guide/developing/eclipse-adt.html">
	In Eclipse, with ADT</a> or <a href="{@docRoot}guide/developing/other-ide.html">In
	Other IDEs</a>, as appropriate for your development environment.</p>

	<p>In order to upgrade your Eclipse IDE to use the new 0.9 ADT, follow the steps below
	for your respective version of Eclipse.</p>

	<h3 id="uninstallAdt">Uninstall your previous ADT plugin</h3>

	<p>You must uninstall your existing ADT plugin (0.8 or older). If you do not uninstall it,
	you will get a conflict with the Android Editors when installing the new ADT.
	(If you have already installed ADT-0.9_pre with the early look 1.5 SDK, you can skip this
	uninstall procedure and continue to <a href="#installAdt">Install the 0.9 ADT plugin</a>).</p>

	<table style="font-size:100%">
	<tr><th>Eclipse 3.3 (Europa)</th><th>Eclipse 3.4 (Ganymede)</th></tr>
	<tr>
	<td width="50%">
	<!-- 3.3 steps -->
	<ol>
	<li>Select <strong>Help</strong> > <strong>Software Updates</strong> >
	<strong>Manage Configuration</strong>. </li>
	<li>Expand the list in the left panel to reveal the installed tools.</li>
	<li>Right-click "Android Editors" and click <strong>Uninstall</strong>. Click <strong>OK</strong>
	to confirm.</li>
	<li>Restart Eclipse.
	<p>(Do not uninstall "Android Development Tools".)</p></li>
	</ol>
	</td>
	<td>
	<!-- 3.4 steps -->
	<ol>
	<li>Select <strong>Help</strong> > <strong>Software Updates</strong>.</li>
	<li>Select the <strong>Installed Software</strong> tab.</li>
	<li>Select "Android Editors". Click <strong>Uninstall</strong>.</li>
	<li>In the next window, be sure "Android Editors" is checked, then click <strong>Finish</strong>
	to uninstall.</li>
	<li>Restart Eclipse.
	<p>(Do not uninstall "Android Development Tools".)</p></li>
	</ol>
	</td>
	</tr>
	</table>


	<h3 id="installAdt">Install the 0.9 ADT plugin</h3>

	<p>Only install the new plugin once you've completed the procedure to
	<a href="#uninstallAdt">Uninstall your previous ADT plugin</a>.</p>

	<table style="font-size:100%">
	<tr><th>Eclipse 3.3 (Europa)</th><th>Eclipse 3.4 (Ganymede)</th></tr>
	<tr>
	<td width="50%">
	<!-- 3.3 steps -->
	<ol>
	<li>Select <strong>Help</strong> > <strong>Software Updates</strong> >
	<strong>Find and Install</strong>. </li>
	<li>Select <strong>Search for new features to install</strong>.</li>
	<li>Select the Android plugin entry by checking the box next to it,
	then click <strong>Finish</strong>.
	<p>(Your original entry for the plugin should still be here. If not, see the guide
	to <a href="{@docRoot}sdk/1.5_r1/installing.html#installingplugin">Installing the ADT Plugin</a>.)
	</p></li>
	<li>In the results, expand the entry for the Android plugin and
	be sure that "Developer Tools" is checked, then click <strong>Next</strong>.
	(This will install "Android DDMS" and "Android Development Tools".)</li>
	<li>Read and accept the license agreement, then click <strong>Next</strong>.
	<li>In the next window, click <strong>Finish</strong> to start installation.</li>
	<li>The ADT plugin is not digitally signed. Accept the installation anyway by clicking
	<strong>Install All</strong>.</li>
	<li>Restart Eclipse.</li>
	</ol>
	</td>
	<td>
	<!-- 3.4 steps -->
	<ol>
	<li>Select <strong>Help</strong> > <strong>Software Updates</strong>.</li>
	<li>Select the <strong>Available Software</strong> tab.</li>
	<li>Expand the entry for the Andriod plugin (may be listed as the location URL)
	and select "Developer Tools" by checking the box next to it, then click
	<strong>Install</strong>.</li>
	<li>On the next window, "Android DDMS" and "Android Development Tools"
	should both be checked. Click <strong>Finish</strong>.</li>
	<li>Restart Eclipse.</li>
	</ol>
	</td>
	</tr>
	</table>

	<p>If you encounter problems, ensure your ADT is fully uninstalled and then
	follow the guide to
	<a href="{@docRoot}sdk/1.5_r1/installing.html#installingplugin">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 <em>SDK Location</em> in the main panel, click <strong>Browse</strong>
	and locate your SDK directory.</li>
	<li>Click <strong>Apply</strong>, then <strong>OK</strong>.</li>
	</ol>


	<h2 id="UpdateYourProjects">Update Your Projects</h2>

	<p>You will now need to update any and all Android projects that you have
	developed using a previous version of the Android SDK.</p>


	<h3 id="EclipseUsers">Eclipse users</h3>

	<p>If you use Eclipse to develop applications, use the following procedure to
	update each project:</p>

	<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 "build target" to compile
	against. This SDK offers the Android 1.1 and Android 1.5 platforms to choose from. When
	you are initially updating your projects to the new SDK, we recommend that you select a build
	target with the Android 1.1 platform. Click <strong>Apply</strong>, then
	<strong>OK</strong>.</li>
	</ol>

	<p>The new plugin creates a <code>gen/</code> folder in your project, in which it puts the
	<code>R.java</code> file
	and all automatically generated AIDL java files. If you get an error such as
	<code>The type R is already defined</code>,
	then you probably need to delete your old <code>R.java</code> or your old auto-generated
	AIDL Java files in the <code>src/</code> folder.
	(This <em>does not</em> apply to your own hand-crafted parcelable AIDL java files.)</p>

	<p>Note that, with the Android 1.5 SDK, there is a new process for running
	applications in the Android Emulator.
	Specifically, you must create an Android Virtual Device (AVD) before you can launch an instance
	of the Emulator. Before attempting to run your applications with the new SDK,
	please continue with the section below to
	<a href="#MigrateYourApplications">Migrate Your Applications</a>.</p>


	<h3 id="AntUsers">Ant users</h3>

	<p>If you build your projects using the Ant tool (rather than with Eclipse), note the
	following changes with the new SDK tools.</p>

	<h4>build.xml has changed</h4>

	<p>You must re-create your <code>build.xml</code> file.</p>

	<p>If you had customized your <code>build.xml</code>, first make a copy of it:</p>

	<pre>
	$ cd <em>my-project</em>
	$ cp build.xml build.xml.old
	</pre>

	<p>Now use the new <code>android</code> tool (located in <code><em>your_sdk</em>/tools/</code>)
	to create a new <code>build.xml</code> that references
	a specific platform target:</p>

	<pre>$ android update project --path /path/to/my-project --target 1</pre>

	<p>The "target" corresponds to an Android platform library (including any add-ons, such as
	Google APIs) that you would like to build your project against. You can view a list of available
	targets (and their corresponding integer ID) with the command, <code>android list targets</code>.
	When you are initially updating your projects to the new SDK, we recommend that you select the
	first target ("1"), which uses the Android 1.1 platform library.</p>

	<p>A <code>gen/</code> folder will be created the first time you build and your <code>R.java</code> and
	your AIDL Java files will be generated in here. You <strong>must</strong> remove
	the old <code>R.java</code> and old auto-generated AIDL java files from the
	<code>src/</code> folder. (This
	does not apply to your own hand-crafted parcelabe AIDL java files.)</p>

	<p class="note"><strong>Note:</strong> The "activitycreator" tool has been replaced
	by the new "android" tool. For information on creating new projects with the android tool,
	see the documentation about <a href="{@docRoot}guide/developing/other-ide.html">Developing
	In Other IDEs</a>.</p>

	<p>Note that, with the Android 1.5 SDK, there is a new process for running
	applications in the Android Emulator.
	Specifically, you must create an Android Virtual Device (AVD) before you can launch an instance
	of the Emulator. Before attempting to run your applications with the new SDK,
	please continue with the section below to
	<a href="#MigrateYourApplications">Migrate Your Applications</a>.</p>


	<h2 id="MigrateYourApplications">Migrate Your Applications</h2>

	<p>After you have completed the process above to <a href="#UpdateYourProjects">Update Your
	Projects</a>, you are strongly encouraged to run each of your applications in an instance
	of the emulator running the Android 1.5 system image. It's possible (however, unlikely)
	that you'll encounter some breakage in your application when you run your applications on
	the Android 1.5 system image. Whether you believe your application will be affected by
	platform changes or not, it's very important that you test the application's
	forward-compatibility on Android 1.5.</p>

	<p>To test forward-compatibility, simply run your existing application (as-is) on an Android
	Emulator that's running the Android 1.5 system image. The following procedure will guide
	you through the process to running your existing applications on an emulator. <em>Please read
	the following guide completely before you begin</em>.</p>

	<p>To test your application on an emulator running Android 1.5:</p>
	<ol>
	<li><a href="#UpdateYourProjects">Update Your Project</a> (you should have done this
	already, in the section above).</li>
	<li>Run your existing project, as-is, on an emulator running the Android 1.5 system image.
	<p>As mentioned in the guide to <a href="#UpdateYourProjects">Update Your Projects</a>,
	you should have selected a "build
	target" of "1", which compiles your application against the Android 1.1 system image, so there
	should be no new errors in your code.</p>
	<p>Eclipse users: follow the
	<a href="{@docRoot}guide/developing/eclipse-adt.html#Running">Eclipse guide to
	Running Your Application</a>.</p>
	<p>Ant users: follow the
	<a href="{@docRoot}guide/developing/other-ide.html#Running">Ant guide to
	Running Your Application</a>
	<p>During the procedure to Running Your Application, select a "deployment target"
	for the AVD that includes the Android 1.5 platform.
	If your application utilizes the Google Maps APIs (i.e.,
	MapView), be certain to select a target that includes the Google APIs.</p>
	<p>Once you complete the procedures to run your application in your respective environment,
	linked above, return here.</p>
	</li>
	<li>With your application running in the emulator, perform all regular testing on the application
	to ensure that it functions normally (in both landscape and portrait orientations).</li>
	</ol>

	<p>Chances are, your application runs just fine on the Android 1.5 platform —
	new devices will be able to safely install and run your application and
	current users who update their devices will be able to continue using your application as usual.
	However, if something doesn't work the way you expect, then you might need to revisit
	your project and make any necessary changes to your code.</p>

	<p>You can check for code breakages caused by API changes by opening your project
	in Eclipse, changing the "build target" to one using the Android 1.5 platform,
	and see where the ADT identifies errors in your code.</p>


	<h3 id="FutureProofYourApps">Future-proof your apps</h3>

	<p>There have been several API additions made for this release, but there have been
	very few actual API <em>changes</em>. Only a couple (relatively unused) elements
	have been removed and a few have been deprecated, so your applications written with the
	Android 1.1 system library should work just fine. However,
	your application is more likely to encounter problems on Android 1.5
	if it performs any of the following:</p>

	<ul>
	<li>Uses internal APIs. That is, APIs that are not officially supported
	and not available in the reference documentation. Any un-official APIs are always subject
	to change (which is why they're un-official) and some have indeed changed.
	</li>
	<li>Directly manipulates system settings. There are some settings (such as
	GPS, data roaming, bluetooth and others) that used to be writable by
	applications but have been changed so that they can only be explicitly modified by the user
	through the system settings. Refer to {@link android.provider.Settings.Secure}
	to see which settings are now secured and cannot be directly changed by your application.
	</li>
	<li>Uses View hierarchies that are unreasonably deep (more than 10 or so levels) or
	broad (more than 30 total). View hierarchies this big have always been troublesome, but
	Android 1.5 is much more efficient at exposing this and your application may crash.
	</li>
	<li>Makes assumptions about the available hardware. With new support for soft keyboards,
	not all devices will have full QWERTY keyboards on the hardware. So if your application
	listens for special keypress events that only occur on a keypad, then your application
	should degrade gracefully when there is no keyboard available.
	</li>
	<li>Performs its own layout orientation changes based on the acceletometer (or via other
	sensors). Some devices running Android 1.5 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>

	<p>Please read our blog post on <a
	href="http://android-developers.blogspot.com/2009/04/future-proofing-your-apps.html">Future-Proofing
	Your Apps</a> for more information on the issues mentioned above.</p>

	<p>For information
	about other changes made to Android 1.5, refer to the following documents:</p>
	<ul>
	<li><a href="{@docRoot}sdk/api_diff/3/changes.html">Android 1.5 API Differences</a></li>
	<li><a href="{@docRoot}sdk/android-1.5.html#api-changes">Android 1.5 Version Notes</a></li>
	<li><a
	href="http://android-developers.blogspot.com/2009/04/ui-framework-changes-in-android-15.html">UI
	framework changes in Android 1.5 »</a></li>
	</ul>

	<p>If you have additional trouble updating your code, visit the
	<a href="http://groups.google.com/group/android-developers">Android Developers Group</a>
	to seek help from other Android developers.</p>