diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 181 |
1 files changed, 84 insertions, 97 deletions
@@ -1,11 +1,12 @@ # Kotlin multiplatform / multi-format reflectionless serialization -[](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub) +[](https://kotlinlang.org/docs/components-stability.html) +[](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub) [](http://www.apache.org/licenses/LICENSE-2.0) [](https://teamcity.jetbrains.com/viewType.html?buildTypeId=KotlinTools_KotlinxSerialization_Ko&guest=1) -[](http://kotlinlang.org) -[](https://search.maven.org/artifact/org.jetbrains.kotlinx/kotlinx-serialization-core/1.3.3/pom) -[](https://kotlin.github.io/kotlinx.serialization/) +[](http://kotlinlang.org) +[](https://central.sonatype.com/artifact/org.jetbrains.kotlinx/kotlinx-serialization-core/1.6.3) +[](https://kotlinlang.org/api/kotlinx.serialization/) [](https://kotlinlang.slack.com/messages/serialization/) Kotlin serialization consists of a compiler plugin, that generates visitor code for serializable classes, @@ -22,18 +23,20 @@ Kotlin serialization consists of a compiler plugin, that generates visitor code * [Introduction and references](#introduction-and-references) * [Setup](#setup) * [Gradle](#gradle) - * [Using the `plugins` block](#using-the-plugins-block) - * [Using `apply plugin` (the old way)](#using-apply-plugin-the-old-way) - * [Dependency on the JSON library](#dependency-on-the-json-library) + * [1) Setting up the serialization plugin](#1-setting-up-the-serialization-plugin) + * [2) Dependency on the JSON library](#2-dependency-on-the-json-library) * [Android](#android) * [Multiplatform (Common, JS, Native)](#multiplatform-common-js-native) * [Maven](#maven) + * [Bazel](#bazel) <!--- END --> * **Additional links** * [Kotlin Serialization Guide](docs/serialization-guide.md) - * [Full API reference](https://kotlin.github.io/kotlinx.serialization/) + * [Full API reference](https://kotlinlang.org/api/kotlinx.serialization/) + * [Submitting issues and PRs](CONTRIBUTING.md) + * [Building this library](docs/building.md) ## Introduction and references @@ -68,28 +71,32 @@ Project(name=kotlinx.serialization, language=Kotlin) **Read the [Kotlin Serialization Guide](docs/serialization-guide.md) for all details.** -You can find auto-generated documentation website on [GitHub Pages](https://kotlin.github.io/kotlinx.serialization/). +You can find auto-generated documentation website on [kotlinlang.org](https://kotlinlang.org/api/kotlinx.serialization/). ## Setup -Kotlin serialization plugin is shipped with the Kotlin compiler distribution, and the IDEA plugin is bundled into the Kotlin plugin. +[New versions](https://plugins.gradle.org/plugin/org.jetbrains.kotlin.plugin.serialization) of the serialization plugin are released in tandem with each new Kotlin compiler version. Using Kotlin Serialization requires Kotlin compiler `1.4.0` or higher. Make sure you have the corresponding Kotlin plugin installed in the IDE, no additional plugins for IDE are required. ### Gradle -#### Using the `plugins` block +To set up kotlinx.serialization, you have to do two things: +1) Add the **[serialization plugin](#1-setting-up-the-serialization-plugin)**. +2) Add the **[serialization library dependency](#2-dependency-on-the-json-library)**. -You can set up the serialization plugin with the Kotlin plugin using +#### 1) Setting up the serialization plugin + +You can set up the serialization plugin with the Kotlin plugin using the [Gradle plugins DSL](https://docs.gradle.org/current/userguide/plugins.html#sec:plugins_block): Kotlin DSL: ```kotlin plugins { - kotlin("jvm") version "1.6.10" // or kotlin("multiplatform") or any other kotlin plugin - kotlin("plugin.serialization") version "1.6.10" + kotlin("jvm") version "1.9.22" // or kotlin("multiplatform") or any other kotlin plugin + kotlin("plugin.serialization") version "1.9.22" } ``` @@ -97,14 +104,15 @@ Groovy DSL: ```gradle plugins { - id 'org.jetbrains.kotlin.multiplatform' version '1.6.10' - id 'org.jetbrains.kotlin.plugin.serialization' version '1.6.10' + id 'org.jetbrains.kotlin.multiplatform' version '1.9.22' + id 'org.jetbrains.kotlin.plugin.serialization' version '1.9.22' } ``` -> Kotlin versions before 1.4.0 are not supported by the stable release of Kotlin serialization +> Kotlin versions before 1.4.0 are not supported by the stable release of Kotlin serialization. -#### Using `apply plugin` (the old way) +<details> + <summary>Using <code>apply plugin</code> (the old way)</summary> First, you have to add the serialization plugin to your classpath as the other [compiler plugins](https://kotlinlang.org/docs/reference/compiler-plugins.html): @@ -115,7 +123,7 @@ buildscript { repositories { mavenCentral() } dependencies { - val kotlinVersion = "1.6.10" + val kotlinVersion = "1.9.22" classpath(kotlin("gradle-plugin", version = kotlinVersion)) classpath(kotlin("serialization", version = kotlinVersion)) } @@ -126,7 +134,7 @@ Groovy DSL: ```gradle buildscript { - ext.kotlin_version = '1.6.10' + ext.kotlin_version = '1.9.22' repositories { mavenCentral() } dependencies { @@ -141,10 +149,11 @@ Then you can `apply plugin` (example in Groovy): apply plugin: 'kotlin' // or 'kotlin-multiplatform' for multiplatform projects apply plugin: 'kotlinx-serialization' ``` +</details> -#### Dependency on the JSON library +#### 2) Dependency on the JSON library -After setting up the plugin one way or another, you have to add a dependency on the serialization library. +After setting up the plugin, you have to add a dependency on the serialization library. Note that while the plugin has version the same as the compiler one, runtime library has different coordinates, repository and versioning. Kotlin DSL: @@ -155,7 +164,7 @@ repositories { } dependencies { - implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.3.3") + implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.3") } ``` @@ -167,104 +176,76 @@ repositories { } dependencies { - implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:1.3.3" + implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.3" } ``` ->We also provide `kotlinx-serialization-core` artifact that contains all serialization API but does not have bundled serialization format with it +>We also provide `kotlinx-serialization-core` artifact that contains all serialization API but does not have a bundled serialization format with it ### Android -The library works on Android, but, if you're using ProGuard, -you need to add rules to your `proguard-rules.pro` configuration to cover all classes that are serialized at runtime. +By default, proguard rules are supplied with the library. +[These rules](rules/common.pro) keep serializers for _all_ serializable classes that are retained after shrinking, +so you don't need additional setup. + +**However, these rules do not affect serializable classes if they have named companion objects.** + +If you want to serialize classes with named companion objects, you need to add and edit rules below to your `proguard-rules.pro` configuration. -The following configuration keeps serializers for _all_ serializable classes that are retained after shrinking. -Uncomment and modify the last section in case you're serializing classes with named companion objects. +Note that the rules for R8 differ depending on the [compatibility mode](https://r8.googlesource.com/r8/+/refs/heads/master/compatibility-faq.md) used. + +<details> +<summary>Example of named companion rules for ProGuard and R8 compatibility mode</summary> ```proguard -# Keep `Companion` object fields of serializable classes. -# This avoids serializer lookup through `getDeclaredClasses` as done for named companion objects. --if @kotlinx.serialization.Serializable class ** --keepclassmembers class <1> { - static <1>$Companion Companion; -} +# Serializer for classes with named companion objects are retrieved using `getDeclaredClasses`. +# If you have any, replace classes with those containing named companion objects. +-keepattributes InnerClasses # Needed for `getDeclaredClasses`. -# Keep `serializer()` on companion objects (both default and named) of serializable classes. --if @kotlinx.serialization.Serializable class ** { +-if @kotlinx.serialization.Serializable class +com.example.myapplication.HasNamedCompanion, # <-- List serializable classes with named companions. +com.example.myapplication.HasNamedCompanion2 +{ static **$* *; } --keepclassmembers class <2>$<3> { - kotlinx.serialization.KSerializer serializer(...); -} - -# Keep `INSTANCE.serializer()` of serializable objects. --if @kotlinx.serialization.Serializable class ** { - public static ** INSTANCE; -} --keepclassmembers class <1> { - public static <1> INSTANCE; - kotlinx.serialization.KSerializer serializer(...); +-keepnames class <1>$$serializer { # -keepnames suffices; class is kept when serializer() is kept. + static <1>$$serializer INSTANCE; } - -# @Serializable and @Polymorphic are used at runtime for polymorphic serialization. --keepattributes RuntimeVisibleAnnotations,AnnotationDefault - -# Serializer for classes with named companion objects are retrieved using `getDeclaredClasses`. -# If you have any, uncomment and replace classes with those containing named companion objects. -#-keepattributes InnerClasses # Needed for `getDeclaredClasses`. -#-if @kotlinx.serialization.Serializable class -#com.example.myapplication.HasNamedCompanion, # <-- List serializable classes with named companions. -#com.example.myapplication.HasNamedCompanion2 -#{ -# static **$* *; -#} -#-keepnames class <1>$$serializer { # -keepnames suffices; class is kept when serializer() is kept. -# static <1>$$serializer INSTANCE; -#} ``` +</details> -In case you want to exclude serializable classes that are used, but never serialized at runtime, -you will need to write custom rules with narrower [class specifications](https://www.guardsquare.com/manual/configuration/usage). <details> -<summary>Example of custom rules</summary> - -```proguard --keepattributes RuntimeVisibleAnnotations,AnnotationDefault - -# kotlinx-serialization-json specific. Add this if you have java.lang.NoClassDefFoundError kotlinx.serialization.json.JsonObjectSerializer --keepclassmembers class kotlinx.serialization.json.** { - *** Companion; -} --keepclasseswithmembers class kotlinx.serialization.json.** { - kotlinx.serialization.KSerializer serializer(...); -} +<summary>Example of named companion rules for R8 full mode</summary> -# Application rules +```proguard +# Serializer for classes with named companion objects are retrieved using `getDeclaredClasses`. +# If you have any, replace classes with those containing named companion objects. +-keepattributes InnerClasses # Needed for `getDeclaredClasses`. -# Change here com.yourcompany.yourpackage --keepclassmembers @kotlinx.serialization.Serializable class com.yourcompany.yourpackage.** { - # lookup for plugin generated serializable classes - *** Companion; - # lookup for serializable objects - *** INSTANCE; - kotlinx.serialization.KSerializer serializer(...); +-if @kotlinx.serialization.Serializable class +com.example.myapplication.HasNamedCompanion, # <-- List serializable classes with named companions. +com.example.myapplication.HasNamedCompanion2 +{ + static **$* *; } -# lookup for plugin generated serializable classes --if @kotlinx.serialization.Serializable class com.yourcompany.yourpackage.** --keepclassmembers class com.yourcompany.yourpackage.<1>$Companion { - kotlinx.serialization.KSerializer serializer(...); +-keepnames class <1>$$serializer { # -keepnames suffices; class is kept when serializer() is kept. + static <1>$$serializer INSTANCE; } -# Serialization supports named companions but for such classes it is necessary to add an additional rule. -# This rule keeps serializer and serializable class from obfuscation. Therefore, it is recommended not to use wildcards in it, but to write rules for each such class. --keepattributes InnerClasses # Needed for `getDeclaredClasses`. --keep class com.yourcompany.yourpackage.SerializableClassWithNamedCompanion$$serializer { - *** INSTANCE; +# Keep both serializer and serializable classes to save the attribute InnerClasses +-keepclasseswithmembers, allowshrinking, allowobfuscation, allowaccessmodification class +com.example.myapplication.HasNamedCompanion, # <-- List serializable classes with named companions. +com.example.myapplication.HasNamedCompanion2 +{ + *; } ``` </details> +In case you want to exclude serializable classes that are used, but never serialized at runtime, +you will need to write custom rules with narrower [class specifications](https://www.guardsquare.com/manual/configuration/usage). + ### Multiplatform (Common, JS, Native) Most of the modules are also available for Kotlin/JS and Kotlin/Native. @@ -285,8 +266,8 @@ Ensure the proper version of Kotlin and serialization version: ```xml <properties> - <kotlin.version>1.6.10</kotlin.version> - <serialization.version>1.3.3</serialization.version> + <kotlin.version>1.9.22</kotlin.version> + <serialization.version>1.6.3</serialization.version> </properties> ``` @@ -334,3 +315,9 @@ Add dependency on serialization runtime library: <version>${serialization.version}</version> </dependency> ``` + +### Bazel + +To setup the Kotlin compiler plugin for Bazel, follow [the +example](https://github.com/bazelbuild/rules_kotlin/tree/master/examples/plugin/src/serialization) +from the `rules_kotlin` repository. |