azalea/kotlin-fork
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Actualize README.md for kotlinx-serialization plugin

Browse Source
This commit is contained in:
Leonid Startsev
2023-02-07 15:03:27 +01:00
committed by Space Team
parent 43cef114c6
commit 5cd817955b
1 changed files with 35 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plugins/kotlinx-serialization/README.md
+35 -17
View File
@@ -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`