erik/semver
erik/semver
1
1
Fork 0
Code Issues Pull requests Releases Activity
semver/docs/README.html
Erik C. Thauvin 24b047ae1b Version 1.2.1
2023-10-01 20:26:21 -07:00

647 lines
41 KiB
HTML
Raw Blame History

<!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;}
div.columns{display: flex; gap: min(4vw, 1.5em);}
div.column{flex: auto; overflow-x: auto;}
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
ul.task-list{list-style: none;}
ul.task-list li input[type="checkbox"] {
width: 0.8em;
margin: 0 0.8em 0.2em -1.6em;
vertical-align: middle;
}
.display.math{display: block; text-align: center; margin: 0.5rem auto;}
/* CSS for syntax highlighting */
pre > code.sourceCode { white-space: pre; position: relative; }
pre > code.sourceCode > span { line-height: 1.25; }
pre > code.sourceCode > span:empty { height: 1.2em; }
.sourceCode { overflow: visible; }
code.sourceCode > span { color: inherit; text-decoration: inherit; }
div.sourceCode { margin: 1em 0; }
pre.sourceCode { margin: 0; }
@media screen {
div.sourceCode { overflow: auto; }
}
@media print {
pre > code.sourceCode { white-space: pre-wrap; }
pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
}
pre.numberSource code
{ counter-reset: source-line 0; }
pre.numberSource code > span
{ position: relative; left: -4em; counter-increment: source-line; }
pre.numberSource code > span > a:first-child::before
{ content: counter(source-line);
position: relative; left: -1em; text-align: right; vertical-align: baseline;
border: none; 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 {
pre > code.sourceCode > span > a:first-child::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 { color: #008000; } /* 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 { color: #008000; font-weight: bold; } /* 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="docs/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="https://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://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html"><img
src="https://img.shields.io/badge/java-17%2B-blue" alt="Java" /></a> <a
href="https://rife2.com/bld"><img
src="https://img.shields.io/badge/1.7.2-FA9052?label=bld&amp;labelColor=2392FF"
alt="bld" /></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://oss.sonatype.org/content/repositories/snapshots/net/thauvin/erik/semver/"><img
src="https://img.shields.io/nexus/s/net.thauvin.erik/semver?label=snapshot&amp;server=https%3A%2F%2Foss.sonatype.org%2F"
alt="Nexus Snapshot" /></a> <a
href="https://central.sonatype.com/artifact/net.thauvin.erik/semver"><img
src="https://img.shields.io/maven-central/v/net.thauvin.erik/semver.svg"
alt="Maven Central" /></a></p>
<p><a href="https://sonarcloud.io/dashboard?id=ethauvin_semver"><img
src="https://sonarcloud.io/api/project_badges/measure?project=ethauvin_semver&amp;metric=alert_status"
alt="Quality Gate Status" /></a> <a
href="https://github.com/ethauvin/semver/actions/workflows/gradle.yml"><img
src="https://github.com/ethauvin/semver/actions/workflows/gradle.yml/badge.svg"
alt="GitHub CI" /></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="https://semver.org/">semantic version</a> (major, minor,
patch, etc.) that is read from a <a
href="https://docs.oracle.com/javase/tutorial/essential/environment/properties.html">Properties</a>
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 &amp; Properties</a></li>
<li><a href="#maven">Maven</a></li>
<li><a href="#bld">bld</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 &amp; Source
Generation</a></li>
</ul></li>
<li><a href="#kotlin">Kotlin</a>
<ul>
<li><a href="#kotlin--gradle">Kotlin &amp; Gradle</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"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="kw">import</span> <span class="im">net</span><span class="op">.</span><span class="im">thauvin</span><span class="op">.</span><span class="im">erik</span><span class="op">.</span><span class="im">semver</span><span class="op">.</span><span class="im">Version</span><span class="op">;</span></span>
<span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb1-3"><a href="#cb1-3" aria-hidden="true" tabindex="-1"></a><span class="at">@Version</span><span class="op">(</span>major <span class="op">=</span> <span class="dv">2</span><span class="op">,</span> minor <span class="op">=</span> <span class="dv">1</span><span class="op">,</span> patch <span class="op">=</span> <span class="dv">1</span><span class="op">,</span> preRelease <span class="op">=</span> <span class="st">&quot;beta&quot;</span><span class="op">)</span></span>
<span id="cb1-4"><a href="#cb1-4" aria-hidden="true" tabindex="-1"></a><span class="kw">public</span> <span class="kw">class</span> A <span class="op">{</span></span>
<span id="cb1-5"><a href="#cb1-5" aria-hidden="true" tabindex="-1"></a> <span class="co">// ...</span></span>
<span id="cb1-6"><a href="#cb1-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code></pre></div>
<ul>
<li>Or using a <a
href="hhttps://github.com/ethauvin/semver/blob/master/examples/java/version.properties">properties</a>
file:</li>
</ul>
<div class="sourceCode" id="cb2"><pre
class="sourceCode java"><code class="sourceCode java"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="kw">import</span> <span class="im">net</span><span class="op">.</span><span class="im">thauvin</span><span class="op">.</span><span class="im">erik</span><span class="op">.</span><span class="im">semver</span><span class="op">.</span><span class="im">Version</span><span class="op">;</span></span>
<span id="cb2-2"><a href="#cb2-2" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb2-3"><a href="#cb2-3" aria-hidden="true" tabindex="-1"></a><span class="at">@Version</span><span class="op">(</span>properties <span class="op">=</span> <span class="st">&quot;version.properties&quot;</span><span class="op">)</span></span>
<span id="cb2-4"><a href="#cb2-4" aria-hidden="true" tabindex="-1"></a><span class="kw">public</span> <span class="kw">class</span> A <span class="op">{</span></span>
<span id="cb2-5"><a href="#cb2-5" aria-hidden="true" tabindex="-1"></a> <span class="co">// ...</span></span>
<span id="cb2-6"><a href="#cb2-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code></pre></div>
<div class="sourceCode" id="cb3"><pre
class="sourceCode ini"><code class="sourceCode ini"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a><span class="co"># version.properties</span></span>
<span id="cb3-2"><a href="#cb3-2" aria-hidden="true" tabindex="-1"></a><span class="dt">version.major</span><span class="ot">=</span><span class="dv">1</span></span>
<span id="cb3-3"><a href="#cb3-3" aria-hidden="true" tabindex="-1"></a><span class="dt">version.minor</span><span class="ot">=</span><span class="dv">0</span></span>
<span id="cb3-4"><a href="#cb3-4" aria-hidden="true" tabindex="-1"></a><span class="dt">version.patch</span><span class="ot">=</span><span class="dv">0</span></span>
<span id="cb3-5"><a href="#cb3-5" aria-hidden="true" tabindex="-1"></a><span class="dt">version.prerelease</span><span class="ot">=</span><span class="st">beta</span></span></code></pre></div>
<p><a
href="https://github.com/ethauvin/semver/tree/master/examples">View
Examples</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">GeneratedVersion.java</a>
is automatically generated with static methods to access the semantic
version data. The source is based on a fully customizable Mustache <a
href="https://github.com/ethauvin/semver/blob/master/src/main/resources/semver.mustache">template</a>.</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"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a><span class="at">@Version</span><span class="op">(</span>template <span class="op">=</span> <span class="st">&quot;version.mustache&quot;</span><span class="op">)</span></span>
<span id="cb4-2"><a href="#cb4-2" aria-hidden="true" tabindex="-1"></a><span class="kw">public</span> <span class="kw">class</span> A <span class="op">{</span></span>
<span id="cb4-3"><a href="#cb4-3" aria-hidden="true" tabindex="-1"></a> <span class="co">// ...</span></span>
<span id="cb4-4"><a href="#cb4-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></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"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="co">/* version.mustache */</span></span>
<span id="cb5-2"><a href="#cb5-2" aria-hidden="true" tabindex="-1"></a><span class="kw">package</span><span class="im"> {{packageName}}</span><span class="op">;</span></span>
<span id="cb5-3"><a href="#cb5-3" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb5-4"><a href="#cb5-4" aria-hidden="true" tabindex="-1"></a><span class="kw">import</span> <span class="im">java</span><span class="op">.</span><span class="im">util</span><span class="op">.</span><span class="im">Date</span><span class="op">;</span></span>
<span id="cb5-5"><a href="#cb5-5" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb5-6"><a href="#cb5-6" aria-hidden="true" tabindex="-1"></a><span class="kw">public</span> <span class="dt">final</span> <span class="kw">class</span> <span class="op">{{</span>className<span class="op">}}</span> <span class="op">{</span></span>
<span id="cb5-7"><a href="#cb5-7" aria-hidden="true" tabindex="-1"></a> <span class="kw">public</span> <span class="dt">final</span> <span class="dt">static</span> <span class="bu">String</span> PROJECT <span class="op">=</span> <span class="st">&quot;{{project}}&quot;</span><span class="op">;</span></span>
<span id="cb5-8"><a href="#cb5-8" aria-hidden="true" tabindex="-1"></a> <span class="kw">public</span> <span class="dt">final</span> <span class="dt">static</span> <span class="bu">Date</span> DATE <span class="op">=</span> <span class="kw">new</span> <span class="bu">Date</span><span class="op">({{</span>epoch<span class="op">}}</span>L<span class="op">);</span></span>
<span id="cb5-9"><a href="#cb5-9" aria-hidden="true" tabindex="-1"></a> <span class="kw">public</span> <span class="dt">final</span> <span class="dt">static</span> <span class="bu">String</span> VERSION <span class="op">=</span> <span class="st">&quot;{{semver}}&quot;</span><span class="op">;</span></span>
<span id="cb5-10"><a href="#cb5-10" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></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 &amp; 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"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="at">@Version</span><span class="op">(</span></span>
<span id="cb6-2"><a href="#cb6-2" aria-hidden="true" tabindex="-1"></a> properties <span class="op">=</span> <span class="st">&quot;example.properties&quot;</span><span class="op">,</span></span>
<span id="cb6-3"><a href="#cb6-3" aria-hidden="true" tabindex="-1"></a> keysPrefix <span class="op">=</span> <span class="st">&quot;example.&quot;</span><span class="op">,</span></span>
<span id="cb6-4"><a href="#cb6-4" aria-hidden="true" tabindex="-1"></a> majorKey <span class="op">=</span> <span class="st">&quot;maj&quot;</span><span class="op">,</span></span>
<span id="cb6-5"><a href="#cb6-5" aria-hidden="true" tabindex="-1"></a> minorKey <span class="op">=</span> <span class="st">&quot;min&quot;</span><span class="op">,</span></span>
<span id="cb6-6"><a href="#cb6-6" aria-hidden="true" tabindex="-1"></a> patchKey <span class="op">=</span> <span class="st">&quot;build&quot;</span><span class="op">,</span></span>
<span id="cb6-7"><a href="#cb6-7" aria-hidden="true" tabindex="-1"></a> preReleaseKey <span class="op">=</span> <span class="st">&quot;rel&quot;</span><span class="op">,</span></span>
<span id="cb6-8"><a href="#cb6-8" aria-hidden="true" tabindex="-1"></a> buildMetaKey <span class="op">=</span> <span class="st">&quot;meta&quot;</span><span class="op">,</span></span>
<span id="cb6-9"><a href="#cb6-9" aria-hidden="true" tabindex="-1"></a> projectKey <span class="op">=</span> <span class="st">&quot;project&quot;</span></span>
<span id="cb6-10"><a href="#cb6-10" aria-hidden="true" tabindex="-1"></a><span class="op">)</span></span>
<span id="cb6-11"><a href="#cb6-11" aria-hidden="true" tabindex="-1"></a><span class="kw">public</span> <span class="kw">class</span> Example <span class="op">{</span></span>
<span id="cb6-12"><a href="#cb6-12" aria-hidden="true" tabindex="-1"></a> <span class="co">// ...</span></span>
<span id="cb6-13"><a href="#cb6-13" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code></pre></div>
<div class="sourceCode" id="cb7"><pre
class="sourceCode ini"><code class="sourceCode ini"><span id="cb7-1"><a href="#cb7-1" aria-hidden="true" tabindex="-1"></a><span class="co"># example.properties</span></span>
<span id="cb7-2"><a href="#cb7-2" aria-hidden="true" tabindex="-1"></a><span class="dt">example.project</span><span class="ot">=</span><span class="st">Example</span></span>
<span id="cb7-3"><a href="#cb7-3" aria-hidden="true" tabindex="-1"></a><span class="dt">example.maj</span><span class="ot">=</span><span class="dv">1</span></span>
<span id="cb7-4"><a href="#cb7-4" aria-hidden="true" tabindex="-1"></a><span class="dt">example.min</span><span class="ot">=</span><span class="dv">0</span></span>
<span id="cb7-5"><a href="#cb7-5" aria-hidden="true" tabindex="-1"></a><span class="dt">example.build</span><span class="ot">=</span><span class="dv">0</span></span>
<span id="cb7-6"><a href="#cb7-6" aria-hidden="true" tabindex="-1"></a><span class="dt">example.rel</span><span class="ot">=</span><span class="st">beta</span></span>
<span id="cb7-7"><a href="#cb7-7" aria-hidden="true" tabindex="-1"></a><span class="dt">example.meta</span><span class="ot">=</span></span>
<span id="cb7-8"><a href="#cb7-8" aria-hidden="true" tabindex="-1"></a><span class="co"># ...</span></span></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="maven">Maven</h2>
<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"><span id="cb8-1"><a href="#cb8-1" aria-hidden="true" tabindex="-1"></a>&lt;<span class="kw">dependency</span>&gt;</span>
<span id="cb8-2"><a href="#cb8-2" aria-hidden="true" tabindex="-1"></a> &lt;<span class="kw">groupId</span>&gt;net.thauvin.erik&lt;/<span class="kw">groupId</span>&gt;</span>
<span id="cb8-3"><a href="#cb8-3" aria-hidden="true" tabindex="-1"></a> &lt;<span class="kw">artifactId</span>&gt;semver&lt;/<span class="kw">artifactId</span>&gt;</span>
<span id="cb8-4"><a href="#cb8-4" aria-hidden="true" tabindex="-1"></a> &lt;<span class="kw">version</span>&gt;1.2.1&lt;/<span class="kw">version</span>&gt;</span>
<span id="cb8-5"><a href="#cb8-5" aria-hidden="true" tabindex="-1"></a>&lt;/<span class="kw">dependency</span>&gt;</span></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">examples/java</a>
directory for a sample:</p>
<div class="sourceCode" id="cb9"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb9-1"><a href="#cb9-1" aria-hidden="true" tabindex="-1"></a><span class="ex">mvn</span> verify</span></code></pre></div>
<h2 id="bld">bld</h2>
<p>To install and run from <a href="https://rife2.com/bld">bld</a>, just
add the dependency to your build file:</p>
<div class="sourceCode" id="cb10"><pre
class="sourceCode java"><code class="sourceCode java"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a><span class="kw">public</span> <span class="kw">class</span> ExampleBuild <span class="kw">extends</span> Project <span class="op">{</span></span>
<span id="cb10-2"><a href="#cb10-2" aria-hidden="true" tabindex="-1"></a> <span class="kw">public</span> <span class="fu">ExampleBuild</span><span class="op">()</span> <span class="op">{</span></span>
<span id="cb10-3"><a href="#cb10-3" aria-hidden="true" tabindex="-1"></a> <span class="co">// ...</span></span>
<span id="cb10-4"><a href="#cb10-4" aria-hidden="true" tabindex="-1"></a> <span class="fu">scope</span><span class="op">(</span>compile<span class="op">)</span></span>
<span id="cb10-5"><a href="#cb10-5" aria-hidden="true" tabindex="-1"></a> <span class="op">.</span><span class="fu">include</span><span class="op">(</span><span class="fu">dependency</span><span class="op">(</span><span class="st">&quot;net.thauvin.erik&quot;</span><span class="op">,</span> <span class="st">&quot;semver&quot;</span><span class="op">,</span> <span class="fu">version</span><span class="op">(</span><span class="dv">1</span><span class="op">,</span> <span class="dv">2</span><span class="op">,</span> <span class="dv">1</span><span class="op">)));</span></span>
<span id="cb10-6"><a href="#cb10-6" aria-hidden="true" tabindex="-1"></a> <span class="op">}</span></span>
<span id="cb10-7"><a href="#cb10-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code></pre></div>
<p>Please look at <a
href="https://github.com/ethauvin/semver/blob/master/examples/java/bld/src/bld/java/com/example/ExampleBuild.java">ExampleBuild</a>
in the <a
href="https://github.com/ethauvin/semver/tree/master/examples/java/bld">examples/java/bld</a>
directory for a sample. It also shows how to incorporate the generated
code into the <code>source tree</code>, more information is also
available <a href="https://forum.uwyn.com/post/36">here</a>.</p>
<h2 id="gradle">Gradle</h2>
<h3 id="class-generation">Class Generation</h3>
<p>To install and run from <a href="https://gradle.org/">Gradle</a>, add
the following to <a
href="https://github.com/ethauvin/semver/blob/master/examples/java/gradle/build.gradle">build.gradle</a>:</p>
<div class="sourceCode" id="cb11"><pre
class="sourceCode gradle"><code class="sourceCode groovy"><span id="cb11-1"><a href="#cb11-1" aria-hidden="true" tabindex="-1"></a>repositories <span class="op">{</span></span>
<span id="cb11-2"><a href="#cb11-2" aria-hidden="true" tabindex="-1"></a> <span class="fu">mavenCentral</span><span class="op">()</span></span>
<span id="cb11-3"><a href="#cb11-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
<span id="cb11-4"><a href="#cb11-4" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb11-5"><a href="#cb11-5" aria-hidden="true" tabindex="-1"></a>dependencies <span class="op">{</span></span>
<span id="cb11-6"><a href="#cb11-6" aria-hidden="true" tabindex="-1"></a> annotationProcessor <span class="st">&#39;net.thauvin.erik:semver:1.2.1&#39;</span></span>
<span id="cb11-7"><a href="#cb11-7" aria-hidden="true" tabindex="-1"></a> compileOnly <span class="st">&#39;net.thauvin.erik:semver:1.2.1&#39;</span></span>
<span id="cb11-8"><a href="#cb11-8" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
<span id="cb11-9"><a href="#cb11-9" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb11-10"><a href="#cb11-10" aria-hidden="true" tabindex="-1"></a>tasks<span class="op">.</span><span class="fu">withType</span><span class="op">(</span>JavaCompile<span class="op">).</span><span class="fu">configureEach</span> <span class="op">{</span></span>
<span id="cb11-11"><a href="#cb11-11" aria-hidden="true" tabindex="-1"></a> options<span class="op">.</span>compilerArgs <span class="op">+=</span> <span class="op">[</span> <span class="st">&quot;-Asemver.project.dir=</span><span class="ss">$projectDir</span><span class="st">&quot;</span> <span class="op">]</span></span>
<span id="cb11-12"><a href="#cb11-12" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code></pre></div>
<p>The directory containing the configuration files
(<code>version.properties</code>, <code>version.mustache</code>) must be
specified using the <code>semver.project.dir</code> processor
argument.</p>
<p>The <a
href="https://github.com/ethauvin/semver/blob/master/examples/java/src/generated/java/com/example/GeneratedVersion.java"><code>GeneratedVersion.java</code></a>
class will be automatically created in the <code>build/generated</code>
directory upon compiling.</p>
<p>Please look at <a
href="https://github.com/ethauvin/semver/blob/master/examples/java/gradle/build.gradle">build.gradle</a>
in the <a
href="https://github.com/ethauvin/semver/tree/master/examples/java/gradle">examples/java/gradle</a>
directory for a sample.</p>
<h3 id="class--source-generation">Class &amp; Source Generation</h3>
<p>In order to also incorporate the generated source code into the
<code>source tree</code>, add the following to <a
href="https://github.com/ethauvin/semver/blob/master/examples/java/build.gradle">build.gradle</a>:</p>
<div class="sourceCode" id="cb12"><pre
class="sourceCode gradle"><code class="sourceCode groovy"><span id="cb12-1"><a href="#cb12-1" aria-hidden="true" tabindex="-1"></a>tasks<span class="op">.</span><span class="fu">withType</span><span class="op">(</span>JavaCompile<span class="op">).</span><span class="fu">configureEach</span> <span class="op">{</span></span>
<span id="cb12-2"><a href="#cb12-2" aria-hidden="true" tabindex="-1"></a> options<span class="op">.</span>generatedSourceOutputDirectory<span class="op">.</span><span class="fu">set</span><span class="op">(</span><span class="fu">file</span><span class="op">(</span><span class="st">&quot;</span><span class="ss">${</span>projectDir<span class="ss">}</span><span class="st">/src/generated/java&quot;</span><span class="op">))</span></span>
<span id="cb12-3"><a href="#cb12-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code></pre></div>
<p>The <a
href="https://github.com/ethauvin/semver/blob/master/examples/java/src/generated/java/com/example/GeneratedVersion.java"><code>GeneratedVersion.java</code></a>
file will now be located in <code>src/generated</code>.</p>
<h2 id="kotlin">Kotlin</h2>
<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="cb13"><pre
class="sourceCode kotlin"><code class="sourceCode kotlin"><span id="cb13-1"><a href="#cb13-1" aria-hidden="true" tabindex="-1"></a><span class="kw">import</span> <span class="im">net</span><span class="op">.</span><span class="im">thauvin</span><span class="op">.</span><span class="im">erik</span><span class="op">.</span><span class="im">semver</span><span class="op">.</span><span class="im">Version</span></span>
<span id="cb13-2"><a href="#cb13-2" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb13-3"><a href="#cb13-3" aria-hidden="true" tabindex="-1"></a><span class="at">@Version</span><span class="op">(</span>properties <span class="op">=</span> <span class="st">&quot;version.properties&quot;</span><span class="op">,</span> type<span class="op">=</span><span class="st">&quot;kt&quot;</span><span class="op">)</span></span>
<span id="cb13-4"><a href="#cb13-4" aria-hidden="true" tabindex="-1"></a><span class="kw">open</span> <span class="kw">class</span> Main <span class="op">{</span></span>
<span id="cb13-5"><a href="#cb13-5" aria-hidden="true" tabindex="-1"></a> <span class="co">// ...</span></span>
<span id="cb13-6"><a href="#cb13-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></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>
<p>Please look at the <a
href="https://github.com/ethauvin/semver/tree/master/examples/kotlin">examples/kotlin</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="kotlin--gradle">Kotlin &amp; Gradle</h3>
<p>To install and run from <a href="https://gradle.org/">Gradle</a>, add
the following to <a
href="https://github.com/ethauvin/semver/blob/master/examples/kotlin/build.gradle.kts">build.gradle.kts</a>:</p>
<div class="sourceCode" id="cb14"><pre
class="sourceCode kotlin"><code class="sourceCode kotlin"><span id="cb14-1"><a href="#cb14-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> <span class="va">semverProcessor</span> <span class="op">=</span> <span class="st">&quot;net.thauvin.erik:semver:1.2.1&quot;</span></span>
<span id="cb14-2"><a href="#cb14-2" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb14-3"><a href="#cb14-3" aria-hidden="true" tabindex="-1"></a>dependencies <span class="op">{</span></span>
<span id="cb14-4"><a href="#cb14-4" aria-hidden="true" tabindex="-1"></a> kapt<span class="op">(</span>semverProcessor<span class="op">)</span></span>
<span id="cb14-5"><a href="#cb14-5" aria-hidden="true" tabindex="-1"></a> compileOnly<span class="op">(</span>semverProcessor<span class="op">)</span></span>
<span id="cb14-6"><a href="#cb14-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
<span id="cb14-7"><a href="#cb14-7" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb14-8"><a href="#cb14-8" aria-hidden="true" tabindex="-1"></a>kapt <span class="op">{</span></span>
<span id="cb14-9"><a href="#cb14-9" aria-hidden="true" tabindex="-1"></a> arguments <span class="op">{</span></span>
<span id="cb14-10"><a href="#cb14-10" aria-hidden="true" tabindex="-1"></a> arg<span class="op">(</span><span class="st">&quot;semver.project.dir&quot;</span><span class="op">,</span> projectDir<span class="op">)</span></span>
<span id="cb14-11"><a href="#cb14-11" aria-hidden="true" tabindex="-1"></a> <span class="op">}</span></span>
<span id="cb14-12"><a href="#cb14-12" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code></pre></div>
<p>The directory containing the configuration files
(<code>version.properties</code>, <code>version.mustache</code>) must be
specified using the <code>semver.project.dir</code> processor
argument.</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>
View git blame Copy permalink