| # 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 |
| ``` |