398 lines
19 KiB
Plaintext
398 lines
19 KiB
Plaintext
page.title=Upgrading the SDK
|
|
sdk.version=1.5
|
|
sdk.rel.id=3
|
|
|
|
@jd:body
|
|
|
|
|
|
<div id="qv-wrapper">
|
|
<div id="qv">
|
|
|
|
<h2>Upgrading the SDK</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="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="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 Android 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="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 parcelable 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 accelerometer (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>
|