From 629c34ee1879454f72b82a82bca2f5cac7f7b3ce Mon Sep 17 00:00:00 2001 From: Ricardo Cervera Date: Thu, 27 Mar 2014 17:14:35 -0700 Subject: docs: Added a document on debugging in Android Studio Change-Id: I073e1db6d7976db0f658aac4aa377877ed931aa2 --- docs/html/images/tools/as-android.png | Bin 0 -> 1058 bytes docs/html/images/tools/as-breakpointline.png | Bin 0 -> 3545 bytes docs/html/images/tools/as-breakpointswindow.png | Bin 0 -> 45098 bytes docs/html/images/tools/as-capture.png | Bin 0 -> 422 bytes docs/html/images/tools/as-currentproc.png | Bin 0 -> 574 bytes docs/html/images/tools/as-ddmslog.png | Bin 0 -> 122022 bytes docs/html/images/tools/as-debugbutton.png | Bin 0 -> 687 bytes docs/html/images/tools/as-debugdevices.png | Bin 0 -> 30598 bytes docs/html/images/tools/as-debugview.png | Bin 0 -> 150250 bytes docs/html/images/tools/as-debugwindowbutton.png | Bin 0 -> 1153 bytes docs/html/images/tools/as-devicecapture.png | Bin 0 -> 33660 bytes docs/html/images/tools/as-evalexpbutton.png | Bin 0 -> 299 bytes docs/html/images/tools/as-launchavdm.png | Bin 0 -> 286 bytes docs/html/images/tools/as-monitorbutton.png | Bin 0 -> 400 bytes docs/html/images/tools/as-record.png | Bin 0 -> 328 bytes docs/html/images/tools/as-restart.png | Bin 0 -> 518 bytes docs/html/images/tools/as-resumeprogrambutton.png | Bin 0 -> 491 bytes docs/html/images/tools/as-showdevview.png | Bin 0 -> 399 bytes docs/html/images/tools/as-stepintobutton.png | Bin 0 -> 429 bytes docs/html/images/tools/as-stepoutbutton.png | Bin 0 -> 432 bytes docs/html/images/tools/as-stepoverbutton.png | Bin 0 -> 471 bytes docs/html/images/tools/as-variablesview.png | Bin 0 -> 32682 bytes docs/html/images/tools/as-varviewbutton.png | Bin 0 -> 207 bytes docs/html/images/tools/as-viewbreakbutton.png | Bin 0 -> 657 bytes docs/html/sdk/installing/studio-debug.jd | 346 ++++++++++++++++++++++ docs/html/tools/tools_toc.cs | 2 + 26 files changed, 348 insertions(+) create mode 100644 docs/html/images/tools/as-android.png create mode 100644 docs/html/images/tools/as-breakpointline.png create mode 100644 docs/html/images/tools/as-breakpointswindow.png create mode 100644 docs/html/images/tools/as-capture.png create mode 100644 docs/html/images/tools/as-currentproc.png create mode 100644 docs/html/images/tools/as-ddmslog.png create mode 100644 docs/html/images/tools/as-debugbutton.png create mode 100644 docs/html/images/tools/as-debugdevices.png create mode 100644 docs/html/images/tools/as-debugview.png create mode 100644 docs/html/images/tools/as-debugwindowbutton.png create mode 100644 docs/html/images/tools/as-devicecapture.png create mode 100644 docs/html/images/tools/as-evalexpbutton.png create mode 100644 docs/html/images/tools/as-launchavdm.png create mode 100644 docs/html/images/tools/as-monitorbutton.png create mode 100644 docs/html/images/tools/as-record.png create mode 100644 docs/html/images/tools/as-restart.png create mode 100644 docs/html/images/tools/as-resumeprogrambutton.png create mode 100644 docs/html/images/tools/as-showdevview.png create mode 100644 docs/html/images/tools/as-stepintobutton.png create mode 100644 docs/html/images/tools/as-stepoutbutton.png create mode 100644 docs/html/images/tools/as-stepoverbutton.png create mode 100644 docs/html/images/tools/as-variablesview.png create mode 100644 docs/html/images/tools/as-varviewbutton.png create mode 100644 docs/html/images/tools/as-viewbreakbutton.png create mode 100644 docs/html/sdk/installing/studio-debug.jd diff --git a/docs/html/images/tools/as-android.png b/docs/html/images/tools/as-android.png new file mode 100644 index 0000000..7808ed1 Binary files /dev/null and b/docs/html/images/tools/as-android.png differ diff --git a/docs/html/images/tools/as-breakpointline.png b/docs/html/images/tools/as-breakpointline.png new file mode 100644 index 0000000..9aea880 Binary files /dev/null and b/docs/html/images/tools/as-breakpointline.png differ diff --git a/docs/html/images/tools/as-breakpointswindow.png b/docs/html/images/tools/as-breakpointswindow.png new file mode 100644 index 0000000..a40b459 Binary files /dev/null and b/docs/html/images/tools/as-breakpointswindow.png differ diff --git a/docs/html/images/tools/as-capture.png b/docs/html/images/tools/as-capture.png new file mode 100644 index 0000000..02f9f6f Binary files /dev/null and b/docs/html/images/tools/as-capture.png differ diff --git a/docs/html/images/tools/as-currentproc.png b/docs/html/images/tools/as-currentproc.png new file mode 100644 index 0000000..4be8305 Binary files /dev/null and b/docs/html/images/tools/as-currentproc.png differ diff --git a/docs/html/images/tools/as-ddmslog.png b/docs/html/images/tools/as-ddmslog.png new file mode 100644 index 0000000..b53b8fe Binary files /dev/null and b/docs/html/images/tools/as-ddmslog.png differ diff --git a/docs/html/images/tools/as-debugbutton.png b/docs/html/images/tools/as-debugbutton.png new file mode 100644 index 0000000..55e95d1 Binary files /dev/null and b/docs/html/images/tools/as-debugbutton.png differ diff --git a/docs/html/images/tools/as-debugdevices.png b/docs/html/images/tools/as-debugdevices.png new file mode 100644 index 0000000..09a9d0e Binary files /dev/null and b/docs/html/images/tools/as-debugdevices.png differ diff --git a/docs/html/images/tools/as-debugview.png b/docs/html/images/tools/as-debugview.png new file mode 100644 index 0000000..0349147 Binary files /dev/null and b/docs/html/images/tools/as-debugview.png differ diff --git a/docs/html/images/tools/as-debugwindowbutton.png b/docs/html/images/tools/as-debugwindowbutton.png new file mode 100644 index 0000000..9016778 Binary files /dev/null and b/docs/html/images/tools/as-debugwindowbutton.png differ diff --git a/docs/html/images/tools/as-devicecapture.png b/docs/html/images/tools/as-devicecapture.png new file mode 100644 index 0000000..3236a89 Binary files /dev/null and b/docs/html/images/tools/as-devicecapture.png differ diff --git a/docs/html/images/tools/as-evalexpbutton.png b/docs/html/images/tools/as-evalexpbutton.png new file mode 100644 index 0000000..85b3c74 Binary files /dev/null and b/docs/html/images/tools/as-evalexpbutton.png differ diff --git a/docs/html/images/tools/as-launchavdm.png b/docs/html/images/tools/as-launchavdm.png new file mode 100644 index 0000000..bf15981 Binary files /dev/null and b/docs/html/images/tools/as-launchavdm.png differ diff --git a/docs/html/images/tools/as-monitorbutton.png b/docs/html/images/tools/as-monitorbutton.png new file mode 100644 index 0000000..6bdc3a5 Binary files /dev/null and b/docs/html/images/tools/as-monitorbutton.png differ diff --git a/docs/html/images/tools/as-record.png b/docs/html/images/tools/as-record.png new file mode 100644 index 0000000..5f7fa99 Binary files /dev/null and b/docs/html/images/tools/as-record.png differ diff --git a/docs/html/images/tools/as-restart.png b/docs/html/images/tools/as-restart.png new file mode 100644 index 0000000..12d2923 Binary files /dev/null and b/docs/html/images/tools/as-restart.png differ diff --git a/docs/html/images/tools/as-resumeprogrambutton.png b/docs/html/images/tools/as-resumeprogrambutton.png new file mode 100644 index 0000000..8096937 Binary files /dev/null and b/docs/html/images/tools/as-resumeprogrambutton.png differ diff --git a/docs/html/images/tools/as-showdevview.png b/docs/html/images/tools/as-showdevview.png new file mode 100644 index 0000000..602a6ad Binary files /dev/null and b/docs/html/images/tools/as-showdevview.png differ diff --git a/docs/html/images/tools/as-stepintobutton.png b/docs/html/images/tools/as-stepintobutton.png new file mode 100644 index 0000000..569d4ed Binary files /dev/null and b/docs/html/images/tools/as-stepintobutton.png differ diff --git a/docs/html/images/tools/as-stepoutbutton.png b/docs/html/images/tools/as-stepoutbutton.png new file mode 100644 index 0000000..ef8871f Binary files /dev/null and b/docs/html/images/tools/as-stepoutbutton.png differ diff --git a/docs/html/images/tools/as-stepoverbutton.png b/docs/html/images/tools/as-stepoverbutton.png new file mode 100644 index 0000000..1c487df Binary files /dev/null and b/docs/html/images/tools/as-stepoverbutton.png differ diff --git a/docs/html/images/tools/as-variablesview.png b/docs/html/images/tools/as-variablesview.png new file mode 100644 index 0000000..6a0b987 Binary files /dev/null and b/docs/html/images/tools/as-variablesview.png differ diff --git a/docs/html/images/tools/as-varviewbutton.png b/docs/html/images/tools/as-varviewbutton.png new file mode 100644 index 0000000..2ad4c58 Binary files /dev/null and b/docs/html/images/tools/as-varviewbutton.png differ diff --git a/docs/html/images/tools/as-viewbreakbutton.png b/docs/html/images/tools/as-viewbreakbutton.png new file mode 100644 index 0000000..22723d4 Binary files /dev/null and b/docs/html/images/tools/as-viewbreakbutton.png differ diff --git a/docs/html/sdk/installing/studio-debug.jd b/docs/html/sdk/installing/studio-debug.jd new file mode 100644 index 0000000..7e2efe3 --- /dev/null +++ b/docs/html/sdk/installing/studio-debug.jd @@ -0,0 +1,346 @@ +page.title=Debugging with Android Studio + +@jd:body + +
+ +
+ +

Android Studio enables you to debug apps running on the emulator or on an Android device. +With Android Studio, you can:

+ + + +

To debug your app, Android Studio builds a debuggable version of your app, connects +to a device or to the emulator, installs the app and runs it. The IDE shows the system log +while your app is running and provides debugging tools to filter log messages, work with +breakpoints, and control the execution flow.

+ + +

Run your App in Debug Mode

+ +
+ +

Figure 1. The Choose Device window enables you to + select a physical Android device or a virtual device to debug your app.

+
+ +

To run your app in debug mode, you build an APK signed with a debug key and install it on a +physical Android device or on the Android emulator. +To set up an Android device for development, see Using +Hardware Devices. For more information about the emulator provided by the Android SDK, see +Using the Emulator.

+ +

To debug your app in Android Studio:

+ +
    +
  1. Open your project in Android Studio.
    2. +
  2. Click Debug in the toolbar.
    3. +
  3. On the Choose Device window, select a hardware device from the list or + choose a virtual device.
    4. +
  4. Click OK. Your app starts on the selected device.
    5. +
+ +

Figure 1 shows the Choose Device window. The list shows all the Android devices +connected to your computer. Select Launch Emulator to use an Android virtual device +instead. Click the ellipsis to open the +Android Virtual Device Manager.

+ +

Android Studio opens the Debug tool window when you debug your app. To open the +Debug window manually, click Debug +. +This window shows threads and variables in the Debugger tab, the device status in the +Console tab, and the system log in the Logcat tab. The Debug tool +window also provides other debugging tools covered in the following sections.

+ + +

Figure 2. The Debug tool window in Android Studio showing +the current thread and the object tree for a variable.

+ + +

Use the System Log

+ +

The system log shows system messages while you debug your app. These messages include +information from apps running on the device. If you want to use the +system log to debug your app, make sure your code writes log messages and prints the stack +trace for exceptions while your app is in the development phase.

+ +

Write log messages in your code

+ +

To write log messages in your code, use the {@link android.util.Log} class. Log messages +help you understand the execution flow by collecting the system debug output while you interact +with your app. Log messages can tell you what part of your application failed. For more +information about logging, see +Reading and Writing Logs.

+ +

The following example shows how you might add log messages to determine if previous state +information is available when your activity starts:

+ +
+import android.util.Log;
+...
+public class MyActivity extends Activity {
+    private static final String TAG = MyActivity.class.getSimpleName();
+    ...
+    @Override
+    public void onCreate(Bundle savedInstanceState) {
+        if (savedInstanceState != null) {
+            Log.d(TAG, "onCreate() Restoring previous state");
+            /* restore state */
+        } else {
+            Log.d(TAG, "onCreate() No saved state available");
+            /* initialize app */
+        }
+    }
+}
+
+ +

During development, your code can also catch exceptions and write the stack trace to the system +log:

+ +
+void someOtherMethod() {
+    try {
+        ...
+    } catch (SomeException e) {
+        Log.d(TAG, "someOtherMethod()", e);
+    }
+}
+
+ +

Note: Remove debug log messages and stack trace print calls from +your code when you are ready to publish your app. You could do this by setting a DEBUG +flag and placing debug log messages inside conditional statements.

+ + +

View the system log

+ +

Both the Android DDMS (Dalvik Debug Monitor Server) and the Debug tool windows +show the system log; however, the Android DDMS tool window lets you view only log messages +for a particular process. To view the system log on the Android DDMS tool window:

+ +
    +
  1. Start your app as described in Run your App in Debug Mode.
    2. +
  2. Click Android to open the Android DDMS + tool window.
    3. +
  3. If the system log is empty in the Logcat view, click Restart + .
    4. +
+ + +

Figure 4. The system log in the Android DDMS tool +window.

+ +

The Android DDMS tool window gives you access to some DDMS features from Android Studio. +For more information about DDMS, see Using DDMS. +

+ +

The system log shows messages from Android services and other Android apps. To filter the log +messages to view only the ones you are interested in, use the tools in the Android DDMS +window:

+ + + + +

Work with Breakpoints

+ +

Breakpoints enable you to pause the execution of your app at a particular line of code, examine +variables, evaluate expressions, and continue the execution line by line. Use breakpoints to +determine the causes of run-time errors that you can't fix by looking at your code only. To debug +your app using breakpoints:

+ +
    +
  1. Open the source file in which you want to set a breakpoint.
    2. +
  2. Locate the line where you want to set a breakpoint and click on it.
    3. +
  3. Click on the yellow portion of the side bar to the left of this line, as shown in figure 5.
    4. +
  4. Start your app as described in Run your App in Debug Mode.
    5. +
+ +

Android Studio pauses the execution of your app when it reaches the breakpoint. You can then +use the tools in the Debug tool window to identify the cause of the error.

+ + +

Figure 5. A red dot appears next to the line when you set +a breakpoint.

+ +

View and configure breakpoints

+ +

To view all the breakpoints and configure breakpoint settings, click View +Breakpoints on the left side of the Debug tool +window. The Breakpoints window appears, as shown in figure 6.

+ + +

Figure 6. The Breakpoints window lists all the current +breakpoints and includes behavior settings for each.

+ +

The Breakpoints window lets you enable or disable each breakpoint from the +list on the left. If a breakpoint is disabled, Android Studio does not pause your app when +it hits that breakpoint. Select a breakpoint from the list to configure its settings. +You can configure a breakpoint to be disabled at first and have the system enable it after a +different breakpoint is hit. You can also configure whether a breakpoint should be disabled after +it is hit. To set a breakpoint for any exception, select Exception Breakpoints +in the list of breakpoints.

+ +

Debug your app with breakpoints

+ +

After you set breakpoints in your code, click Rerun + to start the app again. When a breakpoint is +hit, Android Studio pauses the app and highlights the breakpoint in the source code. The +Debug tool window lets you examine variables and control the execution step by +step:

+ + + + +

Figure 7. The Variables view in the Debug tool window.

+ + +

Analyze Runtime Metrics to Optimize your App

+ +

Even if your application does not generate runtime errors, this does not mean it is free of +problems. You should also consider the following issues:

+ + + +

The Android Device Monitor is a stand-alone tool with a graphical user interface for serveral +Android application debugging and analysis tools, including the Dalvik Debug Monitor Server (DDMS). +You can use the Android Device Monitor to analyze memory usage, profile methods, +monitor network traffic and simulate incoming calls and messages.

+ +

To open the Android Device Monitor from Android Studio, click +Monitor on the toolbar. The Android Device Monitor +opens in a new window.

+ +

For more information about the Android Device Monitor and DDMS, see +Device Monitor and +Using DDMS.

+ + +

Capture Screenshots and Videos

+ +

Android Studio enables you to capture a screenshot or a short video of the device screen +while your app is running. Screenshots and videos are useful as promotional materials for your +app, and you can also attach them to bug reports that you send to your development team.

+ +

To take a screenshot of your app:

+ +
    +
  1. Start your app as described in Run your App in Debug Mode.
    2. +
  2. Click Android to open the Android DDMS + tool window.
    3. +
  3. Click Screen Capture on the left side of the + Android DDMS tool window.
    4. +
  4. Optional: To add a device frame around your screenshot, enable the Frame screenshot + option.
    5. +
  5. Click Save.
    6. +
+ +

To take a video recording of your app:

+ +
    +
  1. Start your app as described in Run your App in Debug Mode.
    2. +
  2. Click Android to open the Android DDMS + tool window.
    3. +
  3. Click Screen Record on the left side of the + Android DDMS tool window.
    4. +
  4. Click Start Recording.
    5. +
  5. Interact with your app.
    6. +
  6. Click Stop Recording.
    7. +
  7. Enter a file name for the recording and click OK.
    8. +
\ No newline at end of file diff --git a/docs/html/tools/tools_toc.cs b/docs/html/tools/tools_toc.cs index c281644..b29b87c 100644 --- a/docs/html/tools/tools_toc.cs +++ b/docs/html/tools/tools_toc.cs @@ -38,6 +38,8 @@ Using the Layout Editor
  • Building Your Project with Gradle
    • +
  • + Debugging with Android Studio
  • -- cgit v1.1