Kotlin Maven Plugin Tools
Maven plugin metadata extractor for plugins written in Kotlin.
Note: this JAR isn't available from Maven Central, see below for how to
configure a pluginRepository
to download the JAR from GitHub Packages.
This project is still a little new, so please help by reporting any issues you find.
Maven plugin support for Kotlin
The Java5 annotation metadata extractor partially works for Kotlin files. It's able to pull all the information from the annotations; the problem is the descriptions, deprecation messages and since version information, is still extracted from the JavaDoc, and this doesn't work for Kotlin files; the generated web site and the command line help are far less useful without descriptions.
This project provides a Kotlin metadata extractor using
Dokka to give the same support for Kotlin
files, as the Java5 annotation extractor does for Java files (including support
for descriptions and since version information from KDoc, and deprecation
messages from @kotlin.Deprecated
).
Writing a Maven Plugin in Kotlin
Writing a Maven plugin in Kotlin (using this extractor) is much the same as it
normally is in Java; you extend org.apache.maven.plugin.AbstractMojo
, annotate
the class and properties, and add descriptions in API code comments. However as
Kotlin has nullability constraints in the type system, you need to declare
whether properties can be null
or not; you can use lateinit
for the non-null
properties.
It's important that the nullability of the properties matches the value of
the required
attribute of the
org.apache.maven.plugins.annotations.Parameter
annotation, or you may get
unfriendly errors at runtime.
package com.example
import org.apache.maven.plugin.AbstractMojo
import org.apache.maven.plugins.annotations.Mojo
import org.apache.maven.plugins.annotations.Parameter
/**
* Example description.
*/
@Mojo(name = "example")
class ExampleMojo : AbstractMojo() {
/**
* Optional parameter description.
*/
@Deprecated("Example optional parameter deprecated message.")
@Parameter(name = "optionalParameter")
var optionalParameter: String? = null
/**
* Required parameter description.
*
* @since 1.1
*/
@Parameter(name = "requiredParameter", required = true)
lateinit var requiredParameter: String
override fun execute() {
// Perform plugin action here
}
}
Your POM will include the following:
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>example-maven-plugin</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>maven-plugin</packaging>
<prerequisites>
<maven>${maven.version}</maven>
</prerequisites>
<properties>
<kotlin.version>1.3.50</kotlin.version>
<maven.compiler.source>1.8</maven.compiler.source>
<maven.compiler.target>1.8</maven.compiler.target>
<maven.version>3.6.2</maven.version>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
</properties>
<dependencies>
<dependency>
<groupId>org.apache.maven</groupId>
<artifactId>maven-core</artifactId>
<version>${maven.version}</version>
</dependency>
<dependency>
<groupId>org.apache.maven</groupId>
<artifactId>maven-plugin-api</artifactId>
<version>${maven.version}</version>
</dependency>
<dependency>
<groupId>org.jetbrains.kotlin</groupId>
<artifactId>kotlin-stdlib-jdk8</artifactId>
<version>${kotlin.version}</version>
</dependency>
<dependency>
<groupId>org.apache.maven.plugin-tools</groupId>
<artifactId>maven-plugin-annotations</artifactId>
<version>3.6.0</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>org.jetbrains.kotlin</groupId>
<artifactId>kotlin-test-junit</artifactId>
<version>${kotlin.version}</version>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<sourceDirectory>src/main/kotlin</sourceDirectory>
<testSourceDirectory>src/test/kotlin</testSourceDirectory>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-plugin-plugin</artifactId>
<version>3.6.0</version>
<configuration>
<extractors>
<!--
Use only the Kotlin extractor (also supports annotated Java
sources)
-->
<extractor>kotlin</extractor>
</extractors>
</configuration>
<dependencies>
<dependency>
<!-- Add kotlin-maven-plugin-tools`as a dependency to the maven-plugin-plugin -->
<groupId>com.github.gantsign.maven.plugin-tools</groupId>
<artifactId>kotlin-maven-plugin-tools</artifactId>
<!-- Replace @version@ with the latest kotlin-maven-plugin-tools release -->
<version>@version@</version>
</dependency>
</dependencies>
<executions>
<execution>
<id>default-descriptor</id>
<phase>process-classes</phase>
</execution>
<execution>
<id>help-goal</id>
<goals>
<goal>helpmojo</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.jetbrains.kotlin</groupId>
<artifactId>kotlin-maven-plugin</artifactId>
<version>${kotlin.version}</version>
<configuration>
<jvmTarget>1.8</jvmTarget>
</configuration>
<executions>
<execution>
<id>compile</id>
<goals>
<goal>compile</goal>
</goals>
<phase>process-sources</phase>
</execution>
<execution>
<id>test-compile</id>
<goals>
<goal>test-compile</goal>
</goals>
<phase>test-compile</phase>
</execution>
</executions>
</plugin>
</plugins>
</build>
<!--
kotlin-maven-plugin-tools isn't available from Maven Central, so you
have to add the following plugin repository.
Where possible you you should use a repository manager rather than adding
the repository directly to your POM.
-->
<pluginRepositories>
<pluginRepository>
<!-- id must match the id of the server in settings.xml -->
<id>github</id>
<name>GitHub Packages</name>
<url>https://maven.pkg.github.com/gantsign/kotlin-maven-plugin-tools</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</pluginRepository>
</pluginRepositories>
</project>
GitHub Packages repositories require authentication, so you need to specify the
credentials in your settings.xml
. You don't need particular permissions, any
valid GitHub account token will do.
<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://maven.apache.org/SETTINGS/1.0.0"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
https://maven.apache.org/xsd/settings-1.0.0.xsd">
<servers>
<server>
<!-- This is setup for you if using id "github" with
https://github.com/actions/setup-java -->
<!-- id must match the id of the pluginRepository -->
<id>github</id>
<username>${env.GITHUB_ACTOR}</username>
<password>${env.GITHUB_TOKEN}</password>
</server>
</servers>
</settings>
If using GitHub Actions, you also need to pass the GITHUB_TOKEN
environment
variable to the build step(s) in your workflow file e.g.:
- name: Build with Maven
run: mvn install
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
License
This software is licensed under the terms in the file named "LICENSE" in the root directory of this project. This project has dependencies that are under different licenses.
Author Information
John Freeman
GantSign Ltd. Company No. 06109112 (registered in England)