• Android

Distributing your Library using JCenter

Series overview

This is the third in a series of blog posts about the process and experience of creating and publishing our “RateTheApp” widget in an Android Library.

The series as a whole will look something like this:

• Part One: Creating an Android Library
• Part Two: Making it open source
• Part Three: Distributing your library (this one)
• Part Four: How to finish your project (originally planned as Advertising your library)

In this post, we'll look at how to distribute your Library using JCenter.

Sit back and wait?

Once you’ve open sourced your library, you might be tempted to sit back and wait for the world to realise how brilliant you’ve been and for your library to go viral.

However, back in the real world, you realise that no-one has noticed that your wonderful library has landed. Or maybe they’ve seen it but don’t seem motivated to try it out (developers are a lazy bunch by nature and any barriers to adoption you can remove the better).

You need a way of getting your library into the hands of developers that doesn’t require any effort on their part.

In this blog post, I’ll be describing how to “distribute your library” so that it is laughably simple for developers to start using it. In fact, it is so simple they can just try it out, on a whim almost, before deciding whether to stick with it.

Now they’ve got NO excuse for not using your wonderful library.

Gradle

Most Android developers will be developing their apps using Android Studio which uses Gradle, an advanced build toolkit, to automate and manage the build process.

Including your Android library can be as simple as including the following one-liner in your project!

dependencies {
 compile 'uk.co.brightec.ratetheapp:rate-the-app:0.9.1'
}

NB. If you want to know how it all works, I got my information from this excellent blog post which explains things in a lot more detail.

Gradle Repository

There are two main repositories that are generally used; JCenter (hosted by Bintray) and the older Maven Central.

In this post, I’ll be describing the process for distributing your library through JCenter which is the default repository for new projects created in Android Studio.

The basic process will be to:

• Create an account on Bintray and create a new package ready to receive your library
• Prepare your Android Studio project and then build arr and pom files
• Upload project files to Bintray
• Sync to JCenter

Steps to distribute your library

1. Create an account and register a new package on Bintray

• Register for an account on bintray.com and click the activation email they send you.
• Add a new Maven repository and click Create New Package
• You should now have a maven repository. For instance: https://bintray.com/brightec/maven

2. Prepare your Android Studio project

• Apply the Bintray plugin to your project - add the following dependencies to your project build.gradle file

dependencies {
 classpath 'com.jfrog.bintray.gradle:gradle-bintray-plugin:1.4'
 classpath 'com.github.dcendents:android-maven-gradle-plugin:1.3'
}

• Define your Bintray username and apikey in a local.properties file (note your API Key should be kept secret so don’t commit your local.properties file to GitHub)

bintray.user=brightec
bintray.apikey=<your bintray apikey>

• Modify library module build.gradle file to include Bintray repo name etc.

ext {
 bintrayRepo = 'maven'
 bintrayName = 'rate-the-app'

 publishedGroupId = 'uk.co.brightec.ratetheapp'
 libraryName = 'RateTheApp'
 artifact = 'rate-the-app'

 libraryDescription = 'RateTheApp is an Android component that allows users to rate your app prompting them for further action depending on the rating they gave.'

 siteUrl = 'https://github.com/brightec/RateTheApp-Android'
 gitUrl = 'https://github.com/brightec/RateTheApp-Android.git'

 libraryVersion = '0.9.1'

 developerId = 'nickh'
 developerName = 'Nick Holcombe'
 developerEmail = 'nick@brightec.co.uk'

 licenseName = 'The Apache Software License, Version 2.0'
 licenseUrl = 'http://www.apache.org/licenses/LICENSE-2.0.txt'
 allLicenses = ["Apache-2.0"]
}

• Fork JCenter repo to get access to the install scripts e.g. https://github.com/brightec/JCenter
• Add the following to the end of the library module build.gradle file to access the install scripts you just forked

// Place it at the end of the file
apply from: 'https://raw.githubusercontent.com/brightec/JCenter/master/installv1.gradle'
apply from: 'https://raw.githubusercontent.com/brightec/JCenter/master/bintrayv1.gradle'

3. Build arr and pom files and upload them to Bintray space

• From the terminal
  • sudo ./gradlew install
  • sudo ./gradlew bintrayUpload
• If all went well, you should be able to use the code from your private Maven repository on Bintray. Test it out in a new Android Project and update your build.gradle file.

repositories {
 maven {
 url 'https://dl.bintray.com/brightec/maven'
 }
}

dependencies {
 compile 'uk.co.brightec.ratetheapp:ratetheapp:0.9.1'
}

• But you don’t want developers to have to use your private repo - they’ll already be using JCenter - so we need to set that up next

4. Sync Bintray user repository to JCenter

• As the blog instructions say “It is pretty easy to sync your library to JCenter. Just go to the web interface and simply click at Add to JCenter”. Once you have done that, you’ll have to wait 2-3 hours to let the Bintray team approve your request - you’ll get an email letting you know when that's done.
• Once approved, you should see the Linked to (1) section on Bintray has a link to JCenter. You can check whether your package is on JCenter by going to http://jcenter.bintray.com and navigating to the directory you setup. For example; http://jcenter.bintray.com/uk/co/brightec/ratetheapp/ratetheapp/

Two warnings from the blog post I was following:

“Please note that linking to JCenter is a one-time action. From now on, if you do any modification in your package, for example, upload new version binary, delete old version binary, etc. The change would affect to JCenter as well. Anyway since your own repository and JCenter are at the different place so you may need to wait for around 2-3 minutes to let JCenter sync the change.”

“And please be careful. If you decide to remove the whole package, library files placed on JCenter repository would not be deleted in this case. And they will be left just like zombie files which nobody could delete it anymore. So I suggest you that if you want to delete the whole package, please delete every single version from web interface first before removing the package.”

Finally, let developers know

From now on, any developer that uses the JCenter() repository will be able to use our library with a single line of Gradle script.

dependencies {
 compile 'uk.co.brightec.ratetheapp:rate-the-app:0.9.1'
}

So, don’t forget to update your README file on GitHub showing how (easily) your library can be installed and used.

As we said earlier, now the developers of the world have NO excuse for not using your wonderful library…

...assuming, of course, your library was worth using in the first place!