Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update Readme & Provide current context on Hardware Acceleration on Github #279

Merged
merged 8 commits into from
Oct 26, 2022
Merged

Update Readme & Provide current context on Hardware Acceleration on Github #279

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
94b88e6
Clarify README with mid-2022 updates, and add info for spellchecker t…
Oct 19, 2022
f04a05b
Remove redundant paragraph in Usage section, and add relevant links t…
Oct 19, 2022
e860dce
Add HAXM installation example and remove linux emphasis
Oct 20, 2022
592f866
Remove gist which contained manual emulator creation/startup
Oct 21, 2022
6722abd
Add clarity to GPU vs VM acceleration in README
Oct 25, 2022
8f64fa8
Fix reversal of examples in README
Oct 25, 2022
b9bd3bb
Add support for commenting run tests on PRs to rerun checks if they fail
Oct 26, 2022
646d92b
Add better conditional logic to determine if comment is issue or PR
Oct 26, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 14 additions & 13 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,18 @@
<a href="https://github.com/ReactiveCircus/android-emulator-runner"><img alt="GitHub Actions status" src="https://github.com/ReactiveCircus/android-emulator-runner/workflows/Main%20workflow/badge.svg"></a>
</p>

A GitHub Action for installing, configuring and running hardware-accelerated Android Emulators on macOS virtual machines.
A GitHub Action for installing, configuring and running Android Emulators on macOS and Ubuntu virtual machines.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's still important to distinguish between macOs and Ubuntu support. Being able to run in swiftshader_indirect mode is still way faster than -accel off. When people read this without any caveat they would expect running the action on linux VMs to be feasible, which is far from the reality.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Addressed in commit: e860dce


The old ARM-based emulators were slow and are no longer supported by Google. The modern Intel Atom (x86 and x86_64) emulators require hardware acceleration (HAXM on Mac & Windows, QEMU on Linux) from the host to run fast. This presents a challenge on CI as to be able to run hardware accelerated emulators within a docker container, **KVM** must be supported by the host VM which isn't the case for cloud-based CI providers due to infrastructural limits. If you want to learn more about this, here's an article I wrote: [Running Android Instrumented Tests on CI](https://dev.to/ychescale9/running-android-emulators-on-ci-from-bitrise-io-to-github-actions-3j76).
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 require hardware acceleration (HAXM on Mac & Windows, KVM on Linux) from the host. This presents a challenge on CI especially when running hardware accelerated 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 this, 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).

The **macOS** VM provided by **GitHub Actions** has **HAXM** installed so we are able to create a new AVD instance, launch an emulator with hardware acceleration, and run our Android
tests directly on the VM. You can also achieve this on a self-hosted Linux runner, but it will need to be on a compatible instance that allows you to enable KVM - for example AWS EC2 Bare Metal instances.
The **macOS** 10.x VM provided by **GitHub Actions** had **HAXM** [pre-installed](https://github.com/actions/runner-images/blob/main/images/macos/macos-10.15-Readme.md) so we were able to create a new AVD instance, launch an emulator with hardware acceleration and run our Android
tests directly on the VM. However, Github's [macOS-11](https://github.com/actions/runner-images/blob/main/images/macos/macos-11-Readme.md) and [macOS-12](https://github.com/actions/runner-images/blob/main/images/macos/macos-12-Readme.md) VMs **no longer** come pre-installed with HAXM. See [here](https://github.com/actions/runner-images/issues/183#issuecomment-610723516) and [here](https://github.com/actions/runner-images/issues/6388) for more info.
Copy link
Contributor

@mattjohnsonpint mattjohnsonpint Oct 20, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reading this and checking the links - I find myself asking, "So, how do I install HAXM then, and do I need to?" We should either point at how to do that (if possible), or explain why we don't need it (if that's so).

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mattjohnsonpint Good call. Will add this

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added in commit: e860dce

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm even more confused now, as the gist shows scripting the emulator directly instead of using the react-android-emulator action.

FWIW, I'm not installing HAXM, and for the most part, react-android-emulator is working.

Copy link
Collaborator Author

@mrk-han mrk-han Oct 21, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mattjohnsonpint Oh whoops, good call! I accidentally linked the wrong gist (same thing but without android-emulator-runner) Thank you!

fixed in 592f866


This action automates the process by doing the following:
You can also achieve nested virtualization with hardware acceleration on a self-hosted Linux runner, but the VM will need to be hosted on a compatible machine that allows you to enable KVM - for example the AWS EC2 Bare Metal instances. **The Github-hosted Linux runners are not currently KVM compatible.**

## Purpose

This action helps automate and configure the process of setting up an emulator and running your tests by doing the following:

- Install / update the required **Android SDK** components including `build-tools`, `platform-tools`, `platform` (for the required API level), `emulator` and `system-images` (for the required API level).
- Create a new instance of **AVD** with the provided [configurations](#configurations).
Expand All @@ -20,9 +24,7 @@ This action automates the process by doing the following:
- Run a custom script provided by user once the Emulator is up and running - e.g. `./gradlew connectedCheck`.
- Kill the Emulator and finish the action.

## Usage

It is recommended to run this action on a **macOS** VM, e.g. `macos-latest`, `macos-10.15` or `macos-11` to take advantage of hardware acceleration support provided by **HAXM**.
## Usage & Examples

A workflow that uses **android-emulator-runner** to run your instrumented tests on **API 29**:

Expand Down Expand Up @@ -146,7 +148,7 @@ jobs:
| `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` |
| `heap-size` | Optional | N/A | Heap size to use for this AVD, in KB or MB, denoted with K or M. - e.g. `512M` |
| `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`. |
| `disk-size` | Optional | N/A | Disk size to use for this AVD. Either in bytes or KB, MB or GB, when denoted with K, M or G. - e.g. `2048M` |
| `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` |
| `avd-name` | Optional | `test` | Custom AVD name used for creating the Android Virtual Device. |
| `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`. |
| `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`. |
Expand All @@ -163,13 +165,12 @@ jobs:

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

## Can I use this action on Linux VMs?
## Can I use this action on Github Hosted Linux VMs?

The short answer is yes but on Github-hosted Linux runners it's expected to be a much worse experience (on some newer API levels it might not work at all) than running it on macOS. You can get it running much faster on self-hosted Linux runners but only if the underlying instances support KVM (which most don't).
The short answer is yes but on Github-hosted Linux runners it's expected to be a much worse experience (on some newer API levels it might not work at all) than running it on macOS, because of the current lack of hardware acceleration support. You can get it running much faster on self-hosted Linux runners but only if the underlying instances support KVM (which most don't). Things might be better on the newer Larger runners but they are still in Beta. It is possible to use this Action with hardware accelerated Linux VMs hosted by a third-party runner provider.

For a longer answer please refer to [this issue](https://github.com/ReactiveCircus/android-emulator-runner/issues/46).


## Who is using Android Emulator Runner?

These are some of the open-source projects using (or used) **Android Emulator Runner**:
Expand Down Expand Up @@ -204,4 +205,4 @@ These are some of the open-source projects using (or used) **Android Emulator Ru
- [tinylog-org/tinylog](https://github.com/tinylog-org/tinylog/blob/v3.0/.github/workflows/build.yaml)
- [hzi-braunschweig/SORMAS-Project](https://github.com/hzi-braunschweig/SORMAS-Project/blob/development/.github/workflows/sormas_app_ci.yml)

If you are using **Android Emulator Runner** and want your project included in the list, please feel free to create an issue or open a pull request.
If you are using **Android Emulator Runner** and want your project included in the list, please feel free to open a pull request.
2 changes: 1 addition & 1 deletion action.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ inputs:
description: 'whether to disable animations - true or false'
default: 'true'
disable-spellchecker:
description: 'whether to disable spellchecker - `true` or `false`'
description: 'whether to disable the Android spell checker framework, a common source of flakiness in text fields - `true` or `false`'
default: 'false'
disable-linux-hw-accel:
description: 'whether to disable hardware acceleration on Linux machines - `true` or `false` or `auto`'
Expand Down