Merge pull request #4 from kanyun-inc/feature/maven-plugin

Add Maven plugin and integrations tests for both Maven and Gradle projects.
kanyun-inc · Oct 7, 2023 · 1619795 · 1619795
2 parents 75a2255 + 4ce1dd8
commit 1619795
Show file tree

Hide file tree

Showing 33 changed files with 1,037 additions and 29 deletions.
diff --git a/.github/scripts/integration_tests.sh b/.github/scripts/integration_tests.sh
@@ -0,0 +1,18 @@
+set -e
+SCRIPT_DIR=$(cd $(dirname $0) && pwd -P)
+PROJECT_DIR=$SCRIPT_DIR/../../
+
+cd $PROJECT_DIR
+pwd
+
+# MAVEN
+cd $PROJECT_DIR/kudos-sample/kudos-maven-sample
+mvn test -Dkudos.version=0.0.0-SNAPSHOT
+cd -
+
+# GRADLE
+cd $PROJECT_DIR/kudos-sample/kudos-gradle-sample
+./gradlew test -PKUDOS_VERSION=0.0.0-SNAPSHOT
+cd -
+
+cd -
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -39,5 +39,8 @@ jobs:
       - name: Publish To Local
         run: ./gradlew publishToMavenLocal -PVERSION_NAME=0.0.0-SNAPSHOT
 
+      - name: Run integration tests
+        run: bash .github/scripts/integration_tests.sh
+
       - name: Check spotless
         run: ./gradlew spotlessCheck --no-configuration-cache
diff --git a/README.md b/README.md
@@ -101,7 +101,9 @@ We kept thinking, is there a way to provide null safety and default values suppo
 
 ## Quick Start
 
-### 1. Add the plugin to classpath
+### 1. Introduce Kudos into Gradle Projects
+
+#### 1.1 Add the plugin to classpath
 
 ```kotlin
 // Option 1
@@ -147,7 +149,7 @@ dependencyResolutionManagement {
 }
 ````
 
-### 2. Apply the plugin
+#### 1.2 Apply the plugin
 
 ```kotlin
 plugins {
@@ -179,6 +181,97 @@ com.kanyun.kudos:kudos-jackson
 
 You can add these libraries to your dependencies explicitly if needed.
 
+### 2. Introduce Kudos into Maven Projects
+
+#### 2.1 Project Dependencies
+
+Add `kudos-gson` or `kudos-jackson` into the dependencies of your project. 
+
+```xml
+<?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/maven-v4_0_0.xsd">
+    ...
+    <dependencies>
+        ...
+        <!-- for gson -->
+        <dependency>
+            <groupId>com.kanyun.kudos</groupId>
+            <artifactId>kudos-gson</artifactId>
+            <version>${kudos.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>com.google.code.gson</groupId>
+            <artifactId>gson</artifactId>
+            <version>2.10</version>
+        </dependency>
+
+        <!-- for jackson -->
+        <dependency>
+            <groupId>com.kanyun.kudos</groupId>
+            <artifactId>kudos-jackson</artifactId>
+            <version>${kudos.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>com.fasterxml.jackson.core</groupId>
+            <artifactId>jackson-databind</artifactId>
+            <version>2.15.0</version>
+        </dependency>
+    </dependencies>
+    ...
+</project>
+```
+
+#### 2.2 Configure the Compiler
+
+```xml
+<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/maven-v4_0_0.xsd">
+    ...
+
+    <build>
+        <sourceDirectory>src/main/java</sourceDirectory>
+        <testSourceDirectory>src/test/java</testSourceDirectory>
+
+        <plugins>
+            <plugin>
+                <groupId>org.jetbrains.kotlin</groupId>
+                <artifactId>kotlin-maven-plugin</artifactId>
+                <version>${kotlin.version}</version>
+
+                <configuration>
+                    <compilerPlugins>
+                        <!-- Tell Kotlin compiler to load Kudos compiler plugin -->
+                        <plugin>kudos</plugin>
+                    </compilerPlugins>
+
+                    <pluginOptions>
+                        <!-- for gson -->
+                        <option>kudos:gson=true</option>
+                        <!-- for jackson -->
+                        <option>kudos:jackson=true</option>
+                    </pluginOptions>
+                </configuration>
+
+                <dependencies>
+                    <!-- add Kudos compiler plugin to the classpath of Kotlin compiler -->
+                    <dependency>
+                        <groupId>com.kanyun.kudos</groupId>
+                        <artifactId>kudos-maven-plugin</artifactId>
+                        <version>${kudos.version}</version>
+                    </dependency>
+                </dependencies>
+
+                <executions>...</executions>
+            </plugin>
+        </plugins>
+    </build>
+
+</project>
+```
+
 ### 3. Annotate classes with `@Kudos`
 
 For types that need to add `Kudos` parsing support, simply add the `@Kudos` annotation, for example:

diff --git a/README_zh.md b/README_zh.md
@@ -101,7 +101,9 @@ User(id=12, name=Benny Huo, age=0, tel=null)
 
 ## 快速上手
 
-### 1. 添加插件到 classpath
+### 1. 将 Kudos 集成到 Gradle 项目中
+
+#### 1.1 添加插件到 classpath
 
 ```kotlin
 // 方式 1
@@ -147,7 +149,7 @@ dependencyResolutionManagement {
 }
 ````
 
-### 2. 在项目中启用插件
+#### 1.2 在项目中启用插件
 
 ```kotlin
 plugins {
@@ -179,6 +181,97 @@ com.kanyun.kudos:kudos-jackson
 
 当然，开发者也可以在合适的场景下手动引入这些依赖。
 
+### 2. 将 Kudos 集成到 Maven 项目中
+
+#### 2.1 添加项目依赖
+
+将 `kudos-gson` 或者 `kudos-jackson` 添加到你的项目依赖中。
+
+```xml
+<?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/maven-v4_0_0.xsd">
+    ...
+    <dependencies>
+        ...
+        <!-- for gson -->
+        <dependency>
+            <groupId>com.kanyun.kudos</groupId>
+            <artifactId>kudos-gson</artifactId>
+            <version>${kudos.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>com.google.code.gson</groupId>
+            <artifactId>gson</artifactId>
+            <version>2.10</version>
+        </dependency>
+
+        <!-- for jackson -->
+        <dependency>
+            <groupId>com.kanyun.kudos</groupId>
+            <artifactId>kudos-jackson</artifactId>
+            <version>${kudos.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>com.fasterxml.jackson.core</groupId>
+            <artifactId>jackson-databind</artifactId>
+            <version>2.15.0</version>
+        </dependency>
+    </dependencies>
+    ...
+</project>
+```
+
+#### 2.2 配置编译器插件
+
+```xml
+<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/maven-v4_0_0.xsd">
+    ...
+
+    <build>
+        <sourceDirectory>src/main/java</sourceDirectory>
+        <testSourceDirectory>src/test/java</testSourceDirectory>
+
+        <plugins>
+            <plugin>
+                <groupId>org.jetbrains.kotlin</groupId>
+                <artifactId>kotlin-maven-plugin</artifactId>
+                <version>${kotlin.version}</version>
+
+                <configuration>
+                    <compilerPlugins>
+                        <!-- Kotlin 编译器会根据配置加载 Kudos 插件 -->
+                        <plugin>kudos</plugin>
+                    </compilerPlugins>
+
+                    <pluginOptions>
+                        <!-- for gson -->
+                        <option>kudos:gson=true</option>
+                        <!-- for jackson -->
+                        <option>kudos:jackson=true</option>
+                    </pluginOptions>
+                </configuration>
+
+                <dependencies>
+                    <!-- 将 Kudos 插件添加到 Kotlin 编译器的 classpath 中 -->
+                    <dependency>
+                        <groupId>com.kanyun.kudos</groupId>
+                        <artifactId>kudos-maven-plugin</artifactId>
+                        <version>${kudos.version}</version>
+                    </dependency>
+                </dependencies>
+
+                <executions>...</executions>
+            </plugin>
+        </plugins>
+    </build>
+
+</project>
+```
+
 ### 3. 为特定类启动 Kudos 的支持
 
 对于需要添加 `Kudos` 解析支持的类型，直接添加 `@Kudos` 注解即可，例如：

diff --git a/gradle.properties b/gradle.properties
@@ -1,6 +1,6 @@
 kotlin.code.style=official
 
-VERSION_NAME=1.8.20-1.0.0
+VERSION_NAME=1.8.20-1.0.1
 
 GROUP=com.kanyun.kudos
 

diff --git a/kudos-compiler/build.gradle.kts b/kudos-compiler/build.gradle.kts
@@ -19,7 +19,6 @@ plugins {
     kotlin("jvm")
     java
     id("com.bennyhuo.kotlin.trimindent")
-    kotlin("kapt")
     id("com.github.gmazzo.buildconfig")
     id("com.bennyhuo.kotlin.plugin.embeddable.test")
 }
@@ -33,9 +32,6 @@ dependencies {
     compileOnly("org.jetbrains.kotlin:kotlin-stdlib")
     compileOnly("org.jetbrains.kotlin:kotlin-compiler")
 
-    kapt("com.google.auto.service:auto-service:1.0.1")
-    compileOnly("com.google.auto.service:auto-service-annotations:1.0.1")
-
     implementation("org.jetbrains.kotlin:kotlin-noarg:1.8.20")
 
     testImplementation(kotlin("test-junit"))
@@ -55,6 +51,6 @@ compileKotlin.kotlinOptions.freeCompilerArgs += listOf(
 compileKotlin.kotlinOptions.jvmTarget = "1.8"
 
 buildConfig {
-    packageName("$group.gson.extensions")
+    packageName("$group")
     buildConfigField("String", "KOTLIN_PLUGIN_ID", "\"${project.property("KOTLIN_PLUGIN_ID")}\"")
 }
diff --git a/kudos-compiler/src/main/java/com/kanyun/kudos/compiler/KudosCommandLineProcessor.kt b/kudos-compiler/src/main/java/com/kanyun/kudos/compiler/KudosCommandLineProcessor.kt
@@ -16,18 +16,16 @@
 
 package com.kanyun.kudos.compiler
 
-import com.google.auto.service.AutoService
+import com.kanyun.kudos.BuildConfig
 import com.kanyun.kudos.compiler.options.Option
 import com.kanyun.kudos.compiler.options.Options
-import com.kanyun.kudos.gson.extensions.BuildConfig
 import org.jetbrains.kotlin.compiler.plugin.AbstractCliOption
 import org.jetbrains.kotlin.compiler.plugin.CliOption
 import org.jetbrains.kotlin.compiler.plugin.CommandLineProcessor
 import org.jetbrains.kotlin.compiler.plugin.ExperimentalCompilerApi
 import org.jetbrains.kotlin.config.CompilerConfiguration
 
 @OptIn(ExperimentalCompilerApi::class)
-@AutoService(CommandLineProcessor::class)
 class KudosCommandLineProcessor : CommandLineProcessor {
 
     override val pluginId: String = BuildConfig.KOTLIN_PLUGIN_ID

diff --git a/kudos-compiler/src/main/java/com/kanyun/kudos/compiler/KudosCompilerPluginRegistrar.kt b/kudos-compiler/src/main/java/com/kanyun/kudos/compiler/KudosCompilerPluginRegistrar.kt
@@ -16,7 +16,6 @@
 
 package com.kanyun.kudos.compiler
 
-import com.google.auto.service.AutoService
 import com.kanyun.kudos.compiler.k1.KudosComponentContainerContributor
 import com.kanyun.kudos.compiler.k1.KudosSyntheticResolveExtension
 import com.kanyun.kudos.compiler.k2.KudosFirExtensionRegistrar
@@ -36,7 +35,6 @@ import org.jetbrains.kotlin.resolve.extensions.SyntheticResolveExtension
 lateinit var logger: Logger
 
 @OptIn(ExperimentalCompilerApi::class)
-@AutoService(CompilerPluginRegistrar::class)
 class KudosCompilerPluginRegistrar : CompilerPluginRegistrar() {
 
     override fun ExtensionStorage.registerExtensions(configuration: CompilerConfiguration) {

diff --git a/kudos-compiler/src/main/java/com/kanyun/kudos/compiler/KudosIrClassTransformer.kt b/kudos-compiler/src/main/java/com/kanyun/kudos/compiler/KudosIrClassTransformer.kt
@@ -83,7 +83,7 @@ class KudosIrClassTransformer(
     private val defaults = HashSet<String>()
 
     fun transform() {
-        if (Options.isGsonEnabled()) {
+        if (Options.gson()) {
             generateJsonAdapter()
         }
         generateNoArgConstructor()

diff --git a/kudos-compiler/src/main/java/com/kanyun/kudos/compiler/k1/KudosDeclarationChecker.kt b/kudos-compiler/src/main/java/com/kanyun/kudos/compiler/k1/KudosDeclarationChecker.kt
@@ -60,7 +60,7 @@ class KudosDeclarationChecker(
             } else {
                 checkInitBlock(context, declaration)
                 checkNoArg(descriptor, context, declaration)
-                if (Options.isGsonEnabled()) {
+                if (Options.gson()) {
                     checkJsonAdapter(descriptor, context, declaration)
                 }
                 checkPrimaryConstructor(declaration, context)

diff --git a/kudos-compiler/src/main/java/com/kanyun/kudos/compiler/k2/KudosFirClassChecker.kt b/kudos-compiler/src/main/java/com/kanyun/kudos/compiler/k2/KudosFirClassChecker.kt
@@ -73,7 +73,7 @@ class KudosFirClassChecker(
             } else {
                 checkInitBlock(declaration, context, reporter)
                 checkNoArg(declaration, context, reporter)
-                if (Options.isGsonEnabled()) {
+                if (Options.gson()) {
                     checkJsonAdapter(declaration, context, reporter)
                 }
                 checkPrimaryConstructor(declaration, context, reporter)

diff --git a/kudos-compiler/src/main/java/com/kanyun/kudos/compiler/options/Options.kt b/kudos-compiler/src/main/java/com/kanyun/kudos/compiler/options/Options.kt
@@ -19,18 +19,18 @@ package com.kanyun.kudos.compiler.options
 object Options {
 
     @JvmField
-    val isGsonEnabled = Option(
-        "isGsonEnabled",
+    val gson = Option(
+        "gson",
         false,
-        "Enable Gson plugin.",
+        "Whether to enable the support for Gson.",
         "<true/false>",
     )
 
     @JvmField
-    val isJacksonEnabled = Option(
-        "isJacksonEnabled",
+    val jackson = Option(
+        "jackson",
         false,
-        "Enable Jackson plugin.",
+        "Whether to enable the support for Jackson.",
         "<true/false>",
     )
 

diff --git a/...ain/resources/META-INF/services/org.jetbrains.kotlin.compiler.plugin.CommandLineProcessor b/...ain/resources/META-INF/services/org.jetbrains.kotlin.compiler.plugin.CommandLineProcessor
@@ -0,0 +1 @@
+com.kanyun.kudos.compiler.KudosCommandLineProcessor
diff --git a/.../resources/META-INF/services/org.jetbrains.kotlin.compiler.plugin.CompilerPluginRegistrar b/.../resources/META-INF/services/org.jetbrains.kotlin.compiler.plugin.CompilerPluginRegistrar
@@ -0,0 +1 @@
+com.kanyun.kudos.compiler.KudosCompilerPluginRegistrar
diff --git a/kudos-compiler/src/test/java/com/kanyun/kudos/compiler/base/TestBase.kt b/kudos-compiler/src/test/java/com/kanyun/kudos/compiler/base/TestBase.kt
@@ -57,7 +57,7 @@ open class TestBase {
     }
 
     private fun gsonDeserialize(): String {
-        Options.isGsonEnabled.set(true)
+        Options.gson.set(true)
 
         return """
             // FILE: Gson.kt
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		com.kanyun.kudos.compiler.KudosCommandLineProcessor
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		com.kanyun.kudos.compiler.KudosCompilerPluginRegistrar