chromium/src
0
Fork 0
Code Activity
Files
1c0129192dc060cf94c59e935af9d6c3e0431f90
src/docs/android_debugging_instructions.md
Clemens Arbesser 46cb4f7cfe Remove components/autofill_assistant 
b: b:259509313
Change-Id: I9063e8d72ee15933c3bf3425295e583a81eeb80c
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/4075567
Reviewed-by: Colin Blundell <blundell@chromium.org>
Reviewed-by: Florian Gauger <fga@google.com>
Commit-Queue: Andrew Grieve <agrieve@chromium.org>
Owners-Override: Andrew Grieve <agrieve@chromium.org>
Reviewed-by: Andrew Grieve <agrieve@chromium.org>
Reviewed-by: Robert Kaplow <rkaplow@chromium.org>
Cr-Commit-Position: refs/heads/main@{#1080337}
2022-12-07 15:08:17 +00:00

326 lines
11 KiB
Markdown
Raw Blame History

# 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 `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.
```
If you have ever run an ASAN build of chromium on the device, you may get
an error like the following when you start up gdb:
```
/tmp/<username>-adb-gdb-tmp-<pid>/gdb.init:11: Error in sourced command file:
"/tmp/<username>-adb-gdb-tmp-<pid>/app_process32": not in executable format: file format not recognized
```
If this happens, run the following command and try again:
```shell
$ src/android/asan/third_party/asan_device_setup.sh --revert
```
### 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
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 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
```
## 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
```
View Git Blame Copy Permalink