Google Git
Sign in
chromium / chromium / src.git / fafb67d05a69c02a39a451f36a169bd76f10f453 / . / docs / android_debugging_instructions.md
blob: fbb4f98041385e2be5954afa973e2f53166c9f75 [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
estevenson8c9318ff2017-03-10 22:16:35[diff] [blame]95### Eclipse
nyquistc75738d2016-09-13 19:25:01[diff] [blame]96* In Eclipse, make a debug configuration of type "Remote Java Application".
97 Choose a "Name" and set "Port" to `8700`.
98
99* Make sure Eclipse Preferences > Run/Debug > Launching > "Build (if required)
100 before launching" is unchecked.
101
102* Run Android Device Monitor:
103
104 ```shell
105 third_party/android_tools/sdk/tools/monitor
106 ```
107
108* Now select the process you want to debug in Device Monitor (the port column
109 should now mention 8700 or xxxx/8700).
110
111* Run your debug configuration, and switch to the Debug perspective.
112
estevenson8c9318ff2017-03-10 22:16:35[diff] [blame]113### Android Studio
114* Build and install the desired target
115
116* Click the "Attach debugger to Android process" (see
117[here](https://developer.android.com/studio/debug/index.html) for more)
118
nyquistc75738d2016-09-13 19:25:01[diff] [blame]119## Waiting for Java Debugger on Early Startup
120
121* To debug early startup, pass `--wait-for-java-debugger` as a command line
122 flag.
123
124## Debugging C/C++
125
126Under `build/android`, there are a few scripts:
127
128```shell
129# Convenient wrappers
130build/android/adb_gdb_content_shell
131build/android/adb_gdb_chrome_shell
132
133# Underlying script, try --help for comprehensive list of options
134build/android/adb_gdb
135```
136
137By default, these wrappers will attach to the browser process.
138
139You can also attach to the renderer process by using `--sandboxed`. (You might
140need to be root on the phone for that. Run `adb root` if needed)
141
142## Waiting for Debugger on Early Startup
143
144Set the target command line flag with `--wait-for-debugger`.
145
146Launch the debugger using one of the `adb_gdb` scripts from above.
147
148Type `info threads` and look for a line like:
149
150```
15111 Thread 2564 clock_gettime () at bionic/libc/arch-arm/syscalls/clock_gettime.S:11
152```
153
154or perhaps:
155
156```
1571 Thread 10870 0x40127050 in nanosleep () from /tmp/user-adb-gdb-libs/system/lib/libc.so
158```
159
160We need to jump out of its sleep routine:
161
162```
163(gdb) thread 11
164(gdb) up
165(gdb) up
166(gdb) return
167Make base::debug::BreakDebugger() return now? (y or n) y
168(gdb) continue
169```
170
171## Symbolizing Crash Stacks and Tombstones (C++)
172
173If a crash has generated a tombstone in your device, use:
174
175```shell
176build/android/tombstones.py --output-directory out/Default
177```
178
179If you have a stack trace (from `adb logcat`) that needs to be symbolized, copy
180it into a text file and symbolize with the following command (run from
181`${CHROME_SRC}`):
182
183```shell
184third_party/android_platform/development/scripts/stack --output-directory out/Default [tombstone file | dump file]
185```
186
187`stack` can also take its input from `stdin`:
188
189```shell
190adb logcat -d | third_party/android_platform/development/scripts/stack --output-directory out/Default
191```
192
193Example:
194
195```shell
196third_party/android_platform/development/scripts/stack --output-directory out/Default ~/crashlogs/tombstone_07-build231.txt
197```
198
199## Deobfuscating Stack Traces (Java)
200
201You will need the ProGuard mapping file that was generated when the application
202that crashed was built. When building locally, these are found in:
203
204```shell
205out/Default/apks/ChromePublic.apk.mapping
206out/Default/apks/Chrome.apk.mapping
207```
208
209To deobfuscate a stack trace from a file, run
210
211```shell
212build/android/stacktrace/java_deobfuscate.py PROGUARD_MAPPING_FILE.mapping --stacktrace STACKTRACE_FILE
213```
214
215Deobfuscation also works from `stdin`:
216
217```shell
218adb logcat -d | build/android/stacktrace/java_deobfuscate.py PROGUARD_MAPPING_FILE.mapping
219```
220
221## Get WebKit code to output to the adb log
222
223In your build environment:
224
225```shell
226adb root
227adb shell stop
228adb shell setprop log.redirect-stdio true
229adb shell start
230```
231
232In the source itself, use `fprintf(stderr, "message");` whenever you need to
233output a message.
234
235## Debug unit tests with GDB
236
237To run unit tests use the following command:
238
239```shell
jbudorick6a94be32017-05-11 22:38:43[diff] [blame]240out/Debug/bin/run_test_name -f <test_filter_if_any> --wait-for-debugger -t 6000
nyquistc75738d2016-09-13 19:25:01[diff] [blame]241```
242
243That command will cause the test process to wait until a debugger is attached.
244
245To attach a debugger:
246
247```shell
248build/android/adb_gdb --output-directory=out/Default --package-name=org.chromium.native_test
249```
250
251After attaching gdb to the process you can use it normally. For example:
252
253```
254(gdb) break main
255Breakpoint 1 at 0x9750793c: main. (2 locations)
256(gdb) continue
257```