# Android Build Test

> Build and test ezEngine on Android devices. Use this skill when building APKs, deploying to Android devices, running tests on Android, debugging Android test failures, or setting up the Android development environment for ezEngine.

- Skill: `ezengine/android-build-test` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ezengine/android-build-test`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ezengine/android-build-test/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ezengine (https://skillmd.com/u/ezengine)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ezengine/android-build-test

---


# Building and Testing ezEngine on Android

This skill covers the full Android workflow: environment setup, CMake configuration, building APKs, deploying to devices, and running tests.

## Prerequisites

### Installing Android SDK/NDK Dependencies

Run the dependency installer once to download the Android SDK, NDK, build-tools, and JDK into `Workspace/shared/android/`, unless the folder already exists:

```bash
pwsh ./Utilities/Android/InstallAndroidDependencies.ps1 -acceptLicence
```

This downloads and configures:
- Android SDK command-line tools
- Android NDK 26.1.10909125
- Android build-tools 34.0.0
- JDK 17
- Android platform API 29

### Setting Environment Variables

Before running any Android commands in the terminal, source the environment setup script:

**Bash:**
```bash
source Utilities/Android/SetupAndroidEnvVars.sh
```

**PowerShell:**
```powershell
. ./Utilities/Android/SetupAndroidEnvVars.ps1
```

This exports `ANDROID_HOME`, `ANDROID_NDK_HOME`, `JAVA_HOME` and adds `platform-tools` (adb) to `PATH`.

The CMake presets also set these variables internally, so they are only needed for manual adb/device interaction.

## CMake Presets

All Android presets inherit from the hidden `android-base` preset which configures the NDK toolchain, Ninja generator, and Vulkan support.

| Preset | ABI | Build Type |
|---|---|---|
| `android-arm64-debug` | arm64-v8a | Debug |
| `android-arm64-dev` | arm64-v8a | Dev |
| `android-arm64-shipping` | arm64-v8a | Shipping |
| `android-x64-debug` | x86_64 | Debug |
| `android-x64-dev` | x86_64 | Dev |
| `android-x64-shipping` | x86_64 | Shipping |

Use `arm64` presets for physical devices and `x64` presets for x86_64 emulators.

## Building

### Shader Compilation

Before building on Android, make sure to compile the Vulkan shaders on the host OS. Build the ShaderCompiler first (Linux or Windows build target), then run:

```bash
pwsh ./Utilities/Android/CompileShaders.ps1 -BinariesDir ./Output/Bin/LinuxNinjaGccDebug64
```

This compiles shaders for `Data/Base`, `Data/UnitTests`, and `Data/Samples/ShaderExplorer`. You need a working Linux build of `ShaderCompiler` before compiling shaders.


### Configure and Build Everything

```bash
cmake --preset android-arm64-debug
cmake --build Workspace/android-arm64-debug
```

### Build a Specific Target

```bash
cmake --build Workspace/android-arm64-debug --target FoundationTest
```

Build outputs (APKs and shared libraries) go to: `Output/Bin/AndroidNinjaClangDebugArm64/`

The output directory name follows the pattern `AndroidNinjaClang<BuildType>Arm64` (or `X64` for x86_64).

| Preset | Output Directory |
|---|---|
| `android-arm64-debug` | `Output/Bin/AndroidNinjaClangDebugArm64/` |
| `android-arm64-dev` | `Output/Bin/AndroidNinjaClangDevArm64/` |
| `android-x64-debug` | `Output/Bin/AndroidNinjaClangDebugX64/` |

### Available Test Targets

- `FoundationTest` — Foundation library tests (math, strings, containers, IO, threading, etc.)
- `CoreTest` — Core library tests (resource system, world, etc.)
- `RendererTest` — Renderer tests (requires Vulkan on device)
- `ToolsFoundationTest` — Tools foundation tests

Each target produces an APK at `Output/Bin/<OutputDir>/<TargetName>.apk`.

## Connecting to a Device

### Physical Device via ADB over TCP/IP

If no device is present, you can connect a physical device over TCP/IP using ADB:

```bash
source Utilities/Android/SetupAndroidEnvVars.sh
adb connect <device-ip>:5555
adb -s <device-ip>:5555 wait-for-device
```

### Verify Connection

Get the name and port of the connected device using:

```bash
adb devices
```

### Wake and Unlock the Device

Before launching a test, wake the device and dismiss the keyguard so the native activity can create its window and receive `APP_CMD_INIT_WINDOW`:

```bash
source Utilities/Android/SetupAndroidEnvVars.sh

# Stop a test process left behind by an earlier timeout, if necessary.
adb -s <adb-device-name> shell am force-stop com.ezengine.RendererTest

adb -s <adb-device-name> shell input keyevent KEYCODE_WAKEUP
```

Verify that the device is awake before starting the test:

```bash
adb -s <adb-device-name> shell dumpsys power | grep 'mWakefulness='
```

The expected output contains `mWakefulness=Awake`.

## Running Tests on Device

### Using AndroidTest.ps1

The `Utilities/Android/AndroidTest.ps1` script handles the full test lifecycle: install APK, launch activity, capture logcat, detect pass/fail, download artifacts.

```bash
pwsh ./Utilities/Android/AndroidTest.ps1 \
  -deviceAdb <adb-device-name> \
  -packageName com.ezengine.FoundationTest \
  -activityName android.app.NativeActivity \
  -outputFolder ./Output \
  -apk ./Output/Bin/AndroidNinjaClangDebugArm64/FoundationTest.apk
```

#### Passing Command-Line Arguments

Use `-arguments` to pass the same flags you would use on desktop (e.g., `-run`, `-noGui`, `-all`, `-filter`):

```bash
pwsh ./Utilities/Android/AndroidTest.ps1 \
  -deviceAdb <adb-device-name> \
  -packageName com.ezengine.FoundationTest \
  -activityName android.app.NativeActivity \
  -outputFolder ./Output \
  -apk ./Output/Bin/AndroidNinjaClangDebugArm64/FoundationTest.apk \
  -arguments "-run -noGui -filter Frustum"
```

Note: `-all` and `-filter` are mutually exclusive. Use `-filter <regex>` to run a subset of tests.

The arguments are delivered to the native code via an Android Intent string extra (`args`), retrieved via JNI in `AndroidTestApplication.cpp`, parsed into argc/argv, and forwarded to `InitTestFramework`.

#### AndroidTest.ps1 Parameters

| Parameter | Required | Description |
|---|---|---|
| `-deviceAdb` | Yes | Device address for adb (e.g., `192.168.178.77:5555`) |
| `-packageName` | Yes | Android package name (e.g., `com.ezengine.FoundationTest`) |
| `-activityName` | Yes | Activity class name (always `android.app.NativeActivity`) |
| `-outputFolder` | Yes | Local directory for logcat output and test artifacts |
| `-apk` | No | Path to APK to install before running |
| `-arguments` | No | Command-line arguments to pass to the test framework |
| `-MessageBoxOnError` | No | Show error dialog on Windows (switch) |

### Test Package Names

| Test | Package Name |
|---|---|
| FoundationTest | `com.ezengine.FoundationTest` |
| CoreTest | `com.ezengine.CoreTest` |
| RendererTest | `com.ezengine.RendererTest` |
| ToolsFoundationTest | `com.ezengine.ToolsFoundationTest` |


### Manual Testing via ADB

If you need to launch a test manually without the script:

```bash
source Utilities/Android/SetupAndroidEnvVars.sh

# Install
adb -s <adb-device-name> install -r -t Output/Bin/AndroidNinjaClangDebugArm64/FoundationTest.apk

# Launch without arguments
adb -s <adb-device-name> shell am start -n com.ezengine.FoundationTest/android.app.NativeActivity

# Launch with arguments (note the quoting)
adb -s <adb-device-name> shell "am start -n com.ezengine.FoundationTest/android.app.NativeActivity --es args '-run -noGui -filter Frustum'"

# Watch logcat
adb -s <adb-device-name> logcat -s ezEngine
```

Important: When passing arguments containing dashes via `adb shell am start --es`, you **must** wrap the entire `am start` command in double quotes and the argument value in single quotes. Otherwise, `am` will misinterpret the dashes as its own flags.

### Put the Device Back to Sleep

After all test runs and artifact downloads have completed, turn off the display:

```bash
adb -s <adb-device-name> shell input keyevent KEYCODE_SLEEP
```

Verify that the device returned to sleep:

```bash
adb -s <adb-device-name> shell dumpsys power | grep 'mWakefulness='
```

The expected output contains `mWakefulness=Asleep`.

## Debugging

### Reading Logcat

All ezEngine log output uses the tag `ezEngine`:

```bash
# Live logcat filtered to ezEngine
adb -s <device>:5555 logcat -s ezEngine

# Dump existing logcat
adb -s <device>:5555 logcat -d -s ezEngine

# Clear logcat before a test run
adb -s <device>:5555 logcat --clear
```

### LLDB Remote Debugging

Use the provided debug script:

```bash
pwsh ./Utilities/Android/DbgAndroidLldb.ps1
```

### Common Issues

**Test runs all tests despite `-filter`**: The arguments must survive multiple quoting layers (PowerShell → adb → Android shell → `am`). When using `AndroidTest.ps1`, pass arguments as a single string: `-arguments "-filter Frustum"`. When using `adb` directly, wrap the whole `am start` command: `adb shell "am start ... --es args '-filter Frustum'"`.

**APK install fails**: Ensure the device is connected (`adb devices`), USB debugging is enabled, and the device allows unknown sources. The script retries up to 6 times.

**Activity crashes immediately**: Check logcat for the full stack trace. Common causes include missing Vulkan drivers (for RendererTest) or missing shader cache files.

**Test times out without any ezEngine log output**: Check the device power state with `adb shell dumpsys power`. If the display is asleep, the native activity can remain stopped without receiving `APP_CMD_INIT_WINDOW`, so the engine and test framework never start. Wake and unlock the device before retrying.

**Build fails with NDK not found**: Ensure dependencies are installed (`InstallAndroidDependencies.ps1`) and environment variables are set. The CMake presets expect the NDK at `Workspace/shared/android/ndk/26.1.10909125`.

## CI Pipeline Reference

The CI pipeline in `Code/BuildSystem/AzurePipelines/Android-arm64.yml` performs the following steps:

1. Configure and build `linux-clang-dev` (host tools only, specifically `ShaderCompiler`)
2. Compile Vulkan shaders using the host ShaderCompiler
3. Install Android dependencies
4. Configure and build `android-arm64-dev`
5. Connect to the physical test device
6. Run FoundationTest, CoreTest, RendererTest, ToolsFoundationTest sequentially
7. Disconnect from device and publish test artifacts

## Key Source Files

- `Utilities/Android/AndroidTest.ps1` — Test runner script (install, launch, logcat, pass/fail detection)
- `Utilities/Android/AndroidUtils.ps1` — Shared utilities (adb wrappers, retry logic, file copy)
- `Utilities/Android/InstallAndroidDependencies.ps1` — SDK/NDK/JDK dependency installer
- `Utilities/Android/CompileShaders.ps1` — Vulkan shader compiler wrapper
- `Utilities/Android/SetupAndroidEnvVars.sh` — Bash environment variable setup
- `Utilities/Android/SetupAndroidEnvVars.ps1` — PowerShell environment variable setup
- `Utilities/Android/BuildApk.ps1` — APK packaging script (called by CMake)
- `Code/UnitTests/TestFramework/Platform/Android/AndroidTestApplication.cpp` — Native activity lifecycle and Intent argument retrieval
- `Code/UnitTests/TestFramework/Platform/Android/TestFrameworkEntryPoint_Platform.h` — Android test entry point macro
- `Code/Engine/Foundation/Platform/Android/Utils/AndroidJni.h` — JNI wrapper classes (ezJniAttachment, ezJniObject, ezJniString)
- `CMakePresets.json` — Android CMake preset definitions