Skip to content

ethauvin/semver

Repository files navigation

Semantic Version Annotation Processor

License (3-Clause BSD) Java bld release Nexus Snapshot Maven Central

Quality Gate Status GitHub CI Build status CircleCI

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

  • Using annotation elements:
import net.thauvin.erik.semver.Version;

@Version(major = 2, minor = 1, patch = 1, 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 Examples

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:

Field Description Example
PROJECT The project name, if any. MyProject
BUILDDATE The build date. java.util.Date
VERSION The full version string. 1.2.3-alpha+001
MAJOR The major version. 1
MINOR The minor version. 2
PATCH The patch version. 3
PRERELEASE The pre-release version, if any. alpha
PRERELASE_PREFIX The pre-release prefix -
BUILDMETA The build metadata, if any. 001
BUILDMETA_PREFIX The metadata prefix. +
SEPARATOR The version separator. .

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:

Variable Description Type
{{packageName}} The package name. String
{{className}} The class name. String
{{project}} The project name. String
{{epoch}} The build epoch/unix time. long
{{major}} The major version. int
{{minor}} The minor version. int
{{patch}} The patch version. int
{{preRelease}} The pre-release version. String
{{preReleasePrefix}} The pre-release prefix. String
{{buildMeta}} The build metadata version. String
{{buildMetaPrefix}} The metadata prefix. String
{{separator}} The version separator. String
{{semver}} or {{version}} The full semantic version. String

Elements & Properties

The following annotation elements and properties are available:

Element Property Description Default
project version.project The project name.
major version.major The major version number. 1
minor version.major The minor version number. 0
patch version.patch The patch version number. 0
preRelease version.prerelease The pre-release version.
preReleasePrefix version.prerelease.prefix The pre-release prefix. -
buildMeta version.buildmeta The build metadata version.
buildMetaPrefix version.buildmeta.prefix The metadata prefix. +
separator version.separator The version separator. .
packageName The package name. Same as annotated class
className The name of the generated class. GeneratedVersion
properties The properties file.
template The template file. version.mustache
type Either java or kt for Kotlin. java
keysPrefix The prefix for all property keys. version.

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.

Maven

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

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

Please look at pom.xml in the examples/java directory for a sample:

mvn verify

bld

To install and run from bld, just add the dependency to your build file:

public class ExampleBuild extends Project {
    public ExampleBuild() {
        // ...
        scope(compile)
            .include(dependency("net.thauvin.erik", "semver", version(1, 2, 1)));
    }
}

Please look at ExampleBuild in the examples/java/bld directory for a sample. It also shows how to incorporate the generated code into the source tree, more information is also available here.

bld also has a Generated Version extension which provides similar functionalities.

Gradle

Class Generation

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

repositories {
    mavenCentral()
}

dependencies {
    annotationProcessor 'net.thauvin.erik:semver:1.2.1'
    compileOnly 'net.thauvin.erik:semver:1.2.1'
}

tasks.withType(JavaCompile).configureEach {
    options.compilerArgs += [ "-Asemver.project.dir=$projectDir" ]
}

The directory containing the configuration files (version.properties, version.mustache) must be specified using the semver.project.dir processor argument.

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

Please look at build.gradle in the examples/java/gradle directory for a sample.

Class & Source Generation

In order to also incorporate the generated source code into the source tree, add the following to build.gradle:

tasks.withType(JavaCompile).configureEach {
    options.generatedSourceOutputDirectory.set(file("${projectDir}/src/generated/java"))
}

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

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 examples/kotlin project for a build.gradle.kts sample.

Kotlin & Gradle

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

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

dependencies {
    kapt(semverProcessor)
    compileOnly(semverProcessor)
}

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

The directory containing the configuration files (version.properties, version.mustache) must be specified using the semver.project.dir processor argument.

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.

Contributing

If you want to contribute to this project, all you have to do is clone the GitHub repository:

git clone git@github.com:ethauvin/semver.git

Then use bld to build:

cd semver
./bld compile

The project has an IntelliJ IDEA project structure. You can just open it after all the dependencies were downloaded and peruse the code.