Google Git
Sign in
chromium / chromium / src / a350dbdbfe91f9f2be20b8946d4352194e839d9e / . / docs / android_debugging_instructions.md
blob: 3c4eba2abd9c5ec8d129d6da98600e93962cd117 [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
agrievea350dbdb2017-07-05 15:27:17[diff] [blame^]206out/Default/apks/ChromeModernPublic.apk.mapping
207etc.
nyquistc75738d2016-09-13 19:25:01[diff] [blame]208```
209
agrievea350dbdb2017-07-05 15:27:17[diff] [blame^]210Build the `java_deobfuscate` tool:
nyquistc75738d2016-09-13 19:25:01[diff] [blame]211
212```shell
agrievea350dbdb2017-07-05 15:27:17[diff] [blame^]213ninja -C out/Default java_deobfuscate
nyquistc75738d2016-09-13 19:25:01[diff] [blame]214```
215
agrievea350dbdb2017-07-05 15:27:17[diff] [blame^]216Then run it via:
nyquistc75738d2016-09-13 19:25:01[diff] [blame]217
218```shell
agrievea350dbdb2017-07-05 15:27:17[diff] [blame^]219# For a file:
220out/Default/bin/java_deobfuscate PROGUARD_MAPPING_FILE.mapping < FILE
221# For logcat:
222adb logcat | out/Default/bin/java_deobfuscate PROGUARD_MAPPING_FILE.mapping
nyquistc75738d2016-09-13 19:25:01[diff] [blame]223```
224
225## Get WebKit code to output to the adb log
226
227In your build environment:
228
229```shell
230adb root
231adb shell stop
232adb shell setprop log.redirect-stdio true
233adb shell start
234```
235
236In the source itself, use `fprintf(stderr, "message");` whenever you need to
237output a message.
238
239## Debug unit tests with GDB
240
241To run unit tests use the following command:
242
243```shell
jbudorick6a94be32017-05-11 22:38:43[diff] [blame]244out/Debug/bin/run_test_name -f <test_filter_if_any> --wait-for-debugger -t 6000
nyquistc75738d2016-09-13 19:25:01[diff] [blame]245```
246
247That command will cause the test process to wait until a debugger is attached.
248
249To attach a debugger:
250
251```shell
252build/android/adb_gdb --output-directory=out/Default --package-name=org.chromium.native_test
253```
254
255After attaching gdb to the process you can use it normally. For example:
256
257```
258(gdb) break main
259Breakpoint 1 at 0x9750793c: main. (2 locations)
260(gdb) continue
261```