Google Git
Sign in
chromium / chromium / src / e2b55cc55202bd9e34e991931deaeb059fb01f23 / . / docs / android_debugging_instructions.md
blob: 92d964ee772873a5046125e861b68876a45fc34c [file] [log] [blame] [view]
nyquistc75738d2016-09-13 19:25:01[diff] [blame]1# Android Debugging Instructions
nyquistc75738d2016-09-13 19:25:01[diff] [blame]2Chrome on Android has java and c/c++ code. Each "side" have its own set of tools
3for debugging. Here's some tips.
4
5[TOC]
6
agrievee453b98f2018-10-22 14:17:17[diff] [blame]7## Launching
8You can run the app by using one of the wrappers.
nyquistc75738d2016-09-13 19:25:01[diff] [blame]9
10```shell
agrievee453b98f2018-10-22 14:17:17[diff] [blame]11# Installs, launches, and enters logcat.
12out/Default/bin/content_shell_apk run --args='--disable-fre' 'data:text/html;utf-8,<html>Hello World!</html>'
13# Launches without first installing. Does not show logcat.
14out/Default/bin/chrome_public_apk launch --args='--disable-fre' 'data:text/html;utf-8,<html>Hello World!</html>'
nyquistc75738d2016-09-13 19:25:01[diff] [blame]15```
16
agrievee453b98f2018-10-22 14:17:17[diff] [blame]17## Logging
nyquistc75738d2016-09-13 19:25:01[diff] [blame]18[Chromium logging from LOG(INFO)](https://chromium.googlesource.com/chromium/src/+/master/docs/android_logging.md)
19etc., is directed to the Android logcat logging facility. You can filter the
20messages, e.g. view chromium verbose logging, everything else at warning level
21with:
22
23```shell
agrievee453b98f2018-10-22 14:17:17[diff] [blame]24# Shows a coloured & filtered logcat.
25out/Default/bin/chrome_public_apk logcat [-v] # Use -v to show logs for other processes
nyquistc75738d2016-09-13 19:25:01[diff] [blame]26```
27
28### Warnings for Blink developers
nyquistc75738d2016-09-13 19:25:01[diff] [blame]29* **Do not use fprintf or printf debugging!** This does not
30 redirect to logcat.
31
32* Redirecting stdio to logcat, as documented
33 [here](https://developer.android.com/studio/command-line/logcat.html#viewingStd),
34 has a bad side-effect that it breaks `adb_install.py`. See
35 [here for details](http://stackoverflow.com/questions/28539676/android-adb-fails-to-install-apk-to-nexus-5-on-windows-8-1).
36
agrievee453b98f2018-10-22 14:17:17[diff] [blame]37## Take a Screenshot
nyquistc75738d2016-09-13 19:25:01[diff] [blame]38```shell
39build/android/screenshot.py /tmp/screenshot.png
40```
41
agrievee453b98f2018-10-22 14:17:17[diff] [blame]42## Inspecting the View Hierarchy
43Generate an [Android Studio](android_studio.md) project, and then use
44[Layout Inspector](https://developer.android.com/studio/debug/layout-inspector).
nyquistc75738d2016-09-13 19:25:01[diff] [blame]45
46## Debugging Java
Andrew Grieve4fe99742017-11-23 19:43:16[diff] [blame]47For both apk and test targets, pass `--wait-for-java-debugger` to the wrapper
48scripts.
49
50Examples:
51
52```shell
53# Install, launch, and wait:
54out/Default/bin/chrome_public_apk run --wait-for-java-debugger
55
56# Launch, and have GPU process wait rather than Browser process:
57out/Default/bin/chrome_public_apk launch --wait-for-java-debugger --debug-process-name privileged_process0
58
59# Have Renderers wait:
60out/Default/bin/chrome_public_apk launch --args="--renderer-wait-for-java-debugger"
61
62# Have tests wait:
63out/Default/bin/run_chrome_public_test_apk --wait-for-java-debugger
64out/Default/bin/run_chrome_junit_tests --wait-for-java-debugger # Specify custom port via --debug-socket=9999
65```
66
67### Android Studio
68* Open Android Studio ([instructions](android_studio.md))
69* Click "Run"->"Attach debugger to Android process" (see
Wei-Yin Chen (陳威尹)0f8750b32017-12-08 21:42:15[diff] [blame]70[here](https://developer.android.com/studio/debug/index.html) for more).
agrievee453b98f2018-10-22 14:17:17[diff] [blame]71* Click "Run"->"Attach to Local Process..." for Robolectric junit tests.
Andrew Grieve4fe99742017-11-23 19:43:16[diff] [blame]72
estevenson8c9318ff2017-03-10 22:16:35[diff] [blame]73### Eclipse
nyquistc75738d2016-09-13 19:25:01[diff] [blame]74* In Eclipse, make a debug configuration of type "Remote Java Application".
75 Choose a "Name" and set "Port" to `8700`.
76
77* Make sure Eclipse Preferences > Run/Debug > Launching > "Build (if required)
78 before launching" is unchecked.
79
80* Run Android Device Monitor:
81
82 ```shell
Yun Liuf57cceaf2019-03-18 21:31:23[diff] [blame]83 third_party/android_sdk/public/tools/monitor
nyquistc75738d2016-09-13 19:25:01[diff] [blame]84 ```
85
86* Now select the process you want to debug in Device Monitor (the port column
87 should now mention 8700 or xxxx/8700).
88
89* Run your debug configuration, and switch to the Debug perspective.
90
nyquistc75738d2016-09-13 19:25:01[diff] [blame]91## Debugging C/C++
agrievee453b98f2018-10-22 14:17:17[diff] [blame]92While the app is running, use the wrapper script's `gdb` command to enter into a
93gdb shell.
nyquistc75738d2016-09-13 19:25:01[diff] [blame]94
agrievee453b98f2018-10-22 14:17:17[diff] [blame]95When running with gdb attached, the app runs **extremely slowly**.
nyquistc75738d2016-09-13 19:25:01[diff] [blame]96
97```shell
Andrew Grieve4fe99742017-11-23 19:43:16[diff] [blame]98# Attaches to browser process.
Andrew Grievec81af4a2017-07-26 18:02:13[diff] [blame]99out/Default/bin/content_shell_apk gdb
100out/Default/bin/chrome_public_apk gdb
Andrew Grieve4fe99742017-11-23 19:43:16[diff] [blame]101
102# Attaches to gpu process.
103out/Default/bin/chrome_public_apk gdb --debug-process-name privileged_process0
104
105# Attach to other processes ("chrome_public_apk ps" to show pids).
106out/Default/bin/chrome_public_apk gdb --pid $PID
nyquistc75738d2016-09-13 19:25:01[diff] [blame]107```
108
agrievee453b98f2018-10-22 14:17:17[diff] [blame]109When connecting, gdb will complain of not being able to load a lot of libraries.
110This happens because of java code. The following messages are all expected:
111```
112Connecting to :5039...
113warning: Could not load shared library symbols for 211 libraries, e.g. /system/framework/arm/boot.oat.
114Use the "info sharedlibrary" command to see the complete listing.
115Do you need "set solib-search-path" or "set sysroot"?
116Failed to read a valid object file image from memory.
117```
118
Stefan Zagere2b55cc2019-10-04 19:57:54[diff] [blame^]119If you have ever run an ASAN build of chromium on the device, you may get
120an error like the following when you start up gdb:
121```
122/tmp/<username>-adb-gdb-tmp-<pid>/gdb.init:11: Error in sourced command file:
123"/tmp/<username>-adb-gdb-tmp-<pid>/app_process32": not in executable format: file format not recognized
124```
125If this happens, run the following command and try again:
126```shell
127$ src/android/asan/third_party/asan_device_setup.sh --revert
128```
129
agrievee453b98f2018-10-22 14:17:17[diff] [blame]130### Using Visual Studio Code
131While the app is running, run the `gdb` command with `--ide`:
132
133```shell
134out/Default/bin/content_shell_apk gdb --ide
135```
136
137Once the script has done its thing (generally ~1 second after the initial
138time its used), open [vscode.md](vscode.md) and ensure you have the
139[Android launch entry](vscode.md#Launch-Commands).
140
141Connect via the IDE's launch entry. Connecting takes 30-40 seconds.
142
143When troubleshooting, it's helpful to enable
144[engine logging](https://github.com/Microsoft/vscode-cpptools/blob/master/launch.md#enginelogging).
145
146Known Issues:
147 * Pretty printers are not working properly.
148
Andrew Grieve4fe99742017-11-23 19:43:16[diff] [blame]149### Waiting for Debugger on Early Startup
agrievee453b98f2018-10-22 14:17:17[diff] [blame]150```shell
151# Install, launch, and wait:
152out/Default/bin/chrome_public_apk run --args="--wait-for-debugger"
153# Launch, and have GPU process wait rather than Browser process:
154out/Default/bin/chrome_public_apk launch --args="--wait-for-debugger-children=gpu-process"
155# Or for renderers:
156out/Default/bin/chrome_public_apk launch --args="--wait-for-debugger-children=renderer"
nyquistc75738d2016-09-13 19:25:01[diff] [blame]157```
158
agrievee453b98f2018-10-22 14:17:17[diff] [blame]159#### With an IDE
160Once `gdb` attaches, the app will resume execution, so you must set your
161breakpoint before attaching.
nyquistc75738d2016-09-13 19:25:01[diff] [blame]162
agrievee453b98f2018-10-22 14:17:17[diff] [blame]163#### With Command-line GDB
164Once attached, gdb will drop into a prompt. Set your breakpoints and run "c" to
165continue.
nyquistc75738d2016-09-13 19:25:01[diff] [blame]166
167## Symbolizing Crash Stacks and Tombstones (C++)
168
169If a crash has generated a tombstone in your device, use:
170
171```shell
172build/android/tombstones.py --output-directory out/Default
173```
174
175If you have a stack trace (from `adb logcat`) that needs to be symbolized, copy
176it into a text file and symbolize with the following command (run from
177`${CHROME_SRC}`):
178
179```shell
180third_party/android_platform/development/scripts/stack --output-directory out/Default [tombstone file | dump file]
181```
182
183`stack` can also take its input from `stdin`: