Java Kotlin HTML Shell Batchfile
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.circleci
.idea
docs
example
gradle/wrapper
kobalt
src
.gitattributes
.gitignore
.travis.yml
LICENSE.txt
README.md
appveyor.yml
build.gradle
clean.sh
gradlew
gradlew.bat
kobaltw
kobaltw-test
kobaltw.bat
pom.xml
semver.iml
settings.gradle
version.properties

README.md

Semantic Version Annotation Processor

License (3-Clause BSD) release Maven Central Download
Known Vulnerabilities Build Status 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.

Examples

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

@Version(major = 1, minor = 0, patch = 0, preRelease = "beta")
public class A {
// ...
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:

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
BUILDMETA The build metadata, if any. 001

And the following methods/functions:

Method Description Example
preReleaseWithPrefix() Returns the pre-release with a prefix, - by default. -alpha
buildMetaWithPrefix() Returns the build metadata with a prefix, + by default. +001

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:

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
{{buildMeta}} The build metadata version. String

Please also look at this example using java.time

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.
buildMeta version.buildmeta The build metadata version.
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

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.1</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.1'
}

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.1'
}

annotationProcessor {
    library 'net.thauvin.erik:semver:1.0.1'
    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.1")
    compileOnly("net.thauvin.erik:semver:1.0.1")
}

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.