From 5cd817955b05268be1edcadfefd0bb83f5aca470 Mon Sep 17 00:00:00 2001 From: Leonid Startsev Date: Tue, 7 Feb 2023 15:03:27 +0100 Subject: [PATCH] Actualize README.md for kotlinx-serialization plugin --- plugins/kotlinx-serialization/README.md | 52 +++++++++++++++++-------- 1 file changed, 35 insertions(+), 17 deletions(-) diff --git a/plugins/kotlinx-serialization/README.md b/plugins/kotlinx-serialization/README.md index c86bd63d45a..c8f4833f850 100644 --- a/plugins/kotlinx-serialization/README.md +++ b/plugins/kotlinx-serialization/README.md @@ -1,31 +1,49 @@ -# Kotlin serialization IDEA plugin +# Kotlinx serialization compiler plugin -Kotlin serialization plugin consists of three parts: a compiler plugin, an IntelliJ plugin and a runtime library. -This is the folder with common source for all plugins, IDEA plugin is built from here. Gradle and Maven plugins can be found in `libraries` folder. +This folder contains compiler plugin counterpart to [kotlinx.serialization](https://github.com/Kotlin/kotlinx.serialization) library: +source code for all compiler-related plugin parts, including code resolution, code generation, diagnostics, and tests. +Gradle and Maven plugins can be found in the `libraries` folder. +The IntelliJ IDEA part (which contains only specific inspections and quickfixes) is located +[inside the Kotlin IDEA plugin in the IntelliJ Community monorepo](https://github.com/JetBrains/intellij-community/tree/master/plugins/kotlin/compiler-plugins/kotlinx-serialization). -## Building and usage +## Brief overview -### Prerequisites: -Before all, follow the instructions from root README.md to download dependencies and build Kotlin compiler. (`./gradlew dist`) +Plugin consists of five parts: -**Plugin works only with IntelliJIDEA 2017.2 and higher.** +1.`backend` — responsible for IR code generation as well as old JVM & JS compiler backends (to be removed in the future). +2. `k1` — Code resolution and diagnostics for the Kotlin frontend. +3. `k2` — Code resolution and diagnostics for the new K2 Kotlin compiler. +4. `cli` — extension points that allow the plugin to be loaded with `-Xplugin` Kotlin CLI compiler argument. +5. `common` — common declarations for other parts. -Make sure you have latest dev version of Kotlin plugin installed. +Tests and test data are common for all parts and located directly in this module (see `testData` and `tests-gen` folders). -### With gradle: +## Building and contributing -Run `./gradlew :kotlinx-serialization-compiler-plugin:dist`. -In IDEA, open `Settings - Plugins - Install plugin from disk...` and choose `$kotlin_root/dist/artifacts/Serialization/lib/kotlinx-serialization-compiler-plugin.jar` +### Prerequisites -### From within IDE (for development): +Before all, it is recommended to read root `README.md` and ensure you have all the necessary things installed (you don't need JDK6 to work with this plugin). -Run `./gradlew runIde` You'll get a fresh copy of IDEA with Kotlin and Kotlin-serialization plugins built from sources. +### Installing locally -## Building gradle plugin +Just run `./gradlew dist install` to get a fresh Kotlin compiler and kotlinx.serialization plugin in your Maven local with `1.x.255-SNAPSHOT` versions. +Installing the serialization plugin alone is not recommended, as it may not be binary compatible with the latest published version of Kotlin. -Run `./gradlew :kotlinx-gradle-serialization-plugin:install` +### Working with tests -## Building maven plugin +As in most Kotlin project modules, tests are generated based on test data. +Tests are located in `test-gen` folder and can be run using the green arrow on the IDE gutter or with standard +`./gradlew :kotlinx-serialization-compiler-plugin:test` task. +To add a new test, add an appropriate file to `testData` folder and then re-generate tests with `./gradlew :kotlinx-serialization-compiler-plugin:generateTests`. + +### Building maven plugin + +A Gradle plugin is installed during project-wide `./gradlew dist install`. In rare cases when you need a snapshot Maven plugin, follow these steps: +Make all prerequisites from `$kotlin_root/libraries/README.md` for Maven projects. Go to `$kotlin_root/libraries/tools/kotlin-maven-serialization`. Run `mvn install`. + +### Contributing + +Follow the common [Kotlin's contribution guidelines](../../docs/contributing.md). +In general, create an issue in Kotlin's YouTrack or [kotlinx.serialization's GitHub](https://github.com/Kotlin/kotlinx.serialization/issues/new/choose) to discuss suggested changes beforehand. -Make all prerequisites from libraries' README.md for Maven projects. Go to `$kotlin_root/libraries/tools/kotlin-maven-serialization`. Run `mvn install`