From 757714fd1568bea785af5738a499c968d994c3ba Mon Sep 17 00:00:00 2001 From: Scott Main <> Date: Wed, 22 Apr 2009 13:33:18 -0700 Subject: [PATCH] AI 147327: am: CL 147325 update the installing and upgrading docs for cupcake Original author: smain Merged from: //branches/cupcake/... Automated import of CL 147327 --- docs/html/sdk/1.5_r1/installing.jd | 324 ++++++++++++++++++++++++++++- docs/html/sdk/1.5_r1/upgrading.jd | 414 ++++++++++++++++++++++++++----------- 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 a1f7cffb0576..bd366ff1add9 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 -
See the Download page for more information.
+ +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 +Download page. Once you've downloaded +the SDK, return here.
+ +If you encounter any problems during installation, see the +Installation Notes at the bottom of +this page.
+ +If you have already developed applications using an earlier version +of the SDK, please read +Upgrading the +SDK, instead. +
+ + +Before you begin, take a moment to confirm that your development machine meets the +System Requirements. +
+ +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:
+ +http://www.eclipse.org/downloads/
+ +A Java or RCP version of Eclipse is recommended.
+ +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
+android_sdk_<platform>_<release>
.
+The directory contains a local copy of the documentation (accessible by opening
+documentation.html
in your browser) and the subdirectories
+tools/
, add-ons/
, platforms/
, and others. Inside
+each subdirectory of platforms/
you'll find samples/
, which includes
+code samples that are specific to each version of the platform.
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.
+ +Optionally, you may want to add the location of the SDK's primary tools
directory
+to your system PATH. The primary tools/
directory is located at the root of the
+SDK folder. Adding tools
to your path lets you run Android Debug Bridge (adb) and
+the other command line tools without
+needing to supply the full path to the tools directory.
~/.bash_profile
or ~/.bashrc
file. Look
+ for a line that sets the PATH environment variable and add the
+ full path to the tools/
directory to it. If you don't
+ see a line setting the path, you can add one:export PATH=${PATH}:<your_sdk_dir>/tools
.bash_profile
and
+ proceed as for Linux. You can create the .bash_profile
if
+ you haven't already set one up on your machine. tools/
directory to the path. 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.
+ +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 Next Steps).
+ + +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.
+ +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.)
+ +Once you have Eclipse installed, as described in Preparing for +Installation, follow the steps below to +download the ADT plugin and install it in your respective Eclipse +environment.
+ +Eclipse 3.3 (Europa) | Eclipse 3.4 (Ganymede) |
---|---|
+
+
|
+
+
+
+
|
+
Now modify your Eclipse preferences to point to the Android SDK directory:
+Done! If you haven't encountered any problems, then you're ready to +begin developing Android applications. See the +Next Steps section for suggestions on how to start.
+ + ++If you are having trouble downloading the ADT plugin after following the steps above, here are +some suggestions:
+ +http://dl-ssl.google.com/android/eclipse/
+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: +
+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.
+ +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 +ADT +Installation Error: "requires plug-in org.eclipse.wst.sse.ui".
+ +If you encounter this error when installing the ADT Plugin for Eclipse: +
+An error occurred during provisioning. +Cannot connect to keystore. +JKS+
+...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.
+ + +Once you have completed installation, you are ready to +begin developing applications. Here are a few ways you can get started:
+ +Learn about Android
+Explore the SDK
+Explore some code
+<sdk>/platforms/<platfrom>/samples
,
+ then compile and run it in your development environmentVisit the Android developer groups
+ia32-libs
package using
+ apt-get:
:
+ apt-get install ia32-libs+
apt-get install sun-java6-bin
A high-level look at what's changed in Android, with - discussion of how the changes may affect your apps.
A detailed report that lists all the specific changes in the latest SDK.
Version details, known issues, and resolved issues.
A forum where you can discuss migration issues and learn from other Android developers.
If you think you may have found a bug, use the issue tracker to report it.
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.
-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.
-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.
-For more information on new SDK features and system changes, +see the Android 1.5 Version Notes.
- -See the Download page for more information.
+(Do not uninstall "Android Development Tools".)
Alternatively,
+ +(Do not uninstall "Android Development Tools".)
Only install the new plugin once you've completed the procedure to +Uninstall your previous ADT plugin.
+ +Eclipse 3.3 (Europa) | Eclipse 3.4 (Ganymede) |
---|---|
+
+
|
+
|
If you encounter problems, ensure your ADT is fully uninstalled and then +follow the guide to +Installing the ADT Plugin +for Eclipse.
+ +The last step is to update your Eclipse preferences to point to the new SDK directory:
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.
+You will now need to update any and all Android projects that you have +developed using a previous version of the Android SDK.
+ + +If you use Eclipse to develop applications, use the following procedure to +update each project:
+ +The new plugin creates a gen/
folder in your project, in which it puts the
+R.java
file
+and all automatically generated AIDL java files. If you get an error such as
+The type R is already defined
,
+then you probably need to delete your old R.java
or your old auto-generated
+AIDL Java files in the src/
folder.
+(This does not apply to your own hand-crafted parcelable AIDL java files.)
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 +Migrate Your Applications.
+ + +If you build your projects using the Ant tool (rather than with Eclipse), note the +following changes with the new SDK tools.
+ +You must re-create your build.xml
file.
If you had customized your build.xml
, first make a copy of it:
+$ cd my-project +$ cp build.xml build.xml.old +-
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 +
Now use the new android
tool (located in your_sdk/tools/
)
+to create a new build.xml
that references
+a specific platform target:
$ android update project --path /path/to/my-project --target 1+ +
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, android list targets
.
+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.
A gen/
folder will be created the first time you build and your R.java
and
+your AIDL Java files will be generated in here. You must remove
+the old R.java
and old auto-generated AIDL java files from the
+src/
folder. (This
+does not apply to your own hand-crafted parcelabe AIDL java files.)
Note: 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 Developing +In Other IDEs.
+ +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 +Migrate Your Applications.
+ + +After you have completed the process above to Update Your +Projects, 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.
+ +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. Please read +the following guide completely before you begin.
+ +To test your application on an emulator running Android 1.5:
+As mentioned in the guide to Update Your Projects, + 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.
+Eclipse users: follow the + Eclipse guide to + Running Your Application.
+Ant users: follow the + Ant guide to + Running Your Application +
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.
+Once you complete the procedures to run your application in your respective environment, + linked above, return here.
+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.
+ +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.
+ +There have been several API additions made for this release, but there have been +very few actual API changes. 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:
+If you have additional trouble updating your code, visit the Android Developers Group to seek help from other Android developers.
- -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 -I can't install ApiDemos -apps in my IDE because of a signing error for information about how to solve the problem.
---> \ No newline at end of file -- 2.11.0