Google Git
Sign in
chromium / chromium / src / lkgr / . / docs / android_debugging_instructions.md
blob: f687b9c833a9b9ce6d345aa09793482033a600a7 [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
Chris Harrelson66168c072025-01-06 18:42:10[diff] [blame]38 redirect to adb logcat. Use `LOG(ERROR)` etc. instead.
39 See also the "Get Blink code to output to the adb log" section.
nyquistc75738d2016-09-13 19:25:01[diff] [blame]40
41* Redirecting stdio to logcat, as documented
42 [here](https://developer.android.com/studio/command-line/logcat.html#viewingStd),
Chris Harrelson66168c072025-01-06 18:42:10[diff] [blame]43 has a bad side-effect in that it breaks `adb_install.py`. See
nyquistc75738d2016-09-13 19:25:01[diff] [blame]44 [here for details](http://stackoverflow.com/questions/28539676/android-adb-fails-to-install-apk-to-nexus-5-on-windows-8-1).
45
agrievee453b98f2018-10-22 14:17:17[diff] [blame]46## Take a Screenshot
nyquistc75738d2016-09-13 19:25:01[diff] [blame]47```shell
48build/android/screenshot.py /tmp/screenshot.png
49```
50
agrievee453b98f2018-10-22 14:17:17[diff] [blame]51## Inspecting the View Hierarchy
52Generate an [Android Studio](android_studio.md) project, and then use
53[Layout Inspector](https://developer.android.com/studio/debug/layout-inspector).
nyquistc75738d2016-09-13 19:25:01[diff] [blame]54
55## Debugging Java
Andrew Grieve4fe99742017-11-23 19:43:16[diff] [blame]56For both apk and test targets, pass `--wait-for-java-debugger` to the wrapper
57scripts.
58
59Examples:
60
61```shell
62# Install, launch, and wait:
63out/Default/bin/chrome_public_apk run --wait-for-java-debugger
64
65# Launch, and have GPU process wait rather than Browser process:
66out/Default/bin/chrome_public_apk launch --wait-for-java-debugger --debug-process-name privileged_process0
67
68# Have Renderers wait:
69out/Default/bin/chrome_public_apk launch --args="--renderer-wait-for-java-debugger"
70
71# Have tests wait:
72out/Default/bin/run_chrome_public_test_apk --wait-for-java-debugger
73out/Default/bin/run_chrome_junit_tests --wait-for-java-debugger # Specify custom port via --debug-socket=9999
74```
75
76### Android Studio
77* Open Android Studio ([instructions](android_studio.md))
78* Click "Run"->"Attach debugger to Android process" (see
Wei-Yin Chen (陳威尹)0f8750b32017-12-08 21:42:15[diff] [blame]79[here](https://developer.android.com/studio/debug/index.html) for more).
agrievee453b98f2018-10-22 14:17:17[diff] [blame]80* Click "Run"->"Attach to Local Process..." for Robolectric junit tests.
Andrew Grievef189506012022-06-20 18:48:45[diff] [blame]81 * 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]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
Yun Liuf57cceaf2019-03-18 21:31:23[diff] [blame]93 third_party/android_sdk/public/tools/monitor
nyquistc75738d2016-09-13 19:25:01[diff] [blame]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
nyquistc75738d2016-09-13 19:25:01[diff] [blame]101## Debugging C/C++
Andrew Grieveb445bdfb2023-11-27 16:35:28[diff] [blame]102While the app is running, use the wrapper script's `lldb` command to enter into a
103lldb shell.
nyquistc75738d2016-09-13 19:25:01[diff] [blame]104
Andrew Grieveb445bdfb2023-11-27 16:35:28[diff] [blame]105When running with `lldb` attached, the app runs **extremely slowly**.
nyquistc75738d2016-09-13 19:25:01[diff] [blame]106
107```shell
Andrew Grieve4fe99742017-11-23 19:43:16[diff] [blame]108# Attaches to browser process.
Andrew Grieveb445bdfb2023-11-27 16:35:28[diff] [blame]109out/Default/bin/content_shell_apk lldb
110out/Default/bin/chrome_public_apk lldb
Andrew Grieve4fe99742017-11-23 19:43:16[diff] [blame]111
112# Attaches to gpu process.
Andrew Grieveb445bdfb2023-11-27 16:35:28[diff] [blame]113out/Default/bin/chrome_public_apk lldb --debug-process-name privileged_process0
Andrew Grieve4fe99742017-11-23 19:43:16[diff] [blame]114
115# Attach to other processes ("chrome_public_apk ps" to show pids).
Andrew Grieveb445bdfb2023-11-27 16:35:28[diff] [blame]116out/Default/bin/chrome_public_apk lldb --pid $PID
Stefan Zagere2b55cc2019-10-04 19:57:54[diff] [blame]117```
118
agrievee453b98f2018-10-22 14:17:17[diff] [blame]119### Using Visual Studio Code
agrievee453b98f2018-10-22 14:17:17[diff] [blame]120
Andrew Grieveb445bdfb2023-11-27 16:35:28[diff] [blame]121**NOT WORKING**
agrievee453b98f2018-10-22 14:17:17[diff] [blame]122
Andrew Grieveb445bdfb2023-11-27 16:35:28[diff] [blame]123This used to work with GDB, but the LLDB instructions have not been written. If
124you would like to take this on, please use:
125[crbug/1266055](https://bugs.chromium.org/p/chromium/issues/detail?id=1266055).
agrievee453b98f2018-10-22 14:17:17[diff] [blame]126
Andrew Grieve4fe99742017-11-23 19:43:16[diff] [blame]127### Waiting for Debugger on Early Startup
agrievee453b98f2018-10-22 14:17:17[diff] [blame]128```shell
129# Install, launch, and wait:
130out/Default/bin/chrome_public_apk run --args="--wait-for-debugger"
131# Launch, and have GPU process wait rather than Browser process:
132out/Default/bin/chrome_public_apk launch --args="--wait-for-debugger-children=gpu-process"
133# Or for renderers:
134out/Default/bin/chrome_public_apk launch --args="--wait-for-debugger-children=renderer"
nyquistc75738d2016-09-13 19:25:01[diff] [blame]135```
136
Andrew Grieveb445bdfb2023-11-27 16:35:28[diff] [blame]137#### With Command-line LLDB
138Once attached, `lldb` will drop into a prompt. Set your breakpoints and run "c" to
agrievee453b98f2018-10-22 14:17:17[diff] [blame]139continue.
nyquistc75738d2016-09-13 19:25:01[diff] [blame]140
141## Symbolizing Crash Stacks and Tombstones (C++)
142
143If a crash has generated a tombstone in your device, use:
144
145```shell
146build/android/tombstones.py --output-directory out/Default
147```
148
149If you have a stack trace (from `adb logcat`) that needs to be symbolized, copy
150it into a text file and symbolize with the following command (run from
151`${CHROME_SRC}`):
152
153```shell
154third_party/android_platform/development/scripts/stack --output-directory out/Default [tombstone file | dump file]
155```
156
157`stack` can also take its input from `stdin`:
158
159```shell
160adb logcat -d | third_party/android_platform/development/scripts/stack --output-directory out/Default
161```
162
163Example:
164
165```shell
166third_party/android_platform/development/scripts/stack --output-directory out/Default ~/crashlogs/tombstone_07-build231.txt
167```
168
169## Deobfuscating Stack Traces (Java)
170
171You will need the ProGuard mapping file that was generated when the application
172that crashed was built. When building locally, these are found in:
173
174```shell
175out/Default/apks/ChromePublic.apk.mapping
agrievea350dbdb2017-07-05 15:27:17[diff] [blame]176etc.
nyquistc75738d2016-09-13 19:25:01[diff] [blame]177```
178
Sami Kyostila3269af12019-07-02 19:02:45[diff] [blame]179When debugging a failing test on the build waterfall, you can find the mapping
180file as follows:
181
1821. Open buildbot page for the failing build (e.g.,
183 https://ci.chromium.org/p/chrome/builders/ci/android-go-perf/1234).
1842. Open the swarming page for the failing shard (e.g., shard #3).
1853. Click on "Isolated Inputs" to locate the files the shard used to run the
186 test.
1874. Download the `.mapping` file for the APK used by the test (e.g.,
188 `ChromePublic.apk.mapping`). Note that you may need to use the
Takuto Ikuta93b8eb802020-01-30 12:11:28[diff] [blame]189 `tools/luci-go/isolated` to download the mapping file if it's too big. The
190 viewer will provide instructions for this.
Sami Kyostila3269af12019-07-02 19:02:45[diff] [blame]191
Andrew Grieveabcac41a2019-08-14 17:16:18[diff] [blame]192**Googlers Only**: For official build mapping files, see
193[go/chromejavadeobfuscation](https://goto.google.com/chromejavadeobfuscation).
194
Andrew Grieve17a59652020-03-19 18:14:53[diff] [blame]195Once you have a .mapping file:
nyquistc75738d2016-09-13 19:25:01[diff] [blame]196
197```shell
agrievea350dbdb2017-07-05 15:27:17[diff] [blame]198# For a file:
Andrew Grieve17a59652020-03-19 18:14:53[diff] [blame]199build/android/stacktrace/java_deobfuscate.py PROGUARD_MAPPING_FILE.mapping < FILE
agrievea350dbdb2017-07-05 15:27:17[diff] [blame]200# For logcat:
Andrew Grieve17a59652020-03-19 18:14:53[diff] [blame]201adb logcat | build/android/stacktrace/java_deobfuscate.py PROGUARD_MAPPING_FILE.mapping
nyquistc75738d2016-09-13 19:25:01[diff] [blame]202```
203
Chris Harrelson66168c072025-01-06 18:42:10[diff] [blame]204## Get Blink code to output to the adb log
nyquistc75738d2016-09-13 19:25:01[diff] [blame]205
206In your build environment:
207
208```shell
209adb root
210adb shell stop
211adb shell setprop log.redirect-stdio true
212adb shell start
213```
214
Chris Harrelson66168c072025-01-06 18:42:10[diff] [blame]215In the source itself, use `LOG(ERROR),` `LOG(INFO)`, etc. whenever you need to
216output a message, and it will be automatically redirected to adb logcat.
217Running `adb logcat chromium:E`, for example, will show all log lines from
218`LOG(ERROR)` (plus others that match "chromium").
nyquistc75738d2016-09-13 19:25:01[diff] [blame]219
Andrew Grieveb445bdfb2023-11-27 16:35:28[diff] [blame]220## Debug unit tests with LLDB
nyquistc75738d2016-09-13 19:25:01[diff] [blame]221
222To run unit tests use the following command:
223
224```shell
jbudorick6a94be32017-05-11 22:38:43[diff] [blame]225out/Debug/bin/run_test_name -f <test_filter_if_any> --wait-for-debugger -t 6000
nyquistc75738d2016-09-13 19:25:01[diff] [blame]226```
227
228That command will cause the test process to wait until a debugger is attached.
229
230To attach a debugger:
231
232```shell
Andrew Grieveb445bdfb2023-11-27 16:35:28[diff] [blame]233build/android/connect_lldb.sh --output-directory=out/Default --package-name=org.chromium.native_test
nyquistc75738d2016-09-13 19:25:01[diff] [blame]234```
Klaus Weidnerffc475b82022-11-04 17:55:08[diff] [blame]235
236## Examine app data on a non-rooted device
237
238If you're developing on a non-rooted device such as a retail phone, security restrictions
239will prevent directly accessing the application's data. However, as long as the app is
240built with debugging enabled, you can use `adb shell run-as PACKAGENAME` to execute
241shell commands using the app's authorization, roughly equivalent to `su $user`.
242
243Non-Play-Store builds with `is_official_build=false` will by default set
244`android:debuggable="true"` in the app's manifest to allow debugging.
245
246For exammple, for a Chromium build, run the following:
247
248```
249adb shell run-as org.chromium.chrome
250```
251
252If successful, this will silently wait for input without printing anything.
253It acts as a simple shell despite not showing the usual `$ ` shell prompt.
254Just type commands and press RETURN to execute them.
255
256The starting directory is the app's user data directory where user preferences and other
257profile data are stored.
258
259```
260pwd
261/data/user/0/org.chromium.chrome
262
263find -type f
264./files/rList
265./shared_prefs/org.chromium.chrome_preferences.xml
266```
267
268If you need to access the app's application data directory, you need to look up the
269obfuscated installation path since you don't have read access to the */data/app/* directory.
270For example:
271
272```
273pm list packages -f org.chromium.chrome
274package:/data/app/~~ybTygSP5u72F9GN-3TMKXA==/org.chromium.chrome-zYY5mcB7YgB5pa3vfS3CBQ==/base.apk=org.chromium.chrome
275
276ls -l /data/app/~~ybTygSP5u72F9GN-3TMKXA==/org.chromium.chrome-zYY5mcB7YgB5pa3vfS3CBQ==/
277total 389079
278-rw-r--r-- 1 system system 369634375 2022-11-05 01:49 base.apk
279drwxr-xr-x 3 system system 3452 2022-11-05 01:49 lib
Klaus Weidnerffc475b82022-11-04 17:55:08[diff] [blame]280-rw-r--r-- 1 system system 786666 2022-11-05 01:49 split_cablev2_authenticator.apk
281-rw-r--r-- 1 system system 21258500 2022-11-05 01:49 split_chrome.apk
282-rw-r--r-- 1 system system 1298934 2022-11-05 01:49 split_config.en.apk
283-rw-r--r-- 1 system system 413913 2022-11-05 01:49 split_dev_ui.apk
284-rw-r--r-- 1 system system 12432 2022-11-05 01:49 split_weblayer.apk
Andrew Grieveb445bdfb2023-11-27 16:35:28[diff] [blame]285```