The Ultimate Guide to Creating and Publishing Android Libraries

I am often amazed by the number of useful third-party libraries in the Android development community. For a long time, I wanted to contribute something, but I didn't know how to do it. After browsing many other articles on how to publish an Android development library, I still found that some details were missing, and all the information was in different places. So, I will walk through the process and show you how I did it.

For beginners, I recommend using Android Studio to create all Android projects. Android Studio officially uses the Gradle build system. Please make sure you download the latest version of Android Studio.

[[185318]]

Introduction to related terms

Before we get started, there are some terms you should be familiar with.

Project — In Android Studio, a project is a complete Android app. An Android Studio project contains one or more modules. In Android Studio, a project is similar to a workspace in Eclipse.

Module – A module is a component of an app that can be built, tested, and debugged separately. A module contains the source code and resource files of an app. In Android Studio, a module is similar to a project in Eclipse.

AAR – The 'aar' package is a binary distribution of the Android development library project. (AAR format) The main output of the development library project is the .aar package (which means Android archive). It is a combination of compiled code (such as jar files or .so files) and resource files (such as manifest files, res files, asset files).

Maven Central Repository – A repository provided by the Maven community. It contains many commonly used development libraries. The Search Maven website can be used to browse the contents of the Maven Central Repository. The Gradle, Please website is another tool that can be used to search the central repository. If you add jCenter() to the repository configuration section of the project configuration file, Gradle will use the jCenter repository (jCenter instructions). Maven Central Repository is also often referred to as Maven Center or Central Repository.

Sonatype — Sonatype's Open Source Software Repository Hosting (OSSRH) service is the primary way for project authors and contributors to publish their components to a central repository. It is a deployment hosting service for open source projects provided by the Sonatype Nexus Professional organization using the Nexus Staging Suite tool. The service is mainly used to handle deployment and verification operations, and also provides synchronization operations to deliver content to the central repository over the network.

GPG - GNU Privacy Guard (also known as GPG or GnuPG), a GNU project, is a cryptographic software that follows the OpenPGP (RFC4880) standard and is a free alternative to PGP. With GPG you can encrypt (decrypt) files containing sensitive data, such as electronic health information that is protected by the privacy and security of the Health Insurance Portability and Accountability Act (HIPAA). For more information on GPG, visit the GNU Privacy Guard website.

Prepare your Android development library

I will use my Trestle development library as an example. In your project, you need to modify some places to prepare it for publishing to Maven Central as a development library.

• Separate the core code of the library from the sample code. In my project, I separate them into two modules: library and sample. Please read the tips about creating a library module carefully. You may also need to rename your module.
• In the build.gradle file of the sample module, make sure to include the following:

 apply plugin: 'com.android.application'   
 
 dependencies { 
 
    compile project( ':library' )
 }

• In your library module's build.gradle file, make sure you include the following:

 apply plugin: 'com.android.library'   
 
 apply from : 'maven-push.gradle'  

• In the library module, add a gradle.properties file and make sure it contains the following content:

 POM_NAME=ProjectName 
 
 POM_ARTIFACT_ID=projectname 
 
 POM_PACKAGING=aar

• In the library module, add the maven-push.gradle file and make sure it contains the following content:

 /* 
 
 * Copyright 2013 Chris Banes 
 
 * 
 
 * Licensed under the Apache License, Version 2.0 (the "License" ); 
 
 * you may not use this file except   in compliance with the License. 
 
 * You may obtain a copy of the License at   
 
 * 
 
 * http://www.apache.org/licenses/LICENSE-2.0 
 
 * 
 
 * Unless required by applicable law or agreed to   in writing, software 
 
 * distributed under the License is distributed on an "AS IS" BASIS, 
 
 * WITHOUT WARRANTIES OR CONDITIONS OF   ANY KIND, either express or implied. 
 
 * See the License for the specific language governing permissions and   
 
 * limitations under the License. 
 
 */ 
 
  
 
 apply plugin: 'maven'   
 
 apply plugin: 'signing'   
 
  
 
 def isReleaseBuild() { 
 
 return VERSION_NAME. contains ( "SNAPSHOT" ) == false   
 
 } 
 
  
 
 def getReleaseRepositoryUrl() { 
 
 return hasProperty( 'RELEASE_REPOSITORY_URL' ) ? RELEASE_REPOSITORY_URL 
 
            : "https://oss.sonatype.org/service/local/staging/deploy/maven2/"   
 
 } 
 
  
 
 def getSnapshotRepositoryUrl() { 
 
 return hasProperty( 'SNAPSHOT_REPOSITORY_URL' ) ? SNAPSHOT_REPOSITORY_URL 
 
            : "https://oss.sonatype.org/content/repositories/snapshots/"   
 
 } 
 
  
 
 def getRepositoryUsername() { 
 
 return hasProperty( 'NEXUS_USERNAME' ) ? NEXUS_USERNAME : ""   
 
 } 
 
  
 
 def getRepositoryPassword() { 
 
 return hasProperty( 'NEXUS_PASSWORD' ) ? NEXUS_PASSWORD : ""   
 
 } 
 
  
 
 afterEvaluate { project -> 
 
 uploadArchives { 
 
 repositories { 
 
 mavenDeployer { 
 
                beforeDeployment { MavenDeployment deployment -> signing.signPom(deployment) } 
 
  
 
                pom.groupId = GROUP   
 
                pom.artifactId = POM_ARTIFACT_ID 
 
                pom.version = VERSION_NAME 
 
  
 
                repository(url: getReleaseRepositoryUrl()) { 
 
                    authentication(userName: getRepositoryUsername(), password : getRepositoryPassword()) 
 
 } 
 
                snapshotRepository(url: getSnapshotRepositoryUrl()) { 
 
                    authentication(userName: getRepositoryUsername(), password : getRepositoryPassword()) 
 
 } 
 
  
 
 pom.project { 
 
 name POM_NAME 
 
                    packaging POM_PACKAGING 
 
                    description POM_DESCRIPTION 
 
                    urlPOM_URL 
 
  
 
 scm { 
 
                        url POM_SCM_URL 
 
 connection POM_SCM_CONNECTION 
 
                        developerConnection POM_SCM_DEV_CONNECTION 
 
 } 
 
  
 
                    licenses { 
 
                        license { 
 
 name POM_LICENCE_NAME 
 
                            url POM_LICENCE_URL 
 
                            distribution POM_LICENCE_DIST 
 
 } 
 
 } 
 
  
 
                    developers { 
 
                        developer { 
 
                            id POM_DEVELOPER_ID 
 
 name POM_DEVELOPER_NAME 
 
 } 
 
 } 
 
 } 
 
 } 
 
 } 
 
 } 
 
  
 
 signing 
 
        required { isReleaseBuild() && gradle.taskGraph.hasTask( "uploadArchives" ) } 
 
        sign configurations.archives 
 
 } 
 
  
 
    //task androidJavadocs(type: Javadoc) { 
 
    //source = android.sourceSets.main.allJava 
 
 //} 
 
  
 
    //task androidJavadocsJar(type: Jar, dependsOn: androidJavadocs) { 
 
 //classifier = 'javadoc'   
 
    // from androidJavadocs.destinationDir 
 
 //} 
 
  
 
    task androidSourcesJar(type: Jar) { 
 
        classifier = 'sources'   
 
 from android.sourceSets.main.java.sourceFiles 
 
 } 
 
  
 
 artifacts 
 
        archives androidSourcesJar 
 
 } 
 
 }

• Modify the .gitignore file in the project root directory

 # [Android] ======================== 
 
 # Built application files 
 
 *.apk 
 
 *.ap_ 
 
  
 
 # Files for the Dalvik VM 
 
 *.dex 
 
  
 
 # Java class files 
 
 *.class 
 
  
 
 # Generated files 
 
 bin/ 
 
 gen/ 
 
  
 
 # Gradle files 
 
 .gradle/ 
 
 build/ 
 
  
 
 # Local configuration file (sdk path, etc) 
 
 local .properties 
 
  
 
 # Proguard folder generated by Eclipse 
 
 proguard/ 
 
  
 
 # Log Files 
 
 *.log 
 
  
 
 ## Directory-based project format: 
 
 .idea/ 
 
  
 
 ## File-based project format: 
 
 *.ipr 
 
 *.iws 
 
  
 
 ## Plugin-specific files: 
 
  
 
 # IntelliJ 
 
 out / 
 
  
 
 # mpeltonen/sbt-idea plugin 
 
 .idea_modules/ 
 
  
 
 # JIRA plugin 
 
 atlassian-ide-plugin.xml 
 
  
 
 # Crashlytics plugin ( for Android Studio and IntelliJ) 
 
 com_crashlytics_export_strings.xml 
 
  
 
 # [Maven] ======================== 
 
 target/ 
 
 pom.xml.tag 
 
 pom.xml.releaseBackup 
 
 pom.xml.versionsBackup 
 
 pom.xml.next   
 
 release.properties 
 
  
 
 # [Gradle-Android] ======================== 
 
  
 
 # Ignore Gradle GUI config 
 
 gradle-app.setting 
 
  
 
 # Gradle Signing 
 
 signing.properties 
 
 trestle.keystore 
 
  
 
 # Mobile Tools for Java (J2ME) 
 
 .mtj.tmp/ 
 
  
 
 # Package Files # 
 
 *.jar 
 
 *.war 
 
 *.ear 
 
  
 
 # virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml 
 
 hs_err_pid* 
 
  
 
 # Misc 
 
 /.idea/workspace.xml 
 
 .DS_Store 
 
 /captures 
 
 **/*.iml 
 
 *.class

• Modify the settings.gradle file in the project root directory

 include ':sample' , ':library'  

• Modify the gradle.properties file in the project root directory

 # Project-wide Gradle settings. 
 
  
 
 # IDE (eg Android Studio) users: 
 
 # Gradle settings configured through the IDE *will override* 
 
 # any settings specified in this file. 
 
  
 
 # For more details on how to configure your build environment visit 
 
 # http://www.gradle.org/docs/ current /userguide/build_environment.html 
 
  
 
 # Specifies the JVM arguments used for the daemon process. 
 
 # The setting is particularly useful for tweaking memory settings. 
 
 # Default value: -Xmx10248m -XX:MaxPermSize=256m 
 
 # org.gradle.jvmargs=-Xmx2048m -XX:MaxPermSize=512m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8 
 
  
 
 # 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   
 
  
 
 VERSION_NAME=0.0.1 
 
 VERSION_CODE=1 
 
 GROUP =com.github.github_username 
 
  
 
 POM_DESCRIPTION=A library that does X, Y, and Z 
 
 POM_URL=https://github.com/github_username/ProjectName 
 
 POM_SCM_URL=https://github.com/github_username/ProjectName 
 
 POM_SCM_CONNECTION=scm:[email protected]:github_username/ProjectName.git 
 
 POM_SCM_DEV_CONNECTION=scm:[email protected]:github_username/ProjectName.git 
 
 POM_LICENCE_NAME=The Apache Software License, Version 2.0 
 
 POM_LICENCE_URL=http://www.apache.org/licenses/LICENSE-2.0.txt 
 
 POM_LICENCE_DIST=repo 
 
 POM_DEVELOPER_ID=github_username 
 
 POM_DEVELOPER_NAME=GitHub FullName

• Add a README.md file to introduce your library to other developers and how to use it. If you want to add some screenshots to your README.md file, I highly recommend an app called Screenr.

Install GPG

If you don't have GPG installed on your machine, you will need to download and install it. If you are using MacOSX, the installation instructions are here.

If you have never used GPG - first, create a GPG key:

 $ gpg --gen-key  

If you're unsure how to answer the questions when you create your GPG key, this guide (Creating an encryption key) can help.

Next, find your key ID:

 $ gpg --list-keys  

The first line will be something like pub XXXXX/YYYYYYYY <date>. Remember, the 'YYYYYYYY' part is your key ID.

Now, publish your key:

 $ gpg --keyserver hkp://keyserver.ubuntu.com --send-keys YYYYYYYY   
 
 $ gpg --keyserver hkp://pgp.mit.edu --send-keys YYYYYYYY  

You can of course use other key servers, and you can also confirm whether your key has been published by running the following command:

 $ gpg --keyserver hkp://pgp.mit.edu --search-keys [email protected] # Use your email  

To get your library listed on the Gradle, Please website (and to make it easier for others to reference your library), please upload your project to Maven Central. The easiest way to upload a project is to use Sonatype.

Sonatype

1. Create a JIRA account at Sonatype.
2. After logging in successfully, create a new issue.

I created a GitHub repository for my Trestle project. So the fields I filled in on the new issue looked like this:

Group Id : com.github.<github_username>

Project URL : https://github.com/<github_username>/<project_name>

SCM url : https://github.com/<github_username>/<project_name>.git

Username : <sonatype_username>

Already Synced to Central : No

Note: I added brackets as placeholders around the fields you need to fill in. You will need to replace them with the appropriate values.

When you are ready to submit an issue, the details of the issue should be similar to the screenshot above. After you submit it, Sonatype will take 2 working days to process your issue. Then, you will receive a confirmation email informing you that your configuration is ready and you can publish your open source library.

Don't deploy your open source repository until you receive an email indicating that your ticket is OK. A common mistake for new projects is to deploy too early. This will mistakenly make your artifacts available in a repository for everyone to access.

Finally, if your component is already in the central repository, please add the following information to your ticket and refer to this article on how to migrate to OSSRH.

Modify the ~/.gradle/gradle.properties file on your machine to include the following:

 NEXUS_USERNAME=sonatype_username 
 
 NEXUS_PASSWORD=sonatype_password 
 
 signing.keyId=gpg_key_id 
 
 signing.password =gpg_password 
 
 signing.secretKeyRingFile=/Users/username/.gnupg/secring.gpg 
 
 org.gradle.daemon = true  

When you publish the repository, the authentication information is provided in the gradle.properties file. Please make sure to provide the correct nexus username and password (that is, the Sonatype username and password), otherwise you will get an unauthorized 401 error.

NOTE: If you have published a repository before, you do not need to create a new issue in JIRA (Sonatype). There is one JIRA issue for each top-level groupId. You should already have all the permissions you need to deploy any new artifacts to your groupId or subordinate groups. Syncing with the central repository follows a top-down process, so any releases from subordinate groups will be automatically synced. When you publish new components, you do not need to tell Sonatype because there is nothing for Sonatype to configure or check when you sync the repository. Sonatype will only post a twitter message the first time it syncs.

release

Once you are ready to publish your development library, in Android Studio, open the Gradle view on the right, under Tasks > upload, click uploadArchives, which will upload your development library to the Sonatype Staging Repositories.

On the Sonatype Staging Repositories page, log in to your Sonatype account, find your 'staging' repository, it should be at the end of the list, select it and press the 'Close' button. Closing a repository actually means you are preparing to publish it. If everything went well – you should see an activated 'Publish' button. You may need to refresh the page. Press the Publish button. Please read the help documentation about managing repositories with Nexus. If this is the first repository you have published, go back to JIRA and post a comment in JIRA that you have improved your repository, if it is not the first, there is no need to tell Sonatype that you have improved your repository. Then, you should receive a reply message from Sonatype saying that your repository will be ready in 10 minutes and will be synchronized to the Maven Central Repository in the next few hours. After a few hours, it will be displayed on the Gradle, Please website.

Using your development libraries

For other developers to use your development library, they need to add a dependency in the build.gradle file of the Android project, as shown below:

 apply plugin: 'android'   
 
 dependencies { 
 
    compile 'com.github.lawloretienne:trestle:0.0.3'   
 
 }

Special Thanks

Many thanks to Chris Banes, Jonathan Le, Serge Zaitsev, and others who posted on the blog, whose articles helped me navigate this complex process.

My development library

QuickReturn — https://github.com/lawloretienne/QuickReturn

Trestle — https://github.com/lawloretienne/Trestle

ImageGallery — https://github.com/lawloretienne/ImageGallery