Submitting a project to maven central - tooltwist/documentation GitHub Wiki
Skip over italics if you wish - it's background information only.
XData is a high speed parser for JSON and XML that allows you to access data using a consistent API irrespective of the data format in use.
It can be incorporated into a project either by including the jar file, or by specifying it as a dependancy for a Maven project. This page describes the process of submitting xdata to Maven Central, the centralized repository of Maven projects. I found existing documentation assumed too much knowledge and skipped over important steps.
I found Maven to be initially quite simple, but occasionally the wagon threw a wheel. Getting back on the right track sometimes took a while, and Googling provided many (thousands?) of pages of un-useful information. I hope this page can save someone a bit of time. This guide specifically talks about how to submit a project that already builds with Maven to the Maven Central repository, so it can be picked up by other users.
My background is with Make, Ant, Eclipse and the like, so the following is from that perspective.
I use OSX and Github.
Maven is not a build tool like make or ant. It is a software distribution tool, that uses plugins that hopefully understand what you are trying to do (create a jar file, create javadoc, submit to a repository, etc). These plugins are not instructions as with Ant but instead perform black magic and may perform various unrelated operations. For example, a plugin to submit files to the repository might modify the version number in the POM file before and afterwards, create .asc files, commit files to version control, build the application, test it, and... submit it to the repository.
You need a basic understanding of Maven and can build a simple application. Chapters 1 to 4 of this free e-book might be helpful:
http://www.topazproject.org/trac/attachment/wiki/MavenInfo/BetterBuildsWithMaven.pdf?format=raw
You don't actually submit your project to Maven Central. Rather you submit to Sonatype who use a product named Nexus to allow you to set up a staging repository. When all is well (it checks) it will submit to Maven Central for you. The guys at Sonatype are great. Follow the steps here to create an account, but only up to step 5 at this stage.
https://docs.sonatype.org/display/Repository/Sonatype+OSS+Maven+Repository+Usage+Guide
Only signed packages can be submitted to Maven Central. This is done using a third party product named GPG.
Install GPG your machine. Follow this instructions here, up to Maven GPG Plugin, and skipping the section Sign a File.
https://docs.sonatype.org/display/Repository/How+To+Generate+PGP+Signatures+With+Maven
Using your account details for SonaType, create a file named ~/.m2/settings.xml. We keep the details for you login separate to the project, because you don't want them saved to Github.
<settings>
<servers>
<server>
<id>sonatype-nexus-snapshots</id>
<username>fredSmith</username>
<password>myPassword</password>
</server>
<server>
<id>sonatype-nexus-staging</id>
<username>fredSmith</username>
<password>myPassword</password>
</server>
</servers>
</settings>
Update your pom.xml file:
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.tooltwist</groupId>
<artifactId>xdata</artifactId>
<packaging>jar</packaging>
<name>xdata</name>
<version>0.3.2-SNAPSHOT</version>
<description>Xdata (Cross Data) library for anonymous format and high speed parsing</description>
<url>https://github.com/tooltwist/xdata</url>
<licenses>
<license>
<name>The Apache Software License, Version 2.0</name>
<url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
<distribution>repo</distribution>
</license>
</licenses>
<!-- What source code management tool to use -->
<scm>
<connection>scm:git:[email protected]:tooltwist/xdata.git</connection>
<developerConnection>scm:git:[email protected]:tooltwist/xdata.git</developerConnection>
<url>[email protected]:tooltwist/xdata.git</url>
</scm>
<!-- Where to deploy snapshots and staging -->
<!-- The login details are defined in settings.xml -->
<distributionManagement>
<snapshotRepository>
<id>sonatype-nexus-snapshots</id>
<name>nexus snapshots</name>
<url>https://oss.sonatype.org/content/repositories/snapshots</url>
</snapshotRepository>
<repository>
<id>sonatype-nexus-staging</id>
<name>nexus releases</name>
<url>https://oss.sonatype.org/service/local/staging/deploy/maven2</url>
</repository>
</distributionManagement>
<developers>
<developer>
<id>philcal</id>
<name>Philip Callender</name>
<email>[email protected]</email>
</developer>
</developers>
<dependencies>
<!--- This depends upon your project -->
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>4.11</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>xalan</groupId>
<artifactId>xalan</artifactId>
<version>2.7.1</version>
</dependency>
</dependencies>
<build>
<plugins>
<!-- Javadoc plugin -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.9</version>
<configuration>
<show>public</show>
<!--
<show>private</show>
<nohelp>true</nohelp>
-->
</configuration>
</plugin>
<!-- Use GPG to sign files -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-gpg-plugin</artifactId>
<version>1.4</version>
<executions>
<execution>
<id>sign-artifacts</id>
<phase>verify</phase>
<goals>
<goal>sign</goal>
</goals>
</execution>
</executions>
</plugin>
<!-- This plugin prevents the gpg plugin from hanging -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-release-plugin</artifactId>
<version>2.0</version>
<configuration>
<mavenExecutorId>forked-path</mavenExecutorId>
</configuration>
</plugin>
</plugins>
</build>
<reporting>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.9</version>
<configuration>
<stylesheetfile>${basedir}/src/main/javadoc/stylesheet.css</stylesheetfile>
<show>public</show>
</configuration>
</plugin>
</plugins>
</reporting>
</project>
This isn't as scary as it looks.
If you use Subversion or Mercurial for source code management (SCM), see examples in Section 7a.1 of the Sonatype's guide.
To deploy a snapshot, follow Section 7a.2 of the Sonatype's guide.
To submit a release to the staging repository, follow Section 7a.3 of the Sonatype guide.
This is done by logging onto SonaType, and following the instructions in section 8a.
I found that if the Stage a Release steps failed, my pom.xml file was left with the incorrect version number. In some cases the -SNAPSHOT suffix got removed, which caused an error. If this happens, simply edit the file and set it right, then run a mvn clean.
Maven: The Complete Reference - http://www.sonatype.com/books/mvnref-book/reference/public-book.html
Maven Cheat Sheet - https://github.com/gwtbootstrap/gwt-bootstrap/wiki/Maven-Cheat-Sheet
Using GPG manually - http://www.benmccann.com/dev-blog/creating-asc-signature-files-with-gpg/
Uploading to Maven Central - http://www.inspire-software.com/en/index/view/maven-overview-tutorial-upload-to-maven-central.html
GitHub Maven Plugins - https://github.com/github/maven-plugins
Fixing GPG plugin hanging - http://skife.org/2010/07/23/maven-oss-sonatype-gpg.html
--