AI 147325: update the installing and upgrading docs for cupcake

  BUG=1793249

Automated import of CL 147325

2 files changed, 618 insertions, 120 deletions

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 @@ sdk.date=April 2009
 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 &mdash; the recommended path if you are new to
+Android &mdash; 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>&lt;platform</em>&gt;_<em>&lt;release&gt;</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 &mdash; 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>&lt;your_sdk_dir&gt;</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> &gt; <strong>Software Updates</strong> 
+&gt; <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> &gt; <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> &gt; <strong>Preferences...</strong> to open the Preferences
+        panel (Mac: <strong>Eclipse</strong> &gt; <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>) &gt; 
+  <strong>Preferences</strong> &gt; <strong>General</strong> &gt; 
+  <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>&lt;sdk&gt;</em>/platforms/<em>&lt;platfrom&gt;</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 @@ page.title=Upgrading the SDK
 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">
+
+  <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></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 &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>
 
-      <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>
-
-        <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>
-
-        <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>
 
+<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>
 
-    <div id="qv-wrapper">
-    <div id="qv">
+<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>
 
-<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>
+<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>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>
+<h2 id="Install">Install the SDK</h2>
 
-<!-- <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>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>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><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>
 
-</ul>
+<p>If you don't use Eclipse for development,
+skip to <a href="#updateYourProjects">Update Your Projects</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="UpdateAdt">Update Your Eclipse ADT Plugin</h2>
 
-<p>After unpacking the new SDK and saving it an appropriate location, you should:</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>
 
-<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>&lt;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>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>
 
-<a name="Updating_the_ADT_plugin" id="Updating_the_ADT_plugin"></a>
-<h2 id="update-plugin">Update your ADT Eclipse Plugin</h2>
+<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>If you develop on Eclipse and are migrating from an Android 1.0
-SDK, no update of the ADT plugin is needed &mdash; skip to <a href="#updateEclipsePrefs">Update your Eclipse SDK Preferences</a>. </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>
 
-<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>
+<h3 id="uninstallAdt">Uninstall your previous ADT plugin</h3>
 
-<p>The steps below describe how to update the ADT plugin to the latest
-version available. </p>
+<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>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>
+    <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>
-<p> Alternatively, </p>
+</td>
+<td>
+<!-- 3.4 steps -->
 <ol>
-    <li> Select <strong>Help</strong> &gt; <strong>Software Updates</strong> &gt; <strong>Manage Configuration</strong>. </li>
+    <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>
 
-    <li> Navigate down the tree and select <strong>Android Development Tools &lt;version&gt;</strong> </li>
-    <li> Select <strong>Scan for Updates</strong> under <strong>Available Tasks</strong>.</li>
+<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, 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> &gt; <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 <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>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>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>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>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>
 
-document.</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>
+
+<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 &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>
+</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