└── README.md /README.md: -------------------------------------------------------------------------------- 1 | # CircleCI Android machine image preview docs 2 | 3 | We are excited to announce the preview of an Android machine image on CircleCI. The purpose of this repository is to walk you through the setup steps required to use the Android machine image. 4 | 5 | ## What is the Android machine image on CircleCI? 6 | 7 | CircleCI offers multiple kinds of environments for you to run jobs in. The 8 | Android machine image can be used via the [Linux `machine` executor](https://circleci.com/docs/2.0/configuration-reference/#machine-executor-linux), like other 9 | Linux machine images on CircleCI. The Android machine image supports nested virtualization and x86 Android emulators, so it can be used for Android UI testing. It also comes with the Android SDK pre-installed. 10 | 11 | ## Pre-installed Software 12 | 13 | ### Android SDK 14 | - sdkmanager 15 | - Android platform 23, 24, 25, 26, 27, 28, 29, 30, S 16 | - Build tools 30.0.3 17 | - emulator, platform-tools, tools 18 | - NDK (Side-by-side) 21.4.7075529 19 | - cmake 3.6.4111459 20 | - extras;android;m2repository, extras;google;m2repository, extras;google;google_play_service 21 | 22 | ### Others 23 | - gcloud 24 | - OpenJDK 8, OpenJDK 11 (default) 25 | - maven 3.6.3, gradle 6.8.3, ant 26 | - nodejs 12.21.0, 14.16.0 (default), 15.11.0 27 | - python 2.7.18, python 3.9.2 28 | - ruby 2.7.2, ruby 3.0.0 29 | - docker 20.10.5, docker-compose 1.28.5 30 | - jq 1.6 31 | 32 | ## Using the Android machine image 33 | 34 | To use the Android machine image, edit your `.circleci/config.yml` file. 35 | Here are example configs, some of which leverage the circleci/android [orb](https://circleci.com/developer/orbs/orb/circleci/android) for a simplified config. More examples 36 | are available [here](https://circleci.com/developer/orbs/orb/circleci/android#usage-examples). 37 | 38 | ### Simple job example 39 | 40 | ```yaml 41 | # .circleci/config.yaml 42 | version: 2.1 43 | orbs: 44 | android: circleci/android@1.0 45 | workflows: 46 | test: 47 | jobs: 48 | # This job uses the Android machine image by default 49 | - android/run-ui-tests: 50 | # Use pre-steps and post-steps if necessary 51 | # to execute custom steps before and afer any of the built-in steps 52 | system-image: system-images;android-29;default;x86 53 | ``` 54 | 55 | ### Example of using the Android machine image in your own job 56 | 57 | This example shows how you could modify your existing job to run UI tests. 58 | 59 | ```yaml 60 | # .circleci/config.yml 61 | version: 2.1 62 | orbs: 63 | android: circleci/android@1.0 64 | jobs: 65 | test: 66 | # Use the Android machine image 67 | executor: 68 | name: android/android-machine 69 | resource-class: large 70 | steps: 71 | - checkout 72 | # Creates an AVD and starts up the emulator using the AVD. 73 | # While the emulator is starting up, the gradle cache will 74 | # be restored and the Android app will be assembled. 75 | # When the emulator is ready, UI tests will be run. 76 | # After the tests are run, the gradle cache will be saved (if it 77 | # hasn't been saved before) 78 | - android/start-emulator-and-run-tests: 79 | system-image: system-images;android-29;default;x86 80 | # The cache prefix can be overridden 81 | # restore-gradle-cache-prefix: v1a 82 | # 83 | # The command to be run, while waiting for emulator startup, can be overridden 84 | # post-emulator-launch-assemble-command: ./gradlew assembleDebugAndroidTest 85 | # 86 | # The test command can be overridden 87 | # test-command: ./gradlew connectedDebugAndroidTest 88 | workflows: 89 | test: 90 | jobs: 91 | - test 92 | ``` 93 | 94 | ### Example of using more granular orb commands 95 | 96 | This example shows how you can use more granular orb commands to 97 | achieve what the [start-emulator-and-run-tests](https://circleci.com/developer/orbs/orb/circleci/android#commands-start-emulator-and-run-tests) command does. 98 | 99 | ```yaml 100 | # .circleci/config.yml 101 | version: 2.1 102 | orbs: 103 | android: circleci/android@1.0 104 | jobs: 105 | test: 106 | executor: 107 | name: android/android-machine 108 | resource-class: large 109 | steps: 110 | - checkout 111 | # Create an AVD named "myavd" 112 | - android/create-avd: 113 | avd-name: myavd 114 | system-image: system-images;android-29;default;x86 115 | install: true 116 | # By default, after starting up the emulator, a cache will be restored, 117 | # "./gradlew assembleDebugAndroidTest" will be run and then a script 118 | # will be run to wait for the emulator to start up. 119 | # Specify the "post-emulator-launch-assemble-command" command to override 120 | # the gradle command run, or set "wait-for-emulator" to false to disable 121 | # waiting for the emulator altogether. 122 | - android/start-emulator: 123 | avd-name: myavd 124 | no-window: true 125 | restore-gradle-cache-prefix: v1a 126 | # Runs "./gradlew connectedDebugAndroidTest" by default. 127 | # Specify the "test-command" parameter to customize the command run. 128 | - android/run-tests 129 | - android/save-gradle-cache: 130 | cache-prefix: v1a 131 | workflows: 132 | test: 133 | jobs: 134 | - test 135 | ``` 136 | 137 | ### No-orb example 138 | 139 | Here is an example of using the image, without using the circleci/android [orb](https://circleci.com/developer/orbs/orb/circleci/android). These steps are similar 140 | to what is run when you use the [run-ui-tests](https://circleci.com/developer/orbs/orb/circleci/android#jobs-run-ui-tests) job of the orb. 141 | 142 | ```yaml 143 | # .circleci/config.yml 144 | version: 2.1 145 | jobs: 146 | build: 147 | machine: 148 | image: android:202102-01 149 | # To optimize build times, we recommend "large" and above for Android-related jobs 150 | resource_class: large 151 | steps: 152 | - checkout 153 | - run: 154 | name: Create avd 155 | command: | 156 | SYSTEM_IMAGES="system-images;android-29;default;x86" 157 | sdkmanager "$SYSTEM_IMAGES" 158 | echo "no" | avdmanager --verbose create avd -n test -k "$SYSTEM_IMAGES" 159 | - run: 160 | name: Launch emulator 161 | command: | 162 | emulator -avd test -delay-adb -verbose -no-window -gpu swiftshader_indirect -no-snapshot -noaudio -no-boot-anim 163 | background: true 164 | - run: 165 | name: Generate cache key 166 | command: | 167 | find . -name 'build.gradle' | sort | xargs cat | 168 | shasum | awk '{print $1}' > /tmp/gradle_cache_seed 169 | - restore_cache: 170 | key: gradle-v1-{{ arch }}-{{ checksum "/tmp/gradle_cache_seed" }} 171 | - run: 172 | # run in parallel with the emulator starting up, to optimize build time 173 | name: Run assembleDebugAndroidTest task 174 | command: | 175 | ./gradlew assembleDebugAndroidTest 176 | - run: 177 | name: Wait for emulator to start 178 | command: | 179 | circle-android wait-for-boot 180 | - run: 181 | name: Disable emulator animations 182 | command: | 183 | adb shell settings put global window_animation_scale 0.0 184 | adb shell settings put global transition_animation_scale 0.0 185 | adb shell settings put global animator_duration_scale 0.0 186 | - run: 187 | name: Run UI tests (with retry) 188 | command: | 189 | MAX_TRIES=2 190 | run_with_retry() { 191 | n=1 192 | until [ $n -gt $MAX_TRIES ] 193 | do 194 | echo "Starting test attempt $n" 195 | ./gradlew connectedDebugAndroidTest && break 196 | n=$[$n+1] 197 | sleep 5 198 | done 199 | if [ $n -gt $MAX_TRIES ]; then 200 | echo "Max tries reached ($MAX_TRIES)" 201 | exit 1 202 | fi 203 | } 204 | run_with_retry 205 | - save_cache: 206 | key: gradle-v1-{{ arch }}-{{ checksum "/tmp/gradle_cache_seed" }} 207 | paths: 208 | - ~/.gradle/caches 209 | - ~/.gradle/wrapper 210 | workflows: 211 | build: 212 | jobs: 213 | - build 214 | ``` 215 | 216 | ## Limitations 217 | 218 | * There may be up to 2 mins of spin-up time before your job actually starts running. This time will decrease as more preview customers start using the 219 | Android image. 220 | * Only one image is currently available, `android:202102-01`. It contains most of the tools you’ll likely need for Android development. If there is software you require that’s not available in the image, please [open an issue](https://github.com/CircleCI-Public/android-image-preview-docs/issues) to let us know. 221 | * We may change and update the pre-installed software on the `android:202102-01` image without prior notice during the preview period. Once the preview period is over, the images for Android images will be stable and will follow our standard image release cadence. 222 | 223 | ## Pricing 224 | 225 | For pricing information, refer to the Linux machine executors under the “Linux VM" section on the [pricing page](https://circleci.com/pricing/). 226 | 227 | ## How to provide feedback 228 | 229 | Please [open an issue](https://github.com/CircleCI-Public/android-image-preview-docs/issues) with any feedback. The specific areas where we would appreciate feedback: 230 | 231 | * Software pre-installed in the image. Do you find everything you need in the image? 232 | * Are there any bugs that you’ve noticed in the pre-installed software? 233 | --------------------------------------------------------------------------------