Skip to content

Commit 3829654

Browse files
Mr3zeeMr3zee
committed
Gradle Plugin API docs
1 parent 779dd32 commit 3829654

20 files changed

+1188
-513
lines changed

‎gradle-plugin/build.gradle.kts‎

Lines changed: 35 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -60,27 +60,51 @@ abstract class GeneratePluginVersionTask @Inject constructor(
6060

6161
sourceFile.writeText(
6262
"""
63-
package kotlinx.rpc
63+
// This file is generated by a $NAME gradle task. Do not modify manually.
6464
65-
public const val LIBRARY_VERSION: String = "$libraryVersion"
65+
package kotlinx.rpc
6666
67-
@Deprecated("Use kotlinx.rpc.LIBRARY_VERSION instead", ReplaceWith("kotlinx.rpc.LIBRARY_VERSION"))
68-
public const val PLUGIN_VERSION: String = LIBRARY_VERSION
67+
/**
68+
* The version of the kotlinx.rpc library.
69+
*/
70+
public const val LIBRARY_VERSION: String = "$libraryVersion"
6971
70-
public const val PROTOBUF_VERSION: String = "$protobufVersion"
71-
public const val GRPC_VERSION: String = "$grpcVersion"
72-
public const val GRPC_KOTLIN_VERSION: String = "$grpcKotlinVersion"
73-
public const val BUF_TOOL_VERSION: String = "$bufToolVersion"
74-
75-
""".trimIndent()
72+
@Deprecated("Use kotlinx.rpc.LIBRARY_VERSION instead", ReplaceWith("kotlinx.rpc.LIBRARY_VERSION"))
73+
public const val PLUGIN_VERSION: String = LIBRARY_VERSION
74+
75+
/**
76+
* The version of the protobuf library.
77+
*/
78+
public const val PROTOBUF_VERSION: String = "$protobufVersion"
79+
80+
/**
81+
* The version of the grpc java library.
82+
*/
83+
public const val GRPC_VERSION: String = "$grpcVersion"
84+
85+
/**
86+
* The version of the grpc kotlin library.
87+
*/
88+
public const val GRPC_KOTLIN_VERSION: String = "$grpcKotlinVersion"
89+
90+
/**
91+
* The version of the buf tool used to generate protobuf.
92+
*/
93+
public const val BUF_TOOL_VERSION: String = "$bufToolVersion"
94+
95+
""".trimIndent()
7696
)
7797
}
98+
99+
companion object {
100+
const val NAME = "generatePluginVersion"
101+
}
78102
}
79103

80104
val sourcesDir = File(project.layout.buildDirectory.asFile.get(), "generated-sources/pluginVersion")
81105

82106
val generatePluginVersionTask = tasks.register<GeneratePluginVersionTask>(
83-
"generatePluginVersion",
107+
GeneratePluginVersionTask.NAME,
84108
version.toString(),
85109
libs.versions.protobuf.asProvider().get(),
86110
libs.versions.grpc.asProvider().get(),

‎gradle-plugin/src/main/kotlin/kotlinx/rpc/Extensions.kt‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66

77
package kotlinx.rpc
88

9+
import kotlinx.rpc.grpc.DefaultGrpcExtension
910
import kotlinx.rpc.grpc.GrpcExtension
1011
import org.gradle.api.Action
1112
import org.gradle.api.Project
@@ -51,13 +52,13 @@ public open class RpcExtension @Inject constructor(objects: ObjectFactory, priva
5152
*/
5253
public val grpc: GrpcExtension by lazy {
5354
grpcApplied.set(true)
54-
objects.newInstance<GrpcExtension>()
55+
objects.newInstance<DefaultGrpcExtension>()
5556
}
5657

5758
/**
5859
* Grpc settings.
5960
*/
60-
public fun grpc(configure: Action<GrpcExtension>) {
61+
public fun grpc(configure: Action<GrpcExtension> = Action {}) {
6162
configure.execute(grpc)
6263
}
6364
}

‎gradle-plugin/src/main/kotlin/kotlinx/rpc/buf/BufExecutable.kt‎

Lines changed: 26 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,6 @@ import org.gradle.api.GradleException
1111
import org.gradle.api.Project
1212
import org.gradle.kotlin.dsl.dependencies
1313

14-
1514
// See: https://github.com/bufbuild/buf-gradle-plugin/blob/1bc48078880887797db3aa412d6a3fea60461276/src/main/kotlin/build/buf/gradle/BufSupport.kt#L28
1615
internal fun Project.configureBufExecutable() {
1716
configurations.create(BUF_EXECUTABLE_CONFIGURATION)
@@ -53,20 +52,41 @@ internal fun BufExecTask.execBuf(args: Iterable<Any>) {
5352
executable.setExecutable(true)
5453
}
5554

56-
val config = configFile.orNull
57-
val configArgs = if (config != null) listOf("--config", config.absolutePath) else emptyList()
55+
val baseArgs = buildList {
56+
val configValue = configFile.orNull
57+
if (configValue != null) {
58+
add("--config")
59+
add(configValue.absolutePath)
60+
}
61+
62+
if (debug.get()) {
63+
add("--debug")
64+
}
65+
66+
val logFormatValue = logFormat.get()
67+
if (logFormatValue != BufExtension.LogFormat.Default) {
68+
add("--log-format")
69+
add(logFormatValue.name.lowercase())
70+
}
71+
72+
val timeoutValue = bufTimeoutInWholeSeconds.get()
73+
if (timeoutValue != 0L) {
74+
add("--timeout")
75+
add("${timeoutValue}s")
76+
}
77+
}
5878

59-
val processArgs = listOf(executable.absolutePath) + configArgs + args
79+
val processArgs = listOf(executable.absolutePath) + args + baseArgs
6080

6181
val workingDirValue = workingDir.get()
6282

63-
logger.info("Running buf from $workingDirValue: `buf ${args.joinToString(" ")}`")
83+
logger.debug("Running buf from {}: `buf {}`", workingDirValue, processArgs.joinToString(" "))
6484

6585
val result = ProcessRunner().use { it.shell("buf", workingDirValue, processArgs) }
6686

6787
if (result.exitCode != 0) {
6888
throw GradleException(result.formattedOutput())
6989
} else {
70-
logger.info(result.formattedOutput())
90+
logger.debug(result.formattedOutput())
7191
}
7292
}

‎gradle-plugin/src/main/kotlin/kotlinx/rpc/buf/BufExtensions.kt‎

Lines changed: 182 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,23 +4,202 @@
44

55
package kotlinx.rpc.buf
66

7+
import kotlinx.rpc.buf.tasks.BufExecTask
78
import org.gradle.api.Action
89
import org.gradle.api.Project
910
import org.gradle.api.provider.Property
1011
import org.gradle.kotlin.dsl.property
1112
import java.io.File
1213
import javax.inject.Inject
14+
import kotlin.time.Duration
15+
import kotlinx.rpc.proto.ProtocPlugin
16+
import org.gradle.api.model.ObjectFactory
17+
import org.gradle.api.plugins.ExtensionAware
18+
import org.gradle.api.plugins.ExtensionContainer
19+
import org.gradle.api.provider.ListProperty
20+
import org.gradle.api.provider.Provider
21+
import org.gradle.kotlin.dsl.listProperty
22+
import kotlin.reflect.KClass
1323

14-
public open class BufExtension @Inject constructor(internal val project: Project) {
15-
public val configFile: Property<File> = project.objects.property<File>()
24+
/**
25+
* Options for the Buf tasks.
26+
*
27+
* @see <a href="https://buf.build/docs/reference/cli/buf/">buf commands</a>
28+
*/
29+
public open class BufExtension @Inject constructor(objects: ObjectFactory) {
30+
/**
31+
* `--config` argument value.
32+
*
33+
* @see <a href="https://buf.build/docs/reference/cli/buf/">buf commands</a>
34+
*/
35+
public val configFile: Property<File> = objects.property<File>()
36+
37+
/**
38+
* `--debug` option.
39+
*
40+
* @see <a href="https://buf.build/docs/reference/cli/buf/#debug">buf --debug</a>
41+
*/
42+
public val debug: Property<Boolean> = objects.property<Boolean>().convention(false)
43+
44+
/**
45+
* `--log-format` option.
46+
*
47+
* @see <a href="https://buf.build/docs/reference/cli/buf/#log-format">buf --log-format</a>
48+
*/
49+
public val logFormat: Property<LogFormat> = objects.property<LogFormat>().convention(LogFormat.Default)
50+
51+
/**
52+
* Possible values for `--log-format` [logFormat] option.
53+
*/
54+
public enum class LogFormat {
55+
Text,
56+
Color,
57+
Json,
58+
59+
/**
60+
* Buf's default value.
61+
*/
62+
Default,
63+
;
64+
}
65+
66+
/**
67+
* `--timeout` option.
68+
*
69+
* Value to Buf is passed in seconds using [Duration.inWholeSeconds].
70+
*
71+
* @see <a href="https://buf.build/docs/reference/cli/buf/#timeout">buf --timeout</a>
72+
*/
73+
public val timeout: Property<Duration> = objects.property<Duration>().convention(Duration.ZERO)
1674

17-
public val generate: BufGenerateExtension = project.objects.newInstance(BufGenerateExtension::class.java, project)
75+
/**
76+
* `buf generate` options.
77+
*
78+
* @see <a href="https://buf.build/docs/reference/cli/buf/generate/">"buf generate" command</a>
79+
* @see [BUF_GEN_YAML]
80+
*/
81+
public val generate: BufGenerateExtension = objects.newInstance(BufGenerateExtension::class.java)
1882

83+
/**
84+
* Configures the `buf generate` options.
85+
*
86+
* @see <a href="https://buf.build/docs/reference/cli/buf/generate/">"buf generate" command</a>
87+
* @see [BUF_GEN_YAML]
88+
*/
1989
public fun generate(configure: Action<BufGenerateExtension>) {
2090
configure.execute(generate)
2191
}
92+
93+
/**
94+
* Use this extension to register custom Buf tasks
95+
* that will operate on the generated workspace.
96+
*/
97+
public val tasks: BufTasksExtension = objects.newInstance(BufTasksExtension::class.java)
98+
99+
/**
100+
* Use this extension to register custom Buf tasks
101+
* that will operate on the generated workspace.
102+
*/
103+
public fun tasks(configure: Action<BufTasksExtension>) {
104+
configure.execute(tasks)
105+
}
106+
}
107+
108+
/**
109+
* Allows registering custom Buf tasks that can operate on the generated workspace.
110+
*/
111+
public open class BufTasksExtension @Inject constructor(internal val project: Project) {
112+
// TODO change to commonMain/commonTest in docs when it's supported
113+
/**
114+
* Registers a custom Buf task that operates on the generated workspace.
115+
*
116+
* Name conventions:
117+
* `lint` input for [name] will result in tasks
118+
* named 'bufLintMain' and 'bufLintTest' for Kotlin/JVM projects
119+
* and 'bufLintJvmMain' and 'bufLintJvmTest' for Kotlin/Multiplatform projects.
120+
*
121+
* Note the by default 'test' task doesn't depend on 'main' task.
122+
*/
123+
public fun <T : BufExecTask> registerWorkspaceTask(kClass: KClass<T>, name: String, configure: Action<T>): Provider<T> {
124+
val property = project.objects.property(kClass)
125+
126+
@Suppress("UNCHECKED_CAST")
127+
customTasks.add(Definition(name, kClass, configure, property as Property<BufExecTask>))
128+
129+
return property
130+
}
131+
132+
// TODO change to commonMain/commonTest in docs when it's supported
133+
/**
134+
* Registers a custom Buf task that operates on the generated workspace.
135+
*
136+
* Name conventions:
137+
* `lint` input for [name] will result in tasks
138+
* named 'bufLintMain' and 'bufLintTest' for Kotlin/JVM projects
139+
* and 'bufLintJvmMain' and 'bufLintJvmTest' for Kotlin/Multiplatform projects.
140+
*
141+
* Note the by default 'test' task doesn't depend on 'main' task.
142+
*/
143+
public inline fun <reified T : BufExecTask> registerWorkspaceTask(name: String, configure: Action<T>): Provider<T> {
144+
return registerWorkspaceTask(T::class, name, configure)
145+
}
146+
147+
internal val customTasks: ListProperty<Definition<out BufExecTask>> = project.objects.listProperty()
148+
149+
internal class Definition<T : BufExecTask>(
150+
val name: String,
151+
val kClass: KClass<T>,
152+
val configure: Action<T>,
153+
val property: Property<BufExecTask>,
154+
)
22155
}
23156

157+
/**
158+
* Options for the `buf generate` command.
159+
*
160+
* @see <a href="https://buf.build/docs/reference/cli/buf/generate/">"buf generate" command</a>
161+
* @see [BUF_GEN_YAML]
162+
*/
24163
public open class BufGenerateExtension @Inject constructor(internal val project: Project) {
164+
/**
165+
* `--include-imports` option.
166+
*
167+
* @see <a href="https://buf.build/docs/reference/cli/buf/generate/#include-imports">buf generate --include-imports</a>
168+
* @see [ProtocPlugin.includeImports]
169+
*/
25170
public val includeImports: Property<Boolean> = project.objects.property<Boolean>().convention(false)
171+
172+
/**
173+
* `--include-wkt` option.
174+
*
175+
* @see <a href="https://buf.build/docs/reference/cli/buf/generate/#include-wkt">buf generate --include-wkt</a>
176+
* @see [ProtocPlugin.includeWkt]
177+
*/
178+
public val includeWkt: Property<Boolean> = project.objects.property<Boolean>().convention(false)
179+
180+
/**
181+
* `--error-format` option.
182+
*
183+
* @see <a href="https://buf.build/docs/reference/cli/buf/generate/#error-format">buf generate --error-format</a>
184+
*/
185+
public val errorFormat: Property<ErrorFormat> = project.objects.property<ErrorFormat>().convention(ErrorFormat.Default)
186+
187+
/**
188+
* Possible values for `--error-format` option.
189+
*
190+
* @see <a href="https://buf.build/docs/reference/cli/buf/generate/#error-format">buf generate --error-format</a>
191+
*/
192+
public enum class ErrorFormat(internal val cliValue: String) {
193+
Text("text"),
194+
Json("json"),
195+
Msvs("msvs"),
196+
Junit("junit"),
197+
GithubActions("github-actions"),
198+
199+
/**
200+
* Buf's default value.
201+
*/
202+
Default(""),
203+
;
204+
}
26205
}

‎gradle-plugin/src/main/kotlin/kotlinx/rpc/buf/consts.kt‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,25 @@
44

55
package kotlinx.rpc.buf
66

7+
import org.gradle.api.artifacts.Configuration
8+
9+
/**
10+
* Name of the buf.gen.yaml file.
11+
*
12+
* @see <a href="https://buf.build/docs/configuration/v2/buf-gen-yaml/">buf.gen.yaml reference</a>
13+
*/
714
public const val BUF_GEN_YAML: String = "buf.gen.yaml"
15+
16+
/**
17+
* Name of the buf.yaml file.
18+
*
19+
* @see <a href="https://buf.build/docs/configuration/v2/buf-yaml/">buf.yaml reference</a>
20+
*/
821
public const val BUF_YAML: String = "buf.yaml"
22+
23+
/**
24+
* [Configuration] name for buf executable.
25+
*
26+
* @see <a href="https://buf.build/docs/">Buf</a>
27+
*/
928
public const val BUF_EXECUTABLE_CONFIGURATION: String = "bufExecutable"

0 commit comments

Comments
 (0)