Semantic Version Annotation Processor

An annotation processor that automatically generates a GeneratedVersion class based on a Mustache template and containing the semantic version (major, minor, patch, etc.) that is read from a Properties file or defined in the annotation.

This processor was inspired by Cédric Beust's version-processor.

Examples

• Using annotation elements:

import net.thauvin.erik.semver.Version;

@Version(major = 1, minor = 0, patch = 0, preRelease = "beta")
public class A {
// ...

• Or using a properties file:

import net.thauvin.erik.semver.Version;

@Version(properties = "version.properties")
public class A {
// ...

# version.properties
version.major=1
version.minor=0
version.patch=0
version.prerelease=beta

View Example

Template

Upon running the annotation processor, a source file GeneratedVersion.java is automatically generated with static methods to access the semantic version data. The source is based on a fully customizable Mustache template.

To use your own template, simply create a version.mustache file. The processor will automatically look for it.

To specify your own template name, use:

@Version(template = "version.mustache")
public class A {
// ...

Default Template

The default template implements the following static fields:

And the following methods/functions:

Custom Template

A very simple custom template might look something like:

/* version.mustache */
package {{packageName}}

import java.util.Date;

public final class {{className}} {
    public final static String PROJECT = "{{project}}";
    public final static Date DATE = new Date({{epoch}}L);
    public final static int MAJOR = {{major}};
    public final static int MINOR = {{minor}};
    public final static int PATCH = {{patch}};
    public final static String PRERELEASE = "{{preRelease}}";
    public final static String BUILDMETA = "{{buildMeta}}";
}

The mustache variables automatically filled in by the processor are:

Please also look at this example using java.time

Elements & Properties

The following annotation elements and properties are available:

In order to easily incorporate with existing projects, the property keys may be assigned custom values:

@Version(
  properties = "example.properties",
  majorKey = "example.major",
  minorKey = "example.minor",
  patchKey = "example.patch",
  preReleaseKey = "example.prerelease",
  buildMetaKey = "example.buildmeta",
  projectKey = "example.project"
)
public class Example {
// ...

# example.properties
example.project=Example
example.major=1
example.minor=0
example.patch=0
# ...

Usage with Maven, Grail, Kobalt and Kotlin

Maven

To install and run from Maven, configure an artifact as follows:

<dependency>
    <groupId>net.thauvin.erik</groupId>
    <artifactId>semver</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle

Class Generation

To install and run from Gradle, add the following to the build.gradle file:

dependencies {
    compileOnly 'net.thauvin.erik:semver:1.0.0'
}

The GeneratedVersion class will be automatically created in the build/generated directory upon compiling.

Class & Source Generation

In order to also incorporate the generated source code into the source tree, use the EWERK Annotation Processor Plugin. Start by adding the following to the very top of the build.gradle file:

plugins {
    id "com.ewerk.gradle.plugins.annotation-processor" version "1.0.4"
}

Then add the following to the build.gradle file:

dependencies {
    compileOnly 'net.thauvin.erik:semver:1.0.0'
}

annotationProcessor {
    library 'net.thauvin.erik:semver:1.0.0'
    processor 'net.thauvin.erik.semver.VersionProcessor'
    // sourcesDir 'src/generated/java'
}

compileJava {
    // Disable the classpath processor
    options.compilerArgs << '-proc:none'
}

The plugin implements a separate compile task that only runs the annotation processor and is executed during the build phase.

Please look at the build.gradle file in the example module directory for a sample.

Kobalt

To install and run from Kobalt, add the following to the Build.kt file:

dependencies {
    apt("net.thauvin.erik:semver:1.0.0")
    compileOnly("net.thauvin.erik:semver:1.0.0")
}

Please look at the Build.kt file in the example module directory for a sample.

Kotlin

The annotation processor also supports Kotlin.

To generate a Kotlin version file, simply specify the type as follows:

import net.thauvin.erik.semver.Version

@Version(properties = "version.properties", type="kt")
open class Main {
// ...

The Kotlin default template implements the same static fields and functions as the Java template.

Please look at the Example for Kotlin project for samples on using Gradle (build.gradle) and Kobalt (Build.kt).

Auto-Increment

Incrementing the version is best left to your favorite build system.

For a solution using Gradle, please have a look at the build.gradle file in the example module directory. To run the example with patch version auto-incrementing, issue the following command:

gradle release run

For a solution using Kobalt look at my Property File Editor plug-in.