Google Git
Sign in
chromium / chromium / src / c75738d04722240738c153373364bec17917573b / . / docs / android_debugging_instructions.md
blob: 1102fbfcc2fef47727111b58b8a3bc8c821b61c6 [file] [log] [blame] [view]
nyquistc75738d2016-09-13 19:25:01[diff] [blame^]1# Android Debugging Instructions
2
3Chrome on Android has java and c/c++ code. Each "side" have its own set of tools
4for debugging. Here's some tips.
5
6[TOC]
7
8## Setting up command line flags
9
10Various commands below requires setting up command line flags.
11
12```shell
13# Content shell
14build/android/adb_content_shell_command_line --flags --to-pass
15# Chromium test shell
16build/android/adb_chrome_shell_command_line --flags --to-pass
17```
18
19## Launching the app
20
21You can launch the app by using one of the wrappers. You can pass URLs directly
22too.
23
24```shell
25# Content shell
26build/android/adb_run_content_shell 'data:text/html;utf-8,<html>Hello World!</html>'
27# Chromium test shell
28build/android/adb_run_chrome_shell 'data:text/html;utf-8,<html>Hello World!</html>'
29```
30
31## Log output
32
33[Chromium logging from LOG(INFO)](https://chromium.googlesource.com/chromium/src/+/master/docs/android_logging.md)
34etc., is directed to the Android logcat logging facility. You can filter the
35messages, e.g. view chromium verbose logging, everything else at warning level
36with:
37
38```shell
39adb logcat chromium:V cr.SomeComponent:V *:W
40```
41
42### Warnings for Blink developers
43
44* **Do not use fprintf or printf debugging!** This does not
45 redirect to logcat.
46
47* Redirecting stdio to logcat, as documented
48 [here](https://developer.android.com/studio/command-line/logcat.html#viewingStd),
49 has a bad side-effect that it breaks `adb_install.py`. See
50 [here for details](http://stackoverflow.com/questions/28539676/android-adb-fails-to-install-apk-to-nexus-5-on-windows-8-1).
51
52## Take a screenshot
53
54While your phone is plugged into USB, use the `screenshot.py` tool in
55`build/android`. `envsetup.sh` should have put it in your path.
56
57```shell
58build/android/screenshot.py /tmp/screenshot.png
59```
60
61## Inspecting the view hierarchy
62
63You can use either
64[hierarchy viewer](https://developer.android.com/studio/profile/hierarchy-viewer-setup.html)
65or [monitor](https://developer.android.com/studio/profile/monitor.html) to see
66the Android view hierarchy and see the layout and drawing properties associated
67with it.
68
69While your phone is plugged into USB, you can inspect the Android view hierarchy
70using the following command:
71
72```shell
73ANDROID_HVPROTO=ddm monitor
74```
75
76Setting `ANDROID_HVPROTO` allows you to inspect debuggable apps on non-rooted
77devices. When building a local version of Chromium, the build tools
78automatically add `android:debuggable=true` to the `AndroidManifest.xml`, which
79will allow you to inspect them on rooted devices.
80
81Want to add some additional information to your Views? You can do that by
82adding the
83[@ViewDebug.ExportedProperty](https://developer.android.com/reference/android/view/ViewDebug.ExportedProperty.html)
84annotation.
85
86Example:
87
88```java
89@ViewDebug.ExportedProperty(category="chrome")
90private int mSuperNiftyDrawingProperty;
91```
92
93## Debugging Java
94
95* In Eclipse, make a debug configuration of type "Remote Java Application".
96 Choose a "Name" and set "Port" to `8700`.
97
98* Make sure Eclipse Preferences > Run/Debug > Launching > "Build (if required)
99 before launching" is unchecked.
100
101* Run Android Device Monitor:
102
103 ```shell
104 third_party/android_tools/sdk/tools/monitor
105 ```
106
107* Now select the process you want to debug in Device Monitor (the port column
108 should now mention 8700 or xxxx/8700).
109
110* Run your debug configuration, and switch to the Debug perspective.
111
112## Waiting for Java Debugger on Early Startup
113
114* To debug early startup, pass `--wait-for-java-debugger` as a command line
115 flag.
116
117## Debugging C/C++
118
119Under `build/android`, there are a few scripts:
120
121```shell
122# Convenient wrappers
123build/android/adb_gdb_content_shell
124build/android/adb_gdb_chrome_shell
125
126# Underlying script, try --help for comprehensive list of options
127build/android/adb_gdb
128```
129
130By default, these wrappers will attach to the browser process.
131
132You can also attach to the renderer process by using `--sandboxed`. (You might
133need to be root on the phone for that. Run `adb root` if needed)
134
135## Waiting for Debugger on Early Startup
136
137Set the target command line flag with `--wait-for-debugger`.
138
139Launch the debugger using one of the `adb_gdb` scripts from above.
140
141Type `info threads` and look for a line like:
142
143```
14411 Thread 2564 clock_gettime () at bionic/libc/arch-arm/syscalls/clock_gettime.S:11
145```
146
147or perhaps:
148
149```
1501 Thread 10870 0x40127050 in nanosleep () from /tmp/user-adb-gdb-libs/system/lib/libc.so
151```
152
153We need to jump out of its sleep routine:
154
155```
156(gdb) thread 11
157(gdb) up
158(gdb) up
159(gdb) return
160Make base::debug::BreakDebugger() return now? (y or n) y
161(gdb) continue
162```
163
164## Symbolizing Crash Stacks and Tombstones (C++)
165
166If a crash has generated a tombstone in your device, use:
167
168```shell
169build/android/tombstones.py --output-directory out/Default
170```
171
172If you have a stack trace (from `adb logcat`) that needs to be symbolized, copy
173it into a text file and symbolize with the following command (run from
174`${CHROME_SRC}`):
175
176```shell
177third_party/android_platform/development/scripts/stack --output-directory out/Default [tombstone file | dump file]
178```
179
180`stack` can also take its input from `stdin`:
181
182```shell
183adb logcat -d | third_party/android_platform/development/scripts/stack --output-directory out/Default
184```
185
186Example:
187
188```shell
189third_party/android_platform/development/scripts/stack --output-directory out/Default ~/crashlogs/tombstone_07-build231.txt
190```
191
192## Deobfuscating Stack Traces (Java)
193
194You will need the ProGuard mapping file that was generated when the application
195that crashed was built. When building locally, these are found in:
196
197```shell
198out/Default/apks/ChromePublic.apk.mapping
199out/Default/apks/Chrome.apk.mapping
200```
201
202To deobfuscate a stack trace from a file, run
203
204```shell
205build/android/stacktrace/java_deobfuscate.py PROGUARD_MAPPING_FILE.mapping --stacktrace STACKTRACE_FILE
206```
207
208Deobfuscation also works from `stdin`:
209
210```shell
211adb logcat -d | build/android/stacktrace/java_deobfuscate.py PROGUARD_MAPPING_FILE.mapping
212```
213
214## Get WebKit code to output to the adb log
215
216In your build environment:
217
218```shell
219adb root
220adb shell stop
221adb shell setprop log.redirect-stdio true
222adb shell start
223```
224
225In the source itself, use `fprintf(stderr, "message");` whenever you need to
226output a message.
227
228## Debug unit tests with GDB
229
230To run unit tests use the following command:
231
232```shell
233out/Debug/bin/run_test_name -f <test_filter_if_any> --test-arguments=--wait-for-debugger -t 6000
234```
235
236That command will cause the test process to wait until a debugger is attached.
237
238To attach a debugger:
239
240```shell
241build/android/adb_gdb --output-directory=out/Default --package-name=org.chromium.native_test
242```
243
244After attaching gdb to the process you can use it normally. For example:
245
246```
247(gdb) break main
248Breakpoint 1 at 0x9750793c: main. (2 locations)
249(gdb) continue
250```