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.