ktargeter / ktargeter

Kotlin compiler plugin that allows overriding annotation use-site targets for properties 🛠️

ktargeter

⚠ Maintainer Wanted

This project is not actively being maintained. If you want to take the lead in developing Ktargeter further, please leave a comment under this issue.

English | 한국어

Ktargeter is a Kotlin compiler plugin that allows overriding annotation use-site targets for properties. Using Java annotations in Kotlin code often requires specifying use-site targets, which is inconvenient and leads to bugs in runtime when a target is not specified. Instead of memorizing whether it is @get:Email, @field:Email, or @set:Email. You can configure it once in Gradle and use @Email throughout your code. Ktargeter works during compilation and adds no overhead in runtime.

As an example, you can replace this code:

data class User(
    @get:One
    val firstName: String,
    @field:Two
    val lastName: String,
    @set:Three
    var birthday: LocalDate,     
)

with this:

data class User(
    @One
    val firstName: String,
    @Two
    val lastName: String,
    @Three
    var birthday: LocalDate,     
)

Usage

Supported Kotlin versions: 1.4, 1.5, and 1.6.

Add ktargeter to the plugins section of your build.gradle:

plugins {
    id 'org.ktargeter' version '0.3.0'
}

Define annotations with new targets in the following way:

ktargeter.annotations = [
        "com.sample.annotations.One"  : "get",
        "com.sample.annotations.Two"  : "field",
        "com.sample.annotations.Three": "set"
]

This will instruct the plugin to override use-site targets for the specified annotations when they are used on properties.

Ktargeter will not override targets of annotations that specify their targets explicitly.

Compatibility

Pick a plugin version depending on the Kotlin version used in your project.

Kotlin version	Ktargeter version
Kotlin 1.6 or newer	Ktargeter 0.3.0
Kotlin 1.5	Ktargeter 0.2.1
Kotlin 1.4	Ktargeter 0.1.0

Contributing

If you found a bug or have an idea on how to improve ktargeter feel free to open an issue. You can also propose your changes via a Pull Request.

Development setup

In order to debug/develop ktargeter, use the following steps:

1. Install Gradle and Kotlin plugins into the local Maven repository:

./gradlew publishToMavenLocal -x signMavenPublication \
 -x signPluginMavenPublication -x signSimplePluginPluginMarkerMavenPublication

2. Import the project to IntelliJ IDEA (the Debug Kotlin Plugin configuration should be available in Run/Debug configuration box).

3. Add breakpoints to the classes in the compiler-plugin module.

4. Clone the sample project and build it using the following command:

./gradlew clean build --no-daemon -Dorg.gradle.debug=true \
 -Dkotlin.compiler.execution.strategy="in-process" \
 -Dkotlin.daemon.jvm.options="-Xdebug,-Xrunjdwp:transport=dt_socket,address=5005,server=y,suspend=n"

5. Run the Debug Kotlin Plugin configuration in Debug mode.

ktargeter's Issues

Add CI

Remove jcenter from repositories

Add Chinese or Japanese version of readme

How to publish the plugin?

I have been trying to create a similar gradle plugin based on your example. Do you have to publish the gradle plugin to gradle or is publishing to maven central is enough?
Can you help me out with this.

Maintainer Wanted

This project is not actively being maintained. If you want to take the lead in developing Ktargeter further, please leave a comment under this issue.

What needs to be developed:

• Support for newer versions of Kotlin
• Regular maintenance (fixing bugs, adding improvements, looking after outdated dependencies, etc.)
• Support configuration through annotations (more info)

Support ktargeter targets configuration through annotations

Hi, this plugin looks quite promising for my openapi project and I'm wondering if there's a chance I could somehow preconfigure default targets for my annotations. Atm Kotlin users have to provide use-site targets, so regular annotation processor is able to pick them from Kotlin sources, e.g.:

• https://github.com/javalin/javalin-openapi/blob/b228214baad7d4087c2cb4f5af62dc08a4455c71/examples/javalin-gradle-kotlin/src/main/kotlin/io/javalin/openapi/plugin/test/KotlinEntity.kt#L30-L35

To use it with ktargeter, each user has to list all annotations in Gradle like in your example:

ktargeter.annotations = [
        "com.sample.annotations.One"  : "get",
        "com.sample.annotations.Two"  : "field",
        "com.sample.annotations.Three": "set"
]

It'd be nice if there would be sth like ktargeter-specification module with cfg annotations like e.g. @KtargeterTarget([GET/FIELD/SET]) I could use on my annotations, so then your compiler plugin would be able to discover them without a need to use ktargeter.annotations 🤔