Building an AAR Library in Android Studio

Purpose of AAR

Library reuse has long been available in Java based applications through Java Archive (.jar) files.  Android AAR files build upon this concept to allow you to package not only the source code but also the libraries self contained Android resources. The library can have its own manifest and resources and can also optionally provide assets, NDK built libraries, proguard configuration and even its own custom lint filters.  This is all bundled into a zip archive that can be published to a repository for your team (or the world!) to get easy access from a Gradle build.

AAR File Format

The AAR File format is simply a zip archive file with extension .aar. The archive contains:
  • /AndroidManifest.xml (mandatory)
  • /classes.jar (mandatory)
  • /res/ (mandatory)
  • /R.txt (mandatory)
  • /assets/ (optional)
  • /libs/*.jar (optional)
  • /jni/<abi>/*.so (optional)
  • /proguard.txt (optional)
  • /lint.jar (optional)

Creating an AAR library project

The good news is creating an AAR library is easy and Android Studio will do all the hard work for you.

Android Studio create library module

Figure 1: Create an Android Library

  1. Start by selecting New Module… from the File menu
  2. Select Android Library as the module to be created (see Figure 1)
  3. Step through the process of using a template for the creation of your library much like creating a new project

One key difference in the created library and an Android application will be the libraries Gradle build script includes apply plugin: ‘com.android.library’ instead of apply plugin: ‘com.android.application’.

When you build your project the AAR file will automatically be assembled and placed in these folders (Android Studio 1.0+)

| build
| outputs
      | aar
           | applib-debug.aar
           | applib-release.aar

Using AAR

You have a few choices as to how to include your AAR library in your project:

  • Publish to a external Maven repository
  • Publish to a local repository
  • Access from a local folder

While Gradle can be used to directly publish to repositories such as Maven Central, this article doesn’t cover publishing your AAR file to Maven repositories.

To include your AAR library as a dependency from a local folder:

1. Copy the AAR file into the libs folder in your project. Create this folder if it doesn’t exist. It needs to be located in the same folder as your application Gradle build file, not the top level project folder.

2. Declare the libs folder as a dependency repository in your application Gradle script.

repositories {
    flatDir {
        dirs 'libs'
    }
}

The Gradle flatDir repository declaration allows you to declare a file system directory that is a repository for dependencies for the project. In the example above I am using the libs folder which needs to be located relative to the location of the build script. The name of this folder does not have to be libs and it is also possible to declare multiple fileDir folders in the one project.

3. Declare your AAR library as a dependency:

dependencies {
    compile(name:'yourlibraryname', ext:'aar')
}

Manifest Merging

Earlier in this article we noted that the AndroidManifest.xml is a compulsory item in an AAR library. When an app includes your AAR library the manifest must be merged with that of the app, as there will be only one manifest included in an APK.

Merging manifests can quickly get messy when multiple conflicting manifests are all merged. The android tools user guide to manifest mergers is the best resource available to explain all the ins and outs of how the merge will happen and how you can control the merge.

The most basic rule of the merge is the order of priorities given to different manifests. From most influential to least:

  1. Product flavors and build types specific manifest files.
  2. Main manifest file for the application.
  3. Library manifest files.

So you can see your Library manifest sits at the bottom of the pecking order.

Most of the time this merging will happen like magic, without the need for intervention. If issues arise in the manifest merge there are a couple of places to start looking in order to track down the issue. The first place to check is the final outputted manifest file. The next place to check is the manifest merge report (which is saved into the app\build\outputs\logs\ folder of your project). The format and contents of the logging in the merge report is explained here.

References

AAR File Format

http://tools.android.com/tech-docs/new-build-system/aar-format

Manifest merging user guide

http://tools.android.com/tech-docs/new-build-system/user-guide/manifest-merger

8 Comments

Filed under Android SDK, Android Studio, Gradle

8 responses to “Building an AAR Library in Android Studio

  1. It looks like I don’t need to merge manifest files. I am using android studio 1.2.2.

    Like

  2. Which aar should I put into folder libs? debug or release. Or both?

    Thanks

    Like

    • If your AAR is a stable component you can just add the release build. It is also possible to use different libs folders for release and debug to match your current build type. For example:

      buildTypes {
      release {
      minifyEnabled false
      proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
      repositories {
      flatDir {
      dirs "/aarlibs/release"
      }
      }
      }
      debug {
      repositories {
      flatDir {
      dirs "/aarlibs/debug"
      }
      }
      }
      }

      Liked by 1 person

  3. When I use proguard /libs/abc.jar gets merged in classes.jar.
    Please tell me how to keep libs folder when using proguard

    Like

  4. My aar file includes external dependencies. If I put my aar to a apk projekt in a local dir the dependencies are not included in the apk and I will get a runtime exception. I tried flag transitive = true but it did not help. Is it possible to have external dependencies in aar when aar is in local folder?

    Like

  5. Michalis Bobotsaris

    Can the AAR library be defined as an external module? So if there are any changes it will be rebuild?

    Like

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s