erik/semver
erik/semver
1
1
Fork 0
Code Issues Pull requests Releases Activity

Cleanup.

Browse source
This commit is contained in:
Erik C. Thauvin 2019-05-27 11:26:50 -07:00
parent fb593a0a1a
commit 84054cb398
1 changed files with 39 additions and 43 deletions
Download patch file Download diff file Expand all files Collapse all files

60
README.md
View file

@ -1,9 +1,9 @@
# Semantic Version Annotation Processor # Semantic Version Annotation Processor
[![License (3-Clause BSD)](https://img.shields.io/badge/license-BSD%203--Clause-blue.svg?style=flat-square)](http://opensource.org/licenses/BSD-3-Clause) [![release](https://img.shields.io/github/release/ethauvin/semver.svg)](https://github.com/ethauvin/semver/releases/latest) [![Maven Central](https://maven-badges.herokuapp.com/maven-central/net.thauvin.erik/semver/badge.svg)](https://maven-badges.herokuapp.com/maven-central/net.thauvin.erik/semver) [ ![Download](https://api.bintray.com/packages/ethauvin/maven/SemVer/images/download.svg) ](https://bintray.com/ethauvin/maven/SemVer/_latestVersion) [![License (3-Clause BSD)](https://img.shields.io/badge/license-BSD%203--Clause-blue.svg?style=flat-square)](http://opensource.org/licenses/BSD-3-Clause) [![release](https://img.shields.io/github/release/ethauvin/semver.svg)](https://github.com/ethauvin/semver/releases/latest) [![Maven Central](https://maven-badges.herokuapp.com/maven-central/net.thauvin.erik/semver/badge.svg)](https://maven-badges.herokuapp.com/maven-central/net.thauvin.erik/semver) [ ![Download](https://api.bintray.com/packages/ethauvin/maven/SemVer/images/download.svg) ](https://bintray.com/ethauvin/maven/SemVer/_latestVersion)\
[![Known Vulnerabilities](https://snyk.io/test/github/ethauvin/semver/badge.svg?targetFile=build.gradle)](https://snyk.io/test/github/ethauvin/semver?targetFile=build.gradle) [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=ethauvin_semver&metric=alert_status)](https://sonarcloud.io/dashboard?id=ethauvin_semver) [![Build Status](https://travis-ci.org/ethauvin/semver.svg?branch=master)](https://travis-ci.org/ethauvin/semver) [![Build status](https://ci.appveyor.com/api/projects/status/nbv4mxd1gpxtx69o?svg=true)](https://ci.appveyor.com/project/ethauvin/semver) [![CircleCI](https://circleci.com/gh/ethauvin/semver/tree/master.svg?style=shield)](https://circleci.com/gh/ethauvin/semver/tree/master) [![Known Vulnerabilities](https://snyk.io/test/github/ethauvin/semver/badge.svg?targetFile=build.gradle)](https://snyk.io/test/github/ethauvin/semver?targetFile=build.gradle) [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=ethauvin_semver&metric=alert_status)](https://sonarcloud.io/dashboard?id=ethauvin_semver) [![Build Status](https://travis-ci.org/ethauvin/semver.svg?branch=master)](https://travis-ci.org/ethauvin/semver) [![Build status](https://ci.appveyor.com/api/projects/status/nbv4mxd1gpxtx69o?svg=true)](https://ci.appveyor.com/project/ethauvin/semver) [![CircleCI](https://circleci.com/gh/ethauvin/semver/tree/master.svg?style=shield)](https://circleci.com/gh/ethauvin/semver/tree/master)
An [annotation processor](https://docs.oracle.com/javase/8/docs/api/javax/annotation/processing/Processor.html) that automatically generates a `GeneratedVersion` class based on a [Mustache](https://mustache.github.io/) template and containing the [semantic version](http://semver.org/) (major, minor, patch, etc.) that is read from a `Properties` file or defined in the [annotation](https://docs.oracle.com/javase/tutorial/java/annotations/basics.html). An [annotation processor](https://docs.oracle.com/javase/8/docs/api/javax/annotation/processing/Processor.html) that automatically generates a `GeneratedVersion` class based on a [Mustache](https://mustache.github.io/) template and containing the [semantic version](http://semver.org/) (major, minor, patch, etc.) that is read from a [Properties](https://docs.oracle.com/javase/tutorial/essential/environment/properties.html) file or defined in the [annotation](https://docs.oracle.com/javase/tutorial/java/annotations/basics.html).
This processor was inspired by Cédric Beust's [version-processor](https://github.com/cbeust/version-processor) and works well in conjunction with the [__Semantic Version Plugin for Gradle__](https://github.com/ethauvin/semver-gradle). This processor was inspired by Cédric Beust's [version-processor](https://github.com/cbeust/version-processor) and works well in conjunction with the [__Semantic Version Plugin for Gradle__](https://github.com/ethauvin/semver-gradle).
@ -13,7 +13,6 @@ This processor was inspired by Cédric Beust's [version-processor](https://githu
- [Default Template](#default-template) - [Default Template](#default-template)
- [Custom Template](#custom-template) - [Custom Template](#custom-template)
- [Elements & Properties](#elements--properties) - [Elements & Properties](#elements--properties)
- [Usage with Maven, Gradle, Kotlin and Kobalt](#usage-with-maven-gradle-kotlin-and-kobalt)
- [Maven](#maven) - [Maven](#maven)
- [Gradle](#gradle) - [Gradle](#gradle)
- [Class Generation](#class-generation) - [Class Generation](#class-generation)
@ -36,7 +35,7 @@ public class A {
// ... // ...
``` ```
* Or using a [properties](https://docs.oracle.com/javase/tutorial/essential/environment/properties.html) file: * Or using a [properties](hhttps://github.com/ethauvin/semver/blob/master/examples/java/version.properties) file:
```java ```java
import net.thauvin.erik.semver.Version; import net.thauvin.erik.semver.Version;
@ -54,11 +53,11 @@ version.patch=0
version.prerelease=beta version.prerelease=beta
``` ```
[View Example](https://github.com/ethauvin/semver/tree/master/examples) [View Examples](https://github.com/ethauvin/semver/tree/master/examples)
## Template ## 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. 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 [template](https://github.com/ethauvin/semver/blob/master/src/main/resources/semver.mustache).
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 use your own template, simply create a `version.mustache` file in the project's root directory. The processor will automatically look for it.
@ -175,12 +174,10 @@ example.meta=
# ... # ...
``` ```
> :warning: `keysPrefix` is a new element staring in `1.1.0` and may break older versions when using custom property keys. > :warning: `keysPrefix` is a new element staring in `1.1.0` and may break older versions when using custom property keys.\
> :zap: A quick fix is to include `keysPrefix=""` in the annotation to remove the default `version.` prefix. > :zap: A quick fix is to include `keysPrefix=""` in the annotation to remove the default `version.` prefix.
## Usage with Maven, Gradle, Kotlin and Kobalt ## Maven
### Maven
To install and run from [Maven](https://maven.apache.org/), configure an artifact as follows: To install and run from [Maven](https://maven.apache.org/), configure an artifact as follows:
@ -192,17 +189,17 @@ To install and run from [Maven](https://maven.apache.org/), configure an artifac
</dependency> </dependency>
``` ```
Please look at [pom.xml](https://github.com/ethauvin/semver/blob/master/examples/java/pom.xml) in the [Java example](https://github.com/ethauvin/semver/tree/master/examples/java) directory for a sample: Please look at [pom.xml](https://github.com/ethauvin/semver/blob/master/examples/java/pom.xml) in the [examples/java](https://github.com/ethauvin/semver/tree/master/examples/java) directory for a sample:
```bash ```bash
mvn verify mvn verify
``` ```
### Gradle ## Gradle
#### Class Generation ### Class Generation
To install and run from [Gradle](https://gradle.org/), add the following to `build.gradle`: To install and run from [Gradle](https://gradle.org/), add the following to [build.gradle](https://github.com/ethauvin/semver/blob/master/examples/java/build.gradle):
```gradle ```gradle
dependencies { dependencies {
@ -211,24 +208,25 @@ dependencies {
} }
``` ```
The `GeneratedVersion` class will be automatically created in the `build/generated` directory upon compiling. The [`GeneratedVersion.java`](https://github.com/ethauvin/semver/blob/master/examples/java/src/generated/java/com/example/GeneratedVersion.java) class will be automatically created in the `build/generated` directory upon compiling.
#### Class & Source Generation Please look at [build.gradle](https://github.com/ethauvin/semver/blob/master/examples/java/build.gradle) in the [examples/java](https://github.com/ethauvin/semver/tree/master/examples/java) directory for a sample.
In order to also incorporate the generated source code into the `source tree`, add the following to the very top of `build.gradle`: ### 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](https://github.com/ethauvin/semver/blob/master/examples/java/build.gradle):
```gradle ```gradle
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`. The [`GeneratedVersion.java`](https://github.com/ethauvin/semver/blob/master/examples/java/src/generated/java/com/example/GeneratedVersion.java) file will now be located in `src/generated`.
### Java 12
#### Java 12
When using properties file (`version.properties`) under Java 12+ and Gradle 5.4.1+, the directory containing the properties file must be specified using the `semver.project.dir` processor argument. When using properties file (`version.properties`) under Java 12+ and Gradle 5.4.1+, the directory containing the properties file must be specified using the `semver.project.dir` processor argument.
For example, if the properties file is in the Gradle project directory: For example, if the properties file is in the Gradle project directory, add the following to [build.gradle](https://github.com/ethauvin/semver/blob/master/examples/java/build.gradle):
```gradle ```gradle
tasks.withType(JavaCompile) { tasks.withType(JavaCompile) {
@ -236,9 +234,7 @@ tasks.withType(JavaCompile) {
} }
``` ```
Please look at [build.gradle](https://github.com/ethauvin/semver/blob/master/examples/java/build.gradle) in the [Java example](https://github.com/ethauvin/semver/tree/master/examples/java) directory for a sample. ## Kotlin
### Kotlin
The annotation processor also supports [Kotlin](https://kotlinlang.org/). The annotation processor also supports [Kotlin](https://kotlinlang.org/).
@ -253,9 +249,11 @@ 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). 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).
#### Kotlin & Gradle Please look at the [examples/kotlin](https://github.com/ethauvin/semver/tree/master/examples/kotlin) project for a [build.gradle.kts](https://github.com/ethauvin/semver/blob/master/examples/kotlin/build.gradle.kts) sample.
To install and run from [Gradle](https://gradle.org/), add the following to `build.gradle.kts`: ### Kotlin & Gradle
To install and run from [Gradle](https://gradle.org/), add the following to [build.gradle.kts](https://github.com/ethauvin/semver/blob/master/examples/kotlin/build.gradle.kts):
```kotlin ```kotlin
var semverProcessor = "net.thauvin.erik:semver:1.2.0" var semverProcessor = "net.thauvin.erik:semver:1.2.0"
@ -272,7 +270,7 @@ kapt {
} }
``` ```
The arguments block is not required if `kapt` is configured to use the Gradle Worker API in `gradle.properties`: The arguments block is not required if `kapt` is configured to use the Gradle Worker API in [gradle.properties](https://github.com/ethauvin/semver/blob/master/examples/kotlin/gradle.properties):
```ini ```ini
kapt.use.worker.api=true kapt.use.worker.api=true
@ -280,11 +278,9 @@ kapt.use.worker.api=true
This option will likely be enabled by default in the future, but is currently not working under Java 10+ see [KT-26203](https://youtrack.jetbrains.net/issue/KT-26203). This option will likely be enabled by default in the future, but is currently not working under Java 10+ see [KT-26203](https://youtrack.jetbrains.net/issue/KT-26203).
Please look at the [Kotlin example](https://github.com/ethauvin/semver/tree/master/examples/kotlin) project for a [build.gradle.kts](https://github.com/ethauvin/semver/blob/master/examples/kotlin/build.gradle.kts) sample. ## Kobalt
### Kobalt To install and run from [Kobalt](https://beust.com/kobalt/), add the following to [Build.kt](https://github.com/ethauvin/semver/blob/master/examples/java/kobalt/src/Build.kt):
To install and run from [Kobalt](https://beust.com/kobalt/), add the following to `Build.kt`:
```gradle ```gradle
dependencies { dependencies {
@ -293,7 +289,7 @@ dependencies {
} }
``` ```
Please look at [Build.kt](https://github.com/ethauvin/semver/blob/master/examples/java/kobalt/src/Build.kt) in the [Java example](https://github.com/ethauvin/semver/tree/master/examples/java) directory for a sample. Please look at [Build.kt](https://github.com/ethauvin/semver/blob/master/examples/java/kobalt/src/Build.kt) in the [examples/java](https://github.com/ethauvin/semver/tree/master/examples/java) directory for a sample.
## Auto-Increment ## Auto-Increment