From 6261d879e79280a3a90bedbf4ffd78e5d4a267a2 Mon Sep 17 00:00:00 2001 From: Scott Main Date: Fri, 15 Jan 2010 17:26:29 -0800 Subject: [PATCH] docs: add a section about debugging web pages with the Console APIs; revise and cleanup some of the other content. Bug: 2353529 --- docs/html/guide/developing/debug-tasks.jd | 273 +++++++++++++--------- 1 file changed, 169 insertions(+), 104 deletions(-) diff --git a/docs/html/guide/developing/debug-tasks.jd b/docs/html/guide/developing/debug-tasks.jd index 3279741aab646..975f6998a75f0 100644 --- a/docs/html/guide/developing/debug-tasks.jd +++ b/docs/html/guide/developing/debug-tasks.jd @@ -6,7 +6,8 @@ page.title=Debugging Tasks

In this document

  1. Tools
    2. -
  2. Debug and Test Settings
    3. +
  3. Debug with Dev Tools
    4. +
  4. Debugging Web Pages
  5. Top Debugging Tips
  6. Configuring Your IDE to Attach to the Debugging Port
@@ -17,178 +18,242 @@ page.title=Debugging Tasks

Tools

-

The Android SDK includes a fairly extensive set of tools to help you debug your programs:

- - -

Also, see the Troubleshooting section - of the doc to figure out why your application isn't appearing on the emulator, - or why it's not starting.

+

For more information about all the development tools provided with the Android SDK, see the Tools document.

+

In addition to the above tools, you may also find the following useful for debugging: +

+
Eclipse ADT +plugin
+
The ADT Plugin for Eclipse integrates a number of the Android development tools (ADB, DDMS, +logcat output, and other functionality), so that you won't work with them directly but will utilize +them through the Eclipse IDE.
+
Developer Settings in the Dev Tools app
+
The Dev Tools application included in the emulator system image exposes several settings + that provide useful information such as CPU usage and frame rate. See Debugging and Testing with Dev Tools below.
+
-

Debug and Test Settings

+

Debugging and Testing with Dev Tools

-

With the Dev Tools application, you can turn on a number of settings that will make it easier to test - and debug your applications. To get to the development settings page on the emulator, launch the - Dev Tools application and open Development Settings. - This will open the development settings page with the following options (among - others):

- + can happen during debugging. + +

These settings will be remembered across emulator restarts.

+

Debugging Web Pages

+ +

If you're developing a web application for Android devices, you can debug your JavaScript on +Android using the Console APIs, which will output messages to logcat. If you're familiar +debugging web pages with Firefox's FireBug or WebKit's Web Inspector, then you're probably familiar +with the Console APIs. The Android Browser (and {@link android.webkit.WebChromeClient}) supports +most of the same APIs.

+ +

When you call a function from the Console APIs (in the DOM's {@code window.console} object), +you will see the output in logcat as a warning. For example, if your web page +executes the following JavaScript:

+
+console.log("Hello World");
+
+

Then the logcat output from the Android Browser will look like this:

+
+W/browser ( 202): Console: Hello World :0
+
+ +

Note: All Console messages from the Android +Browser are tagged with the name "browser" on Android platforms running API Level 7 or higher and +tagged with the name "WebCore" for platforms running API Level 6 or lower.

+ +

Not all of the Console APIs available in Firefox or other WebKit browsers are implemented +on Android. Mostly, you need to depend on basic text logging provided by +functions like {@code console.log(String)}, {@code console.info(String)}, {@code +console.warn(String)}, and {@code console.error(String)}. Although other Console functions may not +be implemented, they will not raise run-time errors, but will simply not behave as you might +expect.

+ +

If you've implemented a custom {@link android.webkit.WebView} in your application, then in order +to receive messages that are sent through the Console APIs, you must provide a {@link +android.webkit.WebChromeClient} that implements the {@link +android.webkit.WebChromeClient#onConsoleMessage(String,int,String) onConsoleMessage()} callback +method. For example, assuming that the {@code myWebView} field references the {@link +android.webkit.WebView} in your application, you can log debug messages like this:

+
+myWebView.setWebChromeClient(new WebChromeClient() {
+  public void onConsoleMessage(String message, int lineNumber, String sourceID) {
+    Log.d("MyApplication", message);
+  }
+});
+
+

The {@link android.webkit.WebChromeClient#onConsoleMessage(String,int,String) +onConsoleMessage()} method will be called each time one of the Console methods is called from +within your {@link android.webkit.WebView}.

+

When the "Hello World" log is executed through your {@link android.webkit.WebView}, it will +now look like this:

+
+D/MyApplication ( 430): Hello World
+
+ +

Note: The {@link +android.webkit.WebChromeClient#onConsoleMessage(String,int,String) onConsoleMessage()} callback +method was added with API Level 7. If you are targetting platforms running API Level 6 or lower, +then your Console messages will automatically be sent to logcat with the "WebCore" logging tag.

+ + + +

Top Debugging Tips

- +
-
Quick stack dump
+
Dump the stack trace
To obtain a stack dump from emulator, you can log in with adb shell, use "ps" to find the process you want, and then "kill -3 ". The stack trace appears in the log file.
-
Displaying useful info on the emulator screen
+
Display useful info on the emulator screen
The device can display useful information such as CPU usage or highlights around redrawn areas. Turn these features on and off in the developer settings window as described in Setting debug and test configurations on the emulator.
-
Getting system state information from the emulator (dumpstate)
+
Get system state information from the emulator (dumpstate)
You can access dumpstate information from the Dalvik Debug Monitor Service tool. See dumpsys and dumpstate on the adb topic page.
-
Getting application state information from the emulator (dumpsys)
+
Get application state information from the emulator (dumpsys)
You can access dumpsys information from the Dalvik Debug Monitor Service tool. See dumpsys and dumpstate on the adb topic page.
-
Getting wireless connectivity information
+
Get wireless connectivity information
You can get information about wireless connectivity using the Dalvik Debug Monitor Service tool. From the Device menu, select "Dump radio state".
-
Logging Trace Data
+
Log trace data
You can log method calls and other tracing data in an activity by calling -android.os.Debug.startMethodTracing(). See Running the Traceview Debugging Program for details.
-
Logging Radio Data
+
Log radio data
By default, radio information is not logged to the system (it is a lot of data). However, you can enable radio logging using the following commands: -
+
 adb shell
 logcat -b radio
-
Running adb
-
Android ships with a tool called adb that provides various capabilities, including -moving and syncing files to the emulator, forwarding ports, and running a UNIX -shell on the emulator. See Using adb for details.
- -
Getting screen captures from the emulator
-
Dalvik Debug Monitor Server (DDMS) can capture screenshots from the emulator.
- - - - -
Using debugging helper classes
+
Capture screenshots
+
The Dalvik Debug Monitor Server (DDMS) can capture screenshots from the emulator. Select +Device > Screen capture.
+
Use debugging helper classes
Android provides debug helper classes such as {@link android.util.Log util.Log} and {@link android.os.Debug} for your convenience.
+

Also see the Troubleshooting document +for answers to some common developing and debugging issues.

+ +

Configuring Your IDE to Attach to the Debugging Port

DDMS will assign a specific debugging port to every virtual machine that it