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/shell/java/src"/>
  69 <classpathentry kind="src" path="chrome/android/shell/javatests/src"/>
  70 <classpathentry kind="src" path="chrome/android/javatests/src"/>
  71 <classpathentry kind="src" path="sync/test/android/javatests/src"/>
  72 <classpathentry kind="src" path="sync/android/java/src"/>
  73 <classpathentry kind="src" path="sync/android/javatests/src"/>
  74 <classpathentry kind="src" path="mojo/public/java/src"/>
  75 <classpathentry kind="src" path="mojo/android/system/src"/>
  76 <classpathentry kind="src" path="mojo/android/javatests/src"/>
  77 <classpathentry kind="src" path="mojo/shell/android/apk/src"/>
  78 <classpathentry kind="src" path="mojo/services/native_viewport/android/src"/>
  79 <classpathentry kind="src" path="testing/android/java/src"/>
  80 <classpathentry kind="src" path="printing/android/java/src"/>
  81 <classpathentry kind="src" path="tools/binary_size/java/src"/>
  82 <classpathentry kind="src" path="tools/android/memconsumer/java/src"/>
  83 <classpathentry kind="src" path="tools/android/findbugs_plugin/test/java/src"/>
  84 <classpathentry kind="src" path="tools/android/findbugs_plugin/src"/>
  85 <classpathentry kind="src" path="remoting/android/java/src"/>
  86 <classpathentry kind="src" path="remoting/android/apk/src"/>
  87 <classpathentry kind="src" path="remoting/android/javatests/src"/>
  88 <classpathentry kind="src" path="third_party/WebKit/Source/devtools/scripts/jsdoc-validator/src"/>
  89 <classpathentry kind="src" path="third_party/WebKit/Source/devtools/scripts/compiler-runner/src"/>
  90 <classpathentry kind="src" path="third_party/webrtc/voice_engine/test/android/android_test/src"/>
  91 <classpathentry kind="src" path="third_party/webrtc/modules/video_capture/android/java/src"/>
  92 <classpathentry kind="src" path="third_party/webrtc/modules/video_render/android/java/src"/>
  93 <classpathentry kind="src" path="third_party/webrtc/modules/audio_device/test/android/audio_device_android_test/src"/>
  94 <classpathentry kind="src" path="third_party/webrtc/modules/audio_device/android/java/src"/>
  95 <classpathentry kind="src" path="third_party/webrtc/examples/android/media_demo/src"/>
  96 <classpathentry kind="src" path="third_party/webrtc/examples/android/opensl_loopback/src"/>
  97 <classpathentry kind="src" path="third_party/webrtc/video_engine/test/auto_test/android/src"/>
  98 <classpathentry kind="src" path="third_party/libjingle/source/talk/app/webrtc/java/src"/>
  99 <classpathentry kind="src" path="third_party/libjingle/source/talk/app/webrtc/javatests/src"/>
 100 <classpathentry kind="src" path="third_party/libjingle/source/talk/examples/android/src"/>
 101 <classpathentry kind="src" path="android_webview/java/src"/>
 102 <classpathentry kind="src" path="android_webview/java/generated_src"/>
 103 <classpathentry kind="src" path="android_webview/test/shell/src"/>
 104 <classpathentry kind="src" path="android_webview/unittestjava/src"/>
 105 <classpathentry kind="src" path="android_webview/javatests/src"/>
 106 <classpathentry kind="src" path="content/public/test/android/javatests/src"/>
 107 <classpathentry kind="src" path="content/public/android/java/src"/>
 108 <classpathentry kind="src" path="content/public/android/javatests/src"/>
 109 <classpathentry kind="src" path="content/shell/android/browsertests_apk/src"/>
 110 <classpathentry kind="src" path="content/shell/android/java/src"/>
 111 <classpathentry kind="src" path="content/shell/android/shell_apk/src"/>
 112 <classpathentry kind="src" path="content/shell/android/javatests/src"/>
 113 <classpathentry kind="src" path="content/shell/android/linker_test_apk/src"/>
 114 <classpathentry kind="lib" path="third_party/android_tools/sdk/platforms/android-19/data/layoutlib.jar"/>
 115 <classpathentry kind="lib" path="third_party/android_tools/sdk/platforms/android-19/android.jar"/>
 116 <classpathentry kind="output" path="out/bin"/>
 117 </classpath>
 118 ```
 119
 120 1.  Obtain the debug port
 121     1.  Go to Window > Open Perspective > DDMS
 122     1.  In order for the app org.chromium.chromoting to show up, you must build
 123         Debug instead of Retail
 124     1.  Note down the port number, should be 8600 or 8700
 125 1.  Setup a debug configuration
 126     1.  Go to Window > Open Perspective > Debug
 127     1.  Run > Debug > Configurations
 128     1.  Select "Remote Java Application" and click "New"
 129     1.  Put Host: localhost and Port: <the port from DDMS>
 130     1.  Hit Debug
 131 1.  Configure source path
 132     1.  Right click on the Chromoting [Application](Remoting.md) and select Edit
 133         source Lookup Path
 134     1.  Click "Add" and select File System Directory
 135     1.  Select the location of your chromium checkout,
 136         e.g. <project root>/src/remoting/android
 137 1.  Debugging
 138     1.  To add a breakpoint, simply open the source file and hit Ctrl+Shift+B to
 139         toggle the breakpoint. Happy hacking.
 140
 141 ### Command line debugger
 142
 143 With the Android Device Monitor open, look under `Devices`, expand the entry for
 144 the device on which you want to debug, and select the entry for
 145 `org.chromium.chromoting` (it must already be running). This forwards the JVM
 146 debugging connection to your local port 8700.  In your shell, do `$ jdb -attach
 147 localhost:8700`.
 148
 149 ## Attaching GDB to debug native code
 150
 151 The Chromium build system provides a convenience wrapper script that can be used
 152 to easily launch GDB. Run
 153
 154 ```shell
 155 $ build/android/adb_gdb --package-name=org.chromium.chromoting \
 156 --activity=.Chromoting --start
 157 ```
 158
 159 Note that if you have multiple devices connected, you must export
 160 `ANDROID_SERIAL` to select one; set it to the serial number of the desired
 161 device as output by `$ adb devices`.