Create a new project with Android Studio

Create a new project with Android Studio

This lesson describes how to set up the Couchbase Lite environment with Android Studio. Android Studio is the recommended development environment for Couchbase Lite Android apps.

Set up the environment

Before you can build an app, you need to set up your development environment:

  1. Download and install Android Studio.

  2. Launch Android Studio.

  3. From the Quick Start menu on the welcome screen, select Configure > SDK Manager.

    If you already have a project open, you can open the SDK Manager by selecting Tools > Android > SDK Manager from the Android Studio menu bar.

  4. In Android SDK Manager, select the following items and then click Install packages:

    • Tools/Android SDK Tools
    • Tools/Android SDK Platform-tools
    • Tools/Android SDK Build-tools
    • Android API (currently recommended: API 19)
    • Extras/Google Repository
    • Extras/Android Support Repository

Create a new project

  1. Launch Android Studio.

  2. In the Welcome to Android Studio screen, choose New Project.

  3. In the New Project window, enter the application name, module name, package name, and project location.

    This example uses CouchbaseEvents for the application name.

  4. Set the minimum required SDK to API 9: Android 2.3 (Gingerbread) or later and use the currently recommended Android API.

    After you fill in the fields, the New Project window should look something like this:

    New project window
  5. Click Next, and then move through the remaining setup screens and enter settings as necessary (or just accept the defaults).

  6. Click Finish.

Add Couchbase Lite Dependencies

  1. Expand the app folder, and then open the build.gradle file.

    You should see a file that looks something like this:

    build.gradle file

    If the build.gradle does not contain an android section, then you are looking at the wrong one. Make sure you open the one in the CouchbaseEvents folder (and not the one at the project level).

  2. Add the following lines to the android section:

    // workaround for "duplicate files during packaging of APK" issue
    // see
    packagingOptions {
        exclude 'META-INF/ASL2.0'
        exclude 'META-INF/LICENSE'
        exclude 'META-INF/NOTICE'
  3. Add the following line to the top-level dependencies section (not the one under the buildscript section).

    Note: Should replace {latest-version} with actual version number (ex: 1.0.4).

    compile 'com.couchbase.lite:couchbase-lite-android:{latest-version}'

    After you add the extra line, the dependencies section should look similar to this:

    dependencies {
        compile fileTree(dir: 'libs', include: ['*.jar'])
        compile ''
        compile 'com.couchbase.lite:couchbase-lite-android:{latest-version}'
  4. In the Android Studio tool bar, click Sync Project with Gradle Files.

    Gradle sync button

Build and run the app

Running the empty app at this point verifies whether the dependencies are set up correctly.

  1. In the Android Studio tool bar, click Run.

  2. When prompted, start the emulator.

    You should see the app start in the emulator and the text “Hello World” in the app window, similar to the following figure:

    simulator display


If the app doesn’t run properly for you, try the following troubleshooting tips.

Errors in the build.gradle file are a common cause of problems:

  • Double-check the spelling of all entries in the file.
  • Make sure all code added to the file is located in the correct sections.
  • Verify the path for Couchbase Lite in the compile statement in the dependencies section.
  • Compare your files to these sample build.gradle files. They should match other than the versions.

Couchbase Lite for Android might not build correctly with ProGuard. If you get build errors that mention ProGuard, you can disable it by changing the build.gradle file `minifyEnabled` property (formerly `runProGuard`) in the android section to false. When you change it, the android section should look something like the following code:

android {
     buildTypes {
        release {
            minifyEnabled false
            proguardFile ...