Simple library - A minimal demo

Let's take a look at the simplest sample project.

The sample project is here. The project contains build scripts in both Groovy and Kotlin. Pick the one you prefer. By default, the Groovy version (build.script) is executed. If you want to try the Kotlin version, use the command line with -c settings.gradle.kts option.

# use build.script$ ./gradlew tasks # use build.script.kts$ ./gradlew -c settings.gradle.kts tasks

It is an absolute minimal Java library that contains a single Java class samplelib.Hello that do trivial work. In this minimal example, we are going to publish it to Maven Local repository so that other projects on your computer can make use of it. We don't need any remote credential set up for this example. By default, the Maven Local repository is located at ~/.m2/repository for Unix/macOS or C:\Users\{your-username}\.m2\repository for Windows. We will check our result of publishing there. (To keep the description simple, I will use the Unix style path from now on, please adapt it for Windows environment).

pom.yaml

First, we look at the pom.yaml file. It is a Jarbird plugin-specific file to specify the information about your component.

pom.yaml

group: jarbirdsamplesartifactId: simplelibversion: 1.0-SNAPSHOT

So here is the typical GAV (Group, Artifact ID, Version) coordinate of Java component. In the good old days of building Java library, we put this information in build.gradle. The benefit of taking that out of build.gradle will be obvious when we work on more sophisticated scenarios. It is also OK to leave this information in build.gradle. We can even omit artifactId, then the project name (usually the project directory name) will be the artifactId.

Note that the version of our component is suffixed with -SNAPSHOT, which signifies that the component is a snapshot component. Snapshot components will not be signed, which save us some effort to make our minimal component works.

build.gradle

The next thing is our familiar build.gradle. First, we have the plugin declaration at the top of the file.

build.gradle

plugins {    id 'java'    id 'io.hkhc.jarbird' version '0.7.0'}// ...

build.gradle.kts

plugins {    id("java")    id("io.hkhc.jarbird") version "0.7.0"}// ...

The Jarbird plugin setups (almost) everything we need to publish components, including applying plugins, setting up publication definition, creating POM file, etc.

The last bit we need is to tell the Jarbird plugin that we publish our component to Maven Local repository.

build.gradle

// ...jarbird {    pub {        mavenLocal() // see the info block below    }}// ...

build.gradle.kts

// ...jarbird {    pub {        mavenLocal() // see the info block below    }}// ...

All configurations that we tell will be in the jarbird extension. This block indicates we have one pub (means publication) which will be published to Maven Local repository, by the mavenLocal() function. By default, the Jarbird plugin configures the pub to sign the artefacts before publishing.

That's it!

info

The mavenLocal() in the jarbird extension block is not the same as the mavenLocal() that could be specified in repositories() block. The latter refers to the repository to resolve (aka download) dependencies, and the former refers to the repository that we publish our artefacts.

Run it

Let's take a look at the Gradle tasks provided by the Jarbird plugin. In your shell which the current directory is the simplelib, we are working with. We list the available tasks by:

$ ./gradlew tasks

We see a section that we may not familiar with:

Jarbird publishing tasks------------------------jbPublish - PublishjbPublishSimplelib - Publish module 'simplelib' to all targeted repositoriesjbPublishSimplelibToMavenLocal - Publish module 'simplelib' to Maven Local repository jbPublishToMavenLocal - Publish to Maven Local repository

All Gradle tasks added by the Jarbird plugin are under the group 'Jarbird publishing tasks' and prefixed by 'jb'. So let's publish our component:

$ ./gradlew jbPublishBuild with Groovy build script
> Task :jbDokkaHtmlSimplelibInitializing pluginsDokka is performing: documentation for simplelibValidity checkCreating documentation models
WARN: The registry key 'java.correct.class.type.by.place.resolve.scope' accessed, but not loaded yet
> Task :jbDokkaHtmlSimplelibTransforming documentation model before mergingMerging documentation modelsTransforming documentation model after mergingCreating pagesTransforming pagesRendering

BUILD SUCCESSFUL in 10s

We may ignore the warning at the moment. All the execution did are compiling and archive the source code, building a Jar file for source code, generating and building a Jar file for document pages, and publishing them to Maven Local repository. To check if we have published the component successfully, check the directory ~/.m2/repository/jarbirdsamples/simplelib/1.0-SNAPSHOT

$ ls -1 ~/.m2/repository/jarbirdsamples/simplelib/1.0-SNAPSHOTmaven-metadata-local.xmlsimplelib-1.0-SNAPSHOT-javadoc.jarsimplelib-1.0-SNAPSHOT-sources.jarsimplelib-1.0-SNAPSHOT.jarsimplelib-1.0-SNAPSHOT.modulesimplelib-1.0-SNAPSHOT.pom

So we have the Jar file itself, the archive of source code, the archive of javadoc, POM file. Everything we need as a Java component in the Maven repository is present (except signatures, which we will come to that shortly).

We could use the component in other projects of the same computer, by adding this line to the build.gradle of these projects:

build.gradle

buildscript {    mavenLocal()    // ... other repositories}dependencies {    implementation 'jarbirdsamples:simplelib:1.0'    // ... other dependencies}

build.gradle.kts

buildscript {    mavenLocal()    // ... other repositories}dependencies {    implementation("jarbirdsamples:simplelib:1.0")    // ... other dependencies}

We have completed our first trial of the Jarbird plugin.