Chromium Docs - Android Debugging Instructions (original) (raw)

Chrome on Android has java and c/c++ code. Each “side” have its own set of tools for debugging. Here's some tips.

Instructions for Google Employees

See also go/clankium/06-debugging-clank.

Launching

You can run the app by using one of the wrappers.

Installs, launches, and enters logcat.

out/Default/bin/content_shell_apk run --args='--disable-fre' 'data:text/html;utf-8,Hello World!'

Launches without first installing. Does not show logcat.

out/Default/bin/chrome_public_apk launch --args='--disable-fre' 'data:text/html;utf-8,Hello World!'

Logging

Chromium logging from LOG(INFO) 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:

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/.

Take a Screenshot

build/android/screenshot.py /tmp/screenshot.png

Inspecting the View Hierarchy

Generate an Android Studio project, and then use Layout Inspector.

Debugging Java

For both apk and test targets, pass --wait-for-java-debugger to the wrapper scripts.

Examples:

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

Eclipse

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.

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.

Waiting for Debugger on Early Startup

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:

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}):

third_party/android_platform/development/scripts/stack --output-directory out/Default [tombstone file | dump file]

stack can also take its input from stdin:

adb logcat -d | third_party/android_platform/development/scripts/stack --output-directory out/Default

Example:

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:

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.

Once you have a .mapping file:

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

In your build environment:

adb root adb shell stop adb shell setprop log.redirect-stdio true adb shell start

In the source itself, use LOG(ERROR), LOG(INFO), etc. whenever you need to output a message, and it will be automatically redirected to adb logcat. Running adb logcat chromium:E, for example, will show all log lines from LOG(ERROR) (plus others that match “chromium”).

Debug unit tests with LLDB

To run unit tests use the following command:

out/Debug/bin/run_test_name -f --wait-for-debugger -t 6000

That command will cause the test process to wait until a debugger is attached.

To attach a debugger:

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