This post is the second part of the series “2:20 to Maven Central” – the complete guide to deploying artifacts to Maven Central.
In the previous post, we looked at how to prepare and verify your luggage (a.k.a the POM file). The next step on the way to Maven Central is verifying your identity.
You verify your identity by signing your artifacts and publishing your public key to a public PGP key server. Signing your artifacts is a requirement for publishing them to Maven Central. This is typically accomplished by creating a signing (OpenPGP) key.
But why, you may ask, do you have to verify your identity. The answer is simple, in order to maintain the integrity of the Maven central ecosystem. By signing your artifact, you are enabling anyone who uses artifacts from maven central to be able to verify that the packages they receive do indeed come from you and have not been modified in any way.
Before going into detail of how to do this, I will summarize the whole signing process here. Basically you create a GnuPG signing keypair containing the private and public keys. The private key is used to sign your artifact, while your public key must be hosted on a public PGP server, allowing anyone to be able to verify your artifacts.
In order to generate a new keypair, you need to enter the following command in your terminal (assuming GnuPG is properly installed on your machine):
Follow the instructions at the command prompt and accept the default settings which are recommended. A few things to note:
You can leave the default key without an expiration date. It is possible to change the expiration date after creating the key, but it may be difficult to communicate it.
Choose a good passphrase and guard it carefully. If someone were to have access to your key, (bad things could happen)™.
There are several GUI front-ends for GnuPG available which you could use to generate the key if you do not want to work on the command line.
Next you need to upload the public part of your generated key to a public PGP server. Uploading can be done with the following command in your terminal:
gpg –keyserver pgp.mit.edu –send-key <keyID>
The Key ID looks something like 5DED768A and is also the name of the key file which is generated
PGP keys are forever. Once you upload a key, you cannot remove it anymore. You may however generate a revocation certificate to let others know that the key is invalid. The MIT PGP public key server FAQ is a good read.
Once you have created and uploaded your key, you should now configure maven to use your key for signing your artifacts. For this, there is the maven-gpg-plugin (note that the gpg command must be available from your terminal when using this plugin).
Ideally we want the artifact to be signed only when we are performing a release, not during development builds. We therefore specify in the POM file that we want signing to be activated only for releases. This is accomplished by adding the following profile to your POM file:
Now you’re all set. When performing a release build, you will be prompted for your passphrase and the artifact will be signed using your GnuPG key.
Having built and signed the artifacts, the next step would be boarding the train to Maven Central.
In a previous post, I mentioned that the Android Contact Picker library is now deployed to maven central. Getting there was a multi-day process which involved a lot of Googling to figure out stuff. Thanks to blogs like this and this, I was able to finally get through the process. But it can be a bit tedious if you are new to all the side-processes involved.
For this reason, I want to document the whole process again for myself and maybe for anyone who might find it useful. I am doing a series about deploying to maven central, starting with preparing your POM file right up to final deployment. The basic assumption here is that you know your way around maven and are looking to deploy to Central.
As there are many ways to get to Maven Central, I am going to focus on using the Sonatype Express which takes only Open Source Software passengers. There is a guide to the Sonatype OSS Maven repository, which focuses on how to deal with things on their end. These series of posts focus on what you the developer need to do to prepare your artifacts for maven central.
This post will focus on the first step, which is preparing your POM file.
Part 1: Verify your luggage – Is your POM ready?
I am assuming you already use maven for building your project (hence the interest in deploying to maven central). This means you know what the pom.xml file is, and if you do not, take a look at the Complete Maven Reference and the POM reference. Maven can easily build your project with a minimum of information like the packaging, dependencies etc.
However, much more is needed in order to deploy your artifacts so that they can be reliably shared with others and dependencies properly resolved. There is a minimum set of tags required in the POM file in order to improve the central repository and support the Maven ecosystem. The minimum required tags are the following:
More details on each of the elements can be found in the POM reference. You can take a look at the Android Contact Picker POM file for an example of how to enter the attributes. Here are a few additional notes about some of the required elements in the POM:
- Choose your Maven coordinates carefully. They need to be unique to your project. Use your domain name or that of your organization as prefix. It is usually recommended, but not required that the coordinates match your Java package names.
- While still in the development phase, use the –SNAPSHOT suffix in your project version. For example <version>2.2.0-SNAPSHOT</version>. This enables you to always get the latest development build when testing.
- Version control links are important (and mandatory) and most popular versioning systems are supported by Maven. They will also be used during the final release phase by the maven-release-plugin.
- Putting the release repository/pluginRepository in your POM is discouraged. In ideal conditions, all your dependencies should be already in central and central repository is self-contained.
Once your pom file has all the necessary components in place you should test your build by running maven clean install. This will build your project and install it into your local maven repository. If this succeeds, then you are ready to go on to the next step. If not, look at the errors and fix any issues and rebuild. Rinse and repeat until it works.
The next stop en route to Maven Central and the topic of the next post is verifying your identity.
Photo credit: Steven Barker on Flickr
GnuCash for Android has been developed with the goals of simplicity, usability and broad compatibility. In order to apply modern Android Design guidelines for the user experience of the app while maintaining broad compatibility, I am using the ActionBarSherlock library. This meant that I had to download the library and include it in my project, as well as distribute it with the source code to allow others to quickly checkout and build the code.
This has become cumbersome in a couple of ways.
- In order for Eclipse to properly find references to Android library projects, they need to also be imported into the workspace. The idea of distributing the library with the GnuCash for Android source code bugs me.
- Updating the library project becomes a burden. Every time it updates, I need to download the source, replace the old source code, import it into Eclipse and then make a large commit for the library source into version control.
- GnuCash for Android also uses Robotium for testing. Admittedly it is just one jar file, but has to also be distributed with the source and updating is also cumbersome.
- There are other libraries which I may use in the future like Roboguice and others which will really inflate the size of the source code with dependencies.
The status quo is not sustainable and there has to be a better way. Enter Maven, the
build project management tool which also manages dependencies. I had introduced Maven build support to the GnuCash for Android project some while ago, but due to the Eclipse requirement for importing apklibs, I still had to distribute the ABS library with the project.
Well, now I am going all-in with Maven and removing support for IDE-specific project files. You can always import the code into Eclipse as a maven project it should setup everything right. This is also mostly a painless switch for me because I am now using IntelliJ IDEA 12 going forward. It has one feature which I really appreciate, and that is downloading any Android library dependencies, importing and properly referencing them.
If you are using Eclipse, then you would need to download the apklib dependencies (ActionBarSherlock) and import into your workspace and also properly reference the library project. Eclipse maven plugins should be able to handle the other dependencies just fine.
I should also note that the name of the GnuCash for Android project on GitHub has been changed from GnucashMobile to gnucash-android. If you have cloned the repository, you may need to rename your remote repository.
So checkout the code and send me that pull request which you’ve been sitting on 🙂