Skip to content

Commit 20eae2b

Browse files
RyanCarrierRyanCarrier
committed
Update README to have more robust avd caching; avoiding issues like ReactiveCircus#392
and ReactiveCircus#362
1 parent 1fef06a commit 20eae2b

File tree

1 file changed

+35
-29
lines changed

1 file changed

+35
-29
lines changed

‎README.md

+35-29
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ A GitHub Action for installing, configuring and running hardware-accelerated And
88

99
The old ARM-based emulators were slow and are no longer supported by Google. The modern Intel Atom (x86 and x86_64) emulators can be fast, but rely on two forms of hardware acceleration to reach their peak potential: [Graphics Acceleration](https://developer.android.com/studio/run/emulator-acceleration#accel-graphics), e.g. `emulator -gpu host` and [Virtual Machine(VM) Acceleration](https://developer.android.com/studio/run/emulator-acceleration#accel-vm), e.g. `emulator -accel on`. **Note:** GPU and VM Acceleration are two different and non-mutually exclusive forms of Hardware Acceleration.
1010

11-
This presents a challenge when running emulators on CI especially when running emulators within a docker container, because **Nested Virtualization** must be supported by the host VM which isn't the case for most cloud-based CI providers due to infrastructural limits. If you want to learn more about Emulators on CI, here's an article [Yang](https://github.com/ychescale9) wrote: [Running Android Instrumented Tests on CI](https://dev.to/ychescale9/running-android-emulators-on-ci-from-bitrise-io-to-github-actions-3j76).
11+
This presents a challenge when running emulators on CI especially when running emulators within a docker container, because **Nested Virtualization** must be supported by the host VM which isn't the case for most cloud-based CI providers due to infrastructural limits. If you want to learn more about Emulators on CI, here's an article [Yang](https://github.com/ychescale9) wrote: [Running Android Instrumented Tests on CI](https://dev.to/ychescale9/running-android-emulators-on-ci-from-bitrise-io-to-github-actions-3j76).
1212

1313
## Running hardware accelerated emulators on Linux runners
1414

@@ -133,6 +133,8 @@ jobs:
133133
strategy:
134134
matrix:
135135
api-level: [21, 23, 29]
136+
target: [default, google_apis]
137+
arch: [x86_64]
136138
steps:
137139
- name: checkout
138140
uses: actions/checkout@v4
@@ -145,21 +147,23 @@ jobs:
145147
146148
- name: Gradle cache
147149
uses: gradle/actions/setup-gradle@v3
148-
150+
149151
- name: AVD cache
150152
uses: actions/cache@v4
151153
id: avd-cache
152154
with:
153155
path: |
154156
~/.android/avd/*
155157
~/.android/adb*
156-
key: avd-${{ matrix.api-level }}
158+
key: avd-${{ matrix.api-level }}-${{ matrix.target }}-${{ matrix.arch }}
157159
158160
- name: create AVD and generate snapshot for caching
159161
if: steps.avd-cache.outputs.cache-hit != 'true'
160162
uses: reactivecircus/android-emulator-runner@v2
161163
with:
162164
api-level: ${{ matrix.api-level }}
165+
target: ${{ matrix.target }}
166+
arch: ${{ matrix.arch }}
163167
force-avd-creation: false
164168
emulator-options: -no-window -gpu swiftshader_indirect -noaudio -no-boot-anim -camera-back none
165169
disable-animations: false
@@ -169,6 +173,8 @@ jobs:
169173
uses: reactivecircus/android-emulator-runner@v2
170174
with:
171175
api-level: ${{ matrix.api-level }}
176+
target: ${{ matrix.target }}
177+
arch: ${{ matrix.arch }}
172178
force-avd-creation: false
173179
emulator-options: -no-snapshot-save -no-window -gpu swiftshader_indirect -noaudio -no-boot-anim -camera-back none
174180
disable-animations: true
@@ -177,32 +183,32 @@ jobs:
177183

178184
## Configurations
179185

180-
| **Input** | **Required** | **Default** | **Description** |
181-
|-|-|-|-|
182-
| `api-level` | Required | N/A | API level of the platform system image - e.g. 23 for Android Marshmallow, 29 for Android 10. **Minimum API level supported is 15**. |
183-
| `target` | Optional | `default` | Target of the system image - `default`, `google_apis`, `playstore`, `android-wear`, `android-wear-cn`, `android-tv`, `google-tv`, `aosp_atd` or `google_atd`. Note that `aosp_atd` and `google_atd` currently require the following: `api-level: 30`, `arch: x86` or `arch: arm64-v8` and `channel: canary`. |
184-
| `arch` | Optional | `x86` | CPU architecture of the system image - `x86`, `x86_64` or `arm64-v8a`. Note that `x86_64` image is only available for API 21+. `arm64-v8a` images require Android 4.2+ and are limited to fewer API levels (e.g. 30). |
185-
| `profile` | Optional | N/A | Hardware profile used for creating the AVD - e.g. `Nexus 6`. For a list of all profiles available, run `avdmanager list device`. |
186-
| `cores` | Optional | 2 | Number of cores to use for the emulator (`hw.cpu.ncore` in config.ini). |
187-
| `ram-size` | Optional | N/A | Size of RAM to use for this AVD, in KB or MB, denoted with K or M. - e.g. `2048M` |
188-
| `heap-size` | Optional | N/A | Heap size to use for this AVD, in KB or MB, denoted with K or M. - e.g. `512M` |
189-
| `sdcard-path-or-size` | Optional | N/A | Path to the SD card image for this AVD or the size of a new SD card image to create for this AVD, in KB or MB, denoted with K or M. - e.g. `path/to/sdcard`, or `1000M`. |
190-
| `disk-size` | Optional | N/A | Disk size, or partition size to use for this AVD. Either in bytes or KB, MB or GB, when denoted with K, M or G. - e.g. `2048M` |
191-
| `avd-name` | Optional | `test` | Custom AVD name used for creating the Android Virtual Device. |
192-
| `force-avd-creation` | Optional | `true` | Whether to force create the AVD by overwriting an existing AVD with the same name as `avd-name` - `true` or `false`. |
193-
| `emulator-boot-timeout` | Optional | `600` | Emulator boot timeout in seconds. If it takes longer to boot, the action would fail - e.g. `300` for 5 minutes. |
194-
| `emulator-options` | Optional | See below | Command-line options used when launching the emulator (replacing all default options) - e.g. `-no-window -no-snapshot -camera-back emulated`. |
195-
| `disable-animations` | Optional | `true` | Whether to disable animations - `true` or `false`. |
196-
| `disable-spellchecker` | Optional | `false` | Whether to disable spellchecker - `true` or `false`. |
197-
| `disable-linux-hw-accel` | Optional | `auto` | Whether to disable hardware acceleration on Linux machines - `true`, `false` or `auto`.|
198-
| `enable-hw-keyboard` | Optional | `false` | Whether to enable hardware keyboard - `true` or `false`. |
199-
| `emulator-build` | Optional | N/A | Build number of a specific version of the emulator binary to use e.g. `6061023` for emulator v29.3.0.0. |
200-
| `working-directory` | Optional | `./` | A custom working directory - e.g. `./android` if your root Gradle project is under the `./android` sub-directory within your repository. Will be used for `script` & `pre-emulator-launch-script`. |
201-
| `ndk` | Optional | N/A | Version of NDK to install - e.g. `21.0.6113669` |
202-
| `cmake` | Optional | N/A | Version of CMake to install - e.g. `3.10.2.4988404` |
203-
| `channel` | Optional | stable | Channel to download the SDK components from - `stable`, `beta`, `dev`, `canary` |
204-
| `script` | Required | N/A | Custom script to run - e.g. to run Android instrumented tests on the emulator: `./gradlew connectedCheck` |
205-
| `pre-emulator-launch-script` | Optional | N/A | Custom script to run after creating the AVD and before launching the emulator - e.g. `./adjust-emulator-configs.sh` |
186+
| **Input** | **Required** | **Default** | **Description** |
187+
| ---------------------------- | ------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
188+
| `api-level` | Required | N/A | API level of the platform system image - e.g. 23 for Android Marshmallow, 29 for Android 10. **Minimum API level supported is 15**. |
189+
| `target` | Optional | `default` | Target of the system image - `default`, `google_apis`, `playstore`, `android-wear`, `android-wear-cn`, `android-tv`, `google-tv`, `aosp_atd` or `google_atd`. Note that `aosp_atd` and `google_atd` currently require the following: `api-level: 30`, `arch: x86` or `arch: arm64-v8` and `channel: canary`. |
190+
| `arch` | Optional | `x86` | CPU architecture of the system image - `x86`, `x86_64` or `arm64-v8a`. Note that `x86_64` image is only available for API 21+. `arm64-v8a` images require Android 4.2+ and are limited to fewer API levels (e.g. 30). |
191+
| `profile` | Optional | N/A | Hardware profile used for creating the AVD - e.g. `Nexus 6`. For a list of all profiles available, run `avdmanager list device`. |
192+
| `cores` | Optional | 2 | Number of cores to use for the emulator (`hw.cpu.ncore` in config.ini). |
193+
| `ram-size` | Optional | N/A | Size of RAM to use for this AVD, in KB or MB, denoted with K or M. - e.g. `2048M` |
194+
| `heap-size` | Optional | N/A | Heap size to use for this AVD, in KB or MB, denoted with K or M. - e.g. `512M` |
195+
| `sdcard-path-or-size` | Optional | N/A | Path to the SD card image for this AVD or the size of a new SD card image to create for this AVD, in KB or MB, denoted with K or M. - e.g. `path/to/sdcard`, or `1000M`. |
196+
| `disk-size` | Optional | N/A | Disk size, or partition size to use for this AVD. Either in bytes or KB, MB or GB, when denoted with K, M or G. - e.g. `2048M` |
197+
| `avd-name` | Optional | `test` | Custom AVD name used for creating the Android Virtual Device. |
198+
| `force-avd-creation` | Optional | `true` | Whether to force create the AVD by overwriting an existing AVD with the same name as `avd-name` - `true` or `false`. |
199+
| `emulator-boot-timeout` | Optional | `600` | Emulator boot timeout in seconds. If it takes longer to boot, the action would fail - e.g. `300` for 5 minutes. |
200+
| `emulator-options` | Optional | See below | Command-line options used when launching the emulator (replacing all default options) - e.g. `-no-window -no-snapshot -camera-back emulated`. |
201+
| `disable-animations` | Optional | `true` | Whether to disable animations - `true` or `false`. |
202+
| `disable-spellchecker` | Optional | `false` | Whether to disable spellchecker - `true` or `false`. |
203+
| `disable-linux-hw-accel` | Optional | `auto` | Whether to disable hardware acceleration on Linux machines - `true`, `false` or `auto`. |
204+
| `enable-hw-keyboard` | Optional | `false` | Whether to enable hardware keyboard - `true` or `false`. |
205+
| `emulator-build` | Optional | N/A | Build number of a specific version of the emulator binary to use e.g. `6061023` for emulator v29.3.0.0. |
206+
| `working-directory` | Optional | `./` | A custom working directory - e.g. `./android` if your root Gradle project is under the `./android` sub-directory within your repository. Will be used for `script` & `pre-emulator-launch-script`. |
207+
| `ndk` | Optional | N/A | Version of NDK to install - e.g. `21.0.6113669` |
208+
| `cmake` | Optional | N/A | Version of CMake to install - e.g. `3.10.2.4988404` |
209+
| `channel` | Optional | stable | Channel to download the SDK components from - `stable`, `beta`, `dev`, `canary` |
210+
| `script` | Required | N/A | Custom script to run - e.g. to run Android instrumented tests on the emulator: `./gradlew connectedCheck` |
211+
| `pre-emulator-launch-script` | Optional | N/A | Custom script to run after creating the AVD and before launching the emulator - e.g. `./adjust-emulator-configs.sh` |
206212

207213
Default `emulator-options`: `-no-window -gpu swiftshader_indirect -no-snapshot -noaudio -no-boot-anim`.
208214

0 commit comments

Comments
 (0)