Skip to content

Commit f886508

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

20 files changed

+1179
-519
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: 4 additions & 3 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
@@ -18,7 +19,7 @@ import org.gradle.kotlin.dsl.property
1819
import java.util.concurrent.atomic.AtomicBoolean
1920
import javax.inject.Inject
2021

21-
public fun Project.rpcExtension(): RpcExtension = extensions.findByType<RpcExtension>() ?: RpcExtension(objects, this)
22+
internal fun Project.rpcExtension(): RpcExtension = extensions.findByType<RpcExtension>() ?: RpcExtension(objects, this)
2223

2324
public open class RpcExtension @Inject constructor(objects: ObjectFactory, private val project: Project) {
2425
/**
@@ -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: 27 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,9 @@ import kotlinx.rpc.buf.tasks.BufExecTask
99
import kotlinx.rpc.util.ProcessRunner
1010
import org.gradle.api.GradleException
1111
import org.gradle.api.Project
12+
import org.gradle.api.logging.LogLevel
1213
import org.gradle.kotlin.dsl.dependencies
1314

14-
1515
// See: https://github.com/bufbuild/buf-gradle-plugin/blob/1bc48078880887797db3aa412d6a3fea60461276/src/main/kotlin/build/buf/gradle/BufSupport.kt#L28
1616
internal fun Project.configureBufExecutable() {
1717
configurations.create(BUF_EXECUTABLE_CONFIGURATION)
@@ -53,20 +53,41 @@ internal fun BufExecTask.execBuf(args: Iterable<Any>) {
5353
executable.setExecutable(true)
5454
}
5555

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

59-
val processArgs = listOf(executable.absolutePath) + configArgs + args
80+
val processArgs = listOf(executable.absolutePath) + args + baseArgs
6081

6182
val workingDirValue = workingDir.get()
6283

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

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

6788
if (result.exitCode != 0) {
6889
throw GradleException(result.formattedOutput())
6990
} else {
70-
logger.info(result.formattedOutput())
91+
logger.debug(result.formattedOutput())
7192
}
7293
}

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

Lines changed: 173 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,23 +4,193 @@
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.provider.ListProperty
18+
import org.gradle.api.provider.Provider
19+
import org.gradle.kotlin.dsl.listProperty
20+
import kotlin.reflect.KClass
1321

14-
public open class BufExtension @Inject constructor(internal val project: Project) {
15-
public val configFile: Property<File> = project.objects.property<File>()
22+
/**
23+
* Options for the Buf tasks.
24+
*
25+
* @see <a href="https://buf.build/docs/reference/cli/buf/">buf commands</a>
26+
*/
27+
public open class BufExtension @Inject constructor(objects: ObjectFactory) {
28+
/**
29+
* `--config` argument value.
30+
*
31+
* @see <a href="https://buf.build/docs/reference/cli/buf/">buf commands</a>
32+
*/
33+
public val configFile: Property<File> = objects.property<File>()
34+
35+
/**
36+
* `--log-format` option.
37+
*
38+
* @see <a href="https://buf.build/docs/reference/cli/buf/#log-format">buf --log-format</a>
39+
*/
40+
public val logFormat: Property<LogFormat> = objects.property<LogFormat>().convention(LogFormat.Default)
1641

17-
public val generate: BufGenerateExtension = project.objects.newInstance(BufGenerateExtension::class.java, project)
42+
/**
43+
* Possible values for `--log-format` [logFormat] option.
44+
*/
45+
public enum class LogFormat {
46+
Text,
47+
Color,
48+
Json,
49+
50+
/**
51+
* Buf's default value.
52+
*/
53+
Default,
54+
;
55+
}
1856

57+
/**
58+
* `--timeout` option.
59+
*
60+
* Value to Buf is passed in seconds using [Duration.inWholeSeconds].
61+
*
62+
* @see <a href="https://buf.build/docs/reference/cli/buf/#timeout">buf --timeout</a>
63+
*/
64+
public val timeout: Property<Duration> = objects.property<Duration>().convention(Duration.ZERO)
65+
66+
/**
67+
* `buf generate` options.
68+
*
69+
* @see <a href="https://buf.build/docs/reference/cli/buf/generate/">"buf generate" command</a>
70+
* @see [BUF_GEN_YAML]
71+
*/
72+
public val generate: BufGenerateExtension = objects.newInstance(BufGenerateExtension::class.java)
73+
74+
/**
75+
* Configures the `buf generate` options.
76+
*
77+
* @see <a href="https://buf.build/docs/reference/cli/buf/generate/">"buf generate" command</a>
78+
* @see [BUF_GEN_YAML]
79+
*/
1980
public fun generate(configure: Action<BufGenerateExtension>) {
2081
configure.execute(generate)
2182
}
83+
84+
/**
85+
* Use this extension to register custom Buf tasks
86+
* that will operate on the generated workspace.
87+
*/
88+
public val tasks: BufTasksExtension = objects.newInstance(BufTasksExtension::class.java)
89+
90+
/**
91+
* Use this extension to register custom Buf tasks
92+
* that will operate on the generated workspace.
93+
*/
94+
public fun tasks(configure: Action<BufTasksExtension>) {
95+
configure.execute(tasks)
96+
}
2297
}
2398

99+
/**
100+
* Allows registering custom Buf tasks that can operate on the generated workspace.
101+
*/
102+
public open class BufTasksExtension @Inject constructor(internal val project: Project) {
103+
// TODO change to commonMain/commonTest in docs when it's supported
104+
/**
105+
* Registers a custom Buf task that operates on the generated workspace.
106+
*
107+
* Name conventions:
108+
* `lint` input for [name] will result in tasks
109+
* named 'bufLintMain' and 'bufLintTest' for Kotlin/JVM projects
110+
* and 'bufLintJvmMain' and 'bufLintJvmTest' for Kotlin/Multiplatform projects.
111+
*
112+
* Note the by default 'test' task doesn't depend on 'main' task.
113+
*/
114+
public fun <T : BufExecTask> registerWorkspaceTask(kClass: KClass<T>, name: String, configure: Action<T>): Provider<T> {
115+
val property = project.objects.property(kClass)
116+
117+
@Suppress("UNCHECKED_CAST")
118+
customTasks.add(Definition(name, kClass, configure, property as Property<BufExecTask>))
119+
120+
return property
121+
}
122+
123+
// TODO change to commonMain/commonTest in docs when it's supported
124+
/**
125+
* Registers a custom Buf task that operates on the generated workspace.
126+
*
127+
* Name conventions:
128+
* `lint` input for [name] will result in tasks
129+
* named 'bufLintMain' and 'bufLintTest' for Kotlin/JVM projects
130+
* and 'bufLintJvmMain' and 'bufLintJvmTest' for Kotlin/Multiplatform projects.
131+
*
132+
* Note the by default 'test' task doesn't depend on 'main' task.
133+
*/
134+
public inline fun <reified T : BufExecTask> registerWorkspaceTask(name: String, configure: Action<T>): Provider<T> {
135+
return registerWorkspaceTask(T::class, name, configure)
136+
}
137+
138+
internal val customTasks: ListProperty<Definition<out BufExecTask>> = project.objects.listProperty()
139+
140+
internal class Definition<T : BufExecTask>(
141+
val name: String,
142+
val kClass: KClass<T>,
143+
val configure: Action<T>,
144+
val property: Property<BufExecTask>,
145+
)
146+
}
147+
148+
/**
149+
* Options for the `buf generate` command.
150+
*
151+
* @see <a href="https://buf.build/docs/reference/cli/buf/generate/">"buf generate" command</a>
152+
* @see [BUF_GEN_YAML]
153+
*/
24154
public open class BufGenerateExtension @Inject constructor(internal val project: Project) {
155+
/**
156+
* `--include-imports` option.
157+
*
158+
* @see <a href="https://buf.build/docs/reference/cli/buf/generate/#include-imports">buf generate --include-imports</a>
159+
* @see [ProtocPlugin.includeImports]
160+
*/
25161
public val includeImports: Property<Boolean> = project.objects.property<Boolean>().convention(false)
162+
163+
/**
164+
* `--include-wkt` option.
165+
*
166+
* @see <a href="https://buf.build/docs/reference/cli/buf/generate/#include-wkt">buf generate --include-wkt</a>
167+
* @see [ProtocPlugin.includeWkt]
168+
*/
169+
public val includeWkt: Property<Boolean> = project.objects.property<Boolean>().convention(false)
170+
171+
/**
172+
* `--error-format` option.
173+
*
174+
* @see <a href="https://buf.build/docs/reference/cli/buf/generate/#error-format">buf generate --error-format</a>
175+
*/
176+
public val errorFormat: Property<ErrorFormat> = project.objects.property<ErrorFormat>().convention(ErrorFormat.Default)
177+
178+
/**
179+
* Possible values for `--error-format` option.
180+
*
181+
* @see <a href="https://buf.build/docs/reference/cli/buf/generate/#error-format">buf generate --error-format</a>
182+
*/
183+
public enum class ErrorFormat(internal val cliValue: String) {
184+
Text("text"),
185+
Json("json"),
186+
Msvs("msvs"),
187+
Junit("junit"),
188+
GithubActions("github-actions"),
189+
190+
/**
191+
* Buf's default value.
192+
*/
193+
Default(""),
194+
;
195+
}
26196
}

‎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)