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 and works well in conjunction with the Semantic Version Plugin for Gradle.

Table of Contents

• Examples
• Template
  • Default Template
  • Custom Template
• Elements & Properties
• Usage with Maven, Gradle, Kotlin and Kobalt
  • Maven
  • Gradle
    • Class Generation
    • Class & Source Generation
  • Kotlin
    • Kotlin & Gradle
  • Kobalt
• Auto-Increment

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 in the project's root directory. 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 variables:

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 String VERSION = "{{semver}}";
}

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",
  keysPrefix = "example."
  majorKey = "maj",
  minorKey = "min",
  patchKey = "build",
  preReleaseKey = "rel",
  buildMetaKey = "meta",
  projectKey = "project"
)
public class Example {
// ...

# example.properties
example.project=Example
example.maj=1
example.min=0
example.build=0
example.rel=beta
example.meta=
# ...

⚠️ keysPrefix is a new element staring in 1.1.0 and may break older versions when using custom property keys.
⚡ A quick fix is to include keysPrefix="" in the annotation to remove the default version. prefix.

Usage with Maven, Gradle, Kotlin and Kobalt

Maven

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

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

Please look at pom.xml in the Java example directory for a sample:

mvn verify

Gradle

Class Generation

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

dependencies {
    annotationProcessor 'net.thauvin.erik:semver:1.2.0'
    implementation 'net.thauvin.erik:semver:1.2.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, add the following to the very top of build.gradle:

compileJava.options.annotationProcessorGeneratedSourcesDirectory = file("${projectDir}/src/generated/java")

The GeneratedVersion.java file will now be located in src/generated.

Please look at build.gradle in the Java example 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.

Kotlin & Gradle

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

var semverProcessor = "net.thauvin.erik:semver:1.2.0"

dependencies {
    kapt(semverProcessor)
    implementation (semverProcessor)
}

kapt {
    arguments {
        arg("semver.project.dir", projectDir)
    }
}

The arguments block is not required if kapt is configured to use the Gradle Worker API in gradle.properties:

kapt.use.worker.api=true

This option will likely be enabled by default in the future, but is currently not working under Java 10+ see KT-26203.

Please look at the Kotlin example project for a build.gradle.kts sample.

Kobalt

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

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

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

Auto-Increment

Incrementing the version is best left to your favorite build system. For a solution using Gradle, please have a look at the Semver Version Plugin for Gradle.

There are also full examples in both Java and Kotlin showing how to use both the plugin and annotation processor concurrently.