blob: 5057007117c61bec9e02d0a9ac7d154fc23bfc4a [file] [view] [edit]
# Setup
Run every command from the project root. The examples use the app module
`app`, the application ID `com.example.app` and the state directory
`app/build/r8-assistant/`. Replace them with the values of the project.
## Download the jar
The skill pins version {{R8_ASSISTANT_VERSION}} of the R8 assistant jar,
`com.android.tools:r8-assistant` on Google Maven. The download step checks the
SHA-256 of the jar and refuses a jar that does not match. When
`R8_ASSISTANT_JAR` is already set, for example to a local build of the jar,
the step uses it as is.
```shell
r8_assistant_sha256() {
if command -v sha256sum > /dev/null 2>&1; then
sha256sum "$1" | cut -d ' ' -f 1
else
shasum -a 256 "$1" | cut -d ' ' -f 1
fi
}
r8_assistant_fetch() {
local version="{{R8_ASSISTANT_VERSION}}"
local expected="{{R8_ASSISTANT_SHA256}}"
if [ -n "${R8_ASSISTANT_JAR:-}" ]; then
echo "Using R8_ASSISTANT_JAR=$R8_ASSISTANT_JAR"
return 0
fi
case "$version" in
"" | *[!0-9A-Za-z.-]*)
echo "This copy of the skill has no released jar version." >&2
echo "Set R8_ASSISTANT_JAR to an r8-assistant jar." >&2
return 1
;;
esac
case "$expected" in
"" | *[!0-9a-fA-F]*)
echo "This copy of the skill has no released jar SHA-256." >&2
echo "Set R8_ASSISTANT_JAR to an r8-assistant jar." >&2
return 1
;;
esac
local repo="${R8_ASSISTANT_MAVEN_REPO:-https://dl.google.com/android/maven2}"
local dir="$HOME/.android/cache/r8-assistant/$version"
local jar="$dir/r8-assistant-$version.jar"
local url="$repo/com/android/tools/r8-assistant/$version"
url="$url/r8-assistant-$version.jar"
if [ ! -f "$jar" ] || [ "$(r8_assistant_sha256 "$jar")" != "$expected" ]; then
mkdir -p "$dir" || return 1
if ! curl -fsSL -o "$jar.part" "$url"; then
rm -f "$jar.part"
echo "Download failed: $url" >&2
return 1
fi
if [ "$(r8_assistant_sha256 "$jar.part")" != "$expected" ]; then
rm -f "$jar.part"
echo "SHA-256 mismatch for $url. Refusing to use it." >&2
return 1
fi
mv -f "$jar.part" "$jar" || return 1
fi
export R8_ASSISTANT_JAR="$jar"
echo "R8_ASSISTANT_JAR=$R8_ASSISTANT_JAR"
}
r8_assistant_fetch
```
The step prints the path of the jar. If your shell does not keep variables
between commands, set `R8_ASSISTANT_JAR` to that path at the start of every
command that runs the jar, or run the step again. It reuses the verified jar.
On Windows, run the same step in PowerShell:
```powershell
$version = "{{R8_ASSISTANT_VERSION}}"
$expected = "{{R8_ASSISTANT_SHA256}}"
if ($env:R8_ASSISTANT_JAR) {
Write-Output "Using R8_ASSISTANT_JAR=$env:R8_ASSISTANT_JAR"
} else {
if ($version -notmatch '^[0-9A-Za-z.-]+$' -or $expected -notmatch '^[0-9a-fA-F]{64}$') {
throw "This copy of the skill has no released jar version. Set R8_ASSISTANT_JAR to an r8-assistant jar."
}
$repo = $env:R8_ASSISTANT_MAVEN_REPO
if (-not $repo) { $repo = "https://dl.google.com/android/maven2" }
$dir = Join-Path $HOME ".android/cache/r8-assistant/$version"
$jar = Join-Path $dir "r8-assistant-$version.jar"
$url = "$repo/com/android/tools/r8-assistant/$version/r8-assistant-$version.jar"
if (-not ((Test-Path $jar) -and ((Get-FileHash -Algorithm SHA256 $jar).Hash -eq $expected))) {
New-Item -ItemType Directory -Force -Path $dir | Out-Null
Invoke-WebRequest -UseBasicParsing -Uri $url -OutFile "$jar.part"
if ((Get-FileHash -Algorithm SHA256 "$jar.part").Hash -ne $expected) {
Remove-Item "$jar.part"
throw "SHA-256 mismatch for $url. Refusing to use it."
}
Move-Item -Force "$jar.part" $jar
}
$env:R8_ASSISTANT_JAR = $jar
Write-Output "R8_ASSISTANT_JAR=$jar"
}
```
When the step fails:
- **Download failed**, for example with HTTP 404: the version is not on Google
Maven, or a proxy blocks the download. Tell the user, and ask for a jar in
`R8_ASSISTANT_JAR` or a Maven mirror in `R8_ASSISTANT_MAVEN_REPO`.
- **SHA-256 mismatch**: stop and tell the user. Never run a jar that failed
the check.
- **No released jar version**: this copy of the skill comes from source and not
from a release. Ask the user for a jar in `R8_ASSISTANT_JAR`.
## Check the tools
```shell
java -version
java -jar "$R8_ASSISTANT_JAR" --version
adb version
adb devices -l
```
- **Java**: the jar needs Java 11 or higher. With an older Java, the
`--version` line fails with `UnsupportedClassVersionError`.
- **Android SDK**: `instrument` finds the SDK through `ANDROID_HOME`, then
`ANDROID_SDK_ROOT`, then `sdk.dir` in `local.properties` in the current
directory. The examples use `ANDROID_HOME`; set it to the SDK directory if
it is not set.
- **Build tools**: `instrument` uses the highest installed build-tools version
that has `aapt2`, `zipalign` and `apksigner`.
- **Retrace**: `retrace` comes with the SDK command line tools, in
`cmdline-tools/latest/bin`.
Find the SDK and list the installed tools:
```shell
sdk="${ANDROID_HOME:-$ANDROID_SDK_ROOT}"
if [ -z "$sdk" ]; then
sdk="$(sed -n 's/^sdk\.dir=//p' local.properties)"
fi
echo "$sdk"
ls "$sdk/build-tools" "$sdk/cmdline-tools/latest/bin"
```
Install missing packages with the Android CLI:
```shell
android sdk install "build-tools;36.0.0" "cmdline-tools;latest"
```
Without the Android CLI, use `sdkmanager` from an existing command line tools
installation:
```shell
"$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager" "build-tools;36.0.0" "cmdline-tools;latest"
```
## Pick the device
Use the device in `ANDROID_SERIAL`, or the only connected device. If several
devices are connected and `ANDROID_SERIAL` is not set, ask the user which one
to use, then set `ANDROID_SERIAL` for every adb command.
If no device is connected, list the virtual devices and ask the user which one
to start:
```shell
android emulator list
android emulator start medium_phone
```
Without the Android CLI, use `emulator -list-avds` and `emulator -avd` from
the `emulator` directory of the SDK.
Check the API level of the device. It must be at least the `minSdk` of the
app. The examples use the log path for API level 29 and higher.
[references/capture.md](capture.md) lists the path for lower API levels.
```shell
adb shell getprop ro.build.version.sdk
```
## Find the project facts
- **App module**: the module that applies the `com.android.application`
plugin, directly or through a version catalog alias such as
`libs.plugins.android.application`. Ask when there are several.
- **Release build type**: the build type with `isMinifyEnabled = true`, or
`minifyEnabled true` in Groovy. If no build type runs R8, stop. If several
build types run R8, such as `release` and `benchmark`, ask which one to use.
- **Product flavors**: with flavors the variant name combines the flavor and
the build type, such as `freeRelease`. The Gradle tasks become
`:app:assembleFreeDebug` and `:app:assembleFreeRelease`, and the outputs go
to `app/build/outputs/apk/free/release/` and
`app/build/outputs/mapping/freeRelease/`. Ask which flavor to use.
- **Rule files**: the `proguardFiles` entries of `defaultConfig` and of the
release build type, and the `consumerProguardFiles` entries of library
modules in the project. After a release build,
`app/build/outputs/mapping/release/configuration.txt` contains every rule
that R8 read. Each section starts with the comment
`# The proguard configuration file for the following section is` followed
by the path of its file. Files in the Gradle cache or in
`build/intermediates` come from dependencies or from the Android Gradle
plugin. Leave them unchanged.
- **Application IDs**: debug builds often add an `applicationIdSuffix`, so the
debug and release application IDs differ. Apps with different IDs are
separate installs that do not share data.
- **Debug keystore**: this skill signs release builds with the debug key when
needed so that they install over a debug build with the same application ID.
The key is `~/.android/debug.keystore`, or `debug.keystore` in
`ANDROID_USER_HOME`. The first debug build creates it.
Read the application ID of each APK with `aapt2` from a build-tools version
that the `ls` output lists. The first line starts with
`package: name='com.example.app'`.
```shell
"$ANDROID_HOME/build-tools/36.0.0/aapt2" dump badging app/build/outputs/apk/debug/app-debug.apk | head -n 1
```
## State directory
Keep all files of a run in the state directory of the app module:
```text
app/build/r8-assistant/
app-debug-instrumented.apk instrumented debug build
debug-settings.json debug log of the journey settings
suggested.pro output of suggest
proposed.pro proposed rules from diff
logcat-settings.txt logcat of a release replay
retraced-settings.txt retraced logcat
journeys/settings.xml journey files that you wrote
```
`./gradlew clean` deletes this directory, so do not run it during a run. At the
end, offer to copy the journey files that you wrote into the project, as
described in [references/journeys.md](journeys.md).
## Windows
Use PowerShell, `.\gradlew.bat` and `retrace.bat`. Quote every `-P` argument,
because PowerShell splits unquoted arguments that contain dots. Use
`Select-String` in place of `grep`. Run the jar with `$env:R8_ASSISTANT_JAR`,
on a single line:
```powershell
java -jar "$env:R8_ASSISTANT_JAR" instrument --input app/build/outputs/apk/debug/app-debug.apk --output app/build/r8-assistant/app-debug-instrumented.apk
```