Command reference

All commands read the jar path from R8_ASSISTANT_JAR, as set up in references/setup.md. Every command prints its usage with --help. When this page and the usage differ, follow the usage:

java -jar "$R8_ASSISTANT_JAR" --help
java -jar "$R8_ASSISTANT_JAR" instrument --help

The commands exit with 0 on success, 1 when the command fails, and 2 for usage errors. On failure, a command prints a line that starts with Error:.

instrument

Adds reflection logging to an APK, then aligns the APK and signs it.

java -jar "$R8_ASSISTANT_JAR" instrument \
  --input app/build/outputs/apk/debug/app-debug.apk \
  --output app/build/r8-assistant/app-debug-instrumented.apk
  • --input or -i: the APK to instrument. It must be debuggable, or signed only with the debug key.
  • --output or -o: the instrumented APK to write.
  • --sdk: the Android SDK directory. Without it, instrument uses ANDROID_HOME, then ANDROID_SDK_ROOT, then sdk.dir in local.properties in the current directory.
  • --build-tools: the build-tools version to use, such as 36.0.0. Without it, instrument uses the highest installed version that has aapt2, zipalign and apksigner.
  • --ks, --ks-pass, --ks-key-alias and --key-pass: the keystore, its password, the key alias and the key password for signing. Passwords take the forms pass:, env: and file:, as in apksigner. Without them, instrument signs with debug.keystore in ~/.android or in ANDROID_USER_HOME, with the password android and the alias androiddebugkey.
  • --verbose or -v: print the build-tools commands that instrument runs.

Pin the build tools when the highest installed version fails:

java -jar "$R8_ASSISTANT_JAR" instrument \
  --input app/build/outputs/apk/debug/app-debug.apk \
  --output app/build/r8-assistant/app-debug-instrumented.apk \
  --build-tools 36.0.0 \
  --verbose

suggest

Writes keep rules for the reflection in the logs.

java -jar "$R8_ASSISTANT_JAR" suggest \
  --log app/build/r8-assistant/debug-settings.json \
  --log app/build/r8-assistant/debug-sync.json \
  --rules app/proguard-rules.pro \
  --output app/build/r8-assistant/suggested.pro
  • --log: a reflection log. Repeat it for several journeys.
  • --rules: an existing rule file. Repeat it for several files. The output leaves out what these files already keep.
  • --output: the file for the rules. Without it, suggest prints the rules.

diff

Compares the logs with existing rules and classifies each rule.

java -jar "$R8_ASSISTANT_JAR" diff \
  --log app/build/r8-assistant/debug-settings.json \
  --log app/build/r8-assistant/debug-sync.json \
  --rules app/proguard-rules.pro \
  --output app/build/r8-assistant/proposed.pro
  • --log: a reflection log. Repeat it for several journeys.
  • --rules: a rule file to compare. Repeat it for several files.
  • --output: the file for the proposed rules. Without it, diff prints the proposed rules after the summary.

diff assigns one of six verdicts to each rule and annotates the proposed rules file with a comment:

  • JUSTIFIED (# Justified:): the rule keeps what the logs require.
  • NARROWED (# Narrowed:): the rule keeps more than the logs require and is replaced by narrower rules for the observed classes and members.
  • NOT_OBSERVED (# Removed, not observed in the logs:): nothing the rule keeps was used reflectively in the logged runs.
  • UNDECIDED (# Undecided, kept as is:): logs do not decide the selector, such as extends, implements, -keepclasseswithmembers, member @Annotation, class @Annotation without members, native-only rules, or unlogged modifiers. Class @Annotation with members and mixed native rules are narrowed or removed.
  • CONDITIONAL (# Conditional, kept as is:): an -if rule that diff keeps as is. -if rules whose target combines a ** class wildcard with member rules are narrowed or removed.
  • NOT_ANALYZED (# Not analyzed, kept as is:): a non-keep directive such as -assumenosideeffects or -checkdiscard.

query

Filters the events of a log.

java -jar "$R8_ASSISTANT_JAR" query \
  --log app/build/r8-assistant/debug-settings.json \
  --class com.example.app.settings.DarkTheme \
  --member load \
  --event CLASS_GET_DECLARED_METHOD \
  --stacks
  • --log: a reflection log to read. Repeat it for several logs.
  • --class: only events on matching classes. Takes a keep rule class pattern with *, ** and ? wildcards. Repeat it for several patterns.
  • --member: only events on matching member names, with * and ? wildcards. Repeat it for several patterns.
  • --event: only events of a matching type or API name, such as CLASS_FOR_NAME or Class.forName, with * and ? wildcards. Repeat it for several patterns.
  • --stacks: print the call stack of each event.