| OLD | NEW |
|---|
| (Empty) | |
| 1 # Android Debugging Instructions |
| 2 |
| 3 Chrome on Android has java and c/c++ code. Each "side" have its own set of tools |
| 4 for debugging. Here's some tips. |
| 5 |
| 6 [TOC] |
| 7 |
| 8 ## Setting up command line flags |
| 9 |
| 10 Various commands below requires setting up command line flags. |
| 11 |
| 12 ```shell |
| 13 # Content shell |
| 14 build/android/adb_content_shell_command_line --flags --to-pass |
| 15 # Chromium test shell |
| 16 build/android/adb_chrome_shell_command_line --flags --to-pass |
| 17 ``` |
| 18 |
| 19 ## Launching the app |
| 20 |
| 21 You can launch the app by using one of the wrappers. You can pass URLs directly |
| 22 too. |
| 23 |
| 24 ```shell |
| 25 # Content shell |
| 26 build/android/adb_run_content_shell 'data:text/html;utf-8,<html>Hello World!</ht
ml>' |
| 27 # Chromium test shell |
| 28 build/android/adb_run_chrome_shell 'data:text/html;utf-8,<html>Hello World!</htm
l>' |
| 29 ``` |
| 30 |
| 31 ## Log output |
| 32 |
| 33 [Chromium logging from LOG(INFO)](https://chromium.googlesource.com/chromium/src
/+/master/docs/android_logging.md) |
| 34 etc., is directed to the Android logcat logging facility. You can filter the |
| 35 messages, e.g. view chromium verbose logging, everything else at warning level |
| 36 with: |
| 37 |
| 38 ```shell |
| 39 adb logcat chromium:V cr.SomeComponent:V *:W |
| 40 ``` |
| 41 |
| 42 ### Warnings for Blink developers |
| 43 |
| 44 * **Do not use fprintf or printf debugging!** This does not |
| 45 redirect to logcat. |
| 46 |
| 47 * Redirecting stdio to logcat, as documented |
| 48 [here](https://developer.android.com/studio/command-line/logcat.html#viewing
Std), |
| 49 has a bad side-effect that it breaks `adb_install.py`. See |
| 50 [here for details](http://stackoverflow.com/questions/28539676/android-adb-f
ails-to-install-apk-to-nexus-5-on-windows-8-1). |
| 51 |
| 52 ## Take a screenshot |
| 53 |
| 54 While your phone is plugged into USB, use the `screenshot.py` tool in |
| 55 `build/android`. `envsetup.sh` should have put it in your path. |
| 56 |
| 57 ```shell |
| 58 build/android/screenshot.py /tmp/screenshot.png |
| 59 ``` |
| 60 |
| 61 ## Inspecting the view hierarchy |
| 62 |
| 63 You can use either |
| 64 [hierarchy viewer](https://developer.android.com/studio/profile/hierarchy-viewer
-setup.html) |
| 65 or [monitor](https://developer.android.com/studio/profile/monitor.html) to see |
| 66 the Android view hierarchy and see the layout and drawing properties associated |
| 67 with it. |
| 68 |
| 69 While your phone is plugged into USB, you can inspect the Android view hierarchy |
| 70 using the following command: |
| 71 |
| 72 ```shell |
| 73 ANDROID_HVPROTO=ddm monitor |
| 74 ``` |
| 75 |
| 76 Setting `ANDROID_HVPROTO` allows you to inspect debuggable apps on non-rooted |
| 77 devices. When building a local version of Chromium, the build tools |
| 78 automatically add `android:debuggable=true` to the `AndroidManifest.xml`, which |
| 79 will allow you to inspect them on rooted devices. |
| 80 |
| 81 Want to add some additional information to your Views? You can do that by |
| 82 adding the |
| 83 [@ViewDebug.ExportedProperty](https://developer.android.com/reference/android/vi
ew/ViewDebug.ExportedProperty.html) |
| 84 annotation. |
| 85 |
| 86 Example: |
| 87 |
| 88 ```java |
| 89 @ViewDebug.ExportedProperty(category="chrome") |
| 90 private int mSuperNiftyDrawingProperty; |
| 91 ``` |
| 92 |
| 93 ## Debugging Java |
| 94 |
| 95 * In Eclipse, make a debug configuration of type "Remote Java Application". |
| 96 Choose a "Name" and set "Port" to `8700`. |
| 97 |
| 98 * Make sure Eclipse Preferences > Run/Debug > Launching > "Build (if required) |
| 99 before launching" is unchecked. |
| 100 |
| 101 * Run Android Device Monitor: |
| 102 |
| 103 ```shell |
| 104 third_party/android_tools/sdk/tools/monitor |
| 105 ``` |
| 106 |
| 107 * Now select the process you want to debug in Device Monitor (the port column |
| 108 should now mention 8700 or xxxx/8700). |
| 109 |
| 110 * Run your debug configuration, and switch to the Debug perspective. |
| 111 |
| 112 ## Waiting for Java Debugger on Early Startup |
| 113 |
| 114 * To debug early startup, pass `--wait-for-java-debugger` as a command line |
| 115 flag. |
| 116 |
| 117 ## Debugging C/C++ |
| 118 |
| 119 Under `build/android`, there are a few scripts: |
| 120 |
| 121 ```shell |
| 122 # Convenient wrappers |
| 123 build/android/adb_gdb_content_shell |
| 124 build/android/adb_gdb_chrome_shell |
| 125 |
| 126 # Underlying script, try --help for comprehensive list of options |
| 127 build/android/adb_gdb |
| 128 ``` |
| 129 |
| 130 By default, these wrappers will attach to the browser process. |
| 131 |
| 132 You can also attach to the renderer process by using `--sandboxed`. (You might |
| 133 need to be root on the phone for that. Run `adb root` if needed) |
| 134 |
| 135 ## Waiting for Debugger on Early Startup |
| 136 |
| 137 Set the target command line flag with `--wait-for-debugger`. |
| 138 |
| 139 Launch the debugger using one of the `adb_gdb` scripts from above. |
| 140 |
| 141 Type `info threads` and look for a line like: |
| 142 |
| 143 ``` |
| 144 11 Thread 2564 clock_gettime () at bionic/libc/arch-arm/syscalls/clock_gettime.
S:11 |
| 145 ``` |
| 146 |
| 147 or perhaps: |
| 148 |
| 149 ``` |
| 150 1 Thread 10870 0x40127050 in nanosleep () from /tmp/user-adb-gdb-libs/syst
em/lib/libc.so |
| 151 ``` |
| 152 |
| 153 We need to jump out of its sleep routine: |
| 154 |
| 155 ``` |
| 156 (gdb) thread 11 |
| 157 (gdb) up |
| 158 (gdb) up |
| 159 (gdb) return |
| 160 Make base::debug::BreakDebugger() return now? (y or n) y |
| 161 (gdb) continue |
| 162 ``` |
| 163 |
| 164 ## Symbolizing Crash Stacks and Tombstones (C++) |
| 165 |
| 166 If a crash has generated a tombstone in your device, use: |
| 167 |
| 168 ```shell |
| 169 build/android/tombstones.py --output-directory out/Default |
| 170 ``` |
| 171 |
| 172 If you have a stack trace (from `adb logcat`) that needs to be symbolized, copy |
| 173 it into a text file and symbolize with the following command (run from |
| 174 `${CHROME_SRC}`): |
| 175 |
| 176 ```shell |
| 177 third_party/android_platform/development/scripts/stack --output-directory out/De
fault [tombstone file | dump file] |
| 178 ``` |
| 179 |
| 180 `stack` can also take its input from `stdin`: |
| 181 |
| 182 ```shell |
| 183 adb logcat -d | third_party/android_platform/development/scripts/stack --output-
directory out/Default |
| 184 ``` |
| 185 |
| 186 Example: |
| 187 |
| 188 ```shell |
| 189 third_party/android_platform/development/scripts/stack --output-directory out/De
fault ~/crashlogs/tombstone_07-build231.txt |
| 190 ``` |
| 191 |
| 192 ## Deobfuscating Stack Traces (Java) |
| 193 |
| 194 You will need the ProGuard mapping file that was generated when the application |
| 195 that crashed was built. When building locally, these are found in: |
| 196 |
| 197 ```shell |
| 198 out/Default/apks/ChromePublic.apk.mapping |
| 199 out/Default/apks/Chrome.apk.mapping |
| 200 ``` |
| 201 |
| 202 To deobfuscate a stack trace from a file, run |
| 203 |
| 204 ```shell |
| 205 build/android/stacktrace/java_deobfuscate.py PROGUARD_MAPPING_FILE.mapping --sta
cktrace STACKTRACE_FILE |
| 206 ``` |
| 207 |
| 208 Deobfuscation also works from `stdin`: |
| 209 |
| 210 ```shell |
| 211 adb logcat -d | build/android/stacktrace/java_deobfuscate.py PROGUARD_MAPPING_FI
LE.mapping |
| 212 ``` |
| 213 |
| 214 ## Get WebKit code to output to the adb log |
| 215 |
| 216 In your build environment: |
| 217 |
| 218 ```shell |
| 219 adb root |
| 220 adb shell stop |
| 221 adb shell setprop log.redirect-stdio true |
| 222 adb shell start |
| 223 ``` |
| 224 |
| 225 In the source itself, use `fprintf(stderr, "message");` whenever you need to |
| 226 output a message. |
| 227 |
| 228 ## Debug unit tests with GDB |
| 229 |
| 230 To run unit tests use the following command: |
| 231 |
| 232 ```shell |
| 233 out/Debug/bin/run_test_name -f <test_filter_if_any> --test-arguments=--wait-for-
debugger -t 6000 |
| 234 ``` |
| 235 |
| 236 That command will cause the test process to wait until a debugger is attached. |
| 237 |
| 238 To attach a debugger: |
| 239 |
| 240 ```shell |
| 241 build/android/adb_gdb --output-directory=out/Default --package-name=org.chromium
.native_test |
| 242 ``` |
| 243 |
| 244 After attaching gdb to the process you can use it normally. For example: |
| 245 |
| 246 ``` |
| 247 (gdb) break main |
| 248 Breakpoint 1 at 0x9750793c: main. (2 locations) |
| 249 (gdb) continue |
| 250 ``` |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 2203123006:
Port Android debugging instructions to Markdown (Closed)
Base URL: https://chromium.googlesource.com/chromium/src.git@master