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
|
# 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]
## 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/+/master/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
```
### 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.
### 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_tools/sdk/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 `gdb` command to enter into a
gdb shell.
When running with gdb attached, the app runs **extremely slowly**.
```shell
# Attaches to browser process.
out/Default/bin/content_shell_apk gdb
out/Default/bin/chrome_public_apk gdb
# Attaches to gpu process.
out/Default/bin/chrome_public_apk gdb --debug-process-name privileged_process0
# Attach to other processes ("chrome_public_apk ps" to show pids).
out/Default/bin/chrome_public_apk gdb --pid $PID
```
When connecting, gdb will complain of not being able to load a lot of libraries.
This happens because of java code. The following messages are all expected:
```
Connecting to :5039...
warning: Could not load shared library symbols for 211 libraries, e.g. /system/framework/arm/boot.oat.
Use the "info sharedlibrary" command to see the complete listing.
Do you need "set solib-search-path" or "set sysroot"?
Failed to read a valid object file image from memory.
```
### Using Visual Studio Code
While the app is running, run the `gdb` command with `--ide`:
```shell
out/Default/bin/content_shell_apk gdb --ide
```
Once the script has done its thing (generally ~1 second after the initial
time its used), open [vscode.md](vscode.md) and ensure you have the
[Android launch entry](vscode.md#Launch-Commands).
Connect via the IDE's launch entry. Connecting takes 30-40 seconds.
When troubleshooting, it's helpful to enable
[engine logging](https://github.com/Microsoft/vscode-cpptools/blob/master/launch.md#enginelogging).
Known Issues:
* Pretty printers are not working properly.
### 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 an IDE
Once `gdb` attaches, the app will resume execution, so you must set your
breakpoint before attaching.
#### With Command-line GDB
Once attached, gdb 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
out/Default/apks/ChromeModernPublic.apk.mapping
etc.
```
Build the `java_deobfuscate` tool:
```shell
ninja -C out/Default java_deobfuscate
```
Then run it via:
```shell
# For a file:
out/Default/bin/java_deobfuscate PROGUARD_MAPPING_FILE.mapping < FILE
# For logcat:
adb logcat | out/Default/bin/java_deobfuscate 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 GDB
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/adb_gdb --output-directory=out/Default --package-name=org.chromium.native_test
```
After attaching gdb to the process you can use it normally. For example:
```
(gdb) break main
Breakpoint 1 at 0x9750793c: main. (2 locations)
(gdb) continue
```
|
