How to Write a System-Level Android (or Java) App (e.g. Monkey)

Introduction

Different from a general Android GUI application, a system-level Android (or Java) application running in command line, using (or not using) Android frameworks, is started by developers using app_process or dalvikvm directly instead of by Android framework itself
To develop such an application, one need to
1. if an Android app, prepare a framework.jar for compiling (implementation of framework.jar can be empty or throwing RuntimeException, doesn’t matter); the framework.jar can be obtained from Android SDK directory (the android.jar), or compiling AOSP directly, or pulled from emulators or devices (located at /system/framework/framework.jar), or using a gradle/maven dependency built by robolectric team; but remember to use compileOnly keyword instead of implementation if you'd like to package then into a uber jar (see here on the differences of these keywords)
2. compiling the compared jar to dex using dx or d8
3. push the recompiled dex to Android devices
4. start it using app_process or dalvikvm

Example

Write a HelloWorld.java in directory src/com/example
Compile to class in src: $ javac –cp /path/to/framework.jar com/example/HelloWorld.java
Compile to jar: $ jar cvfe HelloWorld-jar.jar com.example.HelloWorld com/example/HelloWorld.class
Compile to dex: $ d8 --output HelloWorld.dex HelloWorld-jar.jar
Push to device: $ adb push HelloWorld.dex /data/local/tmp

Run it in devices shell by either app_process or dalvikvm

# app_process
$ CLASSPATH=/data/local/tmp/HelloWorld.dex app_process /data/local/tmp com.example.HelloWorld

# dalvikvm
$ CLASSPATH=/data/local/tmp/HelloWorld.dex dalvikvm com.example.HelloWorld

see also #3

The Simplest Way

As long as a system-level app has no differences from a common app (except running in command line). The simplest way is no more easier than reusing the Android Studio tool chain.

just create an Android project without any activities
write your own codes, for example HelloWorld
build the project like a normal project (AS would automatically compile them using javac and dx, and pack them into a classes.dex inside an apk)
push the apk to the device

use app_process/dalvikvm to run

$ dalvikvm -cp /data/local/tmp/hello.apk com.example.HelloWorld

Debugging A System-Level App

JDWP provides the ability of debugging to JVM, which also works in dalvik/ART. Like CDP (chrome devtools protocol), JDWP defines a debugging protocol of any debugger frontend and the backend. So any client/server that implements the protocol can connect to each other.

Step1: Start debugging server

On devices with Android 8 and/or lower, JDWP is implemented using the java agent, i.e., the -agentlib option. To enable JDWP:

$ dalvikvm -cp /data/local/tmp/hello.apk -agentlib:jdwp=transport=dt_socket,suspend=y,server=y,address=5005 com.example.HelloWorld

Above options "transport=dt_socket,suspend=y,server=y,address=5005" tells JVM to enable JDWP as a TCP server at port 5005, and suspend the app once start.

On devices with Android 8+, use:

$ dalvikvm -cp /data/local/tmp/hello.apk -XjdwpProvider:internal -XjdwpOptions:transport=dt_socket,suspend=y,server=y,address=5005 com.example.HelloWorld

Step2: Forward the debugger

Forward that port to the desktop:

$ adb forward tcp:5005 tcp:5005

Step3: Set breakpoints and connect to the debugger

Set your breakpoints in Android Studio.

Then in the menu: Run > Debug > Edit configurations.... Click on + > Remote, and fill the following:

Host: localhost
Port: 5005

Then click Debug.

connglli / blog-notes