Semantic Version Annotation Processor

An annotation processor that automatically generates a GeneratedVersion class 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:

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

• Or using a properties file:

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

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

Template

Upon running the annotator 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 Velocity template.

@Version(template = "myversion.vm")
public class A {
// ...

Default Template

The default template implements the following static methods:

Custom Template

A very simple custom template might look something like:

/* myversion.vm */
package ${packageName}

import java.util.Date;

public final class ${className} {
    public final static String BUILDMETA = "${buildmeta}";
    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 PROJECT = "${project}";
}

The Velocity variables are automatically filled in by the processor.

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 and Kobalt

Maven

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

<dependency>
    <groupId>net.thauvin.erik</groupId>
    <artifactId>semver</artifactId>
    <version>0.9.5-beta</version>
</dependency>

Gradle

Class Generation

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

dependencies {
    compile 'net.thauvin.erik:semver:0.9.5-beta'
}

The GeneratedVersion class will be automatically created in the build 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 addding the following to the very top of the build.gradle file:

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

Then add the following to the build.gradle file:

dependencies {
    compileOnly 'net.thauvin.erik:semver:0.9.5-beta'
}

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

compileJava {
    // Disable the classpath procesor
    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:0.9.5-beta")
}

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 clean release run