<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
<head>
<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
<title>Semantic Version Annotation Processor</title>
<style>
code{white-space: pre-wrap;}
span.smallcaps{font-variant: small-caps;}
span.underline{text-decoration: underline;}
div.column{display: inline-block; vertical-align: top; width: 50%;}
</style>
<style>
a.sourceLine { display: inline-block; line-height: 1.25; }
a.sourceLine { pointer-events: none; color: inherit; text-decoration: inherit; }
a.sourceLine:empty { height: 1.2em; }
.sourceCode { overflow: visible; }
code.sourceCode { white-space: pre; position: relative; }
div.sourceCode { margin: 1em 0; }
pre.sourceCode { margin: 0; }
@media screen {
div.sourceCode { overflow: auto; }
}
@media print {
code.sourceCode { white-space: pre-wrap; }
a.sourceLine { text-indent: -1em; padding-left: 1em; }
}
pre.numberSource a.sourceLine
{ position: relative; left: -4em; }
pre.numberSource a.sourceLine::before
{ content: attr(title);
position: relative; left: -1em; text-align: right; vertical-align: baseline;
border: none; pointer-events: all; display: inline-block;
-webkit-touch-callout: none; -webkit-user-select: none;
-khtml-user-select: none; -moz-user-select: none;
-ms-user-select: none; user-select: none;
padding: 0 4px; width: 4em;
color: #aaaaaa;
}
pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; }
div.sourceCode
{ }
@media screen {
a.sourceLine::before { text-decoration: underline; }
}
code span.al { color: #ff0000; font-weight: bold; } /* Alert */
code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
code span.at { color: #7d9029; } /* Attribute */
code span.bn { color: #40a070; } /* BaseN */
code span.bu { } /* BuiltIn */
code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
code span.ch { color: #4070a0; } /* Char */
code span.cn { color: #880000; } /* Constant */
code span.co { color: #60a0b0; font-style: italic; } /* Comment */
code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
code span.do { color: #ba2121; font-style: italic; } /* Documentation */
code span.dt { color: #902000; } /* DataType */
code span.dv { color: #40a070; } /* DecVal */
code span.er { color: #ff0000; font-weight: bold; } /* Error */
code span.ex { } /* Extension */
code span.fl { color: #40a070; } /* Float */
code span.fu { color: #06287e; } /* Function */
code span.im { } /* Import */
code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
code span.kw { color: #007020; font-weight: bold; } /* Keyword */
code span.op { color: #666666; } /* Operator */
code span.ot { color: #007020; } /* Other */
code span.pp { color: #bc7a00; } /* Preprocessor */
code span.sc { color: #4070a0; } /* SpecialChar */
code span.ss { color: #bb6688; } /* SpecialString */
code span.st { color: #4070a0; } /* String */
code span.va { color: #19177c; } /* Variable */
code span.vs { color: #4070a0; } /* VerbatimString */
code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
</style>
<link rel="stylesheet" href="github-pandoc.css" />
<!--[if lt IE 9]>
<script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
<![endif]-->
</head>
<body>
<h1 id="semantic-version-annotation-processor">Semantic Version Annotation Processor</h1>
<p><a href="http://opensource.org/licenses/BSD-3-Clause"><img src="https://img.shields.io/badge/license-BSD%203--Clause-blue.svg?style=flat-square" alt="License (3-Clause BSD)" /></a> <a href="https://github.com/ethauvin/semver/releases/latest"><img src="https://img.shields.io/github/release/ethauvin/semver.svg" alt="release" /></a> <a href="https://maven-badges.herokuapp.com/maven-central/net.thauvin.erik/semver"><img src="https://maven-badges.herokuapp.com/maven-central/net.thauvin.erik/semver/badge.svg" alt="Maven Central" /></a> <a href="https://bintray.com/ethauvin/maven/SemVer/_latestVersion"> <img src="https://api.bintray.com/packages/ethauvin/maven/SemVer/images/download.svg" alt="Download" /> </a><br />
<a href="https://snyk.io/test/github/ethauvin/semver?targetFile=build.gradle"><img src="https://snyk.io/test/github/ethauvin/semver/badge.svg?targetFile=build.gradle" alt="Known Vulnerabilities" /></a> <a href="https://sonarcloud.io/dashboard?id=ethauvin_semver"><img src="https://sonarcloud.io/api/project_badges/measure?project=ethauvin_semver&metric=alert_status" alt="Quality Gate Status" /></a> <a href="https://travis-ci.org/ethauvin/semver"><img src="https://travis-ci.org/ethauvin/semver.svg?branch=master" alt="Build Status" /></a> <a href="https://ci.appveyor.com/project/ethauvin/semver"><img src="https://ci.appveyor.com/api/projects/status/nbv4mxd1gpxtx69o?svg=true" alt="Build status" /></a> <a href="https://circleci.com/gh/ethauvin/semver/tree/master"><img src="https://circleci.com/gh/ethauvin/semver/tree/master.svg?style=shield" alt="CircleCI" /></a></p>
<p>An <a href="https://docs.oracle.com/javase/8/docs/api/javax/annotation/processing/Processor.html">annotation processor</a> that automatically generates a <code>GeneratedVersion</code> class based on a <a href="https://mustache.github.io/">Mustache</a> template and containing the <a href="http://semver.org/">semantic version</a> (major, minor, patch, etc.) that is read from a <code>Properties</code> file or defined in the <a href="https://docs.oracle.com/javase/tutorial/java/annotations/basics.html">annotation</a>.</p>
<p>This processor was inspired by Cédric Beust's <a href="https://github.com/cbeust/version-processor">version-processor</a> and works well in conjunction with the <a href="https://github.com/ethauvin/semver-gradle"><strong>Semantic Version Plugin for Gradle</strong></a>.</p>
<h2 id="table-of-contents">Table of Contents</h2>
<ul>
<li><a href="#examples">Examples</a></li>
<li><a href="#template">Template</a>
<ul>
<li><a href="#default-template">Default Template</a></li>
<li><a href="#custom-template">Custom Template</a></li>
</ul></li>
<li><a href="#elements---properties">Elements & Properties</a></li>
<li><a href="#usage-with-maven--gradle--kotlin-and-kobalt">Usage with Maven, Gradle, Kotlin and Kobalt</a>
<ul>
<li><a href="#maven">Maven</a></li>
<li><a href="#gradle">Gradle</a>
<ul>
<li><a href="#class-generation">Class Generation</a></li>
<li><a href="#class---source-generation">Class & Source Generation</a></li>
</ul></li>
<li><a href="#kotlin">Kotlin</a>
<ul>
<li><a href="#kotlin---gradle">Kotlin & Gradle</a></li>
</ul></li>
<li><a href="#kobalt">Kobalt</a></li>
</ul></li>
<li><a href="#auto-increment">Auto-Increment</a></li>
</ul>
<h2 id="examples">Examples</h2>
<ul>
<li>Using annotation elements:</li>
</ul>
<div class="sourceCode" id="cb1"><pre class="sourceCode java"><code class="sourceCode java"><a class="sourceLine" id="cb1-1" title="1"><span class="kw">import</span><span class="im"> net.thauvin.erik.semver.Version;</span></a>
<a class="sourceLine" id="cb1-2" title="2"></a>
<a class="sourceLine" id="cb1-3" title="3"><span class="at">@Version</span>(major = <span class="dv">1</span>, minor = <span class="dv">0</span>, patch = <span class="dv">0</span>, preRelease = <span class="st">"beta"</span>)</a>
<a class="sourceLine" id="cb1-4" title="4"><span class="kw">public</span> <span class="kw">class</span> A {</a>
<a class="sourceLine" id="cb1-5" title="5"><span class="co">// ...</span></a></code></pre></div>
<ul>
<li>Or using a <a href="https://docs.oracle.com/javase/tutorial/essential/environment/properties.html">properties</a> file:</li>
</ul>
<div class="sourceCode" id="cb2"><pre class="sourceCode java"><code class="sourceCode java"><a class="sourceLine" id="cb2-1" title="1"><span class="kw">import</span><span class="im"> net.thauvin.erik.semver.Version;</span></a>
<a class="sourceLine" id="cb2-2" title="2"></a>
<a class="sourceLine" id="cb2-3" title="3"><span class="at">@Version</span>(properties = <span class="st">"version.properties"</span>)</a>
<a class="sourceLine" id="cb2-4" title="4"><span class="kw">public</span> <span class="kw">class</span> A {</a>
<a class="sourceLine" id="cb2-5" title="5"><span class="co">// ...</span></a></code></pre></div>
<div class="sourceCode" id="cb3"><pre class="sourceCode ini"><code class="sourceCode ini"><a class="sourceLine" id="cb3-1" title="1"><span class="co"># version.properties</span></a>
<a class="sourceLine" id="cb3-2" title="2"><span class="dt">version.major</span><span class="ot">=</span><span class="dv">1</span></a>
<a class="sourceLine" id="cb3-3" title="3"><span class="dt">version.minor</span><span class="ot">=</span><span class="dv">0</span></a>
<a class="sourceLine" id="cb3-4" title="4"><span class="dt">version.patch</span><span class="ot">=</span><span class="dv">0</span></a>
<a class="sourceLine" id="cb3-5" title="5"><span class="dt">version.prerelease</span><span class="ot">=</span><span class="st">beta</span></a></code></pre></div>
<p><a href="https://github.com/ethauvin/semver/tree/master/examples">View Example</a></p>
<h2 id="template">Template</h2>
<p>Upon running the annotation processor, a source file <a href="https://github.com/ethauvin/semver/blob/master/examples/java/src/generated/java/com/example/GeneratedVersion.java"><code>GeneratedVersion.java</code></a> is automatically generated with static methods to access the semantic version data. The source is based on a fully customizable <a href="https://mustache.github.io/">Mustache</a> template.</p>
<p>To use your own template, simply create a <code>version.mustache</code> file in the project's root directory. The processor will automatically look for it.</p>
<p>To specify your own template name, use:</p>
<div class="sourceCode" id="cb4"><pre class="sourceCode java"><code class="sourceCode java"><a class="sourceLine" id="cb4-1" title="1"><span class="at">@Version</span>(template = <span class="st">"version.mustache"</span>)</a>
<a class="sourceLine" id="cb4-2" title="2"><span class="kw">public</span> <span class="kw">class</span> A {</a>
<a class="sourceLine" id="cb4-3" title="3"><span class="co">// ...</span></a></code></pre></div>
<h3 id="default-template">Default Template</h3>
<p>The <a href="https://github.com/ethauvin/semver/blob/master/src/main/resources/semver.mustache">default template</a> implements the following static variables:</p>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Field</th>
<th style="text-align: left;">Description</th>
<th style="text-align: left;">Example</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;"><code>PROJECT</code></td>
<td style="text-align: left;">The project name, if any.</td>
<td style="text-align: left;"><code>MyProject</code></td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>BUILDDATE</code></td>
<td style="text-align: left;">The build date.</td>
<td style="text-align: left;"><a href="https://docs.oracle.com/javase/8/docs/api/java/util/Date.html"><code>java.util.Date</code></a></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>VERSION</code></td>
<td style="text-align: left;">The full version string.</td>
<td style="text-align: left;"><code>1.2.3-alpha+001</code></td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>MAJOR</code></td>
<td style="text-align: left;">The major version.</td>
<td style="text-align: left;"><code>1</code></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>MINOR</code></td>
<td style="text-align: left;">The minor version.</td>
<td style="text-align: left;"><code>2</code></td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>PATCH</code></td>
<td style="text-align: left;">The patch version.</td>
<td style="text-align: left;"><code>3</code></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>PRERELEASE</code></td>
<td style="text-align: left;">The pre-release version, if any.</td>
<td style="text-align: left;"><code>alpha</code></td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>PRERELASE_PREFIX</code></td>
<td style="text-align: left;">The pre-release prefix</td>
<td style="text-align: left;"><code>-</code></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>BUILDMETA</code></td>
<td style="text-align: left;">The build metadata, if any.</td>
<td style="text-align: left;"><code>001</code></td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>BUILDMETA_PREFIX</code></td>
<td style="text-align: left;">The metadata prefix.</td>
<td style="text-align: left;"><code>+</code></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>SEPARATOR</code></td>
<td style="text-align: left;">The version separator.</td>
<td style="text-align: left;"><code>.</code></td>
</tr>
</tbody>
</table>
<h3 id="custom-template">Custom Template</h3>
<p>A very simple custom template might look something like:</p>
<div class="sourceCode" id="cb5"><pre class="sourceCode java"><code class="sourceCode java"><a class="sourceLine" id="cb5-1" title="1"><span class="co">/* version.mustache */</span></a>
<a class="sourceLine" id="cb5-2" title="2"><span class="kw">package</span><span class="im"> {{packageName}};</span></a>
<a class="sourceLine" id="cb5-3" title="3"></a>
<a class="sourceLine" id="cb5-4" title="4"><span class="kw">import</span><span class="im"> java.util.Date;</span></a>
<a class="sourceLine" id="cb5-5" title="5"></a>
<a class="sourceLine" id="cb5-6" title="6"><span class="kw">public</span> <span class="dt">final</span> <span class="kw">class</span> {{className}} {</a>
<a class="sourceLine" id="cb5-7" title="7"> <span class="kw">public</span> <span class="dt">final</span> <span class="dt">static</span> <span class="bu">String</span> PROJECT = <span class="st">"{{project}}"</span>;</a>
<a class="sourceLine" id="cb5-8" title="8"> <span class="kw">public</span> <span class="dt">final</span> <span class="dt">static</span> <span class="bu">Date</span> DATE = <span class="kw">new</span> <span class="bu">Date</span>({{epoch}}L);</a>
<a class="sourceLine" id="cb5-9" title="9"> <span class="kw">public</span> <span class="dt">final</span> <span class="dt">static</span> <span class="bu">String</span> VERSION = <span class="st">"{{semver}}"</span>;</a>
<a class="sourceLine" id="cb5-10" title="10">}</a></code></pre></div>
<p>The mustache variables automatically filled in by the processor are:</p>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Variable</th>
<th style="text-align: left;">Description</th>
<th style="text-align: left;">Type</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;"><code>{{packageName}}</code></td>
<td style="text-align: left;">The package name.</td>
<td style="text-align: left;"><code>String</code></td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>{{className}}</code></td>
<td style="text-align: left;">The class name.</td>
<td style="text-align: left;"><code>String</code></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>{{project}}</code></td>
<td style="text-align: left;">The project name.</td>
<td style="text-align: left;"><code>String</code></td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>{{epoch}}</code></td>
<td style="text-align: left;">The build epoch/unix time.</td>
<td style="text-align: left;"><code>long</code></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>{{major}}</code></td>
<td style="text-align: left;">The major version.</td>
<td style="text-align: left;"><code>int</code></td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>{{minor}}</code></td>
<td style="text-align: left;">The minor version.</td>
<td style="text-align: left;"><code>int</code></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>{{patch}}</code></td>
<td style="text-align: left;">The patch version.</td>
<td style="text-align: left;"><code>int</code></td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>{{preRelease}}</code></td>
<td style="text-align: left;">The pre-release version.</td>
<td style="text-align: left;"><code>String</code></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>{{preReleasePrefix}}</code></td>
<td style="text-align: left;">The pre-release prefix.</td>
<td style="text-align: left;"><code>String</code></td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>{{buildMeta}}</code></td>
<td style="text-align: left;">The build metadata version.</td>
<td style="text-align: left;"><code>String</code></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>{{buildMetaPrefix}}</code></td>
<td style="text-align: left;">The metadata prefix.</td>
<td style="text-align: left;"><code>String</code></td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>{{separator}}</code></td>
<td style="text-align: left;">The version separator.</td>
<td style="text-align: left;"><code>String</code></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>{{semver}}</code> or <code>{{version}}</code></td>
<td style="text-align: left;">The full semantic version.</td>
<td style="text-align: left;"><code>String</code></td>
</tr>
</tbody>
</table>
<p>Please also look at this <a href="https://github.com/ethauvin/mobibot/blob/master/version.mustache">example</a> using <a href="https://docs.oracle.com/javase/8/docs/api/java/time/package-summary.html"><code>java.time</code></a></p>
<h2 id="elements--properties">Elements & Properties</h2>
<p>The following annotation elements and properties are available:</p>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Element</th>
<th style="text-align: left;">Property</th>
<th style="text-align: left;">Description</th>
<th style="text-align: left;">Default</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;"><code>project</code></td>
<td style="text-align: left;"><code>version.project</code></td>
<td style="text-align: left;">The project name.</td>
<td style="text-align: left;"></td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>major</code></td>
<td style="text-align: left;"><code>version.major</code></td>
<td style="text-align: left;">The major version number.</td>
<td style="text-align: left;"><code>1</code></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>minor</code></td>
<td style="text-align: left;"><code>version.major</code></td>
<td style="text-align: left;">The minor version number.</td>
<td style="text-align: left;"><code>0</code></td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>patch</code></td>
<td style="text-align: left;"><code>version.patch</code></td>
<td style="text-align: left;">The patch version number.</td>
<td style="text-align: left;"><code>0</code></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>preRelease</code></td>
<td style="text-align: left;"><code>version.prerelease</code></td>
<td style="text-align: left;">The pre-release version.</td>
<td style="text-align: left;"></td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>preReleasePrefix</code></td>
<td style="text-align: left;"><code>version.prerelease.prefix</code></td>
<td style="text-align: left;">The pre-release prefix.</td>
<td style="text-align: left;"><code>-</code></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>buildMeta</code></td>
<td style="text-align: left;"><code>version.buildmeta</code></td>
<td style="text-align: left;">The build metadata version.</td>
<td style="text-align: left;"></td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>buildMetaPrefix</code></td>
<td style="text-align: left;"><code>version.buildmeta.prefix</code></td>
<td style="text-align: left;">The metadata prefix.</td>
<td style="text-align: left;"><code>+</code></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>separator</code></td>
<td style="text-align: left;"><code>version.separator</code></td>
<td style="text-align: left;">The version separator.</td>
<td style="text-align: left;"><code>.</code></td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>packageName</code></td>
<td style="text-align: left;"></td>
<td style="text-align: left;">The package name.</td>
<td style="text-align: left;"><em>Same as annotated class</em></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>className</code></td>
<td style="text-align: left;"></td>
<td style="text-align: left;">The name of the generated class.</td>
<td style="text-align: left;"><code>GeneratedVersion</code></td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>properties</code></td>
<td style="text-align: left;"></td>
<td style="text-align: left;">The properties file.</td>
<td style="text-align: left;"></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>template</code></td>
<td style="text-align: left;"></td>
<td style="text-align: left;">The template file.</td>
<td style="text-align: left;"><code>version.mustache</code></td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>type</code></td>
<td style="text-align: left;"></td>
<td style="text-align: left;">Either <code>java</code> or <code>kt</code> for Kotlin.</td>
<td style="text-align: left;"><code>java</code></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>keysPrefix</code></td>
<td style="text-align: left;"></td>
<td style="text-align: left;">The prefix for all property keys.</td>
<td style="text-align: left;"><code>version.</code></td>
</tr>
</tbody>
</table>
<p>In order to easily incorporate with existing projects, the property keys may be assigned custom values:</p>
<div class="sourceCode" id="cb6"><pre class="sourceCode java"><code class="sourceCode java"><a class="sourceLine" id="cb6-1" title="1"><span class="at">@Version</span>(</a>
<a class="sourceLine" id="cb6-2" title="2"> properties = <span class="st">"example.properties"</span>,</a>
<a class="sourceLine" id="cb6-3" title="3"> keysPrefix = <span class="st">"example."</span></a>
<a class="sourceLine" id="cb6-4" title="4"> majorKey = <span class="st">"maj"</span>,</a>
<a class="sourceLine" id="cb6-5" title="5"> minorKey = <span class="st">"min"</span>,</a>
<a class="sourceLine" id="cb6-6" title="6"> patchKey = <span class="st">"build"</span>,</a>
<a class="sourceLine" id="cb6-7" title="7"> preReleaseKey = <span class="st">"rel"</span>,</a>
<a class="sourceLine" id="cb6-8" title="8"> buildMetaKey = <span class="st">"meta"</span>,</a>
<a class="sourceLine" id="cb6-9" title="9"> projectKey = <span class="st">"project"</span></a>
<a class="sourceLine" id="cb6-10" title="10">)</a>
<a class="sourceLine" id="cb6-11" title="11"><span class="kw">public</span> <span class="kw">class</span> Example {</a>
<a class="sourceLine" id="cb6-12" title="12"><span class="co">// ...</span></a></code></pre></div>
<div class="sourceCode" id="cb7"><pre class="sourceCode ini"><code class="sourceCode ini"><a class="sourceLine" id="cb7-1" title="1"><span class="co"># example.properties</span></a>
<a class="sourceLine" id="cb7-2" title="2"><span class="dt">example.project</span><span class="ot">=</span><span class="st">Example</span></a>
<a class="sourceLine" id="cb7-3" title="3"><span class="dt">example.maj</span><span class="ot">=</span><span class="dv">1</span></a>
<a class="sourceLine" id="cb7-4" title="4"><span class="dt">example.min</span><span class="ot">=</span><span class="dv">0</span></a>
<a class="sourceLine" id="cb7-5" title="5"><span class="dt">example.build</span><span class="ot">=</span><span class="dv">0</span></a>
<a class="sourceLine" id="cb7-6" title="6"><span class="dt">example.rel</span><span class="ot">=</span><span class="st">beta</span></a>
<a class="sourceLine" id="cb7-7" title="7"><span class="dt">example.meta</span><span class="ot">=</span></a>
<a class="sourceLine" id="cb7-8" title="8"><span class="co"># ...</span></a></code></pre></div>
<blockquote>
<p><span class="emoji" data-emoji="warning">⚠️</span> <code>keysPrefix</code> is a new element staring in <code>1.1.0</code> and may break older versions when using custom property keys.<br />
<span class="emoji" data-emoji="zap">⚡</span> A quick fix is to include <code>keysPrefix=""</code> in the annotation to remove the default <code>version.</code> prefix.</p>
</blockquote>
<h2 id="usage-with-maven-gradle-kotlin-and-kobalt">Usage with Maven, Gradle, Kotlin and Kobalt</h2>
<h3 id="maven">Maven</h3>
<p>To install and run from <a href="https://maven.apache.org/">Maven</a>, configure an artifact as follows:</p>
<div class="sourceCode" id="cb8"><pre class="sourceCode xml"><code class="sourceCode xml"><a class="sourceLine" id="cb8-1" title="1"><span class="kw"><dependency></span></a>
<a class="sourceLine" id="cb8-2" title="2"> <span class="kw"><groupId></span>net.thauvin.erik<span class="kw"></groupId></span></a>
<a class="sourceLine" id="cb8-3" title="3"> <span class="kw"><artifactId></span>semver<span class="kw"></artifactId></span></a>
<a class="sourceLine" id="cb8-4" title="4"> <span class="kw"><version></span>1.2.0<span class="kw"></version></span></a>
<a class="sourceLine" id="cb8-5" title="5"><span class="kw"></dependency></span></a></code></pre></div>
<p>Please look at <a href="https://github.com/ethauvin/semver/blob/master/examples/java/pom.xml">pom.xml</a> in the <a href="https://github.com/ethauvin/semver/tree/master/examples/java">Java example</a> directory for a sample:</p>
<div class="sourceCode" id="cb9"><pre class="sourceCode bash"><code class="sourceCode bash"><a class="sourceLine" id="cb9-1" title="1"><span class="ex">mvn</span> compile exec:java</a></code></pre></div>
<h3 id="gradle">Gradle</h3>
<h4 id="class-generation">Class Generation</h4>
<p>To install and run from <a href="https://gradle.org/">Gradle</a>, add the following to <code>build.gradle</code>:</p>
<pre class="gradle"><code>dependencies {
annotationProcessor 'net.thauvin.erik:semver:1.2.0'
compileOnly 'net.thauvin.erik:semver:1.2.0'
}
</code></pre>
<p>The <code>GeneratedVersion</code> class will be automatically created in the <code>build/generated</code> directory upon compiling.</p>
<h4 id="class--source-generation">Class & Source Generation</h4>
<p>In order to also incorporate the generated source code into the <code>source tree</code>, add the following to the very top of <code>build.gradle</code>:</p>
<pre class="gradle"><code>compileJava.options.annotationProcessorGeneratedSourcesDirectory = file("${projectDir}/src/generated/java")
</code></pre>
<p>The <code>GeneratedVersion.java</code> file will now be located in <code>src/generated</code>.</p>
<p>Please look at <a href="https://github.com/ethauvin/semver/blob/master/examples/java/build.gradle">build.gradle</a> in the <a href="https://github.com/ethauvin/semver/tree/master/examples/java">Java example</a> directory for a sample.</p>
<h3 id="kotlin">Kotlin</h3>
<p>The annotation processor also supports <a href="https://kotlinlang.org/">Kotlin</a>.</p>
<p>To generate a Kotlin version file, simply specify the <code>type</code> as follows:</p>
<div class="sourceCode" id="cb12"><pre class="sourceCode kotlin"><code class="sourceCode kotlin"><a class="sourceLine" id="cb12-1" title="1"><span class="kw">import</span> <span class="im">net.thauvin.erik.semver.Version</span></a>
<a class="sourceLine" id="cb12-2" title="2"></a>
<a class="sourceLine" id="cb12-3" title="3"><span class="at">@Version</span>(properties = <span class="st">"version.properties"</span>, type=<span class="st">"kt"</span>)</a>
<a class="sourceLine" id="cb12-4" title="4"><span class="kw">open</span> <span class="kw">class</span> Main {</a>
<a class="sourceLine" id="cb12-5" title="5"><span class="co">// ...</span></a></code></pre></div>
<p>The <a href="https://github.com/ethauvin/semver/blob/master/src/main/resources/semver-kt.mustache">Kotlin default template</a> implements the same static fields and functions as the <a href="#default-template">Java template</a>.</p>
<h4 id="kotlin--gradle">Kotlin & Gradle</h4>
<p>To install and run from <a href="https://gradle.org/">Gradle</a>, add the following to <code>build.gradle.kts</code>:</p>
<div class="sourceCode" id="cb13"><pre class="sourceCode kotlin"><code class="sourceCode kotlin"><a class="sourceLine" id="cb13-1" title="1"><span class="kw">var</span> <span class="va">semverProcessor</span> = <span class="st">"net.thauvin.erik:semver:1.2.0"</span></a>
<a class="sourceLine" id="cb13-2" title="2"></a>
<a class="sourceLine" id="cb13-3" title="3">dependencies {</a>
<a class="sourceLine" id="cb13-4" title="4"> kapt(semverProcessor)</a>
<a class="sourceLine" id="cb13-5" title="5"> compileOnly(semverProcessor)</a>
<a class="sourceLine" id="cb13-6" title="6">}</a></code></pre></div>
<p>As of <a href="https://blog.jetbrains.com/kotlin/2019/04/kotlin-1-3-30-released/#more-6991">Kotlin 1.2.30</a>, when using <code>kapt</code> you must include the following in <code>gradle.properties</code>:</p>
<div class="sourceCode" id="cb14"><pre class="sourceCode ini"><code class="sourceCode ini"><a class="sourceLine" id="cb14-1" title="1"><span class="dt">kapt.use.worker.api</span><span class="ot">=</span><span class="kw">true</span></a></code></pre></div>
<p>This option will likely be enabled by default in the future, but is currently not working under Java 10/11 see <a href="https://youtrack.jetbrains.net/issue/KT-26203">KT-26203</a>.</p>
<p>Please look at the <a href="https://github.com/ethauvin/semver/tree/master/examples/kotlin">Kotlin example</a> project for a <a href="https://github.com/ethauvin/semver/blob/master/examples/kotlin/build.gradle.kts">build.gradle.kts</a> sample.</p>
<h3 id="kobalt">Kobalt</h3>
<p>To install and run from <a href="https://beust.com/kobalt/">Kobalt</a>, add the following to <code>Build.kt</code>:</p>
<pre class="gradle"><code>dependencies {
apt("net.thauvin.erik:semver:1.2.0")
compileOnly("net.thauvin.erik:semver:1.2.0")
}
</code></pre>
<p>Please look at <a href="https://github.com/ethauvin/semver/blob/master/examples/java/kobalt/src/Build.kt">Build.kt</a> in the <a href="https://github.com/ethauvin/semver/tree/master/examples/java">Java example</a> directory for a sample.</p>
<h2 id="auto-increment">Auto-Increment</h2>
<p>Incrementing the version is best left to your favorite build system. For a solution using Gradle, please have a look at the <a href="https://github.com/ethauvin/semver-gradle"><strong>Semver Version Plugin for Gradle</strong></a>.</p>
<p>There are also full <a href="https://github.com/ethauvin/semver-gradle/tree/master/examples/annotation-processor">examples</a> in both <a href="https://github.com/ethauvin/semver-gradle/tree/master/examples/annotation-processor/java">Java</a> and <a href="https://github.com/ethauvin/semver-gradle/tree/master/examples/annotation-processor/kotlin">Kotlin</a> showing how to use both the plugin and annotation processor concurrently.</p>
</body>
</html>
