android_webview
apps
ash
base
build
build_overrides
buildtools
cc
chrome
chromecast
chromeos
codelabs
components
content
courgette
crypto
dbus
device
docs
accessibility
autofill
design
enterprise
experiments
fuchsia
gpu
images
infra
intl
ios
lacros
linux
login
mac
media
memory
memory-infra
patterns
privacy
privacy_budget
process
security
speed
speed_metrics
standards
telemetry_extension
testing
ui
updater
webapps
workflow
DIR_METADATA
OWNERS
README.md
accessibility.md
ad_tagging.md
adding_to_third_party.md
android_accessing_cpp_enums_in_java.md
android_accessing_cpp_features_in_java.md
android_accessing_cpp_switches_in_java.md
android_build_instructions.md
android_cast_build_instructions.md
android_debugging_instructions.md
android_dynamic_feature_modules.md
android_emulator.md
android_isolated_splits.md
android_logging.md
android_native_libraries.md
android_studio.md
angle_in_chromium.md
api_keys.md
asan.md
atom.md
bitmap_pipeline.md
branch_sheriff.md
building_old_revisions.md
callback.md
ccache_mac.md
chrome_os_logging.md
chrome_settings.md
chrome_untrusted.md
chromedriver_status.md
chromeos_build_instructions.md
chromeos_glossary.md
chromium_browser_vs_google_chrome.md
cipd_and_3pp.md
cl_respect.md
clang.md
clang_code_coverage_wrapper.md
clang_format.md
clang_sheriffing.md
clang_static_analyzer.md
clang_tidy.md
clang_tool_refactoring.md
clangd.md
clion.md
closure_compilation.md
cocoa_tips_and_tricks.md
code_review_owners.md
code_reviews.md
commit_checklist.md
component_build.md
configuration.md
contributing.md
cq_quick_run.md
cr_respect.md
cr_user_manual.md
cross_platform_ui.md
cygwin_dll_remapping_failure.md
dangling_ptr.md
dangling_ptr_guide.md
dbus_mojo_connection_service.md
debugging_with_crash_keys.md
deterministic_builds.md
disassemble_code.md
documentation_best_practices.md
documentation_guidelines.md
early-hints.md
eclipse.md
emacs.md
erc_irc.md
flag_expiry.md
flag_guarding_guidelines.md
flag_ownership.md
frame_trees.md
gdbinit.md
get_the_code.md
git_cookbook.md
git_tips.md
google_chrome_branded_builds.md
google_play_services.md
graphical_debugging_aid_chromium_views.md
gwp_asan.md
history_manipulation_intervention.md
how_cc_works.md
how_to_add_your_feature_flag.md
how_to_extend_web_test_framework.md
idn.md
initialize_blink_features.md
inlined_stack_traces.md
installation_at_vmware.md
ios_build_instructions.md
ios_infra.md
ios_voiceover.md
kiosk_mode.md
lacros.md
life_of_a_frame.md
lldbinit.md
mac_arm64.md
mac_build_instructions.md
mac_lld.md
mojo_and_services.md
mojo_ipc_conversion.md
mojo_testing.md
native_relocations.md
navbar.md
navigation-request-navigation-state.gv
navigation-request-navigation-state.png
navigation.md
navigation_concepts.md
network_traffic_annotations.md
no_sources_assignment_filter.md
optimizing_web_uis.md
origin_trials_integration.md
ozone_overview.md
parsing_test_results.md
pgo.md
piranha_plant.md
process_model_and_site_isolation.md
profiling.md
profiling_content_shell_on_android.md
proxy_auto_config.md
python3_migration.md
qtcreator.md
release_branch_guidance.md
render-frame-host-lifecycle-state.gv
render-frame-host-lifecycle-state.png
render_document.md
rust.md
seccomp_sandbox_crash_dumping.md
servicification.md
session_history.md
sheriff.md
shutdown.md
special_case_urls.md
static_initializers.md
sublime_ide.md
system_hardening_features.md
tab_helpers.md
threading_and_tasks.md
threading_and_tasks_faq.md
threading_and_tasks_testing.md
toolchain_support.md
tour_of_luci_ui.md
tpm_quick_ref.md
translation_screenshots.md
trusted_types_on_webui.md
updating_clang.md
updating_clang_format_binaries.md
use_counter_wiki.md
useful_urls.md
user_data_dir.md
user_data_storage.md
user_handle_mapping.md
vanilla_msysgit_workflow.md
vscode.md
vscode_python.md
webui_build_configuration.md
webui_explainer.md
webui_in_chrome.md
webui_in_components.md
webview_policies.md
win_cross.md
win_order_files.md
windows_build_instructions.md
windows_native_window_occlusion_tracking.md
windows_pwa_integration.md
windows_shortcut_and_taskbar_handling.md
windows_split_dll.md
windows_virtual_desktop_handling.md
wmax_tokens.md
working_remotely_with_android.md
writing_clang_plugins.md
extensions
fuchsia_web
gin
google_apis
google_update
gpu
headless
infra
ios
ipc
media
mojo
native_client_sdk
net
pdf
ppapi
printing
remoting
rlz
sandbox
services
skia
sql
storage
styleguide
testing
third_party
tools
ui
url
weblayer
.clang-format
.clang-tidy
.eslintrc.js
.git-blame-ignore-revs
.gitattributes
.gitignore
.gn
.mailmap
.rustfmt.toml
.vpython3
.yapfignore
ATL_OWNERS
AUTHORS
BUILD.gn
CODE_OF_CONDUCT.md
DEPS
DIR_METADATA
LICENSE
LICENSE.chromium_os
OWNERS
PRESUBMIT.py
PRESUBMIT_test.py
PRESUBMIT_test_mocks.py
README.md
WATCHLISTS
codereview.settings

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}
326 lines
11 KiB
Markdown
326 lines
11 KiB
Markdown
# 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
|
|
``` |