diff --git a/README.md b/README.md index 9517013..0b0e976 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ version.prerelease=beta ## Template -Upon running the annotation processor, a source file [`GeneratedVersion.java`](https://github.com/ethauvin/semver/blob/master/examples/java/src/generated/java/net/thauvin/erik/semver/examples/java/GeneratedVersion.java) is automatically generated with static methods to access the semantic version data. The source is based on a fully customizable [Mustache](https://mustache.github.io/) template. +Upon running the annotation processor, a source file [`GeneratedVersion.java`](https://github.com/ethauvin/semver/blob/master/examples/java/src/generated/java/com/example/GeneratedVersion.java) is automatically generated with static methods to access the semantic version data. The source is based on a fully customizable [Mustache](https://mustache.github.io/) 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. @@ -165,7 +165,7 @@ example.meta= ### Maven -To install and run from [Maven](http://maven.apache.org/), configure an artifact as follows: +To install and run from [Maven](https://maven.apache.org/), configure an artifact as follows: ```xml @@ -200,11 +200,11 @@ compileJava.options.annotationProcessorGeneratedSourcesDirectory = file("${proje The `GeneratedVersion.java` file will now be located in `src/generated`. -Please look at the [build.gradle](https://github.com/ethauvin/semver/blob/master/examples/java/build.gradle) file in the [Java example](https://github.com/ethauvin/semver/tree/master/example/java) module directory for a sample. +Please look at the [build.gradle](https://github.com/ethauvin/semver/blob/master/examples/java/build.gradle) file in the [Java example](https://github.com/ethauvin/semver/tree/master/examples/java) module directory for a sample. ### Kobalt -To install and run from [Kobalt](http://beust.com/kobalt/), add the following to the `Build.kt` file: +To install and run from [Kobalt](https://beust.com/kobalt/), add the following to the `Build.kt` file: ```gradle dependencies { @@ -213,7 +213,7 @@ dependencies { } ``` -Please look at the [Build.kt](https://github.com/ethauvin/semver/blob/master/examples/kotlin/kobalt/src/Build.kt) file in the [Kotlin example](https://github.com/ethauvin/semver/tree/master/examples/kotlin) module directory for a sample. +Please look at the [Build.kt](https://github.com/ethauvin/semver/blob/master/examples/java/kobalt/src/Build.kt) file in the [Java example](https://github.com/ethauvin/semver/tree/master/examples/java) module directory for a sample. ### Kotlin @@ -230,7 +230,7 @@ open class Main { ``` The [Kotlin default template](https://github.com/ethauvin/semver/blob/master/src/main/resources/semver-kt.mustache) implements the same static fields and functions as the [Java template](#default-template). -Please look at the [Kotlin example](https://github.com/ethauvin/semver/tree/master/examples/kotlin) project for samples on using Gradle ([build.gradle.kts](https://github.com/ethauvin/semver/blob/master/examples/kotlin/build.gradle.kts)) and Kobalt ([Build.kt](https://github.com/ethauvin/semver/blob/master/examples/kotlin/kobalt/src/Build.kt)). +Please look at the [Kotlin example](https://github.com/ethauvin/semver/tree/master/examples/kotlin) project for samples on using Gradle ([build.gradle.kts](https://github.com/ethauvin/semver/blob/master/examples/kotlin/build.gradle.kts)) and Kobalt ([Build.kt](https://github.com/ethauvin/semver/blob/master/examples/java/kobalt/src/Build.kt)). ## Auto-Increment diff --git a/build.gradle b/build.gradle index 3edf25a..dd6d6fd 100644 --- a/build.gradle +++ b/build.gradle @@ -167,8 +167,9 @@ task release(dependsOn: ['wrapper', 'clean', 'publishToMavenLocal']) { task pandoc(type: Exec) { group = 'Documentation' - def pandoc_args = ['--from', 'markdown_github', + def pandoc_args = ['--from', 'gfm', '--to', 'html5', + '--metadata', "pagetitle=$mavenDescription", '-s', '-c', 'github-pandoc.css', '-o', 'docs/README.html', diff --git a/docs/README.html b/docs/README.html index 2d2e30e..1da1c8d 100644 --- a/docs/README.html +++ b/docs/README.html @@ -1,56 +1,87 @@ - + - - - - - - - + +

Semantic Version Annotation Processor

-

License (3-Clause BSD) release Maven Central Download
+

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

@@ -58,32 +89,32 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf -
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 = 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
+
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.

+

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 {
-// ...
+
@Version(template = "version.mustache")
+public class A {
+// ...

Default Template

The default template implements the following static fields:

@@ -138,12 +169,7 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf

And the following methods/functions:

- ----- +
@@ -166,20 +192,20 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
Method

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}}";
-}
+
/* 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:

@@ -238,7 +264,7 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf

Please also look at this example using java.time

-

Elements & Properties

+

Elements & Properties

The following annotation elements and properties are available:

@@ -325,68 +351,71 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf

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=
-# ...
+
@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.

+

⚠️ 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, 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.1.1</version>
-</dependency>
+
<dependency>
+    <groupId>net.thauvin.erik</groupId>
+    <artifactId>semver</artifactId>
+    <version>1.1.1</version>
+</dependency>

Gradle

Class Generation

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

dependencies {
     annotationProcessor 'net.thauvin.erik:semver:1.1.1'
     compileOnly 'net.thauvin.erik:semver:1.1.1'
-}
+} +

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

-

Class & Source Generation

+

Class & Source Generation

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

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

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

-

Please look at the build.gradle file in the Java example module directory for a sample.

+

Please look at the build.gradle file in the Java 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.1.1")
     compileOnly("net.thauvin.erik:semver:1.1.1")
-}
-

Please look at the Build.kt file in the Kotlin example module directory for a sample.

+} + +

Please look at the Build.kt file in the Java 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 {
-// ...
+
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 Kotlin example project for samples on using Gradle (build.gradle.kts) and Kobalt (Build.kt).

+

Please look at the Kotlin example project for samples on using Gradle (build.gradle.kts) 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 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.