Skip to content

Commit 12559e8

Browse files
Mr3zeevnikolova
Mr3zee
and
vnikolova
committed
Updated docs for 0.4.0; bumped version (#222)
Co-authored-by: Viktoriya Nikolova <[email protected]>
1 parent fca1259 commit 12559e8

15 files changed

+159
-161
lines changed

‎.github/workflows/docs.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ env:
2020
ALGOLIA_INDEX_NAME: 'prod_kotlin_rpc'
2121
ALGOLIA_KEY: '${{ secrets.ALGOLIA_KEY }}'
2222
CONFIG_JSON_PRODUCT: 'kotlinx-rpc'
23-
CONFIG_JSON_VERSION: '0.3.0'
23+
CONFIG_JSON_VERSION: '0.4.0'
2424

2525
jobs:
2626
build:

‎README.md

+18-47
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77

88
[![Kotlin Experimental](https://kotl.in/badges/experimental.svg)](https://kotlinlang.org/docs/components-stability.html)
99
[![Official JetBrains project](http://jb.gg/badges/official.svg)](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub)
10-
[![Kotlin](https://img.shields.io/badge/kotlin-1.7.0--2.0.10-blue.svg?logo=kotlin)](http://kotlinlang.org)
10+
[![Kotlin](https://img.shields.io/badge/kotlin-2.0.0--2.0.21-blue.svg?logo=kotlin)](http://kotlinlang.org)
1111
[![GitHub License](https://img.shields.io/badge/license-Apache%20License%202.0-blue.svg?style=flat)](http://www.apache.org/licenses/LICENSE-2.0)
1212

1313
[//]: # ([![TeamCity build]&#40;https://img.shields.io/teamcity/build/s/Build_kRPC_All.svg?server=http%3A%2F%2Fkrpc.teamcity.com&#41;]&#40;https://teamcity.jetbrains.com/viewType.html?buildTypeId=Build_kRPC_All&guest=1&#41;)
@@ -84,33 +84,18 @@ Check out our [getting started guide](https://kotlin.github.io/kotlinx-rpc) for
8484

8585
### Plugin dependencies
8686

87-
`kotlinx.rpc` has the following plugin dependencies:
88-
- The `org.jetbrains.kotlinx.rpc.plugin` will set up BOM and code generation for targets in the project.
89-
- The `org.jetbrains.kotlinx.rpc.platform` will only set up BOM. It is useful when you want to split your app into modules,
90-
and some of them will contain service declarations, thus using code generation, while others will only consume them.
87+
`kotlinx.rpc` provides Gradle plugin `org.jetbrains.kotlinx.rpc.plugin`
88+
that will set up code generation in a project.
9189

92-
Example of plugins setup in a project's `build.gradle.kts`:
90+
Example of a setup in a project's `build.gradle.kts`:
9391
```kotlin
9492
plugins {
95-
kotlin("jvm") version "2.0.10"
96-
kotlin("plugin.serialization") version "2.0.10"
97-
id("org.jetbrains.kotlinx.rpc.plugin") version "0.3.0"
93+
kotlin("multiplatform") version "2.0.21"
94+
kotlin("plugin.serialization") version "2.0.21"
95+
id("org.jetbrains.kotlinx.rpc.plugin") version "0.4.0"
9896
}
9997
```
10098

101-
For Kotlin versions prior to 2.0,
102-
KSP plugin is required
103-
(Corresponding configurations will be set up automatically by `org.jetbrains.kotlinx.rpc.plugin` plugin):
104-
105-
```kotlin
106-
// build.gradle.kts
107-
plugins {
108-
kotlin("jvm") version "1.9.25"
109-
kotlin("plugin.serialization") version "1.9.25"
110-
id("com.google.devtools.ksp") version "1.9.25-1.0.20"
111-
id("org.jetbrains.kotlinx.rpc.plugin") version "0.3.0"
112-
}
113-
```
11499
### Runtime dependencies
115100
To use `kotlinx.rpc` runtime dependencies, add Maven Central to the list of your repositories:
116101
```kotlin
@@ -121,16 +106,16 @@ repositories {
121106
And now you can add dependencies to your project:
122107
```kotlin
123108
dependencies {
124-
// client API
125-
implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-client")
126-
// server API
127-
implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-server")
128-
// serialization module. also, protobuf and cbor are available
129-
implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-serialization-json")
109+
// Client API
110+
implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-client:0.4.0")
111+
// Server API
112+
implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-server:0.4.0")
113+
// Serialization module. Also, protobuf and cbor are provided
114+
implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-serialization-json:0.4.0")
130115

131-
// transport implementation for Ktor
132-
implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-ktor-client")
133-
implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-ktor-server")
116+
// Transport implementation for Ktor
117+
implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-ktor-client:0.4.0")
118+
implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-ktor-server:0.4.0")
134119

135120
// Ktor API
136121
implementation("io.ktor:ktor-client-cio-jvm:$ktor_version")
@@ -143,7 +128,7 @@ You can see example projects in the [samples](samples) folder.
143128
`kotlinx.rpc` is designed to be transport agnostic.
144129
That means that the library aims to provide the best RPC experience regardless of how the resulting messages are transferred.
145130
That allows for easy integration into existing solutions, such as Ktor, without the need to rewrite code.
146-
Just plug-in `kotlinx.rpc`, provide it with means to transfer encoded data (or use out-of-the-box integrations) and it will run.
131+
Add `kotlinx.rpc`, provide it with means to transfer encoded data (or use out-of-the-box integrations) and it will run.
147132
With enough time it might even work with [avian carriers](https://en.wikipedia.org/wiki/IP_over_Avian_Carriers).
148133

149134
`kotlinx.rpc` provides its own transfer protocol called kRPC, which takes responsibility for tracking serializing and handling other complex request operations.
@@ -154,26 +139,12 @@ Besides that, one can even provide their own protocol or integration with one to
154139
Though possible, it is much more complicated way to use the library and generally not needed.
155140
`kotlinx.rpc` aims to provide most common protocols integrations as well as the in-house one called kRPC.
156141
Integrations in progress:
157-
- Integration with [gRPC](https://grpc.io/) (in prototype)
142+
- Integration with [gRPC](https://grpc.io/) (in prototype)
158143

159144
## Kotlin compatibility
160145
We support all stable Kotlin versions starting from 2.0.0:
161146
- 2.0.0, 2.0.10, 2.0.20, 2.0.21
162147

163-
To simplify project configuration, our Gradle plugin sets a proper library version automatically using BOM,
164-
based on the project's Kotlin version:
165-
```kotlin
166-
plugins {
167-
kotlin("jvm") version "2.0.10"
168-
id("org.jetbrains.kotlinx.rpc.plugin") version "0.3.0"
169-
}
170-
171-
dependencies {
172-
// version 0.3.0 is set by the Gradle plugin
173-
implementation("org.jetbrains.kotlinx:kotlinx-rpc-core")
174-
}
175-
```
176-
177148
For a full compatibility checklist,
178149
see [Versions](https://kotlin.github.io/kotlinx-rpc/versions.html).
179150

‎docs/pages/kotlinx-rpc/help-versions.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
[
2-
{"version":"0.3.0","url":"/kotlinx-rpc/0.3.0/","isCurrent":true}
2+
{"version":"0.4.0","url":"/kotlinx-rpc/0.4.0/","isCurrent":true}
33
]

‎docs/pages/kotlinx-rpc/rpc.tree

+1
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@
2626
</toc-element>
2727
<toc-element topic="versions.topic"/>
2828
<toc-element toc-title="Migration guides">
29+
<toc-element topic="0-4-0.topic"/>
2930
<toc-element topic="0-3-0.topic"/>
3031
<toc-element topic="0-2-4.topic"/>
3132
<toc-element topic="0-2-1.topic"/>

‎docs/pages/kotlinx-rpc/topics/0-4-0.topic

+90
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!DOCTYPE topic
3+
SYSTEM "https://resources.jetbrains.com/writerside/1.0/xhtml-entities.dtd">
4+
<topic xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
5+
xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/topic.v2.xsd"
6+
title="Migration to 0.4.0" id="0-4-0">
7+
<p>
8+
Version <code>0.4.0</code> introduces breaking changes.
9+
</p>
10+
<chapter title="@Rpc Annotation and RemoteService Interface" id="rpc_annotation_and_remote_service_interface">
11+
<p>
12+
This version brings changes to service definitions. Starting with this version, service definitions require
13+
the <code>@Rpc</code> annotation.
14+
</p>
15+
<p>
16+
Prior to <code>0.4.0</code>, a service was defined as follows:
17+
</p>
18+
<code-block lang="kotlin">
19+
interface MyService : RPC
20+
</code-block>
21+
<p>
22+
Starting from <code>0.4.0</code>, the new service definition should be:
23+
</p>
24+
<code-block lang="kotlin">
25+
@Rpc
26+
interface MyService
27+
</code-block>
28+
<p>
29+
This definition is sufficient for the project to build. However, it will not fully support IDE features,
30+
such as code highlighting.
31+
All interfaces annotated with <code>@Rpc</code> are inherently of type <code>RemoteService</code>, which is
32+
added by the compiler plugin, but IDEs won't be able to resolve it.
33+
</p>
34+
<p>
35+
To ensure proper IDE support, add explicit typing:
36+
</p>
37+
<code-block lang="kotlin">
38+
@Rpc
39+
interface MyService : RemoteService
40+
</code-block>
41+
<note>
42+
<p>
43+
The reasoning behind this update is that the Kotlin Compiler Plugin API has changed.
44+
Versions <code>2.0.0</code> and <code>2.0.10</code> allowed our plugin to resolve marker interfaces (like <code>RPC</code>)
45+
before the code generation phase. Starting from version <code>2.0.20</code>, this behaviour changed,
46+
making annotations the only reliable way to detect RPC services.
47+
</p>
48+
<p>
49+
To track changes in this regard, we raised an <a href="https://youtrack.jetbrains.com/issue/KT-72654">issue</a>
50+
with the compiler team.
51+
Note that this approach is subject to change, and the final API design may be updated before the stable
52+
release.
53+
</p>
54+
</note>
55+
</chapter>
56+
<chapter title="Removal of Kotlin versions prior to 2.0" id="removal_of_kotlin_versions_prior_to_2_0">
57+
<p>
58+
We stopped publishing compiler plugin artifacts for Kotlin versions prior to <code>2.0.0</code>.
59+
The reason being its high maintenance cost with little to no usage.
60+
We encourage the migration to Kotlin 2.0, where all stable versions are now supported.
61+
<br/>
62+
</p>
63+
<p>
64+
Currently supported Kotlin versions: <code>2.0.0</code>, <code>2.0.10</code>, <code>2.0.20</code>, <code>2.0.21</code>
65+
</p>
66+
</chapter>
67+
<chapter title="Removal of org.jetbrains.kotlinx.rpc.platform Gradle plugin"
68+
id="removal_of_org_jetbrains_kotlinx_rpc_platform_gradle_plugin">
69+
<p>
70+
The Gradle plugin with id <code>org.jetbrains.kotlinx.rpc.platform</code> is not being published anymore.
71+
The reason is that it's sole role was to set BOM in the project, which is now considered unnecessary.
72+
<a href="https://docs.gradle.org/current/userguide/platforms.html#sub:conventional-dependencies-toml">Gradle version catalogs</a>
73+
can be used instead.
74+
</p>
75+
</chapter>
76+
<chapter title="Removal of BOM from the Gradle plugin" id="removal_of_bom_from_the_gradle_plugin">
77+
<p>
78+
The Gradle plugin with id <code>org.jetbrains.kotlinx.rpc.plugin</code>
79+
does not set BOM for the project anymore.
80+
</p>
81+
<p>
82+
To configure BOM manually, add the following dependency:
83+
</p>
84+
<code-block lang="kotlin">
85+
dependencies {
86+
implementation(platform("org.jetbrains.kotlinx:kotlinx-rpc-bom:%kotlinx-rpc-version%"))
87+
}
88+
</code-block>
89+
</chapter>
90+
</topic>

‎docs/pages/kotlinx-rpc/topics/features.topic

+13-1
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,8 @@
3636
that will provide your flows with their lifetime:</p>
3737

3838
<code-block lang="kotlin">
39-
interface MyService {
39+
@Rpc
40+
interface MyService : RemoteService {
4041
suspend fun sendFlow(flow: Flow&lt;Int&gt;)
4142
}
4243

@@ -81,6 +82,17 @@
8182
}
8283
</code-block>
8384
<p>Note that this API is experimental and may be removed in future releases.</p>
85+
<p>
86+
Another way of managing streams is to do it manually.
87+
For this, you can use the <code>StreamScope</code> constructor function together with
88+
<code>withStreamScope</code>:
89+
</p>
90+
<code-block lang="kotlin">
91+
val streamScope = StreamScope(myJob)
92+
withStreamScope(streamScope) {
93+
// use streams here
94+
}
95+
</code-block>
8496
</chapter>
8597
<chapter title="Service fields" id="service-fields">
8698
<p>Our protocol provides you with an ability to declare service fields:</p>

‎docs/pages/kotlinx-rpc/topics/get-started.topic

+6-16
Original file line numberDiff line numberDiff line change
@@ -110,33 +110,23 @@
110110
</chapter>
111111

112112
<chapter title="Add plugin dependencies" id="add-gradle-plugin">
113-
<p><code>kotlinx.rpc</code> provides <a href="plugins.topic">two Gradle plugins</a>:</p>
114-
<list>
115-
<li>
116-
<a href="plugins.topic" anchor="rpc-platform">
117-
<code>org.jetbrains.kotlinx.rpc.platform</code>
118-
</a>
119-
</li>
120-
<li>
121-
<a href="plugins.topic" anchor="rpc-plugin">
122-
<code>org.jetbrains.kotlinx.rpc.plugin</code>
123-
</a>
124-
</li>
125-
</list>
126113
<p>
127-
To add a plugin to your project, you need to define the following in your <path>build.gradle.kts</path>:
114+
To add a <a href="plugins.topic">Gradle plugin</a> to your project, you need to define the following in your <path>build.gradle.kts</path>:
128115
</p>
129116

130117
<code-block lang="kotlin">
131118
plugins {
132119
id(&quot;org.jetbrains.kotlinx.rpc.plugin&quot;) version &quot;%kotlinx-rpc-version%&quot;
133120
}
134121
</code-block>
135-
<p>To learn more about versioning, see <a href="versions.topic"/>.</p>
122+
123+
<p>
124+
This will configure code generation for your project.
125+
</p>
136126
</chapter>
137127

138128
<chapter title="Add serialization dependency" id="add-serialization-dependency">
139-
<p><code>kotlinx.rpc</code> requires you to add
129+
<p><code>kotlinx.rpc</code> requires you to add the
140130
<a href="https://github.com/Kotlin/kotlinx.serialization">kotlinx.serialization</a>
141131
Gradle plugin to your project.</p>
142132

0 commit comments

Comments
 (0)