# Android build targets

> Every android-* build target Elide registers, what each runs and writes, the options they take, and how elide run, elide test and elide mcp map onto them.

Every step of an Android build, and every device action, is a build target. `elide run`, `elide test --device` and
the `android/*` agent tools run these targets, and `elide build <target>` runs any of them directly. List them, with
their options, without running anything:

```bash
elide build --inspect
elide build android-run-app --help
```

In the names below, `<a>` is an application artifact, `<l>` a library, `<b>` a bundle, `<x>` any of them, `<d>` a
device from `android.devices`, and `<t>` a test source set.

## Building

| Target | Runs | Writes |
| --- | --- | --- |
| `android-sdk` | `sdkmanager` | The lockfile's SDK record |
| `android-libraries` | — | Unpacked `.aar`s under `.dev/android/libraries/` |
| `android-resources-<x>` | `aapt2 compile` | Compiled resources |
| `android-manifest-<x>` | — | The merged `AndroidManifest.xml` |
| `android-link-<x>` | `aapt2 link` | `resources.apk` and `R.java` |
| `android-r-<x>` | `javac` | Compiled `R` classes |
| `android-dex-<a>` | `d8` | `classes*.dex` |
| `android-r8-<a>` | R8, in place of `d8` when minified | `classes*.dex`, `mapping.txt` |
| `android-mapping-<a>` | — | `.dev/artifacts/<a>-mapping.txt` |
| `android-package-<a>` | — | The unaligned APK |
| `android-align-<a>` | `zipalign -P 16` | The aligned APK |
| `android-signing-<a>` | `keytool` | The debug keystore, when it is missing |
| `android-sign-<a>` | `apksigner` | The signed APK |
| `android-classes-<l>` | — | The library's `classes.jar` |
| `android-module-<b>` | — | A bundle module zip |
| `android-bundle-<b>` | `bundletool` | The bundle, before signing |
| `<a>`, `<l>`, `<b>` | — | `.dev/artifacts/<name>.{apk,aar,aab}` |
| `<a>-androidTest` | the same pipeline | The instrumented test APK |

Resources are linked before the code compiles, which is what makes `R` usable: the `R` classes are placed on the
compile classpath of the artifact's source sets. A build that changed nothing re-runs none of it; adding a resource
re-runs the compile, the dex and the packaging. Intermediate files live under `.dev/android/<x>/`.

## Devices

None of these is a default target: `elide build` alone never touches a device.

| Target | Does |
| --- | --- |
| `android-run-<a>` | Install and launch on `--device`, the one attached device, or the project's emulator |
| `android-run-device-<a>` | The same, on a physical device only |
| `android-run-emulator-<a>` | The same, on the project's emulator, booted or reused |
| `android-debug-<a>` | Launch suspended and forward JDWP |
| `android-test-<a>` | Run instrumented tests |
| `android-test-<a>-on-<d>` | Run them on a declared test device |
| `android-test-<a>-on-all` | Run them on every declared test device |
| `android-emulator` | Boot the project's AVD and wait for it |
| `android-emulator-stop` | Stop the emulator running the project's AVD |
| `android-avd` | Create or repair the AVD without booting it |
| `android-keystore-<a>` | Create the keystore `signing` names |

Run and debug targets exist only for a signed APK, and debug targets only for a debuggable one. `android-avd`,
`android-emulator` and `android-emulator-stop` are one per project, registered when it has a signed APK.

## Host tests

Ahead of each test source set's run, one artifact is linked again with the test libraries
([Android tests](https://elide.help/docs/toolchain/android/testing#host-tests)):

| Target | Writes |
| --- | --- |
| `android-resources-<a>-<t>` | The artifact's and every library's resources, compiled |
| `android-manifest-<a>-<t>` | The manifest, merged with test libraries' too |
| `android-link-<a>-<t>`, `android-r-<a>-<t>` | `resources.apk` and `R` for every package |
| `android-host-test-<a>-<t>` | The resource APK, assets and the Robolectric test configuration |

## Options

| Option | Targets | Effect |
| --- | --- | --- |
| `--device=<serial>` | run, debug, test | Use that attached device. |
| `--device=<serial>` | `android-emulator-stop` | Stop that emulator. |
| `--emulator` | debug, test | Use the project's emulator, booting it if needed. |
| `--window`, `--no-window` | anything that boots an emulator | Show the window or run headless. |
| `--no-follow` | run, debug | Return once launched instead of following the log. |
| `--debug[=<port>]` | debug | The local JDWP port; a free one when bare. |
| `--tests=<class>[#<method>]` | test | Tests to run; repeatable or comma-separated. |
| `--install-sdk` | any | Install missing SDK components, accepting their licenses. |
| `--release` | `android-keystore-<a>` | Create a release keystore ([Signing and release](https://elide.help/docs/toolchain/android/release)). |

Options are not part of a target's cache key, except `--release`.

## Commands and their targets

| Command | Target |
| --- | --- |
| `elide run [app]` | `android-run-<app>` |
| `elide run --emulator` | `android-run-emulator-<app>` |
| `elide run --debugger[=<port>]` | `android-debug-<app> [--debug=<port>]` |
| `elide test --device[=<serial>]` | `android-test-<app> [--device=<serial>]` |
| `elide test --device=<d>` | `android-test-<app>-on-<d>` |
| `elide test --device=all` | `android-test-<app>-on-all` |
| `elide install` | `android-sdk`, installing; then `android-libraries` and `android-r-<x>` for the editor classpath |
| `elide build --release` | Every application, as a release build ([Signing and release](https://elide.help/docs/toolchain/android/release#release-builds)) |