From 75f7a2642fc2c790f8f371a0f205d6e989b4224d Mon Sep 17 00:00:00 2001 From: Scott Main Date: Wed, 5 Aug 2009 19:31:00 -0700 Subject: [PATCH] add installing/upgrading docs for donut preview sdk and update eclipse ide doc to include new AVD Manager --- docs/html/guide/developing/eclipse-adt.jd | 50 ++- docs/html/sdk/preview/features.jd | 6 - docs/html/sdk/preview/installing.jd | 352 ++++++++++++++++++++++ docs/html/sdk/preview/requirements.jd | 43 +++ docs/html/sdk/preview/upgrading.jd | 257 ++++++++++++++++ 5 files changed, 670 insertions(+), 38 deletions(-) delete mode 100644 docs/html/sdk/preview/features.jd create mode 100644 docs/html/sdk/preview/installing.jd create mode 100644 docs/html/sdk/preview/requirements.jd create mode 100644 docs/html/sdk/preview/upgrading.jd diff --git a/docs/html/guide/developing/eclipse-adt.jd b/docs/html/guide/developing/eclipse-adt.jd index 3b3bb38a476d5..a5cf7358500cf 100644 --- a/docs/html/guide/developing/eclipse-adt.jd +++ b/docs/html/guide/developing/eclipse-adt.jd @@ -135,7 +135,7 @@ folders and files in your new project:

Running Your Application

-

Wait! Before you can run your application on the Android Emulator, +

Before you can run your application on the Android Emulator, you must create an Android Virtual Device (AVD). An AVD is a configuration that specifies the Android platform to be used on the emulator. You can read more in the Android Virtual @@ -149,45 +149,31 @@ on running your applicaiton.

Creating an AVD

-

To avoid some explanation that's beyond the scope of this document, here's the -basic procedure to create an AVD:

+

With ADT 0.9.2 and above, the Android AVD Manager provides a simple graphical interface +for creating and managing AVDs. (If you're using ADT version 0.9.1 or older, you must +use the android tool to create your AVDs—read the AVD guide to +Creating an AVD.) + +

To create an AVD with the Android AVD Manager:

    -
  1. Open a command-line (e.g.,"Command Prompt" application on Windows, or "Terminal" - on Mac/Linux) and navigate to your SDK package's - tools/ directory.
    2. -
  2. First, you need to select a Deployment Target. To view available targets, execute: - 
    android list targets
    -

    This will output a list of available Android targets, such as:

    -
    -id:1
-    Name: Android 1.1
-    Type: platform
-    API level: 2
-    Skins: HVGA (default), HVGA-L, HVGA-P, QVGA-L, QVGA-P
-id:2
-    Name: Android 1.5
-    Type: platform
-    API level: 3
-    Skins: HVGA (default), HVGA-L, HVGA-P, QVGA-L, QVGA-P
-
    -

    Find the target that matches the Android platform upon which you'd like - to run your application. Note the integer value of the id — - you'll use this in the next step.

    +
  3. Select Window > Android AVD Manager, or click the Android AVD Manager icon (a black device) + in the Eclipse toolbar.

    4. -
  4. Create a new AVD using your selected Deployment Target. Execute: - 
    android create avd --name <your_avd_name> --target <targetID>
    -
  5. Next, you'll be asked whether you'd like to create a custom hardware profile. - If you respond "yes," you'll be presented with a series of prompts to define various aspects of the - device hardware (leave entries blank to use default values, which are shown in brackets). Otherwise, - press return to use all default values ("no" is the default).
    6. +
  6. In the Virtual Devices panel, you'll see a list of existing AVDs. Click New + to create a new AVD.
    7. +
  7. Fill in the details for the AVD. +

    Give it a name, a platform target, an SD card image (optional), and + a skin (HVGA is default).

    8. +
  8. Click Create AVD.
-

That's it; your AVD is ready. In the next section, you'll see how the AVD is used +

Your AVD is now ready and you can close the Android AVD Manager. +In the next section, you'll see how the AVD is used when launching your application on an emulator.

-

To learn more about creating and managing AVDs, please read the +

For more information about AVDs, read the Android Virtual Devices documentation.

diff --git a/docs/html/sdk/preview/features.jd b/docs/html/sdk/preview/features.jd deleted file mode 100644 index 43856deab0bae..0000000000000 --- a/docs/html/sdk/preview/features.jd +++ /dev/null @@ -1,6 +0,0 @@ -sdk.redirect=true -sdk.redirect.path=android-1.5-highlights.html - -@jd:body - - diff --git a/docs/html/sdk/preview/installing.jd b/docs/html/sdk/preview/installing.jd new file mode 100644 index 0000000000000..29c70f6e9a143 --- /dev/null +++ b/docs/html/sdk/preview/installing.jd @@ -0,0 +1,352 @@ +page.title=Installing the Android SDK +sdk.version=1.6 Early Look +sdk.date=August 2009 + +@jd:body + + +
+ +
+ +

This page describes how to install the Android Early Look SDK and set up your +development environment.

+ +

If you encounter any problems during installation, see the +Installation Notes at the bottom of +this page.

+ +

Upgrading?

+

If you have already developed applications using an earlier version +of the Android SDK, please read Upgrading the SDK, instead. +

+ + +

Preparing for Installation

+ +

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.4 or newer is recommended). 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.

+ +

Installing the SDK

+ +

Unpack the Android SDK .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.

+ + +

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 (ADT) 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).

+ + +

Installing the ADT Plugin for Eclipse

+ +

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—skip to Next Steps.)

+ +

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)
+ +
    +
  1. Start Eclipse, then select Help > Software Updates +> Find and Install....
    2. +
  2. In the dialog that appears, select Search for new features to install +and click Next.
    3. +
  3. Click New Remote Site.
    4. +
  4. In the resulting dialog box, enter a name for the remote site (e.g. "Android Plugin") and + enter the URL: + 
    https://dl-ssl.google.com/android/eclipse/
    +

    If you have trouble aqcuiring the plugin, try using "http" in the URL, + instead of "https" (https is preferred for security reasons).

    +

    Click OK.

    5. +
  5. You should now see the new site added to the search list (and checked). + Click Finish.
    6. +
  6. In the subsequent Search Results dialog box, select the checkbox for the + "Android Plugin". + This will select the nested tools: "Android DDMS" and "Android Development Tools". + Click Next.
    7. +
  7. Read and accept the license agreement, then click Next.
    8. +
  8. On the following Installation window, click Finish.
    9. +
  9. The ADT plugin is not digitally signed. Accept the installation anyway + by clicking Install All.
    10. +
  10. Restart Eclipse.
    11. +
+ +		 + + +
    +
  1. Start Eclipse, then select Help > Software Updates....
    2. +
  2. In the dialog that appears, click the Available Software tab.
    3. +
  3. Click Add Site...
    4. +
  4. Enter the Location: + 
    https://dl-ssl.google.com/android/eclipse/
    +

    If you have trouble aqcuiring the plugin, try using "http" in the Location URL, + instead of "https" (https is preferred for security reasons).

    +

    Click OK.

    5. +
  5. 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 Install...
    6. +
  6. On the subsequent Install window, "Android DDMS" and "Android Development Tools" + should both be checked. Click Next.
    7. +
  7. Read and accept the license agreement, then click Finish.
    8. +
  8. Restart Eclipse.
    9. +
+ +
+ +

Now modify your Eclipse preferences to point to the Android SDK directory:

+
    +
  1. Select Window > Preferences... to open the Preferences + panel (Mac: Eclipse > Preferences).
    2. +
  2. Select Android from the left panel.
    3. +
  3. For the SDK Location in the main panel, click Browse... and +locate your downloaded SDK directory.
    4. +
  4. Click Apply, then OK.
    5. +
+ +

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.

+ + +

Troubleshooting ADT Installation

+

+If you are having trouble downloading the ADT plugin after following the steps above, here are +some suggestions:

+ + +

+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: +

+
    +
  1. Download the ADT Plugin zip file (do not unpack it).
    2. +
  2. Follow steps 1 and 2 in the default install instructions (above).
    3. +
  3. In Eclipse 3.3, click New Archive Site....
    + In Eclipse 3.4, click Add Site..., then Archive...
    4. +
  4. Browse and select the downloaded zip file.
    5. +
  5. Follow the remaining procedures, above, starting from steps 5.
    6. +
+

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.

+ +

Other install errors

+ +

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".

+ +

For Linux users

+

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.

+ + +

Next Steps

+

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

+ + +

Visit the Android developer groups

+ + + +

Installation Notes

+ +

Ubuntu Linux Notes

+ + + +

Other Linux Notes

+ + + + + diff --git a/docs/html/sdk/preview/requirements.jd b/docs/html/sdk/preview/requirements.jd new file mode 100644 index 0000000000000..612d23dd00a14 --- /dev/null +++ b/docs/html/sdk/preview/requirements.jd @@ -0,0 +1,43 @@ +page.title=System Requirements +@jd:body + +

The sections below describe the system and software requirements for developing +Android applications using the Android SDK tools included in Android + SDK, Release .

+ +

Supported Operating Systems

+ + +

Supported Development Environments

+ + +

Note: If JDK is already installed on your development computer, please take a moment to make sure that it meets the version requirements listed above. 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.

\ No newline at end of file diff --git a/docs/html/sdk/preview/upgrading.jd b/docs/html/sdk/preview/upgrading.jd new file mode 100644 index 0000000000000..99159fbf0fb92 --- /dev/null +++ b/docs/html/sdk/preview/upgrading.jd @@ -0,0 +1,257 @@ +page.title=Upgrading the SDK +sdk.version=1.6 Early Look +@jd:body + + +
+
+ +

Upgrading the SDK

+
    +
  • To move existing projects into the SDK, you must make some minor changes in your + development environment.
    • +
  • ADT 0.9[.1] is not compatible with the Android 1.6 Early Look SDK. You must upgrade + ADT to 0.9.2.
    • +
+ +

In this document

+
    +
  1. Install the SDK
    2. +
  2. Update Your Eclipse ADT Plugin
    3. +
  3. Run Your Applications
    4. +
  4. Convert Your Applications
    5. +
+ +

Migrating references

+
    +
  1. Android 1.6 Early Look API Differences
    2. +
+ +
+
+ +

This document describes how to move your development environment and existing +Android applications from an Android 1.5 SDK to the Android 1.6 Early Look 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.

+ +

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.

+ +

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 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 the new platform.

+ + + +

Install the SDK

+ + +

Now that you have the Android 1.6 Early Look SDK, +you need to perform some of the regular installation steps.

+ + +

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 +.bashrc or .bash_profile file:

+
export PATH=$PATH:<your_sdk_dir>/tools
+ + +

Update Your Eclipse ADT Plugin

+ +

If you don't use Eclipse for development, +skip to Update Your Projects.

+ + + +

A new ADT plugin (version 0.9.2) is required for the Android 1.6 Early Look SDK. +With ADT 0.9.2, you can still compile your applications against +multiple platform versions, such as Android 1.5. However, previous versions +of ADT will not work with the Android 1.6 Early Look SDK, so you must upgrade +to ADT 0.9.2.

+ +

If you're currently using a version of ADT older than version 0.9, then you must +uninstall ADT before you proceed (read how to +Uninstall +your previous ADT plugin). 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.

+ +

Install the 0.9.2 ADT plugin

+ +

To install the new ADT plugin, follow the steps below for your respective version of Eclipse.

+ + + + + + + +
Eclipse 3.3 (Europa)Eclipse 3.4 (Ganymede)
+ +
    +
  1. Select Help > Software Updates > + Find and Install.
    2. +
  2. Select Search for new features to install.
    3. +
  3. Select the Android plugin entry by checking the box next to it, + then click Finish. +

    (Your original entry for the plugin should still be here. If not, see the guide + to Installing the ADT Plugin.) +

    4. +
  4. In the results, expand the entry for the Android plugin and + be sure that "Developer Tools" is checked, then click Next. + (This will install "Android DDMS" and "Android Development Tools".)
    5. +
  5. Read and accept the license agreement, then click Next. +
  6. In the next window, click Finish to start installation.
    7. +
  7. The ADT plugin is not digitally signed. Accept the installation anyway by clicking + Install All.
    8. +
  8. Restart Eclipse.
    9. +
+		 + +
    +
  1. Select Help > Software Updates.
    2. +
  2. Select the Available Software tab.
    3. +
  3. 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 + Install.
    4. +
  4. On the next window, "Android DDMS" and "Android Development Tools" + should both be checked. Click Finish.
    5. +
  5. Restart Eclipse.
    6. +
+
+ +

If you encounter problems with this update procedure, try performing a fresh installation. +Ensure your current ADT is fully uninstalled and then +follow the guide to Installing the ADT Plugin +for Eclipse.

+ +

Update your Eclipse SDK Preferences

+ +

The last step is to update your Eclipse preferences to point to the new SDK directory:

+
    +
  1. Select Window > Preferences to open the Preferences + panel (Mac: Eclipse > Preferences).
    2. +
  2. Select Android from the left panel.
    3. +
  3. For the SDK Location, click Browse + and locate your SDK directory.
    4. +
  4. Click Apply, then OK.
    5. +
+ + +

Run Your Applications

+ +

Now that you have installed the Android 1.6 Early Look SDK, we encourage you +to run each of your applications in an instance +of the emulator that's running the new Android 1.6 system image. It's possible (however, unlikely) +that you'll encounter unexpected behavior in your application when you run your applications on +the new 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.

+ +

To test forward-compatibility, simply run your application, as-is, on an instance of the Android +Emulator that uses an AVD targeted to "Android Donut (Preview)":

+ +
    +
  1. Make no changes to your application code.
    2. +
  2. Create a new AVD that's targeted to the "Donut" platform.
    3. +
  3. Launch your application in an emulator running the new AVD.
    4. +
  4. Perform normal testing on your application to ensure everything works as expected.
    5. +
+ +

For more information on creating an AVD and launching your application refer to the +Eclipse guide to +Running Your Application or the +Ant guide to +Running Your Application, depending on your development environment.

+ + +

Convert Your Applications

+ +

If you want to fully utilize new APIs introduced with the Android 1.6 Early Look SDK, +then you'll need to convert your application to compile against the new "Donut" platform.

+ +

First, you need to change the value of the minSdkVersion attribute in +the <uses-sdk> manifest element. While +running your application against the Donut platform included with the Early Look SDK, you +must set the minSdkVersion value to "Donut". For example:

+ +
+<manifest>
+  ...
+  <uses-sdk android:minSdkVersion="Donut" />
+  ...
+</manifest>
+
+ +

This value is required only while compiling against the Donut platform included with +the Android 1.6 Early Look SDK. Once the final SDK is made +available for Android 1.6, you will need to change this value. +For more information, read about the Framework API and +Provisional API Level.

+ +

Once you've changed the minSdkVersion value in your application's manifest, +continue with the procedures below to convert your applications.

+ +

Eclipse users

+ +
    +
  1. Right-click on the individual project (in the Package Explorer) + and select Properties.
    2. +
  2. In the properties, open the Android panel and select a new Project Build Target. + Select "Android Donut (Preview)" to target the new + platform (or "Google APIs" with the "Donut" platform if your application uses the Maps APIs).
    3. +
  3. Click Apply, then OK.
    4. +
+ +

Remember that you must create an AVD that targets the same platform in order to run the emulator. + Continue with the + Eclipse guide to + Running Your Application. During the procedure to Running Your Application, select a "deployment + target" or the AVD that includes the "Donut" platform. If your application utilizes the Google Maps APIs (i.e., + MapView), be certain to select a target that includes the Google APIs.

+ + +

Ant users

+ +

Use the android tool (located in your_sdk/tools/) + to create a new build.xml that references + the new platform target. To see a list of available targets, execute:

+ + 
android list targets
+ +

Select the target id that corresponds to the "Donut" platform and pass it with the + --target parameter when updating your project. For example:

+ + 
android update project --path /path/to/my-project --target 2
+ +

Remember that you must create an Android Virtual Device (AVD) that's targeted to the + same platform before you can run the updated application an instance + of the emulator. Please continue with the + Ant guide to + Running Your Application. During the procedure to Running Your Application, select a "deployment + target" for the AVD that includes the "Donut" platform. + If your application utilizes the Google Maps APIs (i.e., + MapView), be certain to select a target that includes the Google APIs.

+ + +
+

If you have additional trouble updating your code, visit the +Android Developers Group +to seek help from other Android developers.

+
+