Menu

Language Guide: Android

Tutorials & 2.0 Demo Apps > Language Guide: Android

This guide will help you get started with an Android application on CircleCI.

Overview

There are some assumptions made in this guide:

  • We assume that your Android project is built with gradle (this is the default for projects created with Android Studio.
  • We assume that your project is located in the root of your git repository, with the application located in a subfolder named app.

Running the Android emulator is not currently supported by the type of virtualization CircleCI 2.0 uses on Linux. To run emulator tests from a job, consider using an external service like Firebase Test Lab. To do this, you can use the gcloud command line. Google Cloud tools are preinstalled in our Android Docker images, which you can find on GitHub or Docker Hub.

Sample Configuration

version: 2
jobs:
  build:
    working_directory: ~/code
    docker:
      - image: circleci/android:api-25-alpha
    environment:
      JVM_OPTS: -Xmx3200m
    steps:
      - checkout
      - restore_cache:
          key: jars-{{ checksum "build.gradle" }}-{{ checksum  "app/build.gradle" }}
#      - run:
#         name: Chmod permissions #if permission for Gradlew Dependencies fail, use this. 
#         command: sudo chmod +x ./gradlew
      - run:
          name: Download Dependencies
          command: ./gradlew androidDependencies
      - save_cache:
          paths:
            - ~/.gradle
          key: jars-{{ checksum "build.gradle" }}-{{ checksum  "app/build.gradle" }}
      - run:
          name: Run Tests
          command: ./gradlew lint test
      - store_artifacts:
          path: app/build/reports
          destination: reports
      - store_test_results:
          path: app/build/test-results

Config Walkthrough

We always start with the version.

version: 2

Next, we have a jobs key. Each job represents a phase in your Build-Test-Deploy process. Our sample app only needs a build job, so everything else is going to live under that key.

In each job, we have the option of specifying a working_directory. This is the directory into which our code will be checked out, and this path will be used as the default working directory for the rest of the job unless otherwise specified.

jobs:
  build:
    working_directory: ~/code

Directly beneath working_directory, we can specify container images under a docker key.

    docker:
      - image: circleci/android:api-25-alpha

We use the CircleCI-provided Android image with the api-25-alpha tag. See Docker Images below for more information about what images are available.

Now we’ll add several steps within the build job.

We start with checkout so we can operate on the codebase.

Next we pull down the cache, if present. If this is your first run, or if you’ve changed either of your build.gradle files, this won’t do anything. We run ./gradlew androidDependencies next to pull down the project’s dependencies. Normally you never call this task directly since it’s done automatically when it’s needed, but calling it directly allows us to insert a save_cache step that will store the dependencies in order to speed things up for next time.

Then ./gradlew lint test runs the unit tests, and runs the built in linting tools to check your code for style issues.

We then upload the build reports as build artifacts, and we upload the test metadata (XML) for CircleCI to process.

Nice! You just set up CircleCI for an Android app.

Docker Images

For convenience, CircleCI provides a set of Docker images for building Android apps. These pre-built images are available in the CircleCI org on Docker Hub. The source code and Dockerfiles for these images are available in this GitHub repository.

The CircleCI Android image is based on the openjdk:8-jdk official Docker image, which is based on buildpack-deps. The base OS is Debian Jessie, and builds run as the circleci user, which has full access to passwordless sudo.

Note: The CircleCI Android image does not include the Android NDK. If you require that toolset, consider using another existing image or making your own image.

API Levels

We have a different Docker image for each Android API level. To use API level 24 (Nougat 7.0) in your build, you should select circleci/android:api-24-alpha.

Alpha Tag

Our Android Docker images are currently tagged with the suffix -alpha. This is to indicate the images are currently under development and might change in backwards incompatible ways from week to week.

Customizing the Images

We welcome contributions on our GitHub repo for the Android image. Our goal is provide a base image that has most of the tools you need; we do not plan to provide every tool that you might need.

To customize the image, create a Dockerfile that builds FROM the circleci/android image. See Using Custom-Built Docker Images for instructions.

React Native projects

React Native projects can be built on CircleCI 2.0 using Linux, Android and macOS capabilities. Please check out this example React Native application on GitHub for a full example of a React Native project.