AI 147328: am: CL 147327 am: CL 147325 update the installing and upgrading docs for cupcake
Original author: smain
Merged from: //branches/cupcake/...
Original author: android-build
Automated import of CL 147328
diff --git a/docs/html/sdk/1.5_r1/installing.jd b/docs/html/sdk/1.5_r1/installing.jd
index a1f7cff..bd366ff 100644
--- a/docs/html/sdk/1.5_r1/installing.jd
+++ b/docs/html/sdk/1.5_r1/installing.jd
@@ -5,6 +5,328 @@
page.title=Installing the Android SDK
@jd:body
-<p>See the <a href="{@docRoot}sdk/preview/index.html">Download page</a> for more information.</p>
+
+<p>This page describes how to install the Android SDK and set up your
+development environment. If you haven't downloaded the SDK, you can
+do so from the
+<a href="{@docRoot}sdk/1.5_r1/index.html">Download</a> page. Once you've downloaded
+the SDK, return here.</p>
+
+<p>If you encounter any problems during installation, see the
+<a href="#installnotes">Installation Notes</a> at the bottom of
+this page.</p>
+
+<h4 style="margin-top">Upgrading?</h4>
+<p>If you have already developed applications using an earlier version
+of the SDK, please read
+<a href="{@docRoot}sdk/1.5_r1/upgrading.html"><strong>Upgrading the
+SDK</strong></a></b>, instead.
+</p>
+
+
+<h2 id="setup">Preparing for Installation</h2>
+
+<p>Before you begin, take a moment to confirm that your development machine meets the
+<a href="{@docRoot}sdk/1.5_r1/requirements.html">System Requirements</a>.
+</p>
+
+<p>If you will be developing on Eclipse with the Android Development
+Tools (ADT) Plugin — the recommended path if you are new to
+Android — make sure that you have a suitable version of Eclipse
+installed on your computer (3.3 or newer). If you need to install Eclipse, you can
+download it from this location: </p>
+
+<p style="margin-left:2em;"><a href=
+"http://www.eclipse.org/downloads/">http://www.eclipse.org/downloads/</a
+></p>
+
+<p>A Java or RCP version of Eclipse is recommended. </p>
+
+<h2 id="installingsdk">Installing the SDK</h2>
+
+<p>After downloading the SDK, unpack the .zip archive to a suitable location on your machine.
+By default, the SDK files are unpacked into a directory named
+<code>android_sdk_<em><platform</em>>_<em><release></em></code>.
+The directory contains a local copy of the documentation (accessible by opening
+<code>documentation.html</code> in your browser) and the subdirectories
+<code>tools/</code>, <code>add-ons/</code>, <code>platforms/</code>, and others. Inside
+each subdirectory of <code>platforms/</code> you'll find <code>samples/</code>, which includes
+code samples that are specific to each version of the platform.</p>
+
+<p>Make a note of the name and location of the unpacked SDK directory on your system — you
+will need to refer to the SDK directory later, when setting up the Android plugin or when
+using the SDK tools.</p>
+
+<p>Optionally, you may want to add the location of the SDK's primary <code>tools</code> directory
+to your system PATH. The primary <code>tools/</code> directory is located at the root of the
+SDK folder. Adding <code>tools</code> to your path lets you run Android Debug Bridge (adb) and
+the other command line <a href="{@docRoot}guide/developing/tools/index.html">tools</a> without
+needing to supply the full path to the tools directory. </p>
+<ul>
+ <li>On Linux, edit your <code>~/.bash_profile</code> or <code>~/.bashrc</code> file. Look
+ for a line that sets the PATH environment variable and add the
+ full path to the <code>tools/</code> directory to it. If you don't
+ see a line setting the path, you can add one:</li>
+
+ <ul><code>export PATH=${PATH}:<em><your_sdk_dir></em>/tools</code></ul>
+
+ <li>On a Mac, look in your home directory for <code>.bash_profile</code> and
+ proceed as for Linux. You can create the <code>.bash_profile</code> if
+ you haven't already set one up on your machine. </li>
+
+ <li>On Windows, right-click on My Computer, and select Properties.
+ Under the Advanced tab, hit the Environment Variables button, and in the
+ dialog that comes up, double-click on Path (under System Variables). Add the full path to the
+ <code>tools/</code> directory to the path. </li>
+ </ul>
+
+<p>Note that, if you update your SDK in the future, you
+should remember to update your PATH settings to point to the new location, if different.</p>
+
+<p>If you will be using the Eclipse IDE as your development environment,
+the next section describes how to install the Android Development Tools plugin and set up Eclipse.
+If you choose not to use Eclipse, you can
+develop Android applications in an IDE of your choice and then compile, debug and deploy using
+the tools included in the SDK (skip to <a href="#next">Next Steps</a>).</p>
+
+
+<h2 id="installingplugin">Installing the ADT Plugin for Eclipse</h2>
+
+<p>Android offers a custom plugin for the Eclipse IDE, called Android
+Development Tools (ADT), that is designed to give you a powerful,
+integrated environment in which to build Android applications. It
+extends the capabilites of Eclipse to let you quickly set up new Android
+projects, create an application UI, add components based on the Android
+Framework API, debug your applications using the Android SDK tools, and even export
+signed (or unsigned) APKs in order to distribute your application.</p>
+
+<p>In general, using Eclipse with ADT is a highly recommended
+approach to Android development and is the fastest way to get started.
+(If you prefer to work in an IDE other than Eclipse,
+you do not need to install Eclipse or ADT, instead, you can directly
+use the SDK tools to build and debug your application.)</p>
+
+<p>Once you have Eclipse installed, as described in <a href="#setup">Preparing for
+Installation</a>, follow the steps below to
+download the ADT plugin and install it in your respective Eclipse
+environment. </p>
+
+<table style="font-size:100%">
+<tr><th>Eclipse 3.3 (Europa)</th><th>Eclipse 3.4 (Ganymede)</th></tr>
+<tr>
+<td width="45%">
+<!-- 3.3 steps -->
+<ol>
+ <li>Start Eclipse, then select <strong>Help</strong> > <strong>Software Updates</strong>
+> <strong>Find and Install...</strong>. </li>
+ <li>In the dialog that appears, select <strong>Search for new features to install</strong>
+and click <strong>Next</strong>. </li>
+ <li>Click <strong>New Remote Site</strong>. </li>
+ <li>In the resulting dialog box, enter a name for the remote site (e.g. "Android Plugin") and
+ enter the URL:
+ <pre>https://dl-ssl.google.com/android/eclipse/</pre>
+ <p>If you have trouble aqcuiring the plugin, try using "http" in the URL,
+ instead of "https" (https is preferred for security reasons).</p>
+ <p>Click <strong>OK</strong>.</p> </li>
+ <li>You should now see the new site added to the search list (and checked).
+ Click <strong>Finish</strong>. </li>
+ <li>In the subsequent Search Results dialog box, select the checkbox for the
+ <strong>Android Plugin</strong>.
+ This will select the nested tools: "Android DDMS" and "Android Developer Tools".
+ Click <strong>Next</strong>.</li>
+ <li>Read and accept the license agreement, then click <strong>Next</strong>. </li>
+ <li>On the following Installation window, click <strong>Finish</strong>. </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>Start Eclipse, then select <strong>Help</strong> > <strong>Software Updates...</strong>.</li>
+ <li>In the dialog that appears, click the <strong>Available Software</strong> tab. </li>
+ <li>Click <strong>Add Site...</strong> </li>
+ <li>Enter the Location:
+ <pre>https://dl-ssl.google.com/android/eclipse/</pre>
+ <p>If you have trouble aqcuiring the plugin, try using "http" in the Location URL,
+ instead of "https" (https is preferred for security reasons).</p>
+ <p>Click <strong>OK</strong>.</p></li>
+ <li>Back in the Available Software view, you should see the plugin listed by the URL,
+ with "Developer Tools" nested within it. Select the checkbox next to
+ Developer Tools and click <strong>Install...</strong></li>
+ <li>On the subsequent Install window, "Android DDMS" and "Android Developer Tools"
+ should both be checked. Click <strong>Next</strong>. </li>
+ <li>Read and accept the license agreement, then click <strong>Finish</strong>.</li>
+ <li>Restart Eclipse. </li>
+</ol>
+
+</td>
+</tr>
+</table>
+
+<p>Now modify your Eclipse preferences to point to the Android 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 downloaded SDK directory. </li>
+ <li>Click <strong>Apply</strong>, then <strong>OK</strong>.</li>
+</ol>
+
+<p>Done! If you haven't encountered any problems, then you're ready to
+begin developing Android applications. See the
+<a href="#next">Next Steps</a> section for suggestions on how to start. </p>
+
+
+<h3 id="troubleshooting">Troubleshooting ADT Installation</h3>
+<p>
+If you are having trouble downloading the ADT plugin after following the steps above, here are
+some suggestions: </p>
+
+<ul>
+ <li>If Eclipse can not find the remote update site containing the ADT plugin, try changing
+ the remote site URL to use http, rather than https. That is, set the Location for the remote site to:
+ <pre>http://dl-ssl.google.com/android/eclipse/</pre></li>
+ <li>If you are behind a firewall (such as a corporate firewall), make
+ sure that you have properly configured your proxy settings in Eclipse.
+ In Eclipse 3.3/3.4, you can configure proxy information from the main
+ Eclipse menu in <strong>Window</strong> (on Mac, <strong>Eclipse</strong>) >
+ <strong>Preferences</strong> > <strong>General</strong> >
+ <strong>Network Connections</strong>.</li>
+</ul>
+<p>
+If you are still unable to use Eclipse to download the ADT plugin as a remote update site, you
+can download the ADT zip file to your local machine and manually install the it:
+</p>
+<ol>
+ <li><a href="{@docRoot}sdk/adt_download.html">Download the ADT zip file</a> (do not unpack it).</li>
+ <li>Follow steps 1 and 2 in the default install instructions (above).</li>
+ <li>In Eclipse 3.3, click <strong>New Archive Site...</strong>. <br/>
+ In Eclipse 3.4, click <strong>Add Site...</strong>, then <strong>Archive...</strong></li>
+ <li>Browse and select the downloaded zip file.</li>
+ <li>Follow the remaining procedures, above, starting from steps 5.</li>
+</ol>
+<p>To update your plugin once you've installed using the zip file, you will have to
+follow these steps again instead of the default update instructions.</p>
+
+<h4>Other install errors</h4>
+
+<p>Note that there are features of ADT that require some optional
+Eclipse components (for example, WST). If you encounter an error when
+installing ADT, your Eclipse installion might not include these components.
+For information about how to quickly add the necessary components to your
+Eclipse installation, see the troubleshooting topic
+<a href="{@docRoot}guide/appendix/faq/troubleshooting.html#installeclipsecomponents">ADT
+Installation Error: "requires plug-in org.eclipse.wst.sse.ui"</a>.</p>
+
+<h4>For Linux users</h4>
+<p>If you encounter this error when installing the ADT Plugin for Eclipse:
+<pre>
+An error occurred during provisioning.
+Cannot connect to keystore.
+JKS</pre>
+<p>
+...then your development machine lacks a suitable Java VM. Installing Sun
+Java 6 will resolve this issue and you can then reinstall the ADT
+Plugin.</p>
+
+
+<h2 id="next">Next Steps</h2>
+<p>Once you have completed installation, you are ready to
+begin developing applications. Here are a few ways you can get started: </p>
+
+<p><strong>Learn about Android</strong></p>
+<ul>
+ <li>Take a look at the <a href="{@docRoot}guide/index.html">Dev
+ Guide</a> and the types of information it provides</li>
+ <li>Read an introduction to Android as a platform in <a
+ href="{@docRoot}guide/basics/what-is-android.html">What is
+ Android?</a></li>
+ <li>Learn about the Android framework and how applications run on it in
+ <a href="{@docRoot}guide/topics/fundamentals.html">Application
+ Fundamentals</a></li>
+ <li>Take a look at the Android framework API specification in the <a
+ href="{@docRoot}reference/index.html">Reference</a> tab</li>
+</ul>
+
+<p><strong>Explore the SDK</strong></p>
+<ul>
+ <li>Get an overview of the <a
+ href="{@docRoot}guide/developming/tools/index.html">development
+ tools</a> that are available to you</li>
+ <li>Read how to develop <a
+ href="{@docRoot}guide/developing/eclipse-adt.html">in Eclipse/ADT</a> or
+ <a href="{@docRoot}guide/developing/other-ide.html">in other IDEs</a>
+ </li>
+</ul>
+
+<p><strong>Explore some code</strong></p>
+<ul>
+ <li>Set up a <a href="{@docRoot}guide/tutorials/hello-world.html">Hello
+ World application</a> (highly recommended, especially for Eclipse users)</li>
+ <li>Follow the <a href="{@docRoot}guide/tutorials/notepad/index.html">
+ Notepad Tutorial</a> to build a full Android application </li>
+ <li>Create a new project for one of the other sample applications
+ included in <code><em><sdk></em>/platforms/<em><platfrom></em>/samples</code>,
+ then compile and run it in your development environment</li>
+</ul>
+
+<p><strong>Visit the Android developer groups</strong></p>
+<ul>
+ <li>Take a look at the <a
+ href="{@docRoot}community/index.html">Community</a> tab to see a list of
+ Android developers groups. In particular, you might want to look at the
+ <a href="http://groups.google.com/group/android-developers">Android
+ Developers</a> group to get a sense for what the Android developer
+ community is like.</li>
+</ul>
+
+
+<h2 id="installnotes">Installation Notes</h2>
+
+<h3>Ubuntu Linux Notes</h3>
+
+<ul>
+ <li>If you need help installing and configuring Java on your
+ development machine, you might find these resources helpful:
+ <ul>
+ <li><a href="https://help.ubuntu.com/community/Java">https://help.ubuntu.com/community/Java </a></li>
+ <li><a href="https://help.ubuntu.com/community/Java">https://help.ubuntu.com/community/JavaInstallation</a></li>
+ </ul>
+ </li>
+ <li>Here are the steps to install Java and Eclipse, prior to installing
+ the Android SDK and ADT Plugin.
+ <ol>
+ <li>If you are running a 64-bit distribution on your development
+ machine, you need to install the <code>ia32-libs</code> package using
+ <code>apt-get:</code>:
+ <pre>apt-get install ia32-libs</pre>
+ </li>
+ <li>Next, install Java: <pre>apt-get install sun-java6-bin</pre></li>
+ <li>The Ubuntu package manager does not currently offer an Eclipse 3.3
+ version for download, so we recommend that you download Eclipse from
+ eclipse.org (<a
+ href="http://www.eclipse.org/downloads/">http://www.eclipse.org/
+ downloads/</a>). A Java or RCP version of Eclipse is recommended.</li>
+ <li>Follow the steps given in previous sections to install the SDK
+ and the ADT plugin. </li>
+ </ol>
+ </li>
+</ul>
+
+<h3>Other Linux Notes</h3>
+
+<ul>
+ <li>If JDK is already installed on your development computer, please
+ take a moment to make sure that it meets the version requirements listed
+ in the <a href="{@docRoot}sdk/1.1_r1/requirements.html">System Requirements</a>.
+ In particular, note that some Linux distributions may include JDK 1.4 or Gnu
+ Compiler for Java, both of which are not supported for Android development.</li>
+</ul>
+
diff --git a/docs/html/sdk/1.5_r1/upgrading.jd b/docs/html/sdk/1.5_r1/upgrading.jd
index 5323131..0b7312b 100644
--- a/docs/html/sdk/1.5_r1/upgrading.jd
+++ b/docs/html/sdk/1.5_r1/upgrading.jd
@@ -2,175 +2,351 @@
sdk.version=1.5_r1
@jd:body
-<!--
-<div class="sidebox-wrapper">
- <div class="sidebox-inner">
- <h2>Useful Links</h2>
+<div id="qv-wrapper">
+<div id="qv">
- <ul class="noindent">
- <li><a href="migrating/0.9-1.0/changes-overview.html">Overview of Changes</a>
- <p>A high-level look at what's changed in Android, with
- discussion of how the changes may affect your apps.</p></li>
+ <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>
- <li><a href="migrating/0.9-1.0/changes.html">API Diff Report</a>
- <p>A detailed report that lists all the specific changes in the latest SDK.</p></li>
+ <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></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="">TODO: LINK TO DAN'S POST »</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>
- <li><a href="RELEASENOTES.html">Release Notes</a>
- <p>Version details, known issues, and resolved issues. </p></li>
-
- <li><a href="http://groups.google.com/group/android-developers">Android Developers Group</a>
- <p>A forum where you can discuss migration issues and learn from other Android developers. </p></li>
-
- <li><a href="http://code.google.com/p/android/issues/list">Android Issue Tracker</a>
- <p>If you think you may have found a bug, use the issue tracker to report it.</p></li>
- </ul>
-
- </div>
-</div>
--->
-
-
- <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>Related Information</h2>
-<ol>
-<li><a href="{@docRoot}sdk/api_diff/3/changes.html">Android 1.5 API Differences</a></li>
-</ol>
--->
</div>
</div>
-<p>See the <a href="{@docRoot}sdk/preview/index.html">Download page</a> for more information.</p>
+<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>This document describes how to move your development environment and existing
-Android applications from an Android 1.1 or 1.0 SDK to the Android 1.5 SDK.
-If you are migrating applications from an earlier SDK, please 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>To ensure that your existing applications run properly with the Android 1.5 system available
-on mobile devices, you need to install the Android 1.5 SDK and port your existing Android
-applications to it. The sections below will guide you through the process.</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>
-</ul>
+<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-new">Installing the SDK</h2>
-<p><a href="{@docRoot}sdk/1.5_r1/index.html">Download the SDK</a> and unpack it into a safe location.</p>
+<h2 id="Install">Install the SDK</h2>
-<p>After unpacking the new SDK and saving it an appropriate location, you should:</p>
+<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>
-<ul>
- <li>Wipe your emulator data. <p>Some data formats have changed since the last
- SDK release, so any previously saved data in your emulator must be removed. Open a console/terminal
- and navigate to the <code>/tools</code> directory of your new SDK. Launch the
- emulator with the <code>-wipe-data</code> option.
- <p>Windows: <code>emulator -wipe-data</code><br/>
- Mac/Linux: <code>./emulator -wipe-data</code></p>
- </li>
- <li>Update your PATH variable (Mac/Linux; optional). <p>If you had previously setup your
- PATH variable to point to the SDK tools directory, then you'll need to update it to
- point to the new SDK. For example, for a <code>.bashrc</code> or <code>.bash_profile</code> file:
- <code>export PATH=$PATH:<em><your_new_sdk_dir></em>/tools</code></p>
- </li>
- <li>If (and only if) you are developing using Ant, you will also need to modify
- your build.xml properties to point to the new SDK.
- <p>Open the <code>default.properties</code> file associated with your build.xml
- file (typically located in the same directory). In the default.properties
- file, update the <code>sdk-folder</code> property with the full path to
- the new SDK directory.</p></li>
-</ul>
+<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>
-<a name="Updating_the_ADT_plugin" id="Updating_the_ADT_plugin"></a>
-<h2 id="update-plugin">Update your ADT Eclipse Plugin</h2>
+<p>If you don't use Eclipse for development,
+skip to <a href="#updateYourProjects">Update Your Projects</a>.</p>
-<p>If you develop on Eclipse and are migrating from an Android 1.0
-SDK, no update of the ADT plugin is needed — skip to <a href="#updateEclipsePrefs">Update your Eclipse SDK Preferences</a>. </p>
-<p>If you are migrating from an earlier version of the SDK, you will
-need to update the ADT plugin. <p>You may also want to upgrade your
-ADT plugin when a new version becomes available for your existing version
-of the SDK.</p>
+<h2 id="UpdateAdt">Update Your Eclipse ADT Plugin</h2>
-<p>The steps below describe how to update the ADT plugin to the latest
-version available. </p>
+<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>Find and Install...</strong>. </li>
- <li> Select <strong>Search for updates of the currently installed features</strong> and click <strong>Finish</strong>. </li>
- <li> If any update for ADT is available, select and install. </li>
- <li> Restart Eclipse.</li>
-</ol>
-<p> Alternatively, </p>
-<ol>
- <li> Select <strong>Help</strong> > <strong>Software Updates</strong> > <strong>Manage Configuration</strong>. </li>
-
- <li> Navigate down the tree and select <strong>Android Development Tools <version></strong> </li>
- <li> Select <strong>Scan for Updates</strong> under <strong>Available Tasks</strong>.</li>
+ <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 <strong>Help</strong> > <strong>Software Updates</strong>.</li>
<li>Select the <strong>Installed Software</strong> tab.</li>
- <li>Click <strong>Update...</strong></li>
- <li>If an update for ADT is available, select it and click <strong>Finish</strong>.</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, be sure that "Developer Tools" is checked, then click <strong>Next</strong>.</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>On the next window, "Android DDMS" and "Android Developer Tools"
+ should both be checked. Click <strong>Next</strong>.</li>
+ <li>Read and accept the license agreement, then click <strong>Finish</strong>.</li>
<li>Restart Eclipse.</li>
</ol>
</td>
</tr>
</table>
-<h2 id="updateEclipsePrefs">Update your Eclipse SDK Preferences</h2>
+<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 OSX: <strong>Eclipse</strong> > <strong>Preferences</strong>)</li>
+ <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 in the main panel, click <strong>Browse...</strong> and locate the SDK directory.</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="migrate">Migrate Your Applications, if Necessary</h2>
-<p>If (and only if) you have written apps in an SDK released previous to
-the Android 1.0 SDK, you will need to migrate your applications. After
-installing the new SDK and updating the ADT Plugin (if applicable), you
-may encounter breakages in your application code, due to
-framework and API changes. You'll need to update your code to match the
-latest APIs.</p>
+<h2 id="UpdateYourProjects">Update Your Projects</h2>
-<p>One way to start is to open your project in Eclipse and see where the ADT
-identifies errors in your application. You can also look up
-specific changes in the Android APIs in the
-android-1.5.html#api-changes
-Android 1.5 Version Notes
+<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>
-document.</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>
+
+<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.
+Your application will be at highest risk of breakage if it uses Android APIs
+that are not available in the public API documentation
+or if it explicitly depends on system bugs. For information
+about 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="">TODO: LINK TO DAN'S POST ON FORWARD COMPATIBILITY »</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>
-
-<p>If you have modified one of the ApiDemos applications and would like to migrate it
-to the new SDK, note that you will need to uninstall the version of ApiDemos that comes
-preinstalled in the emulator. For more information, or if you encounter an "reinstallation"
-error when running or installing ApiDemos, see the troubleshooting topic
-<a href="{@docRoot}guide/appendix/faq/troubleshooting.html#apidemosreinstall">I can't install ApiDemos
-apps in my IDE because of a signing error</a> for information about how to solve the problem.</p>
--->
\ No newline at end of file
