diff options
Diffstat (limited to 'docs/html/sdk/1.6_r1/upgrading.jd')
| -rw-r--r-- | docs/html/sdk/1.6_r1/upgrading.jd | 386 |
1 files changed, 386 insertions, 0 deletions
diff --git a/docs/html/sdk/1.6_r1/upgrading.jd b/docs/html/sdk/1.6_r1/upgrading.jd new file mode 100644 index 0000000..2f9cc73 --- /dev/null +++ b/docs/html/sdk/1.6_r1/upgrading.jd @@ -0,0 +1,386 @@ +page.title=Upgrading the SDK +sdk.version=1.6 +sdk.preview=0 +@jd:body + + +<div id="qv-wrapper"> +<div id="qv"> + + <h2>Upgrading the SDK</h2> + <ul> + <li>If you are developing on the Android 1.5 SDK, migrating your +applications is straightforward and typically requires no modifications.</li> + <li>For Eclipse users, a new version of ADT is available. To use the Android +1.6 SDK, please upgrade to ADT 0.9.3 (or later).</li> + <li>For Windows users, the SDK includes a new USB driver that you can +install, if you are developing on a device. </li> + <li>A new Android SDK and AVD Manager tool is available. To access +it, run the <code>android</code> tool without options. </li> + </ul> + + <h2>In this document</h2> + <ol> + <li><a href="#Install">Install the SDK</a></li> + <li><a href="#UpdateAdt">Update Your Eclipse ADT Plugin</a></li> + <li><a href="#RunYourApps">Run Your Applications</a></li> + <li><a href="#MigrateYourApps">Migrate Your Applications</a></li> + </ol> + + <h2>Migrating information</h2> + <ol> + <li><a href="{@docRoot}sdk/api_diff/4/changes.html">Android 1.6 API +Differences</a></li> + </ol> + +</div> +</div> + +<p>This document describes how to move your development environment and existing +Android applications from an Android 1.5 SDK to the Android 1.6 SDK. If you are +migrating applications from an SDK older than 1.5, please also read the +upgrading document available in the Android 1.5 SDK package.</p> + +<p>There are several compelling reasons to upgrade, such as new SDK tools that +make developing more efficient and new APIs that allow you to expand the +feature-set of your applications. However, even if you or your applications +don't require these enhancements, it's important that you upgrade to ensure that +your applications run properly on the upcoming Android platform.</p> + +<p>The Android 1.6 platform will soon be deployable to devices around the world. +If you have already released Android applications to the public, you should test +the forward-compatibility of your applications on the latest version of the +platform as soon as possible. It's unlikely that you'll encounter problems in +your applications, but in the interest of maintaining the best user experience, +you should take no risks. So, please install the new Android SDK and test your +applications on the new platform.</p> + +<!-- NOT AVAILABLE FOR PREVIEW RELEASES --> +<p>For more information on new SDK features and system changes, +see the <a href="{@docRoot}sdk/android-1.6.html">Android 1.6 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 it from +here</a> and unpack it into a safe location.</p> + +<p>If you had previously setup your <code>PATH</code> variable to point to the SDK +tools directory, then you need to update it to point to the new SDK. For example, for +a <code>.bashrc</code> or <code>.bash_profile</code> file:</p> +<pre>export PATH=$PATH:<em><your_sdk_dir></em>/tools</pre> + + +<h2 id="UpdateAdt">Update Your Eclipse ADT Plugin</h2> + +<p>If you don't use the Eclipse IDE for development, +skip to <a href="#RunYourApps">Run Your Applications</a>.</p> + +<p>A new version of the ADT Plugin, ADT 0.9.3, is available in conjunction with +this SDK release. To use the SDK, you must upgrade your ADT Plugin to version +0.9.3. With ADT 0.9.3, you can still compile your existing applications against +multiple platform versions, such as Android 1.5, Android 1.1, and so on. However, +ADT 0.9.3 is not compatible with previous versions of the SDK and its tools, so +make sure that you upgrade both your SDK <em>and</em> the ADT Plugin.</p> + +The upgrade steps for ADT are described below. For information about new features in ADT, see the <a +href="{@docRoot}sdk/RELEASENOTES.html">Release Notes</a> document. </p> + +<p>If you're currently using a version of ADT <em>older</em> than version 0.9, +then you must uninstall ADT before you proceed (read how to <a +href="{@docRoot}sdk/1.5_r3/upgrading.html#uninstallAdt">Uninstall your previous +ADT plugin</a>). If you currently have version 0.9 or 0.9.1, then you don't need +to uninstall and can continue with the procedure below.</p> + +<table style="font-size:100%"> +<tr><th>Eclipse 3.4 (Ganymede)</th><th>Eclipse 3.5 (Galileo)</th></tr> +<tr> +<td width="50%"> +<!-- 3.4 steps --> +<ol> + <li>Select <strong>Help</strong> > <strong>Software Updates</strong>.</li> + <li>Select the <strong>Available Software</strong> tab.</li> + <li>Select the checkboxes next to Android DDMS and Android Developer Tools, + then click <strong>Update</strong>.</li> + <li>In the resulting Available Updates dialog, ensure that both Android DDMS + and Android Development Tools are selected, then click + <strong>Next</strong>.</li> + <li>Read and accept the license agreement and then click <strong>Finish</strong>. + This will download and install the latest version of Android DDMS and + Android Development Tools.</li> + <li>Restart Eclipse.</li> +</ol> +</td> +<td> +<!-- 3.5 steps --> +<ol> + <li>Select <strong>Help</strong> > <strong>Check for Updates</strong>. </li> + <li>In the resulting Available Updates dialog, locate the Android DDMS and + Android Development Tools features in the list and ensure that the checkboxes + next to them are selected. Click <strong>Next</strong>. + <p>If the Available Updates dialog does not list Android DDMS and Android + Development tools, make sure that you have set up a remote update site + for them, as described in + <a href="installing.html#InstallingADT">Installing the ADT Plugin</a>. + </p></li> + <li>In the Update Details dialog, click <strong>Next</strong>.</li> + <li>Read and accept the license agreement and then click <strong>Finish</strong>. + This will download and install the latest version of Android DDMS and + Android Development Tools.</li> + <li>Restart Eclipse.</li> +</ol> +</td> +</tr> +</table> + +<p>If you encounter problems with this update procedure, try performing a fresh +installation. Fully remove your existing ADT Plugin as described in <a +href="{@docRoot}sdk/1.5_r3/upgrading.html#uninstallAdt">Uninstall your previous +ADT plugin</a> and then follow the guide to <a +href="installing.html#InstallingADT">Installing the ADT Plugin for +Eclipse</a>.</p> + +<h3 id="updateEclipsePrefs">Update your Eclipse SDK Preferences</h3> + +<p>The last step is to update your Eclipse preferences to point to the new +SDK directory:</p> +<ol> + <li>Select <strong>Window</strong> > <strong>Preferences</strong> to open + the Preferences panel (Mac: <strong>Eclipse</strong> > <strong>Preferences + </strong>).</li> + <li>Select <strong>Android</strong> from the left panel.</li> + <li>For the SDK Location, click <strong>Browse</strong> + and locate your SDK directory.</li> + <li>Click <strong>Apply</strong>, then <strong>OK</strong>.</li> +</ol> + + +<h2 id="RunYourApps">Run Your Applications to Test Forward Compatibility</h2> + +<p>Now that you have installed the Android 1.6 SDK, we encourage you run each of +your existing applications on the Android 1.6 system image that is included in +the SDK, to ensure that it functions properly on the new platform. +Testing forward-compatibility in this way is especially important for +applications that you may have already published and that may be installed on +devices that will upgrade to the new platform. </p> + +<p>In most cases, your applications will function properly when run on the new +version of the platform. However, it is possible that you will encounter +unexpected behavior, because of changes in the API or underlying platform. If +you do find problems, you can use the SDK tools to compile and publish an update +to the applications, which users can then download. + +<p>To test forward-compatibility, simply run your application, as-is, on an +instance of the Android Emulator that uses an AVD targeted to the "Android 1.6" +system image. Here are the steps: </p> + +<ol> + <li>Make no changes to your application code.</li> + <li>Create a new AVD that runs the new "Android 1.6" platform. </li> + <li>Launch your application in an emulator running the new AVD.</li> + <li>Perform normal testing on your application to ensure everything works as + expected.</li> +</ol> + +<p>Note that, for the purposes of forward-compatibility testing, you should not +change how your application is compiled. That is, you should continue to compile +the application against the same version of the Android library as before. The +only change needed is to the AVD, which controls the version of the Android +system image (run-time environment) on which the application is run. + +<p>For more information on creating an AVD and launching your application, see +<a href="{@docRoot}guide/developing/eclipse-adt.html#Running">Running Your +Applications (Eclipse)</a> or <a +href="{@docRoot}guide/developing/other-ide.html#Running">Running +Your Applications (other IDEs)</a>, depending on your development +environment.</p> + +<h3 id="FutureProofYourApps">Android 1.6 Forward-Compatibility Tips</h3> + +<p>The new version of the Android platform includes several new APIs, but +very few actual changes to existing APIs. This means that, in most +cases, your applications written with earlier versions of the Android library +should run properly on the Android 1.6 platform. </p> + +<p>However, here are some areas to pay attention to as you test forward-compatibility:</p> + +<ul> + <li><strong>Make sure your application doesn't use internal APIs</strong>. Your +application should not use any APIs that are not officially supported and are +not published in the Android reference documentation. Unofficial APIs can change +at any time without notice and — if your application happens to be using +them — such a change could cause the application to break.</li> + + <li><strong>Watch for assumptions about available hardware</strong>. Remember +that not all compatible devices offer the same hardware capabilities — +screens, keyboards, and physical keys, and so on. As you test your application, +watch for areas where your application depends on the presence of specific +hardware capabilities. If you find dependencies, you can design around them by +building in alternate support or graceful degradation, or you can specify them +as hardware requirements in a +<a href="{@docRoot}guide/topics/manifest/uses-configuration-element.html"><code><uses-configuration></code>.</a> +element in the application's manifest file. Also see the <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><code><uses-feature></code> +manifest element, which lets your application declare a requirement for +specific features, such as an OpenGL ES version or a camera that has +autofocus capability. +</li> + + <li><strong>Watch for assumptions about available features</strong>. Not all +compatible devices offer equal support for embedded features. same hardware capabilities — +screens, keyboards, and physical keys, and so on. As you test your application, +watch for areas where your application depends on the presence of specific +hardware capabilities. If you find dependencies, you can design around them by +building in alternate support or graceful degradation, or you can specify them +as hardware requirements in a +<a href="{@docRoot}guide/topics/manifest/uses-configuration-element.html"><code><uses-configuration></code>.</a> +element in the application's manifest file. </li> + + <p>When testing forward-compatibility, try running your application in various +AVDs that emulate different hardware configurations. For example, you can create +an AVD that does not offer a physical keyboard or one that uses a dpad instead +of a trackball. Running your application in different emulated hardware +configurations will give you an idea of where its dependencies are and help you +identify problems. </p> + </li> + + <li><strong>Watch for assumptions about screen resolution and +density</strong>. A device's screen resolution and density is likely to affect +the way that your application's UI is rendered, especially if your app specifies +dimensions or positions using pixels or absolute layouts. To ensure consistent +UI across screens, your app should specify the dimensions and positions of +layouts and drawables in relative units that can be scaled by the system as +appropriate, according to the density of the device's screen. Alternatively, you +can create custom sets of layout/drawable resources for specific screens, which +the system can then load as appropriate, based on the current device screen.</p> + + <p>When testing forward-compatibility, try running your application in various +AVDs that emulate different screen resolutions and densities. Also note that, +starting with Android 1.6, the platform provides a Compatibility Mode that +automatically scales the UI of applications if they do not explicitly indicate +support for the current screen in the +<a href="{@docRoot}guide/topics/manifest/supports-screen-element.html"><code><supports-screen></code> +element in their manifest files. As part of testing, you should evaluate how +your application is displayed in Compatibility Mode on different screens. </p> + </li> + + <li><strong>Avoid performing layout orientation changes based on the +acceletometer (or via other sensors)</strong>. Some Android-powered devices 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> + +<h2 id="MigrateYourApps">Migrate Your Applications</h2> + +<p>If you want to use any of the new Android 1.6 APIs in your existing +applications, you must first migrate the applications to the new Android +platform version. Generally, migrating an application includes: </p> + +<ul> +<li>Referencing the proper API Level in the application's manifest file, +and</li> +<li>Resetting its project properties so that it is compiled against the Android +1.6 build target.</li> +</ul> + +<p>Additionally, to run your application in the emulator, you need to +create an AVD that uses the Android 1.6 system image. </p> + +<p class="note"><strong>Note:</strong> You only need migrate your application as +described in this section if the application will actually use APIs +<em>introduced</em> in the Android 1.6 platform (which are not available on +devices running older versions of the Android platform). If your application +does not use any new APIs, you can compile and run it without modification and +not migration is necessary.</p> + +<h3>Reference the Proper API Level</h3> + +<p>If your application is using APIs introduced in Android 1.6, you must +reference that dependency in the application's manifest file so that it can be +deployed to devices running the Android 1.6 platform. </p> + +<p>Open the manifest file and locate the <code>minSdkVersion</code> attribute +in the <code><uses-sdk></code> manifest element. Set the value of +<code>minSdkVersion</code> to <code>"4"</code> (the API Level +identifier corresponding to Android 1.6). Here's an example:</p> + +<pre> +<manifest> + ... + <uses-sdk android:minSdkVersion="4" /> + ... +</manifest> +</pre> + +<h3>Compile Against the Proper Build Target</h3> + +<p>Once you've changed the <code>minSdkVersion</code> value in your +application's manifest, you need to set the application's project properties so +that the application will be compiled against the Android 1.6 library. To do so, +follow the steps below for your respective development environment. </p> + +<h4 id="EclipseUsers">Eclipse Users</h4> + +<ol> + <li>Right-click on the individual project (in the Package Explorer) + and select <strong>Properties</strong>.</li> + <li>In the properties, open the Android panel and select a new Project Build Target. + Select "Android 1.6" to target the new platform (or "Google APIs" with the "4" + API Level, if your application uses the Google Maps APIs).</li> + <li>Click <strong>Apply</strong>, then <strong>OK</strong>.</li> +</ol> + +<h4 id="AntUsers">Ant Users</h4> + +<p>Use the <code>android</code> tool (located in +<code><em>your_sdk</em>/tools/</code>) to create a new <code>build.xml</code> +that references the new platform target. To see a list of available targets, +execute:</p> + +<pre>android list targets</pre> + +<p>Select the target <code>id</code> that corresponds to the "Android 1.6" platform +and pass it with the <code>--target</code> parameter when updating your project. +For example:</p> + +<pre>android update project --path /path/to/my-project --target 2</pre> + +<p>If your application uses the Google Maps APIs (i.e., MapView), be certain to +select a Google APIs target.</p> + +<h3>Create an AVD that Uses the Android 1.6 Platform</h3> + +<p>Finally, you need to set up a new AVD that uses the Android 1.6 platform, so that +you can run your application in the emulator. + +<p>To set up the new AVD, use the <code>android</code> tool, available in the +<code>tools/</code> directory of the SDK. You can run the AVD manager by simply +changing to the <code>tools/</code> directory and entering <code>android</code> +at the command line. Click "New" to create the AVD and set its properties.</p> + +<p>When creating the AVD, make sure to select a target of "Android 1.6 - API +Level 4". If your application uses the Google Maps APIs (MapView), select the +target "Google APIs (Google Inc.) - API Level 4". </p> + +<p>For more information about running your application in an AVD, see <a +href="{@docRoot}guide/developing/eclipse-adt.html#Running">Running Your +Application (Eclipse)</a> or <a +href="{@docRoot}guide/developing/other-ide.html#Running">Running Your +Application (other IDEs)</a>. </p> + +<p>For general information about AVDs, see the <a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual +Devices</a> document. </p> + + + +<div class="special"> +<p>If you have trouble migrating to the new version of the SDK, visit the +<a href="http://groups.google.com/group/android-developers">Android Developers Group</a> +to seek help from other Android developers.</p> +</div> + |