| Index: docs/android_debugging_instructions.md
|
| diff --git a/docs/android_debugging_instructions.md b/docs/android_debugging_instructions.md
|
| new file mode 100644
|
| index 0000000000000000000000000000000000000000..1102fbfcc2fef47727111b58b8a3bc8c821b61c6
|
| --- /dev/null
|
| +++ b/docs/android_debugging_instructions.md
|
| @@ -0,0 +1,250 @@
|
| +# 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]
|
| +
|
| +## Setting up command line flags
|
| +
|
| +Various commands below requires setting up command line flags.
|
| +
|
| +```shell
|
| +# Content shell
|
| +build/android/adb_content_shell_command_line --flags --to-pass
|
| +# Chromium test shell
|
| +build/android/adb_chrome_shell_command_line --flags --to-pass
|
| +```
|
| +
|
| +## Launching the app
|
| +
|
| +You can launch the app by using one of the wrappers. You can pass URLs directly
|
| +too.
|
| +
|
| +```shell
|
| +# Content shell
|
| +build/android/adb_run_content_shell 'data:text/html;utf-8,<html>Hello World!</html>'
|
| +# Chromium test shell
|
| +build/android/adb_run_chrome_shell 'data:text/html;utf-8,<html>Hello World!</html>'
|
| +```
|
| +
|
| +## Log output
|
| +
|
| +[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
|
| +adb logcat chromium:V cr.SomeComponent:V *:W
|
| +```
|
| +
|
| +### 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
|
| +
|
| +While your phone is plugged into USB, use the `screenshot.py` tool in
|
| +`build/android`. `envsetup.sh` should have put it in your path.
|
| +
|
| +```shell
|
| +build/android/screenshot.py /tmp/screenshot.png
|
| +```
|
| +
|
| +## Inspecting the view hierarchy
|
| +
|
| +You can use either
|
| +[hierarchy viewer](https://developer.android.com/studio/profile/hierarchy-viewer-setup.html)
|
| +or [monitor](https://developer.android.com/studio/profile/monitor.html) to see
|
| +the Android view hierarchy and see the layout and drawing properties associated
|
| +with it.
|
| +
|
| +While your phone is plugged into USB, you can inspect the Android view hierarchy
|
| +using the following command:
|
| +
|
| +```shell
|
| +ANDROID_HVPROTO=ddm monitor
|
| +```
|
| +
|
| +Setting `ANDROID_HVPROTO` allows you to inspect debuggable apps on non-rooted
|
| +devices. When building a local version of Chromium, the build tools
|
| +automatically add `android:debuggable=true` to the `AndroidManifest.xml`, which
|
| +will allow you to inspect them on rooted devices.
|
| +
|
| +Want to add some additional information to your Views? You can do that by
|
| +adding the
|
| +[@ViewDebug.ExportedProperty](https://developer.android.com/reference/android/view/ViewDebug.ExportedProperty.html)
|
| +annotation.
|
| +
|
| +Example:
|
| +
|
| +```java
|
| +@ViewDebug.ExportedProperty(category="chrome")
|
| +private int mSuperNiftyDrawingProperty;
|
| +```
|
| +
|
| +## Debugging Java
|
| +
|
| +* 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.
|
| +
|
| +## Waiting for Java Debugger on Early Startup
|
| +
|
| +* To debug early startup, pass `--wait-for-java-debugger` as a command line
|
| + flag.
|
| +
|
| +## Debugging C/C++
|
| +
|
| +Under `build/android`, there are a few scripts:
|
| +
|
| +```shell
|
| +# Convenient wrappers
|
| +build/android/adb_gdb_content_shell
|
| +build/android/adb_gdb_chrome_shell
|
| +
|
| +# Underlying script, try --help for comprehensive list of options
|
| +build/android/adb_gdb
|
| +```
|
| +
|
| +By default, these wrappers will attach to the browser process.
|
| +
|
| +You can also attach to the renderer process by using `--sandboxed`. (You might
|
| +need to be root on the phone for that. Run `adb root` if needed)
|
| +
|
| +## Waiting for Debugger on Early Startup
|
| +
|
| +Set the target command line flag with `--wait-for-debugger`.
|
| +
|
| +Launch the debugger using one of the `adb_gdb` scripts from above.
|
| +
|
| +Type `info threads` and look for a line like:
|
| +
|
| +```
|
| +11 Thread 2564 clock_gettime () at bionic/libc/arch-arm/syscalls/clock_gettime.S:11
|
| +```
|
| +
|
| +or perhaps:
|
| +
|
| +```
|
| +1 Thread 10870 0x40127050 in nanosleep () from /tmp/user-adb-gdb-libs/system/lib/libc.so
|
| +```
|
| +
|
| +We need to jump out of its sleep routine:
|
| +
|
| +```
|
| +(gdb) thread 11
|
| +(gdb) up
|
| +(gdb) up
|
| +(gdb) return
|
| +Make base::debug::BreakDebugger() return now? (y or n) y
|
| +(gdb) 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/Chrome.apk.mapping
|
| +```
|
| +
|
| +To deobfuscate a stack trace from a file, run
|
| +
|
| +```shell
|
| +build/android/stacktrace/java_deobfuscate.py PROGUARD_MAPPING_FILE.mapping --stacktrace STACKTRACE_FILE
|
| +```
|
| +
|
| +Deobfuscation also works from `stdin`:
|
| +
|
| +```shell
|
| +adb logcat -d | 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 GDB
|
| +
|
| +To run unit tests use the following command:
|
| +
|
| +```shell
|
| +out/Debug/bin/run_test_name -f <test_filter_if_any> --test-arguments=--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
|
| +```
|
|
|
Chromium Code Reviews
Issue 2203123006:
Port Android debugging instructions to Markdown (Closed)
Base URL: https://chromium.googlesource.com/chromium/src.git@master