1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
docs / android_debugging_instructions.md [blame]
# Android Debugging Instructions
Chrome on Android has java and c/c++ code. Each "side" have its own set of tools
for debugging. Here's some tips.
[TOC]
## Instructions for Google Employees
See also
[go/clankium/06-debugging-clank](https://goto.google.com/clankium/06-debugging-clank).
## Launching
You can run the app by using one of the wrappers.
```shell
# Installs, launches, and enters logcat.
out/Default/bin/content_shell_apk run --args='--disable-fre' 'data:text/html;utf-8,<html>Hello World!</html>'
# Launches without first installing. Does not show logcat.
out/Default/bin/chrome_public_apk launch --args='--disable-fre' 'data:text/html;utf-8,<html>Hello World!</html>'
```
## Logging
[Chromium logging from LOG(INFO)](https://chromium.googlesource.com/chromium/src/+/main/docs/android_logging.md)
etc., is directed to the Android logcat logging facility. You can filter the
messages, e.g. view chromium verbose logging, everything else at warning level
with:
```shell
# Shows a coloured & filtered logcat.
out/Default/bin/chrome_public_apk logcat [-v] # Use -v to show logs for other processes
```
If this doesn't display the logs you're looking for, try `adb logcat` with your system `adb`
or the one in `//third_party/android_sdk/`.
### Warnings for Blink developers
* **Do not use fprintf or printf debugging!** This does not
redirect to logcat.
* Redirecting stdio to logcat, as documented
[here](https://developer.android.com/studio/command-line/logcat.html#viewingStd),
has a bad side-effect that it breaks `adb_install.py`. See
[here for details](http://stackoverflow.com/questions/28539676/android-adb-fails-to-install-apk-to-nexus-5-on-windows-8-1).
## Take a Screenshot
```shell
build/android/screenshot.py /tmp/screenshot.png
```
## Inspecting the View Hierarchy
Generate an [Android Studio](android_studio.md) project, and then use
[Layout Inspector](https://developer.android.com/studio/debug/layout-inspector).
## Debugging Java
For both apk and test targets, pass `--wait-for-java-debugger` to the wrapper
scripts.
Examples:
```shell
# Install, launch, and wait:
out/Default/bin/chrome_public_apk run --wait-for-java-debugger
# Launch, and have GPU process wait rather than Browser process:
out/Default/bin/chrome_public_apk launch --wait-for-java-debugger --debug-process-name privileged_process0
# Have Renderers wait:
out/Default/bin/chrome_public_apk launch --args="--renderer-wait-for-java-debugger"
# Have tests wait:
out/Default/bin/run_chrome_public_test_apk --wait-for-java-debugger
out/Default/bin/run_chrome_junit_tests --wait-for-java-debugger # Specify custom port via --debug-socket=9999
```
### Android Studio
* Open Android Studio ([instructions](android_studio.md))
* Click "Run"->"Attach debugger to Android process" (see
[here](https://developer.android.com/studio/debug/index.html) for more).
* Click "Run"->"Attach to Local Process..." for Robolectric junit tests.
* If this fails, you likely need to follow [these instructions](https://stackoverflow.com/questions/21114066/attach-intellij-idea-debugger-to-a-running-java-process).
### Eclipse
* In Eclipse, make a debug configuration of type "Remote Java Application".
Choose a "Name" and set "Port" to `8700`.
* Make sure Eclipse Preferences > Run/Debug > Launching > "Build (if required)
before launching" is unchecked.
* Run Android Device Monitor:
```shell
third_party/android_sdk/public/tools/monitor
```
* Now select the process you want to debug in Device Monitor (the port column
should now mention 8700 or xxxx/8700).
* Run your debug configuration, and switch to the Debug perspective.
## Debugging C/C++
While the app is running, use the wrapper script's `lldb` command to enter into a
lldb shell.
When running with `lldb` attached, the app runs **extremely slowly**.
```shell
# Attaches to browser process.
out/Default/bin/content_shell_apk lldb
out/Default/bin/chrome_public_apk lldb
# Attaches to gpu process.
out/Default/bin/chrome_public_apk lldb --debug-process-name privileged_process0
# Attach to other processes ("chrome_public_apk ps" to show pids).
out/Default/bin/chrome_public_apk lldb --pid $PID
```
### Using Visual Studio Code
**NOT WORKING**
This used to work with GDB, but the LLDB instructions have not been written. If
you would like to take this on, please use:
[crbug/1266055](https://bugs.chromium.org/p/chromium/issues/detail?id=1266055).
### Waiting for Debugger on Early Startup
```shell
# Install, launch, and wait:
out/Default/bin/chrome_public_apk run --args="--wait-for-debugger"
# Launch, and have GPU process wait rather than Browser process:
out/Default/bin/chrome_public_apk launch --args="--wait-for-debugger-children=gpu-process"
# Or for renderers:
out/Default/bin/chrome_public_apk launch --args="--wait-for-debugger-children=renderer"
```
#### With Command-line LLDB
Once attached, `lldb` will drop into a prompt. Set your breakpoints and run "c" to
continue.
## Symbolizing Crash Stacks and Tombstones (C++)
If a crash has generated a tombstone in your device, use:
```shell
build/android/tombstones.py --output-directory out/Default
```
If you have a stack trace (from `adb logcat`) that needs to be symbolized, copy
it into a text file and symbolize with the following command (run from
`${CHROME_SRC}`):
```shell
third_party/android_platform/development/scripts/stack --output-directory out/Default [tombstone file | dump file]
```
`stack` can also take its input from `stdin`:
```shell
adb logcat -d | third_party/android_platform/development/scripts/stack --output-directory out/Default
```
Example:
```shell
third_party/android_platform/development/scripts/stack --output-directory out/Default ~/crashlogs/tombstone_07-build231.txt
```
## Deobfuscating Stack Traces (Java)
You will need the ProGuard mapping file that was generated when the application
that crashed was built. When building locally, these are found in:
```shell
out/Default/apks/ChromePublic.apk.mapping
etc.
```
When debugging a failing test on the build waterfall, you can find the mapping
file as follows:
1. Open buildbot page for the failing build (e.g.,
https://ci.chromium.org/p/chrome/builders/ci/android-go-perf/1234).
2. Open the swarming page for the failing shard (e.g., shard #3).
3. Click on "Isolated Inputs" to locate the files the shard used to run the
test.
4. Download the `.mapping` file for the APK used by the test (e.g.,
`ChromePublic.apk.mapping`). Note that you may need to use the
`tools/luci-go/isolated` to download the mapping file if it's too big. The
viewer will provide instructions for this.
**Googlers Only**: For official build mapping files, see
[go/chromejavadeobfuscation](https://goto.google.com/chromejavadeobfuscation).
Once you have a .mapping file:
```shell
# For a file:
build/android/stacktrace/java_deobfuscate.py PROGUARD_MAPPING_FILE.mapping < FILE
# For logcat:
adb logcat | build/android/stacktrace/java_deobfuscate.py PROGUARD_MAPPING_FILE.mapping
```
## Get WebKit code to output to the adb log
In your build environment:
```shell
adb root
adb shell stop
adb shell setprop log.redirect-stdio true
adb shell start
```
In the source itself, use `fprintf(stderr, "message");` whenever you need to
output a message.
## Debug unit tests with LLDB
To run unit tests use the following command:
```shell
out/Debug/bin/run_test_name -f <test_filter_if_any> --wait-for-debugger -t 6000
```
That command will cause the test process to wait until a debugger is attached.
To attach a debugger:
```shell
build/android/connect_lldb.sh --output-directory=out/Default --package-name=org.chromium.native_test
```
## Examine app data on a non-rooted device
If you're developing on a non-rooted device such as a retail phone, security restrictions
will prevent directly accessing the application's data. However, as long as the app is
built with debugging enabled, you can use `adb shell run-as PACKAGENAME` to execute
shell commands using the app's authorization, roughly equivalent to `su $user`.
Non-Play-Store builds with `is_official_build=false` will by default set
`android:debuggable="true"` in the app's manifest to allow debugging.
For exammple, for a Chromium build, run the following:
```
adb shell run-as org.chromium.chrome
```
If successful, this will silently wait for input without printing anything.
It acts as a simple shell despite not showing the usual `$ ` shell prompt.
Just type commands and press RETURN to execute them.
The starting directory is the app's user data directory where user preferences and other
profile data are stored.
```
pwd
/data/user/0/org.chromium.chrome
find -type f
./files/rList
./shared_prefs/org.chromium.chrome_preferences.xml
```
If you need to access the app's application data directory, you need to look up the
obfuscated installation path since you don't have read access to the */data/app/* directory.
For example:
```
pm list packages -f org.chromium.chrome
package:/data/app/~~ybTygSP5u72F9GN-3TMKXA==/org.chromium.chrome-zYY5mcB7YgB5pa3vfS3CBQ==/base.apk=org.chromium.chrome
ls -l /data/app/~~ybTygSP5u72F9GN-3TMKXA==/org.chromium.chrome-zYY5mcB7YgB5pa3vfS3CBQ==/
total 389079
-rw-r--r-- 1 system system 369634375 2022-11-05 01:49 base.apk
drwxr-xr-x 3 system system 3452 2022-11-05 01:49 lib
-rw-r--r-- 1 system system 786666 2022-11-05 01:49 split_cablev2_authenticator.apk
-rw-r--r-- 1 system system 21258500 2022-11-05 01:49 split_chrome.apk
-rw-r--r-- 1 system system 1298934 2022-11-05 01:49 split_config.en.apk
-rw-r--r-- 1 system system 413913 2022-11-05 01:49 split_dev_ui.apk
-rw-r--r-- 1 system system 12432 2022-11-05 01:49 split_weblayer.apk
```