Publishing a maven artifact 1/3: glossary
This is the first article in a series describing how I started distributing my android/kotlin libraries. I am quite new to the subject and these articles do not pretend to be exhaustive yet they should be a good introduction for anyone who has been developing for a time and wants to make his/her software more broadly available. Especially, this first article tries to decode a lot of confusion around the different actors of the ecosystem.
Part 2/3 dives into the jcenter vs mavenCentral debate.
Part 3/3 describes a step-by-step solution for publishing your android/kotlin project to MavenCentral.
The common ground
Let’s start by reviewing what exactly maven is and why we should care.
Maven
Maven (or Apache Maven, wikipedia) is an open source build system, developed by the Apache foundation and mostly used for java projects.
It uses pom files that describe the structure of the project and its dependencies. Together with other artifacts like jar files or source.jars, this defines a format for hosting them and make them available for reuse.
These files are hosted on a web server typically using the following structure:
https://baseurl/{groupId}/{packageId}/{version}/{artifact}
For an example, okhttp will be at https://repo1.maven.org/maven2/com/squareup/okhttp3/okhttp/3.9.1/okhttp-3.9.1.jar
Pom file
The pom file is a XML file describing how to build the project, its dependencies as well as some metadata about the authors, licence, version control. For an example, the okhttp pom file.
Artifact
Artifacts are the results of a project compilation. For jvm projects, this is typically .jar files, sources.jar, or .war.
GroupId
The groupId is the namespace where artifacts are store. Usually it is a reversed domain. For an example com.squareup.okhttp3.
ArtifactId
This is the name of the artifact. For an example okhttp.
Snapshot
A snapshot (e.g 0.1.2-SNAPSHOT) is the version of artifacts while they’re still being worked on. If you download the same snapshot version at two different times, you might get different binaries. Snapshots typically cannot be hosted on the main repositories but have their own.
MavenLocal
A local repository simply serving artifacts over the filesystem. Usually it resides on your machine at ~/.m2
Repository
It can refer to two things:
- A complete repository like mavenCentral or jcenter hosting a lot of packages
- A subpart of a complete repository matching a groupId. If you manage a groupId on sonatype or Bintray, they will be shown as “repositories”
Sonatype ecosystem
Sonatype
Sonatype is the company hosting MavenCentral. They are core contributors to the maven build system. They also have a commercial offering for (amongst other things) hosting your own repository and/or monitoring your CI/CD.
MavenCentral
MavenCentral is a repository hosted by Sonatype for open source artifacts. For an exemple, you can find the okhttp files here.
To have your artifacts listed on MavenCentral, you first need to upload them on OSSRH before promoting them to MavenCentral.
Browse at: https://repo1.maven.org/maven2
Search at: https://search.maven.org
Note that MavenCentral is quite different from Maven, the build tool and that there are a lot of other maven repositories out there like jcenter (see below).
OSSRH
The Open Source Software Repository Hosting is the staging repository before artifacts are promoted to mavenCentral. To upload artifacts there, you will need to verify that you own your groupId, most of the time using a TXT DNS record.
Browse at: https://oss.sonatype.org/content/repositories/releases/
Sonatype snapshots repositories
Snapshot can typically not be uploaded to MavenCentral but once you upload them to OSSRH, they become available at https://oss.sonatype.org/content/repositories/snapshots/
Nexus
Nexus is a suite of tools and software developed by Sonatype to host artifacts. MavenCentral uses a Nexus instance to host open source artifacts.
Jfrog ecosystem
Jfrog
JFrog is the company behind JCenter and artifactory.
JCenter
JCenter is the MavenCentral of JFrog. It is public a maven repository for open source artifacts. To have your artifacts listed on MavenCentral, you first need to upload them to Bintray.
Browse at: https://jcenter.bintray.com/
Search at: https://bintray.com
OJO
oss.jfrog.org is an artifactory instance used to serve snapshots.
Browse at: https://oss.jfrog.org/artifactory/libs-snapshot/
Search at: https://oss.jfrog.org/
Artifactory
Artifactory is a suite of tools and software developed by JFrog to host artifacts aimed at development. It can be deployed on premises and allows snapshots of artifacts.
Bintray
Bintray is a suite of tools and software developed by JFrog to host artifacts aimed at distribution. It uses a fast CDN for faster download. JCenter uses Bintray.
Bintray doesn’t verify groupId ownership which has led to compromised artifacts in the past.
Gradle plugins
Gradle ‘maven’
The ‘maven’ plugin is the “old” plugin used to publish to mavenLocal or a remote maven repository.
Gradle ‘maven-publish’
The ‘maven-publish’ plugin is the “new” plugin used to publish to mavenLocal or a remote maven repository. It’s interesting to note that in 2013, this plugin was already considered “new”. It’s still unclear what benefits it brings compared to the old version. Some users have reported issues with signing while others just continue using the old ‘maven’ plugin.
Gradle ‘signing’
The ‘signin’ plugin is used to sign artifacts. This is required by Sonatype OSSRH.
Dcendents ‘android-maven-gradle-plugin’
The dcendents plugin is a third party plugin that allows publishing Android .aar files.
Bintray ‘gradle-bintray-plugin’
The gradle-bintray-plugin is provided by Bintray.
Codearte ‘gradle-nexus-staging-plugin’
Codearte plugin allows to promote Sonatype repositories from the command line without having to login on https://oss.sonatype.org.
Marcphilipp ‘nexus-publish-plugin’
Marcphilipp plugin allows you to specify the staging repository before uploading to OSSRH or any other Nexus repository.
Vanniktech ‘gradle-maven-publish-plugin’
Vanniktech plugin allows to publish kotlin and android code and upload source and javadoc automatically. It is the plugin used by okhttp and since I usually trust this team, I’m using this plugin in part 3/3 of this series to show how to publish artifacts as easily as possible.
Wrapup
That was a lot!
And this list is never near exhaustive. There are other repositories and the amount of third party gradle plugins is overwhelming each one supporting slightly different use cases:
- Android AARs
- Kotlin
- Source jar generation
- Artifact Signing
- Javadoc generation
- Snapshots
- Bintray vs OSSRH (jcenter vs mavenCentral)
This last point will be the topic of the next article in this series. Meet you there !
