Google Git
Sign in
chromium / chromium / src / 93b8eb80e9ab9f5286497be2b826fc389d32c619 / . / docs / android_debugging_instructions.md
blob: 3596bf2df6a78cc1e40c3d805128c98dd1caef48 [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
David Van Clevee0021d32020-01-29 16:02:58[diff] [blame]28If this doesn't display the logs you're looking for, try `adb logcat` with your system `adb`
29or the one in `//third_party/android_sdk/`.
30
nyquistc75738d2016-09-13 19:25:01[diff] [blame]31### Warnings for Blink developers
nyquistc75738d2016-09-13 19:25:01[diff] [blame]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
agrievee453b98f2018-10-22 14:17:17[diff] [blame]40## Take a Screenshot
nyquistc75738d2016-09-13 19:25:01[diff] [blame]41```shell
42build/android/screenshot.py /tmp/screenshot.png
43```
44
agrievee453b98f2018-10-22 14:17:17[diff] [blame]45## Inspecting the View Hierarchy
46Generate an [Android Studio](android_studio.md) project, and then use
47[Layout Inspector](https://developer.android.com/studio/debug/layout-inspector).
nyquistc75738d2016-09-13 19:25:01[diff] [blame]48
49## Debugging Java
Andrew Grieve4fe99742017-11-23 19:43:16[diff] [blame]50For both apk and test targets, pass `--wait-for-java-debugger` to the wrapper
51scripts.
52
53Examples:
54
55```shell
56# Install, launch, and wait:
57out/Default/bin/chrome_public_apk run --wait-for-java-debugger
58
59# Launch, and have GPU process wait rather than Browser process:
60out/Default/bin/chrome_public_apk launch --wait-for-java-debugger --debug-process-name privileged_process0
61
62# Have Renderers wait:
63out/Default/bin/chrome_public_apk launch --args="--renderer-wait-for-java-debugger"
64
65# Have tests wait:
66out/Default/bin/run_chrome_public_test_apk --wait-for-java-debugger
67out/Default/bin/run_chrome_junit_tests --wait-for-java-debugger # Specify custom port via --debug-socket=9999
68```
69
70### Android Studio
71* Open Android Studio ([instructions](android_studio.md))
72* Click "Run"->"Attach debugger to Android process" (see
Wei-Yin Chen (陳威尹)0f8750b32017-12-08 21:42:15[diff] [blame]73[here](https://developer.android.com/studio/debug/index.html) for more).
agrievee453b98f2018-10-22 14:17:17[diff] [blame]74* Click "Run"->"Attach to Local Process..." for Robolectric junit tests.
Andrew Grieve4fe99742017-11-23 19:43:16[diff] [blame]75
estevenson8c9318ff2017-03-10 22:16:35[diff] [blame]76### Eclipse
nyquistc75738d2016-09-13 19:25:01[diff] [blame]77* In Eclipse, make a debug configuration of type "Remote Java Application".
78 Choose a "Name" and set "Port" to `8700`.
79
80* Make sure Eclipse Preferences > Run/Debug > Launching > "Build (if required)
81 before launching" is unchecked.
82
83* Run Android Device Monitor:
84
85 ```shell
Yun Liuf57cceaf2019-03-18 21:31:23[diff] [blame]86 third_party/android_sdk/public/tools/monitor
nyquistc75738d2016-09-13 19:25:01[diff] [blame]87 ```
88
89* Now select the process you want to debug in Device Monitor (the port column
90 should now mention 8700 or xxxx/8700).
91
92* Run your debug configuration, and switch to the Debug perspective.
93
nyquistc75738d2016-09-13 19:25:01[diff] [blame]94## Debugging C/C++
agrievee453b98f2018-10-22 14:17:17[diff] [blame]95While the app is running, use the wrapper script's `gdb` command to enter into a
96gdb shell.
nyquistc75738d2016-09-13 19:25:01[diff] [blame]97
agrievee453b98f2018-10-22 14:17:17[diff] [blame]98When running with gdb attached, the app runs **extremely slowly**.
nyquistc75738d2016-09-13 19:25:01[diff] [blame]99
100```shell
Andrew Grieve4fe99742017-11-23 19:43:16[diff] [blame]101# Attaches to browser process.
Andrew Grievec81af4a2017-07-26 18:02:13[diff] [blame]102out/Default/bin/content_shell_apk gdb
103out/Default/bin/chrome_public_apk gdb
Andrew Grieve4fe99742017-11-23 19:43:16[diff] [blame]104
105# Attaches to gpu process.
106out/Default/bin/chrome_public_apk gdb --debug-process-name privileged_process0
107
108# Attach to other processes ("chrome_public_apk ps" to show pids).
109out/Default/bin/chrome_public_apk gdb --pid $PID
nyquistc75738d2016-09-13 19:25:01[diff] [blame]110```
111
agrievee453b98f2018-10-22 14:17:17[diff] [blame]112When connecting, gdb will complain of not being able to load a lot of libraries.
113This happens because of java code. The following messages are all expected:
114```
115Connecting to :5039...
116warning: Could not load shared library symbols for 211 libraries, e.g. /system/framework/arm/boot.oat.
117Use the "info sharedlibrary" command to see the complete listing.
118Do you need "set solib-search-path" or "set sysroot"?
119Failed to read a valid object file image from memory.
120```
121
Stefan Zagere2b55cc2019-10-04 19:57:54[diff] [blame]122If you have ever run an ASAN build of chromium on the device, you may get
123an error like the following when you start up gdb:
124```
125/tmp/<username>-adb-gdb-tmp-<pid>/gdb.init:11: Error in sourced command file:
126"/tmp/<username>-adb-gdb-tmp-<pid>/app_process32": not in executable format: file format not recognized
127```
128If this happens, run the following command and try again:
129```shell
130$ src/android/asan/third_party/asan_device_setup.sh --revert
131```
132
agrievee453b98f2018-10-22 14:17:17[diff] [blame]133### Using Visual Studio Code
134While the app is running, run the `gdb` command with `--ide`:
135
136```shell
137out/Default/bin/content_shell_apk gdb --ide
138```
139
140Once the script has done its thing (generally ~1 second after the initial
141time its used), open [vscode.md](vscode.md) and ensure you have the
142[Android launch entry](vscode.md#Launch-Commands).
143
144Connect via the IDE's launch entry. Connecting takes 30-40 seconds.
145
146When troubleshooting, it's helpful to enable
147[engine logging](https://github.com/Microsoft/vscode-cpptools/blob/master/launch.md#enginelogging).
148
149Known Issues:
150 * Pretty printers are not working properly.
151
Andrew Grieve4fe99742017-11-23 19:43:16[diff] [blame]152### Waiting for Debugger on Early Startup
agrievee453b98f2018-10-22 14:17:17[diff] [blame]153```shell
154# Install, launch, and wait:
155out/Default/bin/chrome_public_apk run --args="--wait-for-debugger"
156# Launch, and have GPU process wait rather than Browser process:
157out/Default/bin/chrome_public_apk launch --args="--wait-for-debugger-children=gpu-process"
158# Or for renderers:
159out/Default/bin/chrome_public_apk launch --args="--wait-for-debugger-children=renderer"
nyquistc75738d2016-09-13 19:25:01[diff] [blame]160```
161
agrievee453b98f2018-10-22 14:17:17[diff] [blame]162#### With an IDE
163Once `gdb` attaches, the app will resume execution, so you must set your
164breakpoint before attaching.
nyquistc75738d2016-09-13 19:25:01[diff] [blame]165
agrievee453b98f2018-10-22 14:17:17[diff] [blame]166#### With Command-line GDB
167Once attached, gdb will drop into a prompt. Set your breakpoints and run "c" to
168continue.
nyquistc75738d2016-09-13 19:25:01[diff] [blame]169
170## Symbolizing Crash Stacks and Tombstones (C++)
171
172If a crash has generated a tombstone in your device, use:
173
174```shell
175build/android/tombstones.py --output-directory out/Default
176```
177
178If you have a stack trace (from `adb logcat`) that needs to be symbolized, copy
179it into a text file and symbolize with the following command (run from
180`${CHROME_SRC}`):
181
182```shell
183third_party/android_platform/development/scripts/stack --output-directory out/Default [tombstone file | dump file]
184```
185
186`stack` can also take its input from `stdin`:
187
188```shell
189adb logcat -d | third_party/android_platform/development/scripts/stack --output-directory out/Default
190```
191
192Example:
193
194```shell
195third_party/android_platform/development/scripts/stack --output-directory out/Default ~/crashlogs/tombstone_07-build231.txt
196```
197
198## Deobfuscating Stack Traces (Java)
199
200You will need the ProGuard mapping file that was generated when the application
201that crashed was built. When building locally, these are found in:
202
203```shell
204out/Default/apks/ChromePublic.apk.mapping
agrievea350dbdb2017-07-05 15:27:17[diff] [blame]205out/Default/apks/ChromeModernPublic.apk.mapping
206etc.
nyquistc75738d2016-09-13 19:25:01[diff] [blame]207```
208
Sami Kyostila3269af12019-07-02 19:02:45[diff] [blame]209When debugging a failing test on the build waterfall, you can find the mapping
210file as follows:
211
2121. Open buildbot page for the failing build (e.g.,
213 https://ci.chromium.org/p/chrome/builders/ci/android-go-perf/1234).
2142. Open the swarming page for the failing shard (e.g., shard #3).
2153. Click on "Isolated Inputs" to locate the files the shard used to run the
216 test.
2174. Download the `.mapping` file for the APK used by the test (e.g.,
218 `ChromePublic.apk.mapping`). Note that you may need to use the
Takuto Ikuta93b8eb802020-01-30 12:11:28[diff] [blame^]219 `tools/luci-go/isolated` to download the mapping file if it's too big. The
220 viewer will provide instructions for this.
Sami Kyostila3269af12019-07-02 19:02:45[diff] [blame]221
Andrew Grieveabcac41a2019-08-14 17:16:18[diff] [blame]222**Googlers Only**: For official build mapping files, see
223[go/chromejavadeobfuscation](https://goto.google.com/chromejavadeobfuscation).
224
225Once you have a .mapping file, build the `java_deobfuscate` tool:
nyquistc75738d2016-09-13 19:25:01[diff] [blame]226
227```shell
agrievea350dbdb2017-07-05 15:27:17[diff] [blame]228ninja -C out/Default java_deobfuscate
nyquistc75738d2016-09-13 19:25:01[diff] [blame]229```
230
agrievea350dbdb2017-07-05 15:27:17[diff] [blame]231Then run it via:
nyquistc75738d2016-09-13 19:25:01[diff] [blame]232
233```shell
agrievea350dbdb2017-07-05 15:27:17[diff] [blame]234# For a file:
235out/Default/bin/java_deobfuscate PROGUARD_MAPPING_FILE.mapping < FILE
236# For logcat:
237adb logcat | out/Default/bin/java_deobfuscate PROGUARD_MAPPING_FILE.mapping
nyquistc75738d2016-09-13 19:25:01[diff] [blame]238```
239
240## Get WebKit code to output to the adb log
241
242In your build environment:
243
244```shell
245adb root
246adb shell stop
247adb shell setprop log.redirect-stdio true
248adb shell start
249```
250
251In the source itself, use `fprintf(stderr, "message");` whenever you need to
252output a message.
253
254## Debug unit tests with GDB
255
256To run unit tests use the following command:
257
258```shell
jbudorick6a94be32017-05-11 22:38:43[diff] [blame]259out/Debug/bin/run_test_name -f <test_filter_if_any> --wait-for-debugger -t 6000
nyquistc75738d2016-09-13 19:25:01[diff] [blame]260```
261
262That command will cause the test process to wait until a debugger is attached.
263
264To attach a debugger:
265
266```shell
267build/android/adb_gdb --output-directory=out/Default --package-name=org.chromium.native_test
268```
269
270After attaching gdb to the process you can use it normally. For example:
271
272```
273(gdb) break main
274Breakpoint 1 at 0x9750793c: main. (2 locations)
275(gdb) continue
276```