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 @@ -147,72 +94,54 @@ Version Plugin for Gradle.
- Custom Template
Examples
- Using annotation elements:
import net.thauvin.erik.semver.Version;
-
-@Version(major = 2, minor = 1, patch = 1, preRelease = "beta")
-public class A {
- // ...
-}import net.thauvin.erik.semver.Version;
+
+@Version(major = 1, minor = 0, patch = 0, 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 {
- // ...
-}# version.properties
-version.major=1
-version.minor=0
-version.patch=0
-version.prerelease=betaimport net.thauvin.erik.semver.Version;
+
+@Version(properties = "version.properties")
+public class A {
+// ...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.
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 |
@@ -282,19 +210,17 @@ href="https://docs.oracle.com/javase/8/docs/api/java/util/Date.html">
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.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.⚠️
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.
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.
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.
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.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.
+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.