docs/chromoting_android_hacking.md

   1 # Chromoting Android Hacking
   2
   3 This guide, which is meant to accompany the
   4 [compilation guide](chromoting_build_instructions.md), explains the process of
   5 viewing the logs and debugging the CRD Android client. I'll assume you've
   6 already built the APK as described in the aforementioned guide, that you're in
   7 the `src/` directory, and that your binary is at
   8 `out/Release/apks/Chromoting.apk`. Additionally, you should have installed the
   9 app on at least one (still) connected device.
  10
  11 [TOC]
  12
  13 ## Viewing logging output
  14
  15 In order to access LogCat and view the app's logging output, we need to launch
  16 the Android Device Monitor. Run `third_party/android_tools/sdk/tools/monitor`
  17 and select the desired device under `Devices`. Using the app as normal will
  18 display log messages to the `LogCat` pane.
  19
  20 ## Attaching debuggers for Java code
  21
  22 ### Eclipse
  23
  24 1.  Go to http://developer.android.com/sdk/index.html and click "Download the
  25     SDK ADT Bundle for Linux"
  26 1.  Configure eclipse
  27     1.  Select General > Workspace from the tree on the left.
  28         1.  Uncheck Refresh workspace on startup (if present)
  29         1.  Uncheck Refresh using native hooks or polling (if present)
  30         1.  Disable build before launching
  31     1.  Select Run/Debug > Launching
  32         1.  Uncheck Build (if required) before launching
  33 1. Create a project
  34     1.  Select File > New > Project... from the main menu.
  35     1.  Choose Java/Java Project
  36     1.  Eclipse should have generated .project and perhaps a .classpath file in
  37         your <project root>/src/ directory.
  38     1.  Replace/Add the .classpath file with the content from Below. Remember
  39         that the path field should be the location of the chromium source
  40         relative to the current directory of your project.
  41
  42 ```xml
  43 <?xml version="1.0" encoding="UTF-8"?>
  44 <classpath>
  45 <classpathentry kind="src" path="net/test/android/javatests/src"/>
  46 <classpathentry kind="src" path="net/android/java/src"/>
  47 <classpathentry kind="src" path="net/android/javatests/src"/>
  48 <classpathentry kind="src" path="base/test/android/java/src"/>
  49 <classpathentry kind="src" path="base/test/android/javatests/src"/>
  50 <classpathentry kind="src" path="base/android/jni_generator/java/src"/>
  51 <classpathentry kind="src" path="base/android/java/src"/>
  52 <classpathentry kind="src" path="base/android/javatests/src"/>
  53 <classpathentry kind="src" path="components/cronet/android/java/src"/>
  54 <classpathentry kind="src" path="components/cronet/android/sample/src"/>
  55 <classpathentry kind="src" path="components/cronet/android/sample/javatests/src"/>
  56 <classpathentry kind="src" path="components/autofill/core/browser/android/java/src"/>
  57 <classpathentry kind="src" path="components/web_contents_delegate_android/android/java/src"/>
  58 <classpathentry kind="src" path="components/dom_distiller/android/java/src"/>
  59 <classpathentry kind="src" path="components/navigation_interception/android/java/src"/>
  60 <classpathentry kind="src" path="ui/android/java/src"/>
  61 <classpathentry kind="src" path="media/base/android/java/src"/>
  62 <classpathentry kind="src" path="chrome/test/android/unit_tests_apk/src"/>
  63 <classpathentry kind="src" path="chrome/test/android/javatests/src"/>
  64 <classpathentry kind="src" path="chrome/test/chromedriver/test/webview_shell/java/src"/>
  65 <classpathentry kind="src" path="chrome/common/extensions/docs/examples/extensions/irc/servlet/src"/>
  66 <classpathentry kind="src" path="chrome/android/java/src"/>
  67 <classpathentry kind="src" path="chrome/android/uiautomator_tests/src"/>
  68 <classpathentry kind="src" path="chrome/android/javatests/src"/>
  69 <classpathentry kind="src" path="sync/test/android/javatests/src"/>
  70 <classpathentry kind="src" path="sync/android/java/src"/>
  71 <classpathentry kind="src" path="sync/android/javatests/src"/>
  72 <classpathentry kind="src" path="mojo/public/java/src"/>
  73 <classpathentry kind="src" path="mojo/android/system/src"/>
  74 <classpathentry kind="src" path="mojo/android/javatests/src"/>
  75 <classpathentry kind="src" path="mojo/shell/android/apk/src"/>
  76 <classpathentry kind="src" path="mojo/services/native_viewport/android/src"/>
  77 <classpathentry kind="src" path="testing/android/java/src"/>
  78 <classpathentry kind="src" path="printing/android/java/src"/>
  79 <classpathentry kind="src" path="tools/binary_size/java/src"/>
  80 <classpathentry kind="src" path="tools/android/memconsumer/java/src"/>
  81 <classpathentry kind="src" path="tools/android/findbugs_plugin/test/java/src"/>
  82 <classpathentry kind="src" path="tools/android/findbugs_plugin/src"/>
  83 <classpathentry kind="src" path="remoting/android/java/src"/>
  84 <classpathentry kind="src" path="remoting/android/apk/src"/>
  85 <classpathentry kind="src" path="remoting/android/javatests/src"/>
  86 <classpathentry kind="src" path="third_party/WebKit/Source/devtools/scripts/jsdoc-validator/src"/>
  87 <classpathentry kind="src" path="third_party/WebKit/Source/devtools/scripts/compiler-runner/src"/>
  88 <classpathentry kind="src" path="third_party/webrtc/voice_engine/test/android/android_test/src"/>
  89 <classpathentry kind="src" path="third_party/webrtc/modules/video_capture/android/java/src"/>
  90 <classpathentry kind="src" path="third_party/webrtc/modules/video_render/android/java/src"/>
  91 <classpathentry kind="src" path="third_party/webrtc/modules/audio_device/test/android/audio_device_android_test/src"/>
  92 <classpathentry kind="src" path="third_party/webrtc/modules/audio_device/android/java/src"/>
  93 <classpathentry kind="src" path="third_party/webrtc/examples/android/media_demo/src"/>
  94 <classpathentry kind="src" path="third_party/webrtc/examples/android/opensl_loopback/src"/>
  95 <classpathentry kind="src" path="third_party/webrtc/video_engine/test/auto_test/android/src"/>
  96 <classpathentry kind="src" path="third_party/libjingle/source/talk/app/webrtc/java/src"/>
  97 <classpathentry kind="src" path="third_party/libjingle/source/talk/app/webrtc/javatests/src"/>
  98 <classpathentry kind="src" path="third_party/libjingle/source/talk/examples/android/src"/>
  99 <classpathentry kind="src" path="android_webview/java/src"/>
 100 <classpathentry kind="src" path="android_webview/java/generated_src"/>
 101 <classpathentry kind="src" path="android_webview/test/shell/src"/>
 102 <classpathentry kind="src" path="android_webview/unittestjava/src"/>
 103 <classpathentry kind="src" path="android_webview/javatests/src"/>
 104 <classpathentry kind="src" path="content/public/test/android/javatests/src"/>
 105 <classpathentry kind="src" path="content/public/android/java/src"/>
 106 <classpathentry kind="src" path="content/public/android/javatests/src"/>
 107 <classpathentry kind="src" path="content/shell/android/browsertests_apk/src"/>
 108 <classpathentry kind="src" path="content/shell/android/java/src"/>
 109 <classpathentry kind="src" path="content/shell/android/shell_apk/src"/>
 110 <classpathentry kind="src" path="content/shell/android/javatests/src"/>
 111 <classpathentry kind="src" path="content/shell/android/linker_test_apk/src"/>
 112 <classpathentry kind="lib" path="third_party/android_tools/sdk/platforms/android-19/data/layoutlib.jar"/>
 113 <classpathentry kind="lib" path="third_party/android_tools/sdk/platforms/android-19/android.jar"/>
 114 <classpathentry kind="output" path="out/bin"/>
 115 </classpath>
 116 ```
 117
 118 1.  Obtain the debug port
 119     1.  Go to Window > Open Perspective > DDMS
 120     1.  In order for the app org.chromium.chromoting to show up, you must build
 121         Debug instead of Retail
 122     1.  Note down the port number, should be 8600 or 8700
 123 1.  Setup a debug configuration
 124     1.  Go to Window > Open Perspective > Debug
 125     1.  Run > Debug > Configurations
 126     1.  Select "Remote Java Application" and click "New"
 127     1.  Put Host: localhost and Port: <the port from DDMS>
 128     1.  Hit Debug
 129 1.  Configure source path
 130     1.  Right click on the Chromoting [Application](Remoting.md) and select Edit
 131         source Lookup Path
 132     1.  Click "Add" and select File System Directory
 133     1.  Select the location of your chromium checkout,
 134         e.g. <project root>/src/remoting/android
 135 1.  Debugging
 136     1.  To add a breakpoint, simply open the source file and hit Ctrl+Shift+B to
 137         toggle the breakpoint. Happy hacking.
 138
 139 ### Command line debugger
 140
 141 With the Android Device Monitor open, look under `Devices`, expand the entry for
 142 the device on which you want to debug, and select the entry for
 143 `org.chromium.chromoting` (it must already be running). This forwards the JVM
 144 debugging connection to your local port 8700.  In your shell, do `$ jdb -attach
 145 localhost:8700`.
 146
 147 ## Attaching GDB to debug native code
 148
 149 The Chromium build system provides a convenience wrapper script that can be used
 150 to easily launch GDB. Run
 151
 152 ```shell
 153 $ build/android/adb_gdb --package-name=org.chromium.chromoting \
 154 --activity=.Chromoting --start
 155 ```
 156
 157 Note that if you have multiple devices connected, you must export
 158 `ANDROID_SERIAL` to select one; set it to the serial number of the desired
 159 device as output by `$ adb devices`.