Tutorial

If you are curious to get a quick feel for what a Kobalt plug-in looks like, I suggest you go read how to write and publish a plug-in in ten minutes and then you can come back here and keep reading.

Setting up IDEA

Launch configuration

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:

fun main(argv: Array<String>) {
    com.beust.kobalt.main(argv)
}

In order for this code to compile, you will have to switch the dependency of your plug-in from kobalt-plugin-api to just kobalt, which is the actual application (and which therefore contains the main() entry point):

val dev = false // or true for development
val kobaltDependency = if (dev) "kobalt" else "kobalt-plugin-api"

val p = project {
    dependencies {
        compile("com.beust:$kobaltDependency:")
    }

Open the Kobalt side bar and sync your build file in IDEA. Your main() function should now build and be launchable. You can right click on that class file and select "Debug <your class name>", which will launch Kobalt with your plug-in. You can set a breakpoint in one of your tasks or anywhere that gets invoked. Don't forget to invoke this launch configuration with the regular parameters passed to Kobalt (e.g. "assemble").

Local dependencies

In the process of building your plug-in, you will probably be invoking it from test projects and since you will be making changes to your plug-in and generating jar files often, you might find it more convenient to have these test projects point to your local jar file instead of the Maven one (which would require you to upload your plug-in all the time). For this, you might find the file() and homeDir () directives convenient:

    // Regular dependency
    compile("com.example:my-plugin:0.1")

    // Development dependency
    compile(file(homeDir("kotlin/my-plugin/kobaltBuild/libs/my-plugin-0.1.jar"))

With this latter configuration, simply build your plug-in to generate the jar file with ./kobaltw assemble, switch to your test project and invoke Kobalt on it so that your plug-in will get invoked and you should see the latest version of your code being invoked.

Plug-in architecture

Plug-ins often produce files and data that other plug-ins need to use in order for a build to succeed. For example, the Android plug-in needs to generate a file called R.java and then make this file available at compile time by the Java or Kotlin (or any other language) plug-in. Since plug-ins have no idea about what other plug-ins are currently enabled and running, they can't directly talk to each other so instead of calling into Kobalt, Kobalt calls into them. This is done by declaring various "actors" that Kobalt will invoke whenever it needs the information that your plug-in produced. This is a design pattern often referred to as the "Hollywood Principle": "Don't call us, we'll call you".

These "actors" are exactly what the kobalt-plugin.xml file describes. This file informs Kobalt about the various ways in which your plug-in participates in the build system by specifying 1) plug-ins, 2) contributors or 3) interceptors.

Parts

• kobalt-plugin.xml. A file that describes all the components (called "plug-in actors") of your plug-in, such as contributors.
• Directives. Kotlin functions that users of your plug-in can invoke in their build file, such as project or dependencies. These functions typically configure some data that your plug-in will later use to perform its functions.
• Tasks. These tasks are invoked from the command line and ask your plug-ins to perform certain actions.
• Properties. Plug-ins can export properties and read properties from other plug-ins.

kobalt-plugin.xml

The kobalt-plugin.xml file (stored in META-INF in the jar file of your plug-in) is mandatory and describes all the actors of your plug-in. This file contains a list of class names, each of which is expected to implement at least one of IPluginActor's interfaces:

<plugin-actors>
  <class-name>com.beust.kobalt.plugin.java.JavaPlugin</class-name>
  <class-name>com.beust.kobalt.plugin.android.AndroidPlugin</class-name>
  <class-name>com.beust.kobalt.plugin.java.JavaBuildGenerator</class-name>
  <class-name>com.beust.kobalt.plugin.kotlin.KotlinBuildGenerator</class-name>
</plugin-actors>

IPluginActors can be split in several categories:

• Plugins, which contain @Task annotations.
• Interceptors, which transform data that Kobalt gives them.
• Contributors, which produce additional data.

All plug-in actors are interfaces that extend IPluginActor. Plug-ins extend IPlugin, interceptors extend IInterceptor and contributors extend IContributor. When Kobalt parses your kobalt-plugin.xml, it instantiates all the classes found in the <plugin-actors> tag and then introspects them to find out which IPluginActor interfaces that class implements.

If we look a the declarations of these classes, we can get an idea what they do

class JavaPlugin : ICompilerContributor, IDocContributor {

With this declaration, we know that the JavaPlugin contributes a compiler and a doc generator.

class JavaBuildGenerator: ITemplateContributor {

This class is declaring that it wants to take part in the --init process (i.e. it can generate a template), discussed below.

List of plug-in actors

Here is a list of actors (contributors and interceptors) that you can define in your plug-in.

Selection process

Several plug-ins might want to contribute to a specific task where only one participant should be allowed, such as running tests or generating documentation. Even the simple task of compiling should probably only ever be performed by no more than one plug-in for a given project. Therefore, when comes the time to compile a project, Kobalt needs to find which plug-in is the most suitable for that task and pick it. In order to do that, plug-ins that contribute to tasks that can only be performed by one candidate need to declare their affinity to that task for a given project.

Contributors that want to participate in a selection process need to implement the following interface:

interface IProjectAffinity {
    /**
     * @return an integer indicating the affinity of your actor for the given project. The actor that returns
     * the highest affinity gets selected.
     */
    fun affinity(project: Project, context: KobaltContext) : Int
}

For example, the JavaPlugin implements the ICompilerContributor interface and then overrides the affinity() method to make sure it gets run for Java projects but ignored for others:

override fun affinity(project: Project, context: KobaltContext) =
if (project.sourceSuffix == ".java") 1 else 0

Directives

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().apply { init() }

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. The code above defines a myConfig function that accepts a closure as an argument. It creates an Info object, calls the init() function on it (which runs all the code inside that closure) and then return that Info object.

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(init: Info.() -> Unit) = Info().apply {
    init()
    (Kobalt.findPlugin("my-plug-in") as MyPlugin).info = info
    this
}

Obviously, you can choose any kind of API to communicate between the directive and its plug-in. In the code above, I chose to directly override the entire Info field, but you could instead choose to call a function, just set one boolean instead of the whole object, etc...

Tasks

Tasks are provided by plug-ins and can be invoked from the command line, e.g. ./kobaltw assemble. There are two kinds of tasks: static and dynamic.

Static tasks

Static tasks are functions declared directly in your plug-in class and annotated with the @Task annotation. Here is an example:

@Task(name = "lineCount", description = "Count the lines", dependsOn = 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.

The @Task annotation accepts the following attributes:

name

The name of the task, which will be used to invoke it from the command line.

description

The description of this command, which will be displayed if the user invokes the usage for the kobaltw command.

dependsOn

A list of all the tasks that this task depends on.

reverseDependsOn

Make the following tasks depend on this task.

runBefore

A list of all the tasks that this task should run prior to.

runAfter

A list of all the tasks that should run before this task does.

Kobalt defines two different concepts for tasks: dependencies and orderings. And for each of this concept, you can define the relation to go in one direction or the other.

If your task cannot run until another task has run, you need to declare a dependency. Dependencies cause additional tasks than those requested to be executed. For example, "assemble" depends on "compile", which means that whenever you invoke "assemble", "compile" will be automatically run first. This is a dependency and it is controlled by "dependsOn" and "reverseDependsOn". You can see "reverseDependsOn" as a way to insert your task before an existing task.

Orderings, controlled by "runBefore" and "runAfter" merely specify an ordering but do not pull new tasks in. This is how you tell Kobalt "In case the user asks for my task to run, here is when it should be invoked", but your task will run only if it's explicitly invoked by the user.

Here are a few different scenarios to illustrate how the three attributes work for the task example:

Result of the command ./kobaltw --dryRun compile

clean
compile
example

clean
example
compile

clean
compile

Dynamic tasks

Dynamic tasks are useful when you want your plug-in to generate one or several tasks that depend on some other runtime information (therefore, you can't declare a method and put a @Task annotation on it). Plug-ins declare dynamic tasks by implementing the ITaskContributor intrface:

interface ITaskContributor {
    fun tasksFor(project: Project, context: KobaltContext) : List<DynamicTask>
}

For example:

override fun tasksFor(project: Project, context: KobaltContext) = listOf(
    DynamicTask(this
        name = "dynamicTask",
        description = "Description",
        group = "other",
        project = project,
        reverseDependsOn = listOf("compile"),
        closure = { project ->
            println("Running dynamicTask")
            TaskResult()
}))

DynamicTask mirrors the @Task attributes: name, description and dependencies. The only addition is the closure parameter, which specifics the code that will run if your task gets invoked. That closure needs to follow the same constraints that a @Task method obeys: it takes a Project parameter and returns a TaskResult.

Once you have implemented ITaskContributor, you can see your dynamic task in the list of tasks and run it directly:

$ ./kobaltw --tasks
  ===== kobalt-line-count =====
    dynamicTask         Description
    lineCount           Count the lines
$ ./kobaltw dynamicTask
Running dynamictask

Properties

Properties are the mechanism that plug-ins can use to export values and also read values that other plug-ins have exported. There are two kinds of properties that plug-ins can manipulate:

• Project properties: project-specific properties.
• Plug-in properties: general properties that are applicable to no project in particular.

Project properties

Project instances have a property called projectProperties that is an instance of the ProjectProperties class. Plugins can put and get values on this object in order to store project specific properties.

fun taskAssemble(project: Project) : TaskResult {
    project.projectProperties.put("packages", packages)

Another plug-in can then query this property as follows:

    val packages = project.projectProperties.put("packages")

Plug-in properties

The PluginProperties instance can be found on the KobaltContext object that your plug-in receives in its apply() method. Once you have an instance of this class, you can read or write variables into it:

override fun apply(project: Project, context: KobaltContext) {
    // Export a property for other plug-ins to use
    context.pluginProperties.put(PLUGIN_NAME, "somePluginProperty", "someValue")
    // Read a property from another plug-in
    val sourceDir = context.pluginProperties.get("pluginName", "somePluginProperty")
}

Documenting properties

Plug-ins that define properties should annotate them with the @ExportedPluginProperty or @ExportedProjectPropertyannotation:

companion object {
@ExportedProjectProperty
const val BUILD_DIR = "buildDir"