You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A GitHub Action for installing, configuring and running hardware-accelerated Android Emulators on macOS virtual machines.
7
+
A GitHub Action for installing, configuring and running hardware-accelerated Android Emulators on Linux and macOS virtual machines.
8
8
9
9
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.
10
10
11
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).
12
12
13
+
## Running hardware accelerated emulators on Linux runners
14
+
15
+
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:
16
+
17
+
```
18
+
- name: Enable KVM group perms
19
+
run: |
20
+
echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
21
+
sudo udevadm control --reload-rules
22
+
sudo udevadm trigger --name-match=kvm
23
+
```
24
+
13
25
## A note on VM Acceleration and why we don't need HAXM anymore
14
26
15
27
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.**
@@ -34,11 +46,17 @@ A workflow that uses **android-emulator-runner** to run your instrumented tests
34
46
```yml
35
47
jobs:
36
48
test:
37
-
runs-on: macos-latest
49
+
runs-on: ubuntu-latest
38
50
steps:
39
51
- name: checkout
40
52
uses: actions/checkout@v3
41
53
54
+
- name: Enable KVM
55
+
run: |
56
+
echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
57
+
sudo udevadm control --reload-rules
58
+
sudo udevadm trigger --name-match=kvm
59
+
42
60
- name: run tests
43
61
uses: reactivecircus/android-emulator-runner@v2
44
62
with:
@@ -51,7 +69,7 @@ We can also leverage GitHub Actions's build matrix to test across multiple confi
51
69
```yml
52
70
jobs:
53
71
test:
54
-
runs-on: macos-latest
72
+
runs-on: ubuntu-latest
55
73
strategy:
56
74
matrix:
57
75
api-level: [21, 23, 29]
@@ -60,6 +78,12 @@ jobs:
60
78
- name: checkout
61
79
uses: actions/checkout@v3
62
80
81
+
- name: Enable KVM
82
+
run: |
83
+
echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
84
+
sudo udevadm control --reload-rules
85
+
sudo udevadm trigger --name-match=kvm
86
+
63
87
- name: run tests
64
88
uses: reactivecircus/android-emulator-runner@v2
65
89
with:
@@ -75,11 +99,17 @@ If you need specific versions of **NDK** and **CMake** installed:
75
99
```yml
76
100
jobs:
77
101
test:
78
-
runs-on: macos-latest
102
+
runs-on: ubuntu-latest
79
103
steps:
80
104
- name: checkout
81
105
uses: actions/checkout@v3
82
106
107
+
- name: Enable KVM
108
+
run: |
109
+
echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
110
+
sudo udevadm control --reload-rules
111
+
sudo udevadm trigger --name-match=kvm
112
+
83
113
- name: run tests
84
114
uses: reactivecircus/android-emulator-runner@v2
85
115
with:
@@ -99,14 +129,20 @@ We can significantly reduce emulator startup time by setting up AVD snapshot cac
99
129
```yml
100
130
jobs:
101
131
test:
102
-
runs-on: macos-latest
132
+
runs-on: ubuntu-latest
103
133
strategy:
104
134
matrix:
105
135
api-level: [21, 23, 29]
106
136
steps:
107
137
- name: checkout
108
138
uses: actions/checkout@v3
109
139
140
+
- name: Enable KVM
141
+
run: |
142
+
echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
## Can I use this action on Github Hosted Linux VMs?
174
-
175
-
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.
176
-
177
-
For a longer answer please refer to [this issue](https://github.com/ReactiveCircus/android-emulator-runner/issues/46).
178
-
179
209
## Who is using Android Emulator Runner?
180
210
181
211
These are some of the open-source projects using (or used) **Android Emulator Runner**:
@@ -211,5 +241,6 @@ These are some of the open-source projects using (or used) **Android Emulator Ru
0 commit comments