+ Kobalt plug-ins are usually made of two parts. + +
kotlinProject or dependencies. These functions typically configure some data that your plug-in will later use to perform its functions.+ We'll cover these two items shortly but first of all, let's go over a quick example that will show you the whole process of writing a plug-in from scratch and publishing it on JCenter in ten minutes. +
@@ -235,7 +248,7 @@ Found 4972 lines in 65 files
And that's it! You can now iterate on your plug-in and upload it with additional ./kobaltw uploadJcenter. This plug-in is available on github.
The simplest way to run your plug-in in your IDE is to create a main function in the main class of your plug-in as follows: @@ -269,7 +282,122 @@ val p = plugins(
You can now set a breakpoint in your plug-in and launch the configuration you created above.
-
+ When your plug-in is activated, Kobalt will invoke its apply() function:
+
+override fun apply(project: Project, context: KobaltContext) {
+}
+
+
+ project is the project that your plug-in is currently being initialized for (keep in mind there can be multiple projects in a build) and the context gives you some information about other external data you might find useful, such as the command line that was passed to Kobalt.
+
+ Directives are functions that users of your plug-in can use in their build file in order to configure your plug-in. These can be any kind of Kotlin function but in the interest of preserving a clean syntax in the build file, it's recommended to use the type safe builder pattern, as described here. +
+
+ Imagine that you want to offer a boolean parameter publish to users of your plug-in, you start by creating a class to hold that parameter:
+
+class Info(val publish: Boolean) ++
+ Next, you create a directive that returns such a class and which also allows to configure it via the type safe builder pattern: +
+
+@Directive
+public fun myConfig(init: Info.() -> Unit) : Info {
+ val info = Info()
+ info.init()
+ return info
+}
+
+
+ The @Directive annotation is not enforced but you should always use it in order to help future tools (e.g. an IDEA plug-in) identify Kobalt directives so they can be treated differently from regular Kotlin functions.
+
+ Users can now specify the following in their build file: +
+
+// Build.kt
+import.com.example.plugin.myConfig
+
+myConfig {
+ publish = true
+}
+
+
+ If you need access to the project being built, just declare an additional parameter of type Project to your directive and have the user pass that project:
+
+@Directive
+public fun myConfig(project: Project, init: Info.() -> Unit) : Info {
+// ...
+
+
+myConfig(project) {
+ publish = true
+}
+
+
+ The last piece of this puzzle is how you give this data back to your plug-in so it can act on it. In order to do this, you simply look up the name of your plug-in in the Plugins registry and invoke whatever function you need to run:
+
+@Directive
+public fun myConfig(project: Project, init: Info.() -> Unit) : Info {
+ val info = Info()
+ info.init()
+ (Plugins.getPlugin("my-plug-in") as MyPlugin).addInfo(info)
+ return info
+}
+
+
+
+ Tasks are provided by plug-ins and can be invoked from the command line, e.g. ./gradlew assemble. There are two kinds of tasks: static and dynamic.
+
+ Static tasks are functions declared directly on your plug-in and annotated with the @Task annotation. Here is an example:
+
+@Task(name = "lineCount", description = "Count the lines", runBefore = arrayOf("compile"))
+fun lineCount(project: Project): TaskResult {
+ // ...
+ return TaskResult()
+}
+
+
+ A Kobalt task needs to accept a Project in parameter and return a TaskResult, which indicates whether this task completed successfully.
+
Project passed in both the apply() function and in each task feels redundant, although it avoids the trouble from having to store that project in a field of the plug-in, making it essentially stateless.
+
+ The @Task annotation accepts the following attributes:
+
gradlew command.