path: root/docs/html/sdk/preview/upgrading.jd

page.title=Upgrading the SDK
sdk.version=1.6
sdk.preview=true
@jd:body


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

  <h2>Upgrading the SDK</h2>
  <ul>
    <li>ADT 0.9 / 0.9.1 is not compatible with the Android 1.6 Early Look SDK. You must upgrade
    ADT to 0.9.2.</li>
    <li>The Early Look SDK uses a special provisional API Level, "Donut", which is required
    to compile against the new Donut platform.</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="#ConvertYourApps">Convert Your Applications</a></li>
  </ol>
  
  <h2>Migrating references</h2>
  <ol>
    <li><a href="{@docRoot}sdk/api_diff/4/changes.html">Android 1.6 Early Look 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 Early Look 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 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 the new platform.</p>

<!-- NOT AVAILABLE FOR THE PREVIEW
<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="index.html">download from here</a> 
and unpack it into a safe location.</p>
-->
<p>Now that you have the Android 1.6 Early Look SDK,
you need to perform some of the regular installation steps.</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>&lt;your_sdk_dir></em>/tools</pre>


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

<p>If you don't use Eclipse for development,
skip to <a href="#RunYourApps">Run Your Applications</a>.</p>

<!--
<p><em>If you installed ADT 0.9.2 with the Android 1.6 Early Look SDK, there have been
additional changes, so please continue with this guide and update ADT.</em></p>
-->

<p>A new ADT plugin (version 0.9.2) is required for the Android 1.6 Early Look SDK.
With ADT 0.9.2, you can still compile your applications against 
multiple platform versions, such as Android 1.5. However, previous versions
of ADT will not work with the Android 1.6 Early Look SDK, so you must upgrade
to ADT 0.9.2.</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="http://developer.android.com/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>

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

<p>To install the new ADT plugin, follow the steps below for your respective version of Eclipse.</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="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 with this update procedure, try performing a fresh installation. 
Ensure your current ADT is fully uninstalled 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</h2>

<p>Now that you have installed the Android 1.6 Early Look SDK, we encourage you
to run each of your applications in an instance
of the emulator that's running the new Android 1.6 system image. It's possible (however, unlikely) 
that you'll encounter unexpected behavior in your application when you run your applications on
the new 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.</p>

<p>To test forward-compatibility, simply run your application, as-is, on an instance of the Android
Emulator that uses an AVD targeted to "Android Donut (Preview)":</p>

<ol>
  <li>Make no changes to your application code.</li>
  <li>Create a new AVD that's targeted to the "Donut" 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>For more information on creating an AVD and launching your application refer to the 
<a href="{@docRoot}guide/developing/eclipse-adt.html#Running">Eclipse guide to 
Running Your Application</a> or the 
<a href="{@docRoot}guide/developing/other-ide.html#Running">Ant guide to 
Running Your Application</a>, depending on your development environment.</p>


<h2 id="ConvertYourApps">Convert Your Applications</h2>

<p>If you want to fully utilize new APIs introduced with the Android 1.6 Early Look SDK,
then you'll need to convert your application to compile against the new "Donut" platform.</p>

<p>First, you need to change the value of the <code>minSdkVersion</code> attribute in
the <code>&lt;uses-sdk></code> manifest element. While
running your application against the Donut platform included with the Early Look SDK, you
<strong>must</strong> set the <code>minSdkVersion</code> value to "Donut". For example:</p>

<pre>
&lt;manifest>
  ...
  &lt;uses-sdk android:minSdkVersion="Donut" />
  ...
&lt;/manifest>
</pre>

<p>This value is required only while compiling against the Donut platform included with
the Android 1.6 Early Look SDK. Once the final SDK is made
available for Android 1.6, you will need to change this value.
For more information, read about the <a href="index.html#provisional">Framework API and
Provisional API Level</a>.</p>

<p>Once you've changed the <code>minSdkVersion</code> value in your application's manifest, 
continue with the procedures below to convert your applications.</p>

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

<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 Donut (Preview)" to target the new
	    platform (or "Google APIs" with the "Donut" platform if your application uses the Maps APIs).</li>
	<li>Click <strong>Apply</strong>, then <strong>OK</strong>.</li>
</ol>
	
	<p>Remember that you must create an AVD that targets the same platform in order to run the emulator.
  Continue with the
	<a href="{@docRoot}guide/developing/eclipse-adt.html#Running">Eclipse guide to
	Running Your Application</a>. During the procedure to Running Your Application, select a "deployment
  target" or the AVD that includes the "Donut" platform. If your application utilizes the Google Maps APIs (i.e.,
	MapView), be certain to select a target that includes the Google APIs.</p>
	
	
<h3 id="AntUsers">Ant users</h3>
	
	<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 "Donut" 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>Remember that you must create an Android Virtual Device (AVD) that's targeted to the
	same platform before you can run the updated application an instance
	of the emulator. Please continue with the
	<a href="{@docRoot}guide/developing/other-ide.html#Running">Ant guide to
	Running Your Application</a>. During the procedure to Running Your Application, select a "deployment
  target" for the AVD that includes the "Donut" platform.
	If your application utilizes the Google Maps APIs (i.e.,
	MapView), be certain to select a target that includes the Google APIs.</p>


<div class="special">
<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>
</div>