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