Merge "Import revised translations" into froyo
diff --git a/cmds/dumpstate/dumpstate.c b/cmds/dumpstate/dumpstate.c
index e8b5eaf..082e704 100644
--- a/cmds/dumpstate/dumpstate.c
+++ b/cmds/dumpstate/dumpstate.c
@@ -138,6 +138,8 @@
dump_file("LAST PANIC CONSOLE", "/data/dontpanic/apanic_console");
dump_file("LAST PANIC THREADS", "/data/dontpanic/apanic_threads");
+ for_each_pid(show_wchan, "BLOCKED PROCESS WAIT-CHANNELS");
+
printf("------ BACKLIGHTS ------\n");
printf("LCD brightness=");
dump_file(NULL, "/sys/class/leds/lcd-backlight/brightness");
@@ -161,7 +163,6 @@
run_command("DUMPSYS", 60, "dumpsys", NULL);
}
-
static void usage() {
fprintf(stderr, "usage: dumpstate [-d] [-o file] [-s] [-z]\n"
" -d: append date to filename (requires -o)\n"
diff --git a/cmds/dumpstate/dumpstate.h b/cmds/dumpstate/dumpstate.h
index 6d48a85..682eafd 100644
--- a/cmds/dumpstate/dumpstate.h
+++ b/cmds/dumpstate/dumpstate.h
@@ -38,4 +38,10 @@
/* dump Dalvik stack traces, return the trace file location (NULL if none) */
const char *dump_vm_traces();
+/* for each process in the system, run the specified function */
+void for_each_pid(void (*func)(int, const char *), const char *header);
+
+/* Displays a blocked processes in-kernel wait channel */
+void show_wchan(int pid, const char *name);
+
#endif /* _DUMPSTATE_H_ */
diff --git a/cmds/dumpstate/utils.c b/cmds/dumpstate/utils.c
index c21dace..c7a78cc 100644
--- a/cmds/dumpstate/utils.c
+++ b/cmds/dumpstate/utils.c
@@ -37,6 +37,64 @@
#include "dumpstate.h"
+void for_each_pid(void (*func)(int, const char *), const char *header) {
+ DIR *d;
+ struct dirent *de;
+
+ if (!(d = opendir("/proc"))) {
+ printf("Failed to open /proc (%s)\n", strerror(errno));
+ return;
+ }
+
+ printf("\n------ %s ------\n", header);
+ while ((de = readdir(d))) {
+ int pid;
+ int fd;
+ char cmdpath[255];
+ char cmdline[255];
+
+ if (!(pid = atoi(de->d_name))) {
+ continue;
+ }
+
+ sprintf(cmdpath,"/proc/%d/cmdline", pid);
+ memset(cmdline, 0, sizeof(cmdline));
+ if ((fd = open(cmdpath, O_RDONLY)) < 0) {
+ strcpy(cmdline, "N/A");
+ } else {
+ read(fd, cmdline, sizeof(cmdline));
+ close(fd);
+ }
+ func(pid, cmdline);
+ }
+
+ closedir(d);
+}
+
+void show_wchan(int pid, const char *name) {
+ char path[255];
+ char buffer[255];
+ int fd;
+
+ memset(buffer, 0, sizeof(buffer));
+
+ sprintf(path, "/proc/%d/wchan", pid);
+ if ((fd = open(path, O_RDONLY)) < 0) {
+ printf("Failed to open '%s' (%s)\n", path, strerror(errno));
+ return;
+ }
+
+ if (read(fd, buffer, sizeof(buffer)) < 0) {
+ printf("Failed to read '%s' (%s)\n", path, strerror(errno));
+ goto out_close;
+ }
+
+ printf("%-7d %-32s %s\n", pid, name, buffer);
+
+out_close:
+ close(fd);
+ return;
+}
/* prints the contents of a file */
int dump_file(const char *title, const char* path) {
diff --git a/core/java/android/content/SyncResult.java b/core/java/android/content/SyncResult.java
index 18abebe..8b0afbd 100644
--- a/core/java/android/content/SyncResult.java
+++ b/core/java/android/content/SyncResult.java
@@ -20,30 +20,110 @@
import android.os.Parcelable;
/**
- * This class is used to store information about the result of a sync
+ * This class is used to communicate the results of a sync operation to the SyncManager.
+ * Based on the values here the SyncManager will determine the disposition of the
+ * sync and whether or not a new sync operation needs to be scheduled in the future.
+ *
*/
public final class SyncResult implements Parcelable {
+ /**
+ * Used to indicate that the SyncAdapter is already performing a sync operation, though
+ * not necessarily for the requested account and authority and that it wasn't able to
+ * process this request. The SyncManager will reschedule the request to run later.
+ */
public final boolean syncAlreadyInProgress;
+
+ /**
+ * Used to indicate that the SyncAdapter determined that it would need to issue
+ * too many delete operations to the server in order to satisfy the request
+ * (as defined by the SyncAdapter). The SyncManager will record
+ * that the sync request failed and will cause a System Notification to be created
+ * asking the user what they want to do about this. It will give the user a chance to
+ * choose between (1) go ahead even with those deletes, (2) revert the deletes,
+ * or (3) take no action. If the user decides (1) or (2) the SyncManager will issue another
+ * sync request with either {@link ContentResolver#SYNC_EXTRAS_OVERRIDE_TOO_MANY_DELETIONS}
+ * or {@link ContentResolver#SYNC_EXTRAS_DISCARD_LOCAL_DELETIONS} set in the extras.
+ * It is then up to the SyncAdapter to decide how to honor that request.
+ */
public boolean tooManyDeletions;
+
+ /**
+ * Used to indicate that the SyncAdapter experienced a hard error due to trying the same
+ * operation too many times (as defined by the SyncAdapter). The SyncManager will record
+ * that the sync request failed and it will not reschedule the request.
+ */
public boolean tooManyRetries;
+
+ /**
+ * Used to indicate that the SyncAdapter experienced a hard error due to an error it
+ * received from interacting with the storage later. The SyncManager will record that
+ * the sync request failed and it will not reschedule the request.
+ */
public boolean databaseError;
+
+ /**
+ * If set the SyncManager will request an immediate sync with the same Account and authority
+ * (but empty extras Bundle) as was used in the sync request.
+ */
public boolean fullSyncRequested;
+
+ /**
+ * This field is ignored by the SyncManager.
+ */
public boolean partialSyncUnavailable;
+
+ /**
+ * This field is ignored by the SyncManager.
+ */
public boolean moreRecordsToGet;
- // in seconds since epoch
+ /**
+ * Used to indicate to the SyncManager that future sync requests that match the request's
+ * Account and authority should be delayed at least this many seconds.
+ */
public long delayUntil;
+
+ /**
+ * Used to hold extras statistics about the sync operation. Some of these indicate that
+ * the sync request resulted in a hard or soft error, others are for purely informational
+ * purposes.
+ */
public final SyncStats stats;
+
+ /**
+ * This instance of a SyncResult is returned by the SyncAdapter in response to a
+ * sync request when a sync is already underway. The SyncManager will reschedule the
+ * sync request to try again later.
+ */
public static final SyncResult ALREADY_IN_PROGRESS;
static {
ALREADY_IN_PROGRESS = new SyncResult(true);
}
+ /**
+ * Create a "clean" SyncResult. If this is returned without any changes then the
+ * SyncManager will consider the sync to have completed successfully. The various fields
+ * can be set by the SyncAdapter in order to give the SyncManager more information as to
+ * the disposition of the sync.
+ * <p>
+ * The errors are classified into two broad categories: hard errors and soft errors.
+ * Soft errors are retried with exponential backoff. Hard errors are not retried (except
+ * when the hard error is for a {@link ContentResolver#SYNC_EXTRAS_UPLOAD} request,
+ * in which the request is retryed without the {@link ContentResolver#SYNC_EXTRAS_UPLOAD}
+ * extra set). The SyncManager checks the type of error by calling
+ * {@link SyncResult#hasHardError()} and {@link SyncResult#hasSoftError()}. If both are
+ * true then the SyncManager treats it as a hard error, not a soft error.
+ */
public SyncResult() {
this(false);
}
+ /**
+ * Internal helper for creating a clean SyncResult or one that indicated that
+ * a sync is already in progress.
+ * @param syncAlreadyInProgress if true then set the {@link #syncAlreadyInProgress} flag
+ */
private SyncResult(boolean syncAlreadyInProgress) {
this.syncAlreadyInProgress = syncAlreadyInProgress;
this.tooManyDeletions = false;
@@ -67,6 +147,21 @@
stats = new SyncStats(parcel);
}
+ /**
+ * Convenience method for determining if the SyncResult indicates that a hard error
+ * occurred. See {@link #SyncResult()} for an explanation of what the SyncManager does
+ * when it sees a hard error.
+ * <p>
+ * A hard error is indicated when any of the following is true:
+ * <ul>
+ * <li> {@link SyncStats#numParseExceptions} > 0
+ * <li> {@link SyncStats#numConflictDetectedExceptions} > 0
+ * <li> {@link SyncStats#numAuthExceptions} > 0
+ * <li> {@link #tooManyDeletions}
+ * <li> {@link #tooManyRetries}
+ * <li> {@link #databaseError}
+ * @return true if a hard error is indicated
+ */
public boolean hasHardError() {
return stats.numParseExceptions > 0
|| stats.numConflictDetectedExceptions > 0
@@ -76,10 +171,26 @@
|| databaseError;
}
+ /**
+ * Convenience method for determining if the SyncResult indicates that a soft error
+ * occurred. See {@link #SyncResult()} for an explanation of what the SyncManager does
+ * when it sees a soft error.
+ * <p>
+ * A soft error is indicated when any of the following is true:
+ * <ul>
+ * <li> {@link SyncStats#numIoExceptions} > 0
+ * <li> {@link #syncAlreadyInProgress}
+ * </ul>
+ * @return true if a hard error is indicated
+ */
public boolean hasSoftError() {
return syncAlreadyInProgress || stats.numIoExceptions > 0;
}
+ /**
+ * A convenience method for determining of the SyncResult indicates that an error occurred.
+ * @return true if either a soft or hard error occurred
+ */
public boolean hasError() {
return hasSoftError() || hasHardError();
}
@@ -90,6 +201,10 @@
|| stats.numUpdates > 0;
}
+ /**
+ * Clears the SyncResult to a clean state. Throws an {@link UnsupportedOperationException}
+ * if this is called when {@link #syncAlreadyInProgress} is set.
+ */
public void clear() {
if (syncAlreadyInProgress) {
throw new UnsupportedOperationException(
diff --git a/core/java/android/content/SyncStats.java b/core/java/android/content/SyncStats.java
index cc544c0..b7f2a85 100644
--- a/core/java/android/content/SyncStats.java
+++ b/core/java/android/content/SyncStats.java
@@ -20,17 +20,77 @@
import android.os.Parcel;
/**
- * @hide
+ * Used to record various statistics about the result of a sync operation. The SyncManager
+ * gets access to these via a {@link SyncResult} and uses some of them to determine the
+ * disposition of the sync. See {@link SyncResult} for further dicussion on how the
+ * SyncManager uses these values.
*/
public class SyncStats implements Parcelable {
+ /**
+ * The SyncAdapter was unable to authenticate the {@link android.accounts.Account}
+ * that was specified in the request. The user needs to take some action to resolve
+ * before a future request can expect to succeed. This is considered a hard error.
+ */
public long numAuthExceptions;
+
+ /**
+ * The SyncAdapter had a problem, most likely with the network connectivity or a timeout
+ * while waiting for a network response. The request may succeed if it is tried again
+ * later. This is considered a soft error.
+ */
public long numIoExceptions;
+
+ /**
+ * The SyncAdapter had a problem with the data it received from the server or the storage
+ * later. This problem will likely repeat if the request is tried again. The problem
+ * will need to be cleared up by either the server or the storage layer (likely with help
+ * from the user). If the SyncAdapter cleans up the data itself then it typically won't
+ * increment this value although it may still do so in order to record that it had to
+ * perform some cleanup. E.g., if the SyncAdapter received a bad entry from the server
+ * when processing a feed of entries, it may choose to drop the entry and thus make
+ * progress and still increment this value just so the SyncAdapter can record that an
+ * error occurred. This is considered a hard error.
+ */
public long numParseExceptions;
+
+ /**
+ * The SyncAdapter detected that there was an unrecoverable version conflict when it
+ * attempted to update or delete a version of a resource on the server. This is expected
+ * to clear itself automatically once the new state is retrieved from the server,
+ * though it may remain until the user intervenes manually, perhaps by clearing the
+ * local storage and starting over frmo scratch. This is considered a hard error.
+ */
public long numConflictDetectedExceptions;
+
+ /**
+ * Counter for tracking how many inserts were performed by the sync operation, as defined
+ * by the SyncAdapter.
+ */
public long numInserts;
+
+ /**
+ * Counter for tracking how many updates were performed by the sync operation, as defined
+ * by the SyncAdapter.
+ */
public long numUpdates;
+
+ /**
+ * Counter for tracking how many deletes were performed by the sync operation, as defined
+ * by the SyncAdapter.
+ */
public long numDeletes;
+
+ /**
+ * Counter for tracking how many entries were affected by the sync operation, as defined
+ * by the SyncAdapter.
+ */
public long numEntries;
+
+ /**
+ * Counter for tracking how many entries, either from the server or the local store, were
+ * ignored during the sync operation. This could happen if the SyncAdapter detected some
+ * unparsable data but decided to skip it and move on rather than failing immediately.
+ */
public long numSkippedEntries;
public SyncStats() {
@@ -75,6 +135,9 @@
return sb.toString();
}
+ /**
+ * Reset all the counters to 0.
+ */
public void clear() {
numAuthExceptions = 0;
numIoExceptions = 0;
diff --git a/core/java/android/database/sqlite/SQLiteDebug.java b/core/java/android/database/sqlite/SQLiteDebug.java
index a4db6d9..89c3f96 100644
--- a/core/java/android/database/sqlite/SQLiteDebug.java
+++ b/core/java/android/database/sqlite/SQLiteDebug.java
@@ -118,8 +118,6 @@
/**
* contains statistics about a database
- * @author vnori@google.com (Your Name Here)
- *
*/
public static class DbStats {
/** name of the database */
diff --git a/core/java/android/service/wallpaper/WallpaperService.java b/core/java/android/service/wallpaper/WallpaperService.java
index 7f202a7..3d1d7d6 100644
--- a/core/java/android/service/wallpaper/WallpaperService.java
+++ b/core/java/android/service/wallpaper/WallpaperService.java
@@ -127,6 +127,7 @@
// Current window state.
boolean mCreated;
+ boolean mSurfaceCreated;
boolean mIsCreating;
boolean mDrawingAllowed;
int mWidth;
@@ -137,7 +138,6 @@
int mCurHeight;
int mWindowFlags = WindowManager.LayoutParams.FLAG_NOT_TOUCHABLE;
int mCurWindowFlags = mWindowFlags;
- boolean mDestroyReportNeeded;
final Rect mVisibleInsets = new Rect();
final Rect mWinFrame = new Rect();
final Rect mContentInsets = new Rect();
@@ -447,11 +447,12 @@
if (myHeight <= 0) myHeight = ViewGroup.LayoutParams.MATCH_PARENT;
final boolean creating = !mCreated;
+ final boolean surfaceCreating = !mSurfaceCreated;
final boolean formatChanged = mFormat != mSurfaceHolder.getRequestedFormat();
boolean sizeChanged = mWidth != myWidth || mHeight != myHeight;
final boolean typeChanged = mType != mSurfaceHolder.getRequestedType();
final boolean flagsChanged = mCurWindowFlags != mWindowFlags;
- if (forceRelayout || creating || formatChanged || sizeChanged
+ if (forceRelayout || creating || surfaceCreating || formatChanged || sizeChanged
|| typeChanged || flagsChanged) {
if (DEBUG) Log.v(TAG, "Changes: creating=" + creating
@@ -487,6 +488,7 @@
mLayout.windowAnimations =
com.android.internal.R.style.Animation_Wallpaper;
mSession.add(mWindow, mLayout, View.VISIBLE, mContentInsets);
+ mCreated = true;
}
mSurfaceHolder.mSurfaceLock.lock();
@@ -513,9 +515,13 @@
mSurfaceHolder.mSurfaceLock.unlock();
+ if (!mSurfaceHolder.mSurface.isValid()) {
+ reportSurfaceDestroyed();
+ if (DEBUG) Log.v(TAG, "Layout: Surface destroyed");
+ return;
+ }
+
try {
- mDestroyReportNeeded = true;
-
SurfaceHolder.Callback callbacks[] = null;
synchronized (mSurfaceHolder.mCallbacks) {
final int N = mSurfaceHolder.mCallbacks.size();
@@ -525,7 +531,7 @@
}
}
- if (!mCreated) {
+ if (surfaceCreating) {
mIsCreating = true;
if (DEBUG) Log.v(TAG, "onSurfaceCreated("
+ mSurfaceHolder + "): " + this);
@@ -536,7 +542,8 @@
}
}
}
- if (forceReport || creating || formatChanged || sizeChanged) {
+ if (forceReport || creating || surfaceCreating
+ || formatChanged || sizeChanged) {
if (DEBUG) {
RuntimeException e = new RuntimeException();
e.fillInStackTrace();
@@ -559,7 +566,7 @@
}
} finally {
mIsCreating = false;
- mCreated = true;
+ mSurfaceCreated = true;
if (creating || (relayoutResult&WindowManagerImpl.RELAYOUT_FIRST_TIME) != 0) {
mSession.finishDrawing(mWindow);
}
@@ -621,6 +628,12 @@
mReportedVisible = visible;
if (DEBUG) Log.v(TAG, "onVisibilityChanged(" + visible
+ "): " + this);
+ if (visible) {
+ // If becoming visible, in preview mode the surface
+ // may have been destroyed so now we need to make
+ // sure it is re-created.
+ updateSurface(false, false);
+ }
onVisibilityChanged(visible);
}
}
@@ -645,13 +658,16 @@
mPendingSync = false;
mOffsetMessageEnqueued = false;
}
- if (DEBUG) Log.v(TAG, "Offsets change in " + this
- + ": " + xOffset + "," + yOffset);
- final int availw = mIWallpaperEngine.mReqWidth-mCurWidth;
- final int xPixels = availw > 0 ? -(int)(availw*xOffset+.5f) : 0;
- final int availh = mIWallpaperEngine.mReqHeight-mCurHeight;
- final int yPixels = availh > 0 ? -(int)(availh*yOffset+.5f) : 0;
- onOffsetsChanged(xOffset, yOffset, xOffsetStep, yOffsetStep, xPixels, yPixels);
+
+ if (mSurfaceCreated) {
+ if (DEBUG) Log.v(TAG, "Offsets change in " + this
+ + ": " + xOffset + "," + yOffset);
+ final int availw = mIWallpaperEngine.mReqWidth-mCurWidth;
+ final int xPixels = availw > 0 ? -(int)(availw*xOffset+.5f) : 0;
+ final int availh = mIWallpaperEngine.mReqHeight-mCurHeight;
+ final int yPixels = availh > 0 ? -(int)(availh*yOffset+.5f) : 0;
+ onOffsetsChanged(xOffset, yOffset, xOffsetStep, yOffsetStep, xPixels, yPixels);
+ }
if (sync) {
try {
@@ -679,21 +695,9 @@
}
}
- void detach() {
- if (mDestroyed) {
- return;
- }
-
- mDestroyed = true;
-
- if (mVisible) {
- mVisible = false;
- if (DEBUG) Log.v(TAG, "onVisibilityChanged(false): " + this);
- onVisibilityChanged(false);
- }
-
- if (mDestroyReportNeeded) {
- mDestroyReportNeeded = false;
+ void reportSurfaceDestroyed() {
+ if (mSurfaceCreated) {
+ mSurfaceCreated = false;
SurfaceHolder.Callback callbacks[];
synchronized (mSurfaceHolder.mCallbacks) {
callbacks = new SurfaceHolder.Callback[
@@ -707,6 +711,22 @@
+ mSurfaceHolder + "): " + this);
onSurfaceDestroyed(mSurfaceHolder);
}
+ }
+
+ void detach() {
+ if (mDestroyed) {
+ return;
+ }
+
+ mDestroyed = true;
+
+ if (mVisible) {
+ mVisible = false;
+ if (DEBUG) Log.v(TAG, "onVisibilityChanged(false): " + this);
+ onVisibilityChanged(false);
+ }
+
+ reportSurfaceDestroyed();
if (DEBUG) Log.v(TAG, "onDestroy(): " + this);
onDestroy();
diff --git a/core/java/android/util/Patterns.java b/core/java/android/util/Patterns.java
index 2ee6e8a..5cbfd29 100644
--- a/core/java/android/util/Patterns.java
+++ b/core/java/android/util/Patterns.java
@@ -124,7 +124,7 @@
+ "[0-9]{2}|[1-9][0-9]|[1-9]|0)\\.(?:25[0-5]|2[0-4][0-9]|[0-1][0-9]{2}"
+ "|[1-9][0-9]|[0-9])))"
+ "(?:\\:\\d{1,5})?)" // plus option port number
- + "(\\/(?:(?:[a-zA-Z0-9\\;\\/\\?\\:\\@\\&\\=\\#\\~" // plus option query params
+ + "(\\/(?:(?:[" + GOOD_IRI_CHAR + "\\;\\/\\?\\:\\@\\&\\=\\#\\~" // plus option query params
+ "\\-\\.\\+\\!\\*\\'\\(\\)\\,\\_])|(?:\\%[a-fA-F0-9]{2}))*)?"
+ "(?:\\b|$)"); // and finally, a word boundary or end of
// input. This is to stop foo.sure from
diff --git a/core/java/android/webkit/WebView.java b/core/java/android/webkit/WebView.java
index 6f4c6ff..6b316ce 100644
--- a/core/java/android/webkit/WebView.java
+++ b/core/java/android/webkit/WebView.java
@@ -4814,6 +4814,8 @@
boolean done = false;
boolean keepScrollBarsVisible = false;
if (Math.abs(fDeltaX) < 1.0f && Math.abs(fDeltaY) < 1.0f) {
+ mLastTouchX = x;
+ mLastTouchY = y;
keepScrollBarsVisible = done = true;
} else {
if (mSnapScrollMode == SNAP_X || mSnapScrollMode == SNAP_Y) {
@@ -4865,6 +4867,8 @@
} else {
// keep the scrollbar on the screen even there is no
// scroll
+ mLastTouchX = x;
+ mLastTouchY = y;
keepScrollBarsVisible = true;
}
mLastTouchTime = eventTime;
diff --git a/core/tests/coretests/src/android/util/PatternsTest.java b/core/tests/coretests/src/android/util/PatternsTest.java
index 957c593..b90c97b 100644
--- a/core/tests/coretests/src/android/util/PatternsTest.java
+++ b/core/tests/coretests/src/android/util/PatternsTest.java
@@ -74,6 +74,10 @@
t = Patterns.WEB_URL.matcher("\uD604\uAE08\uC601\uC218\uC99D.kr").matches();
assertTrue("Valid URL", t);
+ t = Patterns.WEB_URL.matcher("http://brainstormtech.blogs.fortune.cnn.com/2010/03/11/" +
+ "top-five-moments-from-eric-schmidt\u2019s-talk-in-abu-dhabi/").matches();
+ assertTrue("Valid URL", t);
+
t = Patterns.WEB_URL.matcher("ftp://www.example.com").matches();
assertFalse("Matched invalid protocol", t);
diff --git a/docs/html/guide/developing/device.jd b/docs/html/guide/developing/device.jd
index 22c099f..2e2d803 100644
--- a/docs/html/guide/developing/device.jd
+++ b/docs/html/guide/developing/device.jd
@@ -5,12 +5,6 @@
<div id="qv">
<h2>In this document</h2>
<ol>
- <li><a href="#devices">Available Devices</a>
- <ol>
- <li><a href="#consumer">Consumer devices</a></li>
- <li><a href="#dev-phone-1">Android Dev Phone 1</a></li>
- </ol>
- </li>
<li><a href="#setting-up">Setting up a Device for Development</a>
<ol>
<li><a href="#VendorIds">USB Vendor IDs</a></li>
@@ -21,101 +15,50 @@
<ol>
<li><a
href="{@docRoot}sdk/win-usb.html">USB Driver for Windows</a></li>
+ <li><a
+href="{@docRoot}guide/developing/eclipse-adt.html">Developing in Eclipse, with ADT</a></li>
+ <li><a
+href="{@docRoot}guide/developing/other-ide.html">Developing in other IDEs</a></li>
</ol>
</div>
</div>
-<p>When building mobile applications, it's vital to test them on real
-devices prior to releasing them to users. This page covers what you need to know,
-including the types of devices that you can use, and how to set one up for
-developing and debugging.</p>
+<p>When building a mobile application, it's important that you always test your application on a
+real device before releasing it to users. This page describes how to set up your development
+environment and Android-powered device for testing and debugging on the device.</p>
+<p>You can use any Android-powered device as an environment for running,
+debugging, and testing your applications. The tools included in the SDK make it easy to install and
+run your application on the device each time you compile. You can install your application on the
+device <a
+href="{@docRoot}guide/developing/eclipse-adt.html#RunningOnDevice">directly from
+Eclipse</a> or <a href="{@docRoot}guide/developing/other-ide.html#RunningOnDevice">from the
+command line</a>. If
+you don't yet have a device, check with the service providers in your area to determine which
+Android-powered devices are available.</p>
-<h2 id="devices">Available Devices</h2>
-<p>Here are some options for obtaining devices capable of testing your applications.</p>
+<p>If you want a SIM-unlocked phone, then you might consider either an Android Dev Phone or the
+Google Nexus One. Both are SIM-unlocked so that you can use them on any GSM network using a SIM
+card. The Android Dev Phones also feature an unlocked bootloader so you can install custom system
+images (great for developing and installing custom versions of the Android platform). To purchase a
+Nexus One, visit <a href="http://www.google.com/phone">google.com/phone</a>. To purchase an Android
+Dev Phone, see the <a href="http://market.android.com/publish">Android Market</a> site
+(requires a developer account).</p>
-
-<h3 id="consumer">Consumer devices</h3>
-
-<p>It's likely that one of your local mobile carriers offers an Android-powered device.
-Any Android-powered device (even one bought from your mobile carrier) is a perfectly good
-device for running and testing your own Android applications.
-You can write applications using the Android SDK and then install them
-directly onto the device for testing.</p>
-
-<p>Check with the service providers in your area to determine which Android-powered
-devices are available.</p>
-
-<p>Be aware that consumer devices are not designed to allow system image updates by the
-user. If you're interested in manually updating the device with custom system images, then
-you'll need a developer device such as the <a href="#dev-phone-1">Android Dev Phone 1</a>.</p>
-
-
-
-<h3 id="dev-phone-1">Android Dev Phone 1</h3>
-
-<div class="sidebox-wrapper">
-<div class="sidebox">
-<p>Selected specs for Android Dev Phone 1:</p>
-<ul>
-<li>Touch screen</li>
-<li>Trackball</li>
-<li>3.2 megapixel camera with autofocus</li>
-<li>Wi-Fi</li>
-<li>GPS-enabled</li>
-<li>Bluetooth v2.0
- <ul><li>Handsfree profile v1.5</li>
- <li>Headset profile v1.0</li></ul></li>
-<li>3G WCDMA (1700/2100 MHz)</li>
-<li>Quad-band GSM (850/900/1800/1900 MHz)</li>
-<li>QWERTY slider keyboard</li>
-<li>Includes 1GB MicroSD card (can be replaced with up to 16GB card)</li>
-</ul>
-</div>
-</div>
-
-<p>The Android Dev Phone 1 is a SIM-unlocked and hardware-unlocked device that
-is designed for advanced developers. The device ships with a system image that
-is fully compatible with Android 1.0, so you can rely on it when developing your
-applications. You can use any SIM in the device and can flash custom Android
-builds that will work with the unlocked bootloader. Unlike the bootloader on
-retail devices, the bootloader on the Android Dev Phone 1 does not enforce
-signed system images. The Android Dev Phone 1 should also appeal to developers
-who live in geographies where local mobile carriers do not currently offer Android-powered devices. </p>
-
-<p>To purchase an Android Dev Phone 1 device, you must first register as an
-Android developer on the Android Market site, if you haven't done so already.
-Once you've logged into your developer account on Android Market, you can
-purchase the device by following the link to "Development phones." To accommodate demand,
-there is a limit of 1 device per developer account, for now.</p>
-
-<p>The device currently costs $399 (USD) (including free shipping in the US),
-and is available for purchase in 18 international markets, including the
-US, UK, Germany, Japan, India, Canada, France, Taiwan, Spain, Australia,
-Singapore, Switzerland, Netherlands, Austria, Sweden, Finland, Poland, and
-Hungary. We will continue to expand this program into new geographies over
-time. Check this page for updated information.</p>
-
-<p>Android Dev Phone 1 devices are <em>not</em> intended for
-non-developer end-users. Because the device can be configured with system
-software not provided by or supported by Google or any other company, end-users
-operate these devices at their own risk.</p>
-
-<p>Note that your Android Dev Phone 1 will not receive automated
-over-the-air (OTA) updates for the system image. System updates must be flashed manually.
-See the HTC site for a guide to <a href="http://www.htc.com/www/support/android/adp.html">Flashing
-your Android Dev Phone with a Factory System Image</a>.</p>
-
-<p>For full device specs and more information about obtaining an Android Dev
-Phone 1 device, see the <a href="http://market.android.com/publish">Android
-Market</a> site.</p>
-
+<p class="note"><strong>Note:</strong> When developing on a device, keep in mind that you should
+still use the <a
+href="{@docRoot}guide/developing/tools/emulator.html">Android emulator</a> to test your application
+on configurations that are not equivalent to those of your real device. Although the emulator
+does not allow you to test every device feature (such as the accelerometer), it does
+allow you to verify that your application functions properly on different versions of the Android
+platform, in different screen sizes and orientations, and more.</p>
<h2 id="setting-up">Setting up a Device for Development</h2>
<p>With an Android-powered device, you can develop and debug your Android applications just as you
-would on the emulator. There are just a few things to do before you can start.</p>
+would on the emulator. Before you can start, there are just a few things to do:</p>
+
<ol>
<li>Declare your application as "debuggable" in your Android Manifest.
<p>In Eclipse, you can do this from the <b>Application</b> tab when viewing the Manifest
@@ -159,37 +102,70 @@
</ul>
</li>
</ol>
-<p>You can verify that your device is connected by executing <code>adb devices</code> from your
-SDK tools/ directory. If connected, you'll see the device name listed as a "device."</p>
-<p>If using Eclipse, select run or debug as usual. You will be presented
-with a <b>Device Chooser</b> dialog that lists the available emulator(s) and connected device(s).
-Select the device to install and run the application there.</p>
-<p>If using the <a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a> (adb),
+<p>You can verify that your device is connected by executing <code>adb devices</code> from your
+SDK {@code tools/} directory. If connected, you'll see the device name listed as a "device."</p>
+
+<p>If using Eclipse, run or debug as usual. You will be presented
+with a <b>Device Chooser</b> dialog that lists the available emulator(s) and connected device(s).
+Select the device upon which you want to install and run the application.</p>
+
+<p>If using the <a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a> (adb),
you can issue commands with the <code>-d</code> flag to target your
connected device.</p>
<h3 id="VendorIds">USB Vendor IDs</h3>
<p>This table provides a reference to the vendor IDs needed in order to add
-device support on Linux. The USB Vendor ID is the value given to the
-<code>SYSFS{idVendor}</code> property in the rules file.</p>
+USB device support on Linux. The USB Vendor ID is the value given to the
+<code>SYSFS{idVendor}</code> property in the rules file, as described in step 3, above.</p>
+
<table>
<tr>
<th>Manufacturer</th><th>USB Vendor ID</th></tr>
<tr>
- <td>Acer</td><td>0502</td></tr>
+ <td>Acer</td>
+ <td><code>0502</code></td></tr>
<tr>
- <td>HTC</td><td>0bb4</td></tr>
+ <td>Dell</td>
+ <td><code>413c</code></td></tr>
<tr>
- <td>Huawei</td><td>12d1</td></tr>
+ <td>Foxconn</td>
+ <td><code>0489</code></td></tr>
<tr>
- <td>LG</td><td>1004</td></tr>
+ <td>Garmin-Asus</td>
+ <td><code>091E</code></td></tr>
<tr>
- <td>Motorola</td><td>22b8</td></tr>
+ <td>HTC</td>
+ <td><code>0bb4</code></td></tr>
<tr>
- <td>Samsung</td><td>04e8</td></tr>
+ <td>Huawei</td>
+ <td><code>12d1</code></td></tr>
<tr>
- <td>Sony Ericsson</td><td>0fce</td></tr>
+ <td>Kyocera</td>
+ <td><code>0482</code></td></tr>
+ <tr>
+ <td>LG</td>
+ <td><code>1004</code></td></tr>
+ <tr>
+ <td>Motorola</td>
+ <td><code>22b8</code></td></tr>
+ <tr>
+ <td>Nvidia</td>
+ <td><code>0955</code></td></tr>
+ <tr>
+ <td>Pantech</td>
+ <td><code>10A9</code></td></tr>
+ <tr>
+ <td>Samsung</td>
+ <td><code>04e8</code></td></tr>
+ <tr>
+ <td>Sharp</td>
+ <td><code>04dd</code></td></tr>
+ <tr>
+ <td>Sony Ericsson</td>
+ <td><code>0fce</code></td></tr>
+ <tr>
+ <td>ZTE</td>
+ <td><code>19D2</code></td></tr>
</table>
-
diff --git a/docs/html/guide/developing/eclipse-adt.jd b/docs/html/guide/developing/eclipse-adt.jd
index c01745e..549e093 100644
--- a/docs/html/guide/developing/eclipse-adt.jd
+++ b/docs/html/guide/developing/eclipse-adt.jd
@@ -6,10 +6,11 @@
<h2>In this document</h2>
<ol>
<li><a href="#CreatingAProject">Creating an Android Project</a></li>
+ <li><a href="#AVD">Creating an AVD</a></li>
<li><a href="#Running">Running Your Application</a>
<ol>
- <li><a href="#CreatingAnAvd">Creating an AVD</a></li>
- <li><a href="#RunningAnApplication">Running an application</a></li>
+ <li><a href="#RunningOnEmulator">Running on the emulator</a></li>
+ <li><a href="#RunningOnDevice">Running on a device</a></li>
</ol>
</li>
<li><a href="#RunConfig">Creating a Custom Run Configuration</a></li>
@@ -27,7 +28,8 @@
<ul>
<li>It gives you access to other Android development tools from inside the Eclipse IDE. For
example, ADT lets you access the many capabilities of the DDMS tool: take screenshots, manage
-port-forwarding, set breakpoints, and view thread and process information directly from Eclipse.</li>
+port-forwarding, set breakpoints, and view thread and process information directly from
+Eclipse.</li>
<li>It provides a New Project Wizard, which helps you quickly create and set up all of the
basic files you'll need for a new Android application.</li>
<li>It automates and simplifies the process of building your Android application.</li>
@@ -70,7 +72,7 @@
The Build Target
specifies which Android platform you'd like your application built against.
<p>Unless you know that you'll be using new APIs introduced in the latest SDK, you should
- select a target with the lowest platform version possible, such as Android 1.1.</p>
+ select a target with the lowest platform version possible.</p>
<p class="note"><strong>Note:</strong> You can change your the Build Target for your
project at any time: Right-click the project in the Package Explorer, select
<strong>Properties</strong>, select <strong>Android</strong> and then check
@@ -89,7 +91,8 @@
the minimum API Level required to properly run your application.
Entering this here automatically sets the <code>minSdkVersion</code> attribute in the
<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a>
- of your Android Manifest file. If you're unsure of the appropriate API Level to use,
+ of your Android Manifest file. If you're unsure of the appropriate <a
+href="{@docRoot}guide/appendix/api-levels.html">API Level</a> to use,
copy the API Level listed for the Build Target you selected in the Target tab.</li>
</ul>
</li>
@@ -133,87 +136,117 @@
</dl>
-<h2 id="Running">Running Your Application</h2>
+<h2 id="AVD">Creating an AVD</h2>
-<p>Before you can run your application on the Android Emulator,
-you <strong>must</strong> 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 <a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual
-Devices</a> document, but if you just want to get started, follow the simple guide below to
-create an AVD.</p>
+<p>An Android Virtual Device (AVD) is a device configuration for the emulator that
+allows you to model real world devices. In order to run an instance of the emulator, you must create
+an AVD.</p>
-<p>If you will be running your applications only on actual device hardware, you do not
-need an AVD — see
-<a href="{@docRoot}guide/developing/device.html">Developing On a Device</a> for information
-on running your application.</p>
-
-<h3 id="CreatingAnAvd">Creating an AVD</h3>
-
-<p>With ADT 0.9.3 and above, the Android SDK and 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 <code>android</code> tool to create your AVDs—read the AVD guide to
-<a href="{@docRoot}guide/developing/tools/avd.html#creating">Creating an AVD</a>.)
-
-<p>To create an AVD with the AVD Manager:</p>
+<p>To create an AVD from Eclipse:</p>
<ol>
- <li>Select <strong>Window > Android SDK and AVD Manager</strong>, or click the Android SDK and AVD Manager icon (a black device)
- in the Eclipse toolbar.</p>
+ <li>Select <strong>Window > Android SDK and AVD Manager</strong>, or click the Android SDK and
+AVD Manager icon in the Eclipse toolbar.</p>
</li>
- <li>In the Virtual Devices panel, you'll see a list of existing AVDs. Click <strong>New</strong>
- to create a new AVD.</li>
- <li>Fill in the details for the AVD.
- <p>Give it a name, a platform target, an SD card image (optional), and
+ <li>In the <em>Virtual Devices</em> panel, you'll see a list of existing AVDs. Click
+<strong>New</strong> to create a new AVD.</li>
+ <li>Fill in the details for the AVD.
+ <p>Give it a name, a platform target, an SD card size, and
a skin (HVGA is default).</p>
+ <p class="note"><strong>Note:</strong> Be sure to define
+ a target for your AVD that satisfies your application's Build Target (the AVD
+ platform target must have an API Level equal to or greater than the API Level that your
+application compiles against).</p>
</li>
<li>Click <strong>Create AVD</strong>.</li>
</ol>
-<p>Your AVD is now ready and you can close the AVD Manager.
-In the next section, you'll see how the AVD is used
-when launching your application on an emulator.</p>
+<p>Your AVD is now ready and you can either close the SDK and AVD Manager, create more AVDs, or
+launch an emulator with the AVD by selecting a device and clicking <strong>Start</strong>.</p>
-<p>For more information about AVDs, read the
+<p>For more information about AVDs, read the
<a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a>
documentation.</p>
-<h3 id="RunningYourApplication">Running your application</h3>
+<h2 id="Running">Running Your Application</h2>
-<p class="note"><strong>Note:</strong> Before you can run your application, be sure that
-you have created an AVD with a target that satisfies your application's Build Target.
-If an AVD cannot be found that meets the requirements of your Build Target, you will see
-a console error telling you so and the launch will be aborted.</p>
+<div class="sidebox-wrapper">
+<div class="sidebox">
+<h2>Use the Emulator to Test Different Configurations</h2>
+<p>Create multiple AVDs that each define a different device configuration with which your
+application is compatible, then launch each AVD into a new emulator from the SDK and AVD Manager.
+Set the target mode in your app's run configuration to manual, so that when you run your
+application, you can select from the available virtual devices.</p>
+</div>
+</div>
-<p>To run (or debug) your application, select <strong>Run</strong> > <strong>Run</strong> (or
-<strong>Run</strong> > <strong>Debug</strong>) from the Eclipse main menu. The ADT plugin
-will automatically create a default launch configuration for the project.</p>
+<p>Running your application from Eclipse will usually require just a couple clicks, whether you're
+running it on the emulator or on an attached device. The information below describes how to get
+set up and run your application from Eclipse.</p>
-<p>When you choose to run or debug your application, Eclipse will perform the following:</p>
+<h3 id="RunningOnEmulator">Running on the emulator</h3>
+
+<p>Before you can run your application on the Android Emulator,
+you <strong>must</strong> <a href="#AVD">create an AVD</a>.</p>
+
+<p>To run (or debug) your application, select <strong>Run</strong> > <strong>Run</strong> (or
+<strong>Run</strong> > <strong>Debug</strong>) from the Eclipse menu bar. The ADT plugin
+will automatically create a default launch configuration for the project. Eclipse will then perform
+the following:</p>
<ol>
<li>Compile the project (if there have been changes since the last build).</li>
- <li>Create a default launch configuration (if one does not already exist for the project).</li>
- <li>Install and start the application on an emulator or device (based on the Deployment Target
- defined by the run configuration).
- <p>By default, Android application run configurations use an "automatic target" mode for
- selecting a device target. For information on how automatic target mode selects a
- deployment target, see <a href="#AutoAndManualTargetModes">Automatic and manual
+ <li>Create a default launch configuration (if one does not already exist for the
+project).</li>
+ <li>Install and start the application on an emulator (or device), based on the Deployment
+Target
+ defined by the run configuration.
+ <p>By default, Android run configurations use an "automatic target" mode for
+ selecting a device target. For information on how automatic target mode selects a
+ deployment target, see <a href="#AutoAndManualTargetModes">Automatic and manual
target modes</a> below.</p>
</li>
</ol>
-<p>If debugging, the application will start in the "Waiting For Debugger" mode. Once the
+<p>If debugging, the application will start in the "Waiting For Debugger" mode. Once the
debugger is attached, Eclipse will open the Debug perspective.</p>
-<p>To set or change the launch configuration used for your project, use the launch configuration manager.
+<p>To set or change the launch configuration used for your project, use the launch configuration
+manager.
See <a href="#launchconfig">Creating a Launch Configuration</a> for information.</p>
+<p>Be certain to create multiple AVDs upon which to test your application. You should have one AVD
+for each platform and screen type with which your application is compatible. For
+instance, if your application compiles against the Android 1.5 (API Level 3) platform, you should
+create an AVD for each platform equal to and greater than 1.5 and an AVD for each <a
+href="{@docRoot}guide/practices/screens_support.html">screen type</a> you support, then test
+your application on each one.</p>
+
+
+<h3 id="RunningOnDevice">Running on a device</h3>
+
+<p>Before you can run your application on a device, you must perform some basic setup for your
+device:</p>
+
+<ul>
+ <li>Declare your application as debuggable in your manifest</li>
+ <li>Enable USB Debugging on your device</li>
+ <li>Ensure that your development computer can detect your device when connected via USB</li>
+</ul>
+<p>Read <a href="{@docRoot}guide/developing/device.html#setting-up">Setting up a Device for
+Development</a> for more information.</p>
+
+<p>Once set up and your device is connected via USB, install your application on the device by
+selecting <strong>Run</strong> > <strong>Run</strong> (or
+<strong>Run</strong> > <strong>Debug</strong>) from the Eclipse menu bar.</p>
+
+
<h2 id="RunConfig">Creating a Run Configuration</h2>
<p>The run configuration specifies the project to run, the Activity
-to start, the emulator options to use, and so on. When you first run a project
+to start, the emulator or connected device to use, and so on. When you first run a project
as an <em>Android Application</em>, ADT will automatically create a run configuration.
The default run configuration will
launch the default project Activity and use automatic target mode for device selection
@@ -240,7 +273,8 @@
<ul>
<li>To create a new configuration:
<ol>
- <li>Select <strong>Android Application</strong> and click the <em>New launch configuration</em>
+ <li>Select <strong>Android Application</strong> and click the <em>New launch
+configuration</em>
icon above the list (or, right-click <strong>Android Application</strong> and click
<strong>New</strong>).</li>
<li>Enter a Name for your configuration.</li>
@@ -268,7 +302,8 @@
<h3 id="AutoAndManualTargetModes">Automatic and manual target modes</h3>
-<p>By default, a run configuration uses the <strong>automatic</strong> target mode in order to select
+<p>By default, a run configuration uses the <strong>automatic</strong> target mode in order to
+select
an AVD. In this mode, ADT will select an AVD for the application in the following manner:</p>
<ol>
@@ -323,8 +358,8 @@
information about packages and call class methods. You can also invoke arbitrary
static methods: for example, entering <code>android.os.Debug.startMethodTracing()</code> will
start dmTrace. </p>
-<p>Open a code execution window, select <strong>Window</strong>><strong>Show
- View</strong>><strong>Display</strong> from the main menu to open the
+<p>Open a code execution window, select <strong>Window</strong> > <strong>Show
+ View</strong> > <strong>Display</strong> from the main menu to open the
Display window, a simple text editor. Type your expression, highlight the
text, and click the 'J' icon (or CTRL + SHIFT + D) to run your
code. The code runs in the context of the selected thread, which must be
diff --git a/docs/html/guide/developing/other-ide.jd b/docs/html/guide/developing/other-ide.jd
index d043a7d..76b2d9f 100644
--- a/docs/html/guide/developing/other-ide.jd
+++ b/docs/html/guide/developing/other-ide.jd
@@ -13,7 +13,13 @@
<li><a href="#ReleaseMode">Building in release mode</a></li>
</ol>
</li>
- <li><a href="#Running">Running Your Application</a></li>
+ <li><a href="#AVD">Creating an AVD</a></li>
+ <li><a href="#Running">Running Your Application</a>
+ <ol>
+ <li><a href="#RunningOnEmulator">Running on the emulator</a></li>
+ <li><a href="#RunningOnDevice">Running on a device</a></li>
+ </ol>
+ </li>
<li><a href="#AttachingADebugger">Attaching a Debugger to Your Application</a></li>
</ol>
@@ -97,15 +103,20 @@
to an Android platform library (including any add-ons, such as Google APIs) that you would like to
build your project against. To see a list of available targets and their corresponding IDs,
execute: <code>android list targets</code>.</li>
- <li><code>name</code> is the name for your project. This is optional. If provided, this name will be used
+ <li><code>name</code> is the name for your project. This is optional. If provided, this name will
+be used
for your .apk filename when you build your application.</li>
<li><code>path</code> is the location of your project directory. If the directory does not exist,
it will be created for you.</li>
- <li><code>activity</code> is the name for your default {@link android.app.Activity} class. This class file
+ <li><code>activity</code> is the name for your default {@link android.app.Activity} class. This
+class file
will be created for you inside
- <code><em><path_to_your_project></em>/src/<em><your_package_namespace_path></em>/</code>.
+
+<code><em><path_to_your_project></em>/src/<em><your_package_namespace_path></em>/</code>
+.
This will also be used for your .apk filename unless you provide a the <code>name</code>.</li>
- <li><code>package</code> is the package namespace for your project, following the same rules as for
+ <li><code>package</code> is the package namespace for your project, following the same rules as
+for
packages in the Java programming language.</li>
</ul>
@@ -127,13 +138,16 @@
<li><code>build.xml</code> - Build file for Ant.</li>
<li><code>default.properties</code> - Properties for the build system. <em>Do not modify
this file</em>.</li>
- <li><code>build.properties</code> - Customizable properties for the build system. You can edit this
- file to override default build settings used by Ant and provide a pointer to your keystore and key alias
+ <li><code>build.properties</code> - Customizable properties for the build system. You can edit
+this
+ file to override default build settings used by Ant and provide a pointer to your keystore and key
+alias
so that the build tools can sign your application when built in release mode.</li>
<li><code>src<em>/your/package/namespace/ActivityName</em>.java</code> - The Activity class
you specified during project creation.</li>
<li><code>bin/</code> - Output directory for the build script.</li>
- <li><code>gen/</code> - Holds <code>Ant</code>-generated files, such as <code>R.java</code>. </li>
+ <li><code>gen/</code> - Holds <code>Ant</code>-generated files, such as <code>R.java</code>.
+</li>
<li><code>libs/</code> - Holds private libraries.</li>
<li><code>res/</code> - Holds project resources.</li>
<li><code>src/</code> - Holds source code.</li>
@@ -167,13 +181,15 @@
<p>To update an existing Android project, open a command-line
and navigate to the <code>tools/</code> directory of your SDK. Now run:</p>
<pre>
-android update project --name <em><project_name></em> --target <em><target_ID></em> --path <em>path/to/your/project/</em>
+android update project --name <em><project_name></em> --target <em><target_ID></em>
+--path <em><path_to_your_project></em>
</pre>
<ul>
<li><code>target</code> is the "build target" for your application. It corresponds to
an Android platform library (including any add-ons, such as Google APIs) that you would
- like to build your project against. To see a list of available targets and their corresponding IDs,
+ like to build your project against. To see a list of available targets and their corresponding
+IDs,
execute: <code>android list targets</code>.</li>
<li><code>path</code> is the location of your project directory.</li>
<li><code>name</code> is the name for the project. This is optional—if you're not
@@ -218,7 +234,8 @@
<p>Whether you're building in debug mode or release mode, you
need to use the Ant tool to compile and build your project. This will create the .apk file
that is installed onto the emulator or device. When you build in debug mode, the .apk
-file is automatically signed by the SDK tools with a debug key, so it's instantly ready for installation
+file is automatically signed by the SDK tools with a debug key, so it's instantly ready for
+installation
(but only onto an emulator or attached development device).
When you build in release mode, the .apk file is <em>unsigned</em>, so you must manually
sign it with your own private key, using Keytool and Jarsigner.</p>
@@ -239,7 +256,7 @@
<p class="note"><strong>Note:</strong> When installing JDK on Windows, the default is to install
in the "Program Files" directory. This location will cause <code>ant</code> to fail, because of
the space. To fix the problem, you can specify the JAVA_HOME variable like this:
-<code>set JAVA_HOME=c:\Progra~1\Java\<jdkdir></code>. The easiest solution, however, is to
+<code>set JAVA_HOME=c:\Progra~1\Java\<jdkdir></code>. The easiest solution, however, is to
install JDK in a non-space directory, for example: <code>c:\java\jdk1.6.0_02</code>.</p>
@@ -322,8 +339,10 @@
<p class="caution"><strong>Caution:</strong> Due to the way Ant handles input, the password that
you enter during the build process <strong>will be visible</strong>. If you are
concerned about your keystore and alias password being visible on screen, then you
-may prefer to perform the application signing manually, via Jarsigner (or a similar tool). To instead
-perform the signing procedure manually, <a href="#ManualReleaseMode">buid unsigned</a> and then continue
+may prefer to perform the application signing manually, via Jarsigner (or a similar tool). To
+instead
+perform the signing procedure manually, <a href="#ManualReleaseMode">build unsigned</a> and then
+continue
with <a href="{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a>.</p>
<p>To specify your keystore and alias, open the project {@code build.properties} file (found in the
@@ -366,87 +385,125 @@
(On your device, be sure you have enabled <em>Settings > Applications > Unknown sources</em>.)</p>
-<h2 id="Running">Running Your Application</h2>
+<h2 id="AVD">Creating an AVD</h2>
-<p>Unless you'll be running your application on device hardware,
-you need to launch an emulator upon which you will install your application.
-An instance of the Android emulator runs a specific Android platform with specific device configuration
-settings. The platform and configuration is defined with an Android Virtual Device (AVD).
-So before you can launch your emulator, you must define an AVD.</p>
+<p>An Android Virtual Device (AVD) is a device configuration for the emulator that
+allows you to model real world devices. In order to run an instance of the emulator, you must create
+an AVD.</p>
-<p>If you'll be running your application on device hardware, please read about
-<a href="{@docRoot}guide/developing/device.html">Developing On a Device</a> instead.</p>
+<p>To create an AVD using the SDK tools:</p>
<ol>
- <li><strong>Create an AVD</strong>
- <ol>
- <li>Open a command-line and navigate to your SDK package's
- <code>tools/</code> directory.</li>
- <li>First, you need to select a "deployment target." To view available targets, execute:
- <pre>android list targets</pre>
- <p>This will output a list of available Android targets, such as:</p>
-<pre>
-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
-</pre>
- <p>Find the target that matches the Android platform upon which you'd like
- to run your application. Note the integer value of the <code>id</code> —
- you'll use this in the next step.</p>
- </li>
- <li>Create a new AVD using your selected deployment target:
- <pre>android create avd --name <em><your_avd_name></em> --target <em><target_ID></em></pre>
- <li>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).</li>
- </li>
- </ol>
+ <li>Navigate to your SDK's <code>tools/</code> directory and execute the {@code android}
+tool with no arguments:
+ <pre>android</pre>
+ <p>This will launch the SDK and AVD Manager GUI.</p>
+ </li>
+ <li>In the <em>Virtual Devices</em> panel, you'll see a list of existing AVDs. Click
+<strong>New</strong>
+ to create a new AVD.</li>
+ <li>Fill in the details for the AVD.
+ <p>Give it a name, a platform target, an SD card size, and
+ a skin (HVGA is default).</p>
+ <p class="note"><strong>Note:</strong> Be sure to define
+ a target for your AVD that satisfies your application's build target (the AVD
+ platform target must have an API Level equal to or greater than the API Level that your
+application compiles against).</p>
+ </li>
+ <li>Click <strong>Create AVD</strong>.</li>
+</ol>
+
+<p>Your AVD is now ready and you can either close the AVD Manager, create more AVDs, or
+launch an emulator with the AVD by clicking <strong>Start</strong>.</p>
+
+<p>For more information about AVDs, read the
+<a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a>
+documentation.</p>
+
+
+<h2 id="Running">Running Your Application</h2>
+
+<div class="sidebox-wrapper">
+<div class="sidebox">
+<h2>Use the Emulator to Test Different Configurations</h2>
+<p>Create multiple AVDs that each define a different device configuration with which your
+application is compatible, then launch each AVD into a new emulator from the SDK and AVD Manager.
+Set the target mode in your app's run configuration to manual, so that when you run your
+application, you can select from the available virtual devices.</p>
+</div>
+</div>
+
+<p>Running your application on a virtual or real device takes just a couple steps. Remember to
+first <a href="#Building">build your application</a>.</p>
+
+<h3 id="RunningOnEmulator">Running on the emulator</h3>
+
+<p>Before you can run your application on the Android Emulator,
+you must <a href="#AVD">create an AVD</a>.</p>
+
+<p>To run your application:</p>
+<ol>
+ <li><strong>Open the SDK and AVD Manager and launch a virtual device</strong></li>
+ <p>From your SDK's <code>tools/</code> directory, execute the {@code android} tool with no
+arguments:
+ <pre>android</pre>
+ <p>In the <em>Virtual Devices</em> view, select an AVD and click <strong>Start</strong>.</p>
</li>
- <li><strong>Launch an emulator</strong></li>
- <p>From your SDK's <code>tools/</code> directory, launch an emulator
- using an existing AVD (created above):
- <pre>emulator -avd <em><your_avd_name></em></pre>
- <p>An instance of the emulator will now launch, running the target and configuration
- defined by your AVD.</p>
- </li>
-
<li><strong>Install your application</strong>
- <p>From your SDK's <code>tools/</code> directory, install the .apk on the emulator:
- <pre>adb install <em>/path/to/your/application</em>.apk</pre>
- <p>If there is more than one emulator running, you must specify the emulator upon which to install
- the application, by its serial number, with the <code>-s</code> option. For example:</p>
- <pre>adb -s emulator-5554 install /my/project/path/myapp.apk</pre>
- </li>
- <li><strong>Open your application</strong>
- <p>In the emulator, open the list of available applications to find
- and open your application.</p>
+ <p>From your SDK's <code>tools/</code> directory, install the {@code .apk} on the
+emulator:
+ <pre>adb install <em><path_to_your_bin></em>.apk</pre>
+ <p>Your APK file (signed with either a release or debug key) is in your project {@code bin/}
+directory after you <a href="#Building">build your application</a>.</p>
+ <p>If there is more than one emulator running, you must specify the emulator upon which to
+install the application, by its serial number, with the <code>-s</code> option. For example:</p>
+ <pre>adb -s emulator-5554 install <em>/path/to/your/app</em>.apk</pre>
+ <p>To see a list of available device serial numbers, execute {@code adb devices}.</p>
</li>
</ol>
-<p>If you don't see your application on the emulator. Try restarting the emulator
-(with the same AVD). Sometimes when you install an Activity for the
+<p>If you don't see your application on the emulator. Try closing the emulator and launching the
+virtual device again from the SDK and AVD Manager. Sometimes when you install an Activity for the
first time, it won't show up in the application launcher or be accessible by other
applications. This is because the package manager usually examines manifests
completely only on emulator startup.</p>
-<p class="note"><strong>Tip:</strong> If you have only one emulator running,
+<p>Be certain to create multiple AVDs upon which to test your application. You should have one AVD
+for each platform and screen type with which your application is compatible. For
+instance, if your application compiles against the Android 1.5 (API Level 3) platform, you should
+create an AVD for each platform equal to and greater than 1.5 and an AVD for each <a
+href="{@docRoot}guide/practices/screens_support.html">screen type</a> you support, then test
+your application on each one.</p>
+
+<p class="note"><strong>Tip:</strong> If you have <em>only one</em> emulator running,
you can build your application and install it on the emulator in one simple step.
Navigate to the root of your project directory and use Ant to compile the project
with <em>install mode</em>:
-<code>ant install</code>. This will build your application, sign it with the debug key,
-and install it on the currently running emulator.
-If there is more than one emulator currently running
-when using the <code>install</code> command, it will fail — it can't select between the
-multiple emulators.</p>
+<code>ant install</code>. This will build your application, sign it with the debug key,
+and install it on the currently running emulator.</p>
+
+
+<h3 id="RunningOnDevice">Running on a device</h3>
+
+<p>Before you can run your application on a device, you must perform some basic setup for your
+device:</p>
+
+<ul>
+ <li>Declare your application as debuggable in your manifest</li>
+ <li>Enable USB Debugging on your device</li>
+ <li>Ensure that your development computer can detect your device when connected via USB</li>
+</ul>
+<p>Read <a href="{@docRoot}guide/developing/device.html#setting-up">Setting up a Device for
+Development</a> for more information.</p>
+
+<p>Once your device is set up and connected via USB, navigate to your
+SDK's <code>tools/</code> directory and install the <code>.apk</code> on the device:
+ <pre>adb -d install <em>/path/to/your/app</em>.apk</pre>
+ <p>The {@code -d} flag specifies that you want to use the attached device (in case you also
+have an emulator running).</p>
+
+
<p>For more information on the tools used above, please see the following documents:</p>
<ul>
diff --git a/docs/html/sdk/installing.jd b/docs/html/sdk/installing.jd
index 1099c3c..73190a0 100644
--- a/docs/html/sdk/installing.jd
+++ b/docs/html/sdk/installing.jd
@@ -361,7 +361,7 @@
</tr>
<tr>
<td style="width:2em;border-bottom-color:white;"></td>
-<td colspan="2"><code><platform>/</code></td>
+<td colspan="2"><code><em><platform></em>/</code></td>
<td>Platform version directory, for example "android-1.6". All platform version
directories contain a similar set of files and subdirectory structure.</td>
</tr>
@@ -439,11 +439,11 @@
<p><strong>Set up the Hello World application</strong></p>
<ul>
- <li>If you have just installed the SDK for the first time, <a
- href="{@docRoot}resources/tutorials/hello-world.html">go to the Hello
+ <li>If you have just installed the SDK for the first time, go to the <a
+ href="{@docRoot}resources/tutorials/hello-world.html">Hello
World tutorial</a>. The tutorial takes you step-by-step through the process
of setting up your first Android project, including setting up an Android
- Virtual Device (AVD) on which to run the application.
+ Virtual Device (AVD) on which to run the application.
</li>
</ul>
@@ -473,6 +473,8 @@
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>
+ <li>Read <a href="{@docRoot}guide/developing/device.html">Developing on a Device</a> to set up an
+Android-powered device to run and test your application.</li>
</ul>
<p><strong>Follow the Notepad tutorial</strong></p>