Android DebugPort

Android DebugPort is a drop-in utility which allows you to write and execute code within your app's context, at runtime, and from the comfort of your computer's terminal. Think of it as a window into your application through which you can both inspect and modify its state.

You can connect to one of two REPL servers running within your app:

• Debug REPL - Run java-like code and inspect/modify the state of your android application.
• SQLite REPL - Execute queries against your app's SQLite databaases.

Getting Started - Drop-in

Configure Your Dependencies

Add the jitpack.io repository to your root build.gradle:

allprojects {
    repositories {
        jcenter()
        maven { url "https://jitpack.io" }
    }
}

In your application's build.gradle file, add a dependency for Android DebugPort:

debugCompile 'com.github.jasonwyatt.Android-DebugPort:lib:2.1.0'
releaseCompile 'com.github.jasonwyatt.Android-DebugPort:lib-noop:2.1.0'

Note: The final line above will use a no-op version of the DebugPort library in production builds. This makes it impossible for people to run the DebugPort server on a production build.

Run Your App

When you start your app after building for debug, you will see a low-priority notification in your system tray which will allow you to start the debugport servers.

Connecting to the Debug Server

$ telnet 192.168.2.83 8562 # on MacOS High Sierra: `nc 192.168.2.83 8562`
Trying 192.168.2.83...
Connected to 192.168.2.83.
Escape character is '^]'.

Android DebugPort v1.0
Report issues at https://github.com/jasonwyatt/Android-DebugPort/issues

BeanShell 2.0b6 - by Pat Niemeyer ([email protected])
bsh %

There are a few built in commands, to see what they are, run help();

bsh % help();
Available Commands:
  Access:
      call(Object obj, String method, Object... params)
          Call a method, regardless of access modifiers, on the provided object.
      get(Object obj, String fieldName)
          Get the value of a field, regardless of access modifiers, on the provided object.
      set(Object obj, String fieldName, Object value)
          Set the value of a field on the provided object to the given value, regardless of access modifiers.

  Field Inspection:
      fields(Class class)
          List all of the fields available for a particular class.
      fields(Object obj)
          List all of the fields available for a particular object.
      fieldsLocal(Class class)
          List all of the fields defined locally for a particular class.
      fieldsLocal(Object obj)
          List all of the fields defined locally for an object.

  Method Inspection:
      methods(Class class)
          Get the available methods for the provided class.
      methods(Object obj)
          Get the available methods for the provided object.
      methodsLocal(Class class)
          Show all of the locally-declared methods for the provided class.
      methodsLocal(Object obj)
          Show all of the locally-declared methods for the provided object.

  Other:
      exit()
          Exit this interpreter.
      help()
          Show this help message.
      source(String scriptPath)
          Load and run a Beanshell script within your app's assets folder.

bsh %

Also, your application variable is automatically included as a global variable in the interpreter. It's called app. Try running methodsLocal(app);:

bsh % methodsLocal(app);
declared methods: {
  public void onCreate()
}
bsh %

Don't forget that you can execute whatever code you wish within the DebugPort. See the beanshell documentation for the full rundown.

You can exit at any time by running the exit(); command.

Connecting to the SQLite Server

$ telnet 192.168.0.100 8563 # on MacOS High Sierra: `nc 192.168.2.83 8563`
Trying 192.168.0.100...
Connected to 192.168.0.100.
Escape character is '^]'.

Android DebugPort v1.0
Report issues at https://github.com/jasonwyatt/Android-DebugPort/issues

SQLite Database REPL

sqlite>

As with the Debug server, there is a help command for the SQLite server:

sqlite> help;
Help:
  As you'd expect, you can execute any valid SQLite statements against the database to which you're
  currently connected (see: `USE [database name];` below).

  In addition to regular SQLite commands, Android DebugPort provides additional functionality via several
  additional commands.

  Available non-SQLite commands (case insensitive):
    Databases:
        CREATE DATABASE [database name];
            Create a new database called [database name].
        DROP DATABASE [database name];
            Drop the database named [database name] from the app's collection of databases.
        USE [database name];
            Connect to the database called [database name]. All SQL commands will be executed against
            this database until USE is called again.

    Inspection:
        SHOW CREATE TABLE [table name];
            Show the CREATE TABLE command used to create [table name].
        SHOW DATABASES;
            Show all available databases for the app, including temporary databases.
        SHOW TABLES;
            Show all of the tables defined for the database to which you are currently connected.

    Other:
        exit; or quit;
            Exit this interpreter.
        help;
            Show this help message.

sqlite>

Try running show databases; to see the available databases for your app:

sqlite> show databases;
+----------+
| Database |
+----------+
| blog     |
| projects |
+----------+

sqlite>

Run use [database name]; to connect to a database, and once you're connected, you can run any SQLite command you want. You can quit at any time by running the exit; command.

Advanced Configuration

You can configure Android-DebugPort by setting any of the following <meta-data> values in your Application's AndroidManifest.xml.

<application 
    name=".MyApplication"
    label="@string/app_name"
    >
    
    <!-- Customize the port on which the BeanShell REPL will be exposed. -->
    <meta-data android:name="jwf.debugport.METADATA_DEBUG_PORT" android:value="8000"/>
    <!-- Customize the port on which the SQLite REPL will be exposed. -->
    <meta-data android:name="jwf.debugport.METADATA_SQLITE_PORT" android:value="9000"/>
    <!-- Provide any startup commands for the BeanShell REPL by referencing a string array resource. -->
    <meta-data android:name="jwf.debugport.METADATA_STARTUP_COMMANDS" android:resource="@array/startup_commands"/>
    
    <!-- ... -->
</application>

Note: It is recommended that if you wish to supply these meta-data values, you should consider setting them within an AndroidManifest.xml file for the debug build variant.

License

This library is released under the Apache 2.0 License.