Skip to content


Subversion checkout URL

You can clone with
Download ZIP
A scriptable debugger library to interact with Android applications
Branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib fixed bug in inspect_array_reference recursion
template Added sample usage code


This is a scriptable debugger for Android applications. Sample usage:

require 'android_debug'
dbg = AndroidDebug.launch_and_attach("", "")
dbg.on_break do |event|
    puts("Break type: #{event}")
    if(dbg.frame.method_name == "registerReceiver")
        puts("Frame variables:")
        dbg.frame.variables.each do |var|

Core concepts:

  • Environmental or global vairable ANDROID_HOME must be set to your SDK home (ex: /Users/wuntee/android-sdk-macosx). This is because it uses the 'adb' binary to launch applications for the debugger, and utilizes some of the DDMS java libraries.
  • On a breakpoint, you can access variables, methods, locations via the initial 'AndroidDebug::Debugger' object
  • Create/Launch a debugger via AndroidDebug.launch_and_attach(classpath, classname)
  • AndroidDebug::Debugger.this is the "this" object within the class you broken in.
  • AndroidDebug::Debugger.frame is the stackframe on where the break occured and is a AndroidDebug::Jpda::Frame object. This class has a bunch of helper methods to get fun data.
  • You can invoke remote methods by calling Object.method(args)
  • Invoking methods will re-start the application, and you will lose your break.
  • Most classes are extending existing Java classes. Any method you will typically call on a java class will percilate down to the core Java class, if it exists. (See the JavaPassthrough mixin for specifics)
  • You must resume the debugger in the 'on_break' block ('dbg.resume') before returning. This is because there is the ability to step within the block as well.

Linux users:

  • You must use the sun 'JDK' as it is the only packages that has the com.sun.jdi classes
  • You also may have to explicitally add the tools.jar to teh $CLASSPATH variable in your script. (This will be the case if you see the following exception: NameError: cannot load Java class com.sun.jdi.Bootstrap)

Contributing to android_debug

  • Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
  • Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
  • Fork the project.
  • Start a feature/bugfix branch.
  • Commit and push until you are happy with your contribution.
  • Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
  • Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.


Copyright (c) 2013 wuntee. See LICENSE.txt for further details.

Something went wrong with that request. Please try again.