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.