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