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.
+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 @@ -94,54 +147,72 @@ code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warni
- Custom Template
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(major = 2, minor = 1, patch = 1, preRelease = "beta")
+public class A {
+ // ...
+}-
-
- Or using a properties file: +
- Or using a properties +file:
import net.thauvin.erik.semver.Version;
-
-@Version(properties = "version.properties")
-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=betaTemplate
-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.
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:
+The default +template implements the following static variables:
BUILDDATE |
The build date. | -java.util.Date |
+java.util.Date |
VERSION |
@@ -210,17 +282,19 @@ code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warni
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:
+/* 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:
String |
|||
{{semver}} or {{version}} |
+{{semver}} or
+{{version}} |
The full semantic version. | String |
Please also look at this example using java.time
Elements & Properties
The following annotation elements and properties are available:
preReleasePrefix |
-version.prerelease.prefix |
+version.prerelease.prefix |
The pre-release prefix. | - |
type |
- | Either java or kt for Kotlin. |
+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",
- 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=
-# ...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=
+# ...--⚠️
+keysPrefixis a new element staring in1.1.0and may break older versions when using custom property keys.
-⚡ A quick fix is to includekeysPrefix=""in the annotation to remove the defaultversion.prefix.⚠️ +
keysPrefixis a new element staring in1.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:
- -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:
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.
+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 verifybld
+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)
+ }
+}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.
+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.gitThen use bld to build:
+cd semver
+./bld compileThe project has an IntelliJ +IDEA project structure. You can just open it after all the +dependencies were downloaded and peruse the code.