How to distribute your own Android library through Jitpack or jCenter and Maven Central from Android Studio
Note: This tutorial uses the latest maven-publish and maven Gradle plugins.
Many of us must have seen a lot of libraries especially in Github or Bitbucket that look like this:
If you have something like this in the build.gradle of the module then you are ready to go. Library is now usable. BUT wouldn’t it be nice if you could do something like this?
How they other people did it?
I guess there are a lot of ways on how to do this and the easiest way would be to use something like Jitpack and it is pretty easy to follow like this:
and then you are ready to go. But the thing is that you must include jitpack’s maven url so you can access your library.
2. jCenter and Maven Central
jcenter is a Maven Repository hosted by bintray.com. You could find the whole repository here. jCenter is used by default in Android Studio, also it includes everything that Maven Central has and even more.
Maven Central is a Maven Repository hosted by sonatype.org. You could find the whole repository here.
In order to use jCenter(if not already included) and mavenCentral in Android
you have to do something like this:
Understand jcenter and Maven Central
Wonder why is there not only just one but two standard repositories out there?
Actually both of them are the repositories having the same duty: hosting Java/Android libraries. It is a developers’ choice to upload their libraries to which one or may be both.
But the big problem of Maven Central is it is surprisingly hard to upload the library to. To be able to do so, developer has to be at some level of geeky. And with some more reason for example a security concern and etc, Android Studio team decided to switch the default repository to jcenter instead as you can see that once you create a new project from latest version of Android Studio, jcenter() would be automatically defined instead of mavenCentral().
There are load of good reasons why they decided to switch from Maven Central to jcenter. Here are some of the major one.
- jcenter delivers library through CDN which means that developer could enjoy the faster loading experience.
- jcenter is the largest Java Repository on earth. So whatever that is available on Maven Central could be implied that it would be available on jcenter as well. In the other words, jcenter is superset of Maven Central.
- It is incredibly easy to upload our own library to the repository. No need to sign or do any complex thing like we have to on Maven Central.
- Friendly-UI
- If you want to upload your library to Maven Central you could do it easily with a single click on bintray site (and with some step of one-time setup).
With above reasons and from my own experiences, I must say that it is the brilliant decision switching default repository to jcenter.
So this article will focus on just jcenter since once you successfully upload your library to jcenter, it could be forwarded to Maven Central easily after that.
How does gradle pull a library from Repository?
Before we start talking about how to upload a library to jcenter. We should start with how gradle fetch a library from repository. For example, when we type like below in build.gradle, how are those library files magically downloaded to your project.
It is a combination of GROUP_ID:ARTIFACT_ID:VERSION
So gradle is able to identify a library by the above combination. In my case it will be:
GROUP_ID = com.github.kostasdrakonakisARTIFACT_ID = spinner-preferenceVERSION = 1.0.0
GROUP_ID defines the name of library’s group. It is possible that there would be more than one library with different functionality in the same context or from the same company. If library are in the same group, it would share the same GROUP_ID. Generally we name it with developer’s package name and then follow with the name of library’s group, for example, com.squareup. And then defines the name of the library in ARTIFACT_ID. For VERSION, there is nothing but a version number. Although it could be any text but I suggest to use Semantic Versioning if you want.
Here is the real example of library from Square. You will notice that each one could be easily recognised the library’s and developer’s name.
How to upload your library to jcenter
Now let’s begin the most important part: uploading processes. The objective here is as simple as how to upload our library files to http://jcenter.bintray.com. Once we could do it, the library is published. Well … two things to concern: how to create an aar file and how to upload built files to the repository?
It is as easy as described in the image above.
Step 1. Create a Sonatype account for uploading to Maven Central (Optional)
Skip this step if you have no plans in uploading the library to Maven Central.
You have to create an account in the JIRA Issue Tracker on Sonatype site. To do so, please go to Sonatype Dashboard and simply sign up for an account.
Once you’re done you have to request a permission to distribute your library to Maven Central. What you have to do is to create an issue in JIRA to let them allow you to upload your library that match the GROUP_ID provided to Maven Central.
To create an issue like described, go to Sonatype Dashboard and login with account created. And then click at Create placed at the top menu.
It should look like this:
Fill in the following information:
Project: Community Support — Open Source Project Repository Hosting
Issue Type: New Project
Summary: Your library’s name in summary, for example, Spinner Preference
Group Id: Put the root GROUP_ID, for example, com.github.kostasdrakonakis . After you got an approval, every single library starts with com.github.kostasdrakonakis will be allowed to upload to repository, for example, com.github.kostasdrakonakis. Choose wisely and do not try to fool them with group_id like com.google.* or something like this because:
- You must own the domain
- It is illegal and they will not allow you.
Project URL: Put a URL of any library you plan to distribute, for example, https://github.com/kostasdrakonakis/spinner_preference
SCM URL: URL of Source Control, for example, https://github.com/kostasdrakonakis/spinner_preference.git
when ready click Create. That’s all. Now you should wait patiently until you will be granted an access to distribute your library to Maven Central after that. You will receive an email that someone commented on your post and the message should be something like:
That means that when we try to push artifacts to Maven Central we should be able to see them under http://search.maven.org/.
Step 2. Create an account in Bintray and create a repository.
Navigate to https://bintray.com/signup/oss and simply create an account. You can also signup with Github, Google or Twitter account for faster signup.
Login to the dashboard and add a new repository like this:
You can choose any name you want but for demo purposes I chose maven. Make sure the type is Maven. You can also choose the licence and press Create.
You should be in a page that looks like this:
Step 3. Create a package for repository in Bintray
Since everything is properly setup so far let’s go ahead and add a package to the repository we created in the previous Step.
Navigate to your repository created in the previous Step and click at the Add New Package
Fill in the details like:
Name: your package name, e.g. spinner-preference
Licences: The licence that you are using for your package, e.g. Apache-2.0
Tags: The tags that better describe the technologies used in your library
Website: Your website URL, if there is none use the repository URL from Github or Bitbucket.
Issues Tracker: You can leave it blank or use the Github/Bitbucket repository URL/issues
Version Control: Your Github/Bitbucket URL of the project’s repository
After that you can click at Create Package.
Once the package is created it should look like this:
Step 4. Enable auto signing for Bintray
As mentioned above, we could upload a library to Maven Central through jcenter but to do that we need to sign that library first. bintray provides a mechanic to do that easily through web interface that allows library to be signed automatically once uploaded.
First step is to generate a key via command line with the command below. (In case you use Windows, please do it under cygwin or cmder)
gpg --gen-key
You should be prompted to select a Passphrase after you press O so select one, then retype it and press enter. It should look something like this:
Once key is created. Call the following command to see the created key’s information.
gpg --list-keys
You should now see something like the above. Now we have to upload the public key to keyservers. To do so, please call the following command and replace PUBLIC_KEY_ID with 8-digits hexadecimal value after 2048R/ in the pub line which is 235D2978 in this example.
gpg --keyserver hkp://pool.sks-keyservers.net --send-keys PUBLIC_KEY_IDAnd then, export both public and private key as ASCII armor format with the following command and please replace yourmail@email.com to the email you used to create your own key in the previous step.
gpg -a --export yourmail@email.com > public_key_sender.asc
gpg -a --export-secret-key yourmail@email.com > private_key_sender.ascAfter both keys are exported open Bintray’s Edit Profile page and click at GPG Signing. Fill in both Public Key and Private Key using content in public_key_sender.asc and private_key_sender.asc files exported in previous step respectively.
Put your public key and your private key and then click Update to save the keys. The last thing to do is go back to your repository and click Edit and then you should be presented to a page that looks like this:
and check the Checkbox that says GPG sign uploaded files automatically.
Step 5. Create the Android Studio Library Project and Prepare files for upload to Bintray
Create an Android Studio Project and create a New Android Library Module that looks like this:
Modify the Project’s build.gradle to include those classpath’s:
classpath 'com.jfrog.bintray.gradle:gradle-bintray-plugin:1.4'
classpath 'com.github.dcendents:android-maven-gradle-plugin:1.5'It should look something like this:
Then in your library module’s build.gradle add those lines:
apply from: 'https://raw.githubusercontent.com/kostasdrakonakis/maven-upload/master/bintray.gradle'
apply from: 'https://raw.githubusercontent.com/kostasdrakonakis/maven-upload/master/publications.gradle'It should look like this:
Notice that we also modified the versionName attribute from “1.0” to
project.getProperty(“libraryVersion”)We did this just to make it easier for us to modify the version from only 1 place. Now the interesting part is to modify the gradle.properties file accordingly like this:
# When configured, Gradle will run in incubating parallel mode.
# This option should only be used with decoupled projects. More details, visit
# http://www.gradle.org/docs/current/userguide/multi_project_builds.html#sec:decoupled_projects
# org.gradle.parallel=true
libraryVersion = 1.0.0
libraryName = SpinnerPreference
libraryDescription = A custom Preference that implements Spinner in PreferenceActivity in android.
publishedGroupId = com.github.kostasdrakonakis
artifact = spinner-preference
bintrayRepo = maven
bintrayName = spinner-preference
siteUrl = https://github.com/kostasdrakonakis/spinner_preference
gitUrl = https://github.com/kostasdrakonakis/spinner_preference.git
developerId = kdrakonakis
developerName = Kostas Drakonakis
developerEmail = test@gmail.com
licenseName = The Apache Software License, Version 2.0
licenseUrl = http://www.apache.org/licenses/LICENSE-2.0.txt
allLicenses = ["Apache-2.0"]notice that I named my bintray repository “maven” earlier in Step 2 and the bintrayName(package name) as “spinner-preference”. The others are pretty much self explanable.
Do not forget to modify your local.properties like this:
bintray.apikey=abcefdaslkjdhakjsdhlkaskkjd54asd321qw8dasd1
bintray.gpg.password=mypassword
bintray.user=mybintrayusernameYou can find your API Key under Edit Profile in Bintray just as shown in here:
When you done with all of this modifications open terminal from Android Studio and execute the tasks:
in Windows:
gradlew installor if you are in Mac/Linux
gradle installand after the task succesfully executed you should execute the task:
in Windows:
gradlew bintrayUploador if you are in Mac/Linux
gradle bintrayUploadIf everything is successful you should see your files uploaded to Bintray packageName like it looks in here:
the .asc files mean that the files are automatically signed with the GPG Keys that we enabled earlier.
Step 6. Add to jCenter
If you are happy with the library you can press from the General tab Add to jCenter.
and just hit Send so that it will create a Request to bintray and once it is approved your package name will be included to jCenter.
You have to wait something like 2–3 hours normally for request to be approved and once it is approved you will see something like this:
It is finally done. Your project now can be used by any developer that includes the jCenter() in Android Studio. You can check your project in jcenter.bintray.com like this for example:
http://jcenter.bintray.com/com/github/kostasdrakonakis/spinner-preference/1.0.0/
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.
BUT how do we also include it in Maven Central?
Step 7. Sync to Maven Central
Not all of android developers use jcenter. There are still a number of developers who still use mavenCentral() so let's upload our library to Maven Central as well.
To forward library from jcenter to Maven Central, there are two missions that you need to achieve first:
1) Bintray package must be already linked to jcenter
2) Repository on Maven Central has already been approved to open
If you have already passed those qualifications. The way to forward your library package to Maven Central is incredibly easy. Just simply click at Maven Central link on package’s details page.
Navigate to https://oss.sonatype.org/ and login with the credentials you used to create your account when you Signed Up for Issues tracker.
Once you logged in you will see your username on the top right corner. Click the dropdown menu and select Profile and then in the Profile tab select User Token like the image below:
After that click Access User Token and enter your password to verify identity and you will be prompted with something like this:
enter the user token key and user token password under the Bintray Repository -> Paackage Name -> Maven Central
and click Sync. If everything is succesfull you will see Successfully synced and closed repo in Last Sync Status once it’s done. But if there is any problem, it would be shown in Last Sync Errors. You have to fix the problem case by case since the condition of library that could be uploaded to Maven Central is quite strict, for example, + sign couldn’t be used in the version of library’s dependency definition.
Once done. You could find your library binaries in Maven Central Repository at the directory matched your library’s group/artifact id. In this example, it is com -> github -> kostasdrakonakis -> spinner-preference -> 1.0.0
Congratulations ! That’s all. Although it requires quite a lot of steps but steps are quite straightforward. And most of them are one-time action. Once things are set, you almost have to do any additional step after that.
I hope this article will help you!