Skip to content

Commit

Permalink
Merge branch 'main' into release/v2
Browse files Browse the repository at this point in the history
* main:
  Prepare for release 2.30.0.
  Node 20. (#369)
  Add another user: robolectric/robolectric (#352)
  Promote using ubuntu runner with KVM. (#366)
  • Loading branch information
ychescale9 committed Jan 25, 2024
2 parents 99a4aac + 426fbd2 commit eaf4c24
Show file tree
Hide file tree
Showing 47 changed files with 1,445 additions and 1,278 deletions.
25 changes: 16 additions & 9 deletions .github/workflows/main.yml
Original file line number Diff line number Diff line change
Expand Up @@ -18,34 +18,34 @@ jobs:
timeout-minutes: 15
strategy:
matrix:
os: [macos-latest, ubuntu-latest]
os: [ubuntu-latest]
api-level: [23, 29]
target: [default, google_apis]
arch: [x86]
exclude:
- os: ubuntu-latest
api-level: 23
- os: ubuntu-latest
api-level: 29
- target: google_apis
api-level: 16
- target: google_apis
api-level: 23
- target: google_apis
api-level: 29
include:
- os: macos-latest
- os: ubuntu-latest
api-level: 24
target: playstore
arch: x86
- os: macos-latest
- os: ubuntu-latest
api-level: 30
target: aosp_atd
arch: x86
- os: macos-11
- os: macos-latest
api-level: 31
target: google_apis
arch: x86_64
- os: ubuntu-latest
api-level: 34
target: aosp_atd
arch: x86_64

steps:
- name: checkout
Expand All @@ -64,7 +64,7 @@ jobs:
- uses: actions/setup-java@v3
with:
distribution: 'zulu'
java-version: 19
java-version: 21

- uses: actions/cache@v3
id: avd-cache
Expand All @@ -81,6 +81,13 @@ jobs:
build-root-directory: test-fixture
arguments: assembleAndroidTest

- name: enable KVM for linux runners
if: runner.os == 'Linux'
run: |
echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
sudo udevadm control --reload-rules
sudo udevadm trigger --name-match=kvm
- name: run emulator to generate snapshot for caching
if: steps.avd-cache.outputs.cache-hit != 'true'
uses: ./
Expand Down
11 changes: 9 additions & 2 deletions .github/workflows/manually.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ on:
os:
description: 'OS'
required: true
default: 'macos-latest'
default: 'ubuntu-latest'
api-level:
description: 'API level of the platform and system image'
required: true
Expand Down Expand Up @@ -54,12 +54,19 @@ jobs:
- uses: actions/setup-java@v3
with:
distribution: 'zulu'
java-version: 19
java-version: 21

- uses: gradle/gradle-build-action@v2
with:
gradle-home-cache-cleanup: true

- name: enable KVM for linux runners
if: runner.os == 'Linux'
run: |
echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
sudo udevadm control --reload-rules
sudo udevadm trigger --name-match=kvm
- name: run action
uses: ./
with:
Expand Down
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
# Change Log

## v2.30.0

* Update to Node 20. - [#369](https://github.com/ReactiveCircus/android-emulator-runner/pull/369)

## v2.29.0

* Fixed emulator download URL. - [#343](https://github.com/ReactiveCircus/android-emulator-runner/pull/343)
Expand Down
53 changes: 42 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,24 @@
<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 hardware-accelerated Android Emulators on Linux and macOS virtual machines.

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.

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).

## Running hardware accelerated emulators on Linux runners

GitHub's [larger Linux runners support running hardware accelerated emulators](https://github.blog/changelog/2023-02-23-hardware-accelerated-android-virtualization-on-actions-windows-and-linux-larger-hosted-runners/) which is [free for public GitHub repos](https://github.blog/2024-01-17-github-hosted-runners-double-the-power-for-open-source/). It is now recommended to use the **Ubuntu** (`ubuntu-latest`) runners which are 2-3 times faster than the **macOS** ones which are also a lot more expensive. Remember to enable KVM in your workflow before running this action:

```
- name: Enable KVM group perms
run: |
echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
sudo udevadm control --reload-rules
sudo udevadm trigger --name-match=kvm
```

## A note on VM Acceleration and why we don't need HAXM anymore

According to [this documentation](https://developer.android.com/studio/run/emulator-acceleration#vm-mac), "on Mac OS X v10.10 Yosemite and higher, the Android Emulator uses the built-in [Hypervisor.Framework](https://developer.apple.com/documentation/hypervisor) by default, and falls back to using Intel HAXM if Hypervisor.Framework fails to initialize." This means that **HAXM is only needed to achieve VM Acceleration if this default Hypervisor is not available on macOS machines.**
Expand All @@ -34,11 +46,17 @@ A workflow that uses **android-emulator-runner** to run your instrumented tests
```yml
jobs:
test:
runs-on: macos-latest
runs-on: ubuntu-latest
steps:
- name: checkout
uses: actions/checkout@v3

- name: Enable KVM
run: |
echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
sudo udevadm control --reload-rules
sudo udevadm trigger --name-match=kvm
- name: run tests
uses: reactivecircus/android-emulator-runner@v2
with:
Expand All @@ -51,7 +69,7 @@ We can also leverage GitHub Actions's build matrix to test across multiple confi
```yml
jobs:
test:
runs-on: macos-latest
runs-on: ubuntu-latest
strategy:
matrix:
api-level: [21, 23, 29]
Expand All @@ -60,6 +78,12 @@ jobs:
- name: checkout
uses: actions/checkout@v3

- name: Enable KVM
run: |
echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
sudo udevadm control --reload-rules
sudo udevadm trigger --name-match=kvm
- name: run tests
uses: reactivecircus/android-emulator-runner@v2
with:
Expand All @@ -75,11 +99,17 @@ If you need specific versions of **NDK** and **CMake** installed:
```yml
jobs:
test:
runs-on: macos-latest
runs-on: ubuntu-latest
steps:
- name: checkout
uses: actions/checkout@v3

- name: Enable KVM
run: |
echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
sudo udevadm control --reload-rules
sudo udevadm trigger --name-match=kvm
- name: run tests
uses: reactivecircus/android-emulator-runner@v2
with:
Expand All @@ -99,14 +129,20 @@ We can significantly reduce emulator startup time by setting up AVD snapshot cac
```yml
jobs:
test:
runs-on: macos-latest
runs-on: ubuntu-latest
strategy:
matrix:
api-level: [21, 23, 29]
steps:
- name: checkout
uses: actions/checkout@v3
- name: Enable KVM
run: |
echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
sudo udevadm control --reload-rules
sudo udevadm trigger --name-match=kvm
- name: Gradle cache
uses: gradle/gradle-build-action@v2
Expand Down Expand Up @@ -170,12 +206,6 @@ jobs:

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

## 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, 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 @@ -211,5 +241,6 @@ These are some of the open-source projects using (or used) **Android Emulator Ru
- [hzi-braunschweig/SORMAS-Project](https://github.com/hzi-braunschweig/SORMAS-Project/blob/development/.github/workflows/sormas_app_ci.yml)
- [ACRA/acra](https://github.com/ACRA/acra/blob/master/.github/workflows/test.yml)
- [bitfireAT/davx5-ose](https://github.com/bitfireAT/davx5-ose/blob/dev-ose/.github/workflows/test-dev.yml)
- [robolectric/robolectric](https://github.com/robolectric/robolectric/blob/master/.github/workflows/tests.yml)

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
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
name: 'Android Emulator Runner'
description: 'Installs, configures and starts an Android Emulator directly on macOS virtual machines.'
description: 'Installs, configures and starts an Android Emulator directly on hardware-accelerated runners.'
author: 'Reactive Circus'
branding:
icon: 'smartphone'
Expand Down
2 changes: 1 addition & 1 deletion lib/emulator-manager.js
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ function launchEmulator(apiLevel, target, arch, profile, cores, ramSize, heapSiz
if (diskSize) {
yield exec.exec(`sh -c \\"printf 'disk.dataPartition.size=${diskSize}\n' >> ${process.env.ANDROID_AVD_HOME}/"${avdName}".avd"/config.ini`);
}
//turn off hardware acceleration on Linux
// turn off hardware acceleration on Linux
if (process.platform === 'linux' && disableLinuxHardwareAcceleration) {
console.log('Disabling Linux hardware acceleration.');
emulatorOptions += ' -accel off';
Expand Down
26 changes: 13 additions & 13 deletions node_modules/.package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion node_modules/@actions/http-client/lib/auth.js.map

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions node_modules/@actions/http-client/lib/index.d.ts

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

13 changes: 13 additions & 0 deletions node_modules/@actions/http-client/lib/index.js

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion node_modules/@actions/http-client/lib/index.js.map

Large diffs are not rendered by default.

25 changes: 23 additions & 2 deletions node_modules/@actions/http-client/lib/proxy.js

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading

0 comments on commit eaf4c24

Please sign in to comment.